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.

Methods:

  • register(baseUrl: string, authHeader?: string): Promise<AgentRegistrationResult> Registers the primary and secondary agents with the platform.

    const result = await engine.register('https://api.culvii.com', 'Bearer my-token');

  • run(task: string, options?: MultiAgentRunOptions): Promise<AgentExecutionResult> Starts the multi-agent execution process for a given task.

    const result = await engine.run('Analyze this data', { runId: 'custom-run-id' });

  • getProcessLog(): MultiAgentProcessEvent[] Returns the log of all process events that occurred during execution.

    const events = engine.getProcessLog();

Constructor Options:

You can pass MultiAgentEngineOptions as the second argument to the constructor to listen to process events.

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: 'openai/gpt-4o',
  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: 'openai/gpt-4o-mini',
  // 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 & AgentModelName​

Types for specifying the AI model.

const modelName: AgentModelName = 'openai/gpt-4o';

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

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.
  • AgentRegistrationResult: The result of registering an agent.
  • MultiAgentRunOptions: Options passed to engine.run().
  • Permission: Type representing a user or system permission.