@agent-ruler/agent-sdk

AgentRuler SDK — A production-grade agent loop with Node.js backend, permission system, and full toolbar settings API.

Features

• AgentLoop — Platform-agnostic ReAct loop with streaming and callback APIs
• NodeBackendAdapter — Full Node.js backend: MCP clients, LLM streaming, bash, file I/O, web tools
• Permission Engine — Identity-based access control with presets (Admin / Maintainer / Reader / Guest)
• Toolbar Settings API — Programmatic control of all chat settings: mode, thinking, temperature, tools, skills, permissions
• MCP Support — STDIO, SSE, and Streamable HTTP transports
• Dual Module — ESM + CJS with TypeScript declarations

Installation

npm install @agent-ruler/agent-sdk

Quick Start

import { AgentSDK } from '@agent-ruler/agent-sdk';

const sdk = new AgentSDK();

// Configure LLM
sdk.setDefaultLLM({
  baseURL: 'https://api.openai.com/v1',
  apiToken: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o',
});

// Configure MCP servers
sdk.loadMcpConfig({
  mcpServers: {
    filesystem: {
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
    },
  },
  defaultLLM: {
    baseURL: 'https://api.openai.com/v1',
    apiToken: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  },
});

// Simple invocation
const answer = await sdk.ainvoke({ messages: 'List files in /tmp' });
console.log(answer);

Toolbar Settings API

All chat toolbar settings are fully configurable via the SDK:

Agent Loop Mode

sdk.setAgentLoopMode('chat');   // Pure conversation
sdk.setAgentLoopMode('agent');  // Tool-enhanced (default)
sdk.setAgentLoopMode('plan');   // Planning mode (reserved)

Thinking Mode

sdk.setThinking(true, 'high');  // Enable with effort level
sdk.setThinking(false);         // Disable
// effort: 'low' | 'medium' | 'high' | 'max'

Temperature

sdk.setTemperature(0.7);  // 0.0 – 2.0, defaults to 0.6

Parallel Tool Calls

sdk.setParallelToolCalls(true);   // Default
sdk.setParallelToolCalls(false);

XML Wrapper

sdk.setXmlWrapper(true);

System Prompt

sdk.setSystemPrompt('You are a senior TypeScript engineer.');

Tool Management

sdk.setToolEnabled('Bash', true);
sdk.setToolEnabled('WebSearch', false);
sdk.setAllToolsEnabled(true);

Skill Management

sdk.setSkillEntries([
  { id: 'my-skill', enabled: true },
]);
sdk.enableSkill('my-skill', false);

Defer Loading

sdk.setDeferLoading(true);   // MCP tools deferred by default
sdk.setDeferLoading(false);

Permission System

Preset Identities

sdk.setPresetIdentity('admin');       // Full access
sdk.setPresetIdentity('maintainer');  // Elevated with restrictions
sdk.setPresetIdentity('reader');      // Read-only
sdk.setPresetIdentity('guest');       // Minimal access

Custom Permissions

sdk.setPermissionProfile({
  presetId: 'maintainer',
  toolOverrides: {
    Bash: { enabled: true },
    Agent: { enabled: false },
  },
  resourceOverrides: [
    { resourceType: 'file', pathPattern: '/secrets/**', actions: ['read'], effect: 'deny' },
  ],
  workingDirectory: '/project',
  allowSandboxEscapeWithConsent: true,
});

sdk.overrideToolPermission('Bash', false);
sdk.setWorkingDirectory('/project');
sdk.setSandboxEscapeConsent(true);

Streaming

const stream = sdk.stream({ messages: 'Explain quantum computing' });

for await (const event of stream) {
  switch (event.type) {
    case 'stream_event':
      process.stdout.write(event.event.choices[0]?.delta.content ?? '');
      break;
    case 'tool_call':
      console.log('Tool:', event.toolCall.function?.name);
      break;
    case 'tool_result':
      console.log('Result:', event.result.content);
      break;
    case 'done':
      console.log('\nTokens:', event.consumption);
      break;
  }
}

Sub-Agents

const result = await sdk.runSubAgent(
  'Explore codebase',
  'Find all uses of the deprecated API',
  {
    model: 'gpt-4o-mini',
    onProgress: (progress) => {
      console.log(`Steps: ${progress.stepCount}, Tools: ${progress.toolUseCount}`);
    },
  }
);
console.log(result.output);

Low-Level AgentLoop

For advanced use cases, use AgentLoop directly:

import { AgentLoop, NodeBackendAdapter } from '@agent-ruler/agent-sdk';

const adapter = new NodeBackendAdapter();
const loop = new AgentLoop(adapter);

loop.setLlmConfig({
  baseUrl: 'https://api.openai.com/v1',
  userToken: 'sk-...',
  userModel: 'gpt-4o',
});

const storage = await loop.createStorage();

loop.registerOnChunk((chunk) => {
  console.log(chunk.choices[0]?.delta.content);
});

await loop.start(storage, 'Hello');

License

MIT