Skip to main content

Multi-Agent API

The Multi-Agent API lets you configure and run primary and secondary agents, and define tools they can use.

Classes​

MultiAgentEngine​

The core engine that orchestrates agent execution and communication.

Constructor:

  • new MultiAgentEngine(primaryConfig: PrimaryAgentConfig, options?: MultiAgentEngineOptions) Creates an engine from a primary agent config and optional engine options.

Methods:

  • run(task: string, options?: MultiAgentRunOptions): Promise<AgentExecutionResult> Runs the multi-agent process for a given task and resolves with the result. This is the only public method on the engine. 
    const result = await engine.run('Analyze this data', { runId: 'custom-run-id' });
    console.log(result.output);

Constructor Options:

Pass MultiAgentEngineOptions as the second argument to observe process events as they happen. The full event log is also returned on the result as result.process.

const engine = new MultiAgentEngine(primaryConfig, {
  onProcess: async (event) => {
    console.log(event.type, event.agentId);
  }
});

Functions​

defineWorkflowTool​

Creates a tool from a workflow that agents can call.

const myTool = defineWorkflowTool({
  name: 'runWorkflow',
  description: 'Run the selected workflow.',
  workflowId: 'workflow-id',
});

deriveAllowedToolsFromPermissions​

Helper to get a list of allowed tools based on user permissions.

const allowedTools = deriveAllowedToolsFromPermissions(userPermissions);

Types & Interfaces​

PrimaryAgentConfig​

Configuration for a primary agent that coordinates tasks.

const agent: PrimaryAgentConfig = {
  id: 'planner',
  name: 'Planner',
  role: 'primary',
  systemPrompt: 'Coordinate the task.',
  model: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'openai-key' },
  secondaryAgents: [],
  // Optional fields
  description: 'Coordinates tasks and delegates to secondary agents',
  goal: 'Successfully complete the user request efficiently',
  backstory: 'An expert project manager who delegates work effectively',
  maxIterations: 10,
  temperature: 0.2,
  permissions: { 'fs:read': true },
  tools: {},
  allowedTools: ['readFile'],
  mcp: { servers: {} },
  metadata: { version: '1.0' },
  delegationGuidance: 'Delegate research tasks to the research agent',
};

SecondaryAgentConfig​

Configuration for a specialized secondary agent.

const research: SecondaryAgentConfig = {
  id: 'research',
  name: 'Research',
  role: 'secondary',
  systemPrompt: 'Find evidence and return concise notes.',
  model: { provider: 'openai', modelId: 'gpt-4o-mini', credentialId: 'openai-key' },
  // Optional fields
  description: 'Research agent for gathering facts',
  goal: 'Find accurate and relevant information quickly',
  backstory: 'A meticulous librarian who finds facts efficiently',
  maxIterations: 5,
  temperature: 0.1,
  permissions: { 'fs:read': true },
  tools: {},
  allowedTools: ['readFile'],
  mcp: { servers: {} },
  metadata: { priority: 'high' },
};

AgentModelConfig & AgentModelRef​

Types for specifying the AI model. AgentModelRef is the <provider>/<model-id> string form (e.g. for tooling that parses refs); an agent's model field is an AgentModelConfig object. The object always carries a credentialId reference — never a raw API key.

const modelRef: AgentModelRef = 'openai/gpt-4o';

const modelConfig: AgentModelConfig = {
  provider: 'openai',
  modelId: 'gpt-4o',
  credentialId: 'openai-key',
};

WorkflowToolConfig​

Configuration for a workflow-backed tool.

const tool: WorkflowToolConfig = {
  kind: 'workflow',
  name: 'runWorkflow',
  description: 'Run the selected workflow.',
  workflowId: 'workflow-id',
};

MultiAgentProcessEvent​

Event shape emitted during agent execution.

function handleEvent(event: MultiAgentProcessEvent) {
  console.log(event.type, event.agentId);
}

AllowedToolName​

A string literal type for allowed tools.

const allowedTools: AllowedToolName[] = ['readFile', 'grep'];

Additional Types​

  • AgentExecutionResult: The final output of an agent run, including output, the process event log, toolsUsed, delegations, per-agent agents reports, and optional usage.
  • MultiAgentRunOptions: Options passed to engine.run() — context, runId, and messages.
  • Permission: Type representing a user or system permission.