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: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'openai-key' },
  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 config object: { provider, modelId, credentialId }
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: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'openai-key' },
  secondaryAgents: [
    {
      id: 'research',
      name: 'Research',
      role: 'secondary',
      systemPrompt: 'Inspect the files named by the primary agent. Return findings with file paths.',
      model: { provider: 'openai', modelId: 'gpt-4o-mini', credentialId: 'openai-key' },
      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 config object: { provider, modelId, credentialId }
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's model is an AgentModelConfig object. At minimum it carries a provider, a modelId, and a credentialId — the identifier of a credential stored on the platform that the runtime uses to resolve the provider API key.

model: {
  provider: 'openai',
  modelId: 'gpt-4o',
  credentialId: 'openai-key',
}

Supported providers include:

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

Advanced options

Use the optional fields when you need to override the endpoint or pass provider-specific options.

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

Keep raw credentials out of SDK definitions — the model config references a credential by credentialId and never carries an API key. Deploys are rejected if an agent's model is missing a credentialId.

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: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'openai-key' },
secondaryAgents: [
  {
    // Secondary agent uses a smaller model
    model: { provider: 'openai', modelId: 'gpt-4o-mini', credentialId: 'openai-key' },
    // ...
  }
]