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 (defaults to 50). This bounds autonomous execution across the entire session turn, including all secondary agent delegations |
maxToolCalls | (Optional) Maximum individual tool executions in one agent run (defaults to 100). This bounds autonomous execution across the entire session turn, including all secondary agent delegations |
temperature | (Optional) Controls response creativity (0.0 for deterministic, higher for creative) |
permissions | (Optional) Top-level tool and integration permission policy: { default, integrations } (see Tools and permissions) |
metadata | (Optional) runtimeDetails configures sandboxProfile, skills, and networking; 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 or model 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' },
},
],
});
The secondary agent id becomes part of the delegation contract. Write secondary prompts as narrow job descriptions. Secondary agents cannot configure permissions, tools, or networking; governed sandbox, integration, skill, and workflow tools belong to the primary agent so durable continuation has one model transcript.
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 } |
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 (defaults to 50). Controlled by the primary agent's session turn budget |
maxToolCalls | (Optional) Maximum individual tool executions in one agent run (defaults to 100). Controlled by the primary agent's session turn budget |
temperature | (Optional) Controls response creativity (0.0 for deterministic, higher for creative) |
metadata | (Optional) Custom metadata object (session turn budgets, sandboxProfile, skills, and networking are controlled by the primary agent) |
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.
Only models enabled in the platform model catalog are supported; culvii dev, culvii deploy, and runtime execution reject unconfigured or disabled models.
You can use the createAgentModelConfigFromRef helper to parse a <provider>/<model-id> string, or provide the raw object:
import { createAgentModelConfigFromRef, parseAgentModelRef } from '@culvii/kit';
// Using the helper:
model: createAgentModelConfigFromRef('openai/gpt-4o', 'my-openai-credential', options)
// Or the raw object:
model: {
provider: 'openai',
modelId: 'gpt-4o',
credentialId: 'my-openai-credential',
}
AgentModelConfigOptions
Both createAgentModelConfigFromRef(modelRef, credentialId, options?) and the AgentModelConfig object accept these optional fields:
| Field | Use |
|---|---|
baseUrl | Custom API endpoint URL |
headers | Custom HTTP headers for the provider request |
providerOptions | Provider-specific configuration parameters |
project | Project ID (for Vertex AI / Google Cloud) |
location | Region or location (for Vertex AI / Google Cloud) |
googleAuthOptions | Google authentication configuration: { keyFile?, keyFilename?, projectId?, scopes?, credentials?: { client_email, private_key } } |
Supported providers include:
openaianthropicgeminivertexaigoogle-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' },
// ...
}
]
Runtime details, skills, and networking
The metadata.runtimeDetails object on the primary agent configures the session's execution environment.
metadata: {
runtimeDetails: {
sandboxProfile: 'default',
networking: {
type: 'limited',
allow_package_managers: true,
allowed_hosts: ['api.example.com'],
},
skills: [
{
type: 'github_repository',
url: 'https://github.com/org/skills',
source: 'skills/pdf',
credentialId: 'my-github-credential',
ref: 'main',
fallback_paths: ['skills/default'],
},
],
},
}
Sandbox profile
Sandbox sessions run on the platform's single default sandbox image. The metadata.runtimeDetails.sandboxProfile field defaults to 'default' and only 'default' is supported. Resolved from the primary agent's metadata.runtimeDetails when the session sandbox is created.
Networking
Configured on the primary agent only (rejected on secondary agents). Controls outbound network access from the sandbox. Sandbox tools (web_fetch, exec_process, git) run inside the agent sandbox and use this networking policy. Integration tools (permissions.integrations), workflow tools (defineWorkflowTool), and session-start skills downloads run on the platform outside the sandbox and do NOT use metadata.runtimeDetails.networking.
{ type: 'limited', allow_package_managers?: boolean, allowed_hosts?: string[] }: The default whennetworkingis omitted is{ type: 'limited', allow_package_managers: false, allowed_hosts: [] }.allow_package_managers: Whentrue, allows outbound HTTPS access to standard package registries and code hosts. This only unlocks built-in package registries and Git hosts, so downloading viaexec_processorgitagainst other hosts requires adding that bare hostname toallowed_hosts.allowed_hosts: Array of exact public bare hostnames (max 253 characters, normalized to lowercase). Any domain fetched withweb_fetchmust be inallowed_hosts. Rejects schemes/URLs, ports, paths, wildcards (*), IP addresses, andlocalhost/.local/.internalnames.
{ type: 'unrestricted' }: Allows outbound access to public hostnames. Cannot be combined withallow_package_managersorallowed_hosts.
Skills
Configured in metadata.runtimeDetails.skills on the primary agent (resolved when a session starts).
| Field | Use |
|---|---|
type | 'github_repository' (required) |
url | HTTPS https://github.com/<owner>/<repo> repository URL, e.g. 'https://github.com/org/skills' (required, max 500 chars; no port, credentials, query string, or fragment) |
source | Repository-relative path to a *.md file or folder containing SKILL.md, e.g. 'skills/pdf' (required, 1–500 chars; no leading /, \, control chars, or . / .. segments) |
credentialId | GitHub credential ID matching ^[A-Za-z0-9_-]{1,128}$ (required for both public and private repositories) |
ref | (Optional) Branch, tag, or commit SHA (defaults to 'HEAD', 1–200 chars without whitespace or control chars; resolved to an exact 40-char commit SHA at session start) |
fallback_paths | (Optional) Non-empty ordered array of alternative repository-relative paths (1–100 entries, each 1–500 chars) checked in order if source has no skill instructions; only the first matching location is imported |
Runtime behavior:
- Skills are fetched, verified, and snapshotted at session start, and mounted under
/skills/<repo-name>(using the lowercase repository name). - Multiple sources from the same repository share
/skills/<repo-name>(identical overlapping files are deduplicated; conflicting file contents or file-vs-directory path collisions are rejected). Two different repositories with the same lowercase repo name are rejected as a mount collision. - Only regular Git blobs (
100644or100755) are supported; symlinks, submodules, and special files are rejected. - Each
SKILL.mdrequires YAML frontmatter (--- ... ---with unique keys and at most10YAML aliases) containing a unique lowercasename(^[a-z0-9][a-z0-9-]{0,63}$) and a non-emptydescription(max1,024chars). - On each turn, the primary agent receives the installed skill catalog (
skill_id,name,description) and loads instructions or UTF-8 text references on demand via the built-inread_skilltool ({ skill_id, path? }). Binary skill files cannot be read withread_skilland must be inspected using permitted sandbox tools. Skill content is untrusted guidance and does not grant tool permissions, credentials, or network access. - Skill additions, removals, or refreshes require starting a new session. Restarting a direct session restores the original snapshotted skills while applying the agent's current networking configuration.
Limits:
| Limit | Default | Scope & Notes |
|---|---|---|
| Files per configured source | 200 files | Includes SKILL.md and files in subfolders; excludes directories and unselected repository files. Checked before downloading blobs. |
| Size per file | 1 MiB (1,048,576 bytes) | Maximum raw (unencoded) byte size of any single file in a skill source. |
| Total size per configured source | 8 MiB (8,388,608 bytes) | Maximum combined raw (unencoded) byte size of all selected files within one skills entry. Separate entries each get their own 200-file and 8 MiB budget. |
| Catalog prompt size | 1 MiB (1,048,576 bytes) | Maximum UTF-8 byte length of the session-wide skill catalog prompt injected into the primary agent's system prompt across all installed skills. |
| Max path length | 500 characters | Applies to source, each fallback_paths entry, and every repository-relative skill file path. |
Max fallback_paths | 100 entries | Maximum alternative paths per configured skill source (1–100 when provided). |
Skill name pattern | ^[a-z0-9][a-z0-9-]{0,63}$ | 1–64 lowercase alphanumeric/hyphen characters; must be unique within a source. |
Skill description length | 1,024 characters | Required non-empty string in SKILL.md YAML frontmatter (frontmatter allows at most 10 YAML aliases). |
| Max repository tree entries | 10,000 entries | Total files and directories across the entire GitHub repository's recursive tree. |
| Max GitHub API response size | 10 MiB (10,485,760 bytes) | Per GitHub commit/tree API JSON response (2 MiB per blob response; 20s per-request timeout, 5m total acquisition timeout per source). |
One configured source selecting multiple skills (for example source: 'skills') shares that source's 200-file and 8 MiB allowance. Separate entries in metadata.runtimeDetails.skills (for example separate source: 'skills/pdf' and source: 'skills/xlsx' entries) each get their own 200-file and 8 MiB allowance, even when they come from the same repository and merge into /skills/<repo-name>.
Context window and execution budgets
Context-window capacity and maximum output tokens are configured per model in the platform model catalog. There is no default context window; the platform includes the current prompt when deciding turn compaction. When session history approaches the model's context window, the platform automatically compacts older turns into session memory.
Each agent run is bounded by maxIterations (defaults to 50 tool-loop steps) and maxToolCalls (defaults to 100 individual tool executions). When an agent pauses on a tool approval ('ask') or invokes a workflow tool (defineWorkflowTool()), the execution suspends durably and resumes once the approval or child workflow completes. Individual sandbox commands (exec_process) default to a 60-second timeout, sandbox file reads and attachments cap at 10 MiB, and idle session sandboxes are snapshotted after 30 minutes of inactivity.