MultiAgentEngine

Use MultiAgentEngine to define a primary agent and optional secondary agents.

The primary agent owns the request. Secondary agents handle specific tasks the primary delegates to them.

Initialize the engine

Define a primary agent by passing a configuration object to MultiAgentEngine.

import { MultiAgentEngine } from '@culvii/kit';

const planner = new MultiAgentEngine({
  id: 'planner',
  name: 'Planner',
  role: 'primary',
  systemPrompt: 'Coordinate the user request. Delegate evidence gathering to Research. Return a concise final answer.',
  model: 'openai/gpt-4o',
  secondaryAgents: [],
});

Primary agent fields

Field	Use
id	Stable runtime identifier
name	Human-readable name
role	Must be primary
systemPrompt	Coordination instructions for the agent
model	Model reference string or object
secondaryAgents	Array of secondary agent definitions
permissions	(Optional) Built-in tool access
tools	(Optional) Workflow tool declarations
description	(Optional) A brief overview of what the agent does
goal	(Optional) The specific objective the agent is trying to achieve
backstory	(Optional) The agent's persona or background context. This shapes how it reasons
maxIterations	(Optional) Maximum number of steps the agent can take before stopping
temperature	(Optional) Controls response creativity (0.0 for deterministic, higher for creative)
allowedTools	(Optional) Specific tools this agent is permitted to use
mcp	(Optional) Configuration for Model Context Protocol integrations
metadata	(Optional) Custom key-value pairs to attach to the agent
delegationGuidance	(Optional) Instructions on how and when to hand off tasks to secondary agents

Add secondary agents

Add secondary agents when you need a different prompt, model, or permission set for a specific task.

const planner = new MultiAgentEngine({
  id: 'planner',
  name: 'Planner',
  role: 'primary',
  systemPrompt: 'Coordinate the task and delegate research.',
  model: 'openai/gpt-4o',
  secondaryAgents: [
    {
      id: 'research',
      name: 'Research',
      role: 'secondary',
      systemPrompt: 'Inspect the files named by the primary agent. Return findings with file paths.',
      model: 'openai/gpt-4o-mini',
      permissions: {
        'fs:read': true,
      },
    },
  ],
});

The secondary agent id becomes part of the delegation contract. Write secondary prompts as narrow job descriptions.

Secondary agent fields

Field	Use
id	Stable delegation identifier
name	Human-readable name
role	Must be secondary
systemPrompt	Focused instruction for the specific task
model	Model reference string or object
permissions	Optional built-in tool access
tools	Optional workflow tool declarations
description	(Optional) A brief overview of what the agent does
goal	(Optional) The specific objective the agent is trying to achieve
backstory	(Optional) The agent's persona or background context
maxIterations	(Optional) Maximum number of steps the agent can take before stopping
temperature	(Optional) Controls response creativity (0.0 for deterministic, higher for creative)
allowedTools	(Optional) Specific tools this agent is permitted to use
mcp	(Optional) Configuration for Model Context Protocol integrations
metadata	(Optional) Custom key-value pairs to attach to the agent

Configure models

Every agent needs a model. You can use a string for the common case or an object for advanced configuration.

Model strings

Model strings use the <provider>/<model-id> format.

model: 'openai/gpt-4o'

Supported providers include:

• openai
• anthropic
• gemini
• vertexai
• google-vertex

Model objects

Use the object form when you need to keep the provider and model ID separate, or when you need to pass provider-specific options.

model: {
  provider: 'openai',
  modelId: 'gpt-4o',
  baseUrl: 'https://example.com/v1',
  headers: {
    'x-workspace-id': 'workspace-id',
  },
}

Keep credentials out of SDK definitions. Store them in the system that runs the engine.

Pick models by role

You can assign different models to different agents. A stronger model can own planning, while a smaller, faster model handles narrow support work.

// Primary agent uses a stronger model
model: 'openai/gpt-4o',
secondaryAgents: [
  {
    // Secondary agent uses a smaller model
    model: 'openai/gpt-4o-mini',
    // ...
  }
]