MultiAgentEngine

Use MultiAgentEngine to define a primary agent and optional secondary agents: the primary agent owns the request, and secondary agents handle specific tasks the primary delegates to them. This is @culvii/kit's MultiAgentEngine, authoring only, and it just defines the agent; once deployed, the agent runs either inside a workflow execution, invoked by a core.agent step, or directly from the Console by starting a new session with it.

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.',
  // credentialId is the auth identity's ID from the Console's Integrations tab, not a raw API key
  model: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'my-openai-credential' },
  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
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)
mcp	(Optional) Configuration for Model Context Protocol integrations
metadata	(Optional) runtimeDetails.permissions grants built-in tools (see Tools and permissions); other keys store custom metadata
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: 'my-openai-credential' },
  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: 'my-openai-credential' },
      metadata: {
        runtimeDetails: {
          permissions: {
            'workflow:binary: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 }
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)
mcp	(Optional) Configuration for Model Context Protocol integrations
metadata	(Optional) runtimeDetails.permissions grants built-in tools (see Tools and permissions); other keys store custom metadata

Configure models

Every agent's model is an AgentModelConfig object. At minimum it carries a provider, a modelId, and a credentialId: the ID of an auth identity you created in the Console's Integrations tab, which the runtime uses to resolve the provider API key at call time. See Credentials.

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

Supported providers include:

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

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

Run timeout

An agent run has 10 minutes of wall-clock time before the platform kills it, regardless of how many iterations or tool calls it's made.

Set maxIterations on your agent definition to a value that comfortably finishes within that window, so a runaway loop fails fast on a clear iteration limit instead of running until the timeout kills it. See also the tool call timeout that applies to workflow tools an agent calls.