Skip to main content

Multi-Agent

See how the single main agent delegates focused work to a scoped subagent — spawned natively by Codex — and how to add a new subagent type.

Prerequisites​

Model​

AIBox does not expose researcher, coder, or analyst as top-level /v1/chat agents. One adaptive main agent runs the session. When it needs a focused child context, it delegates to a subagent.

There is no Delegate tool. Subagent types are defined as Markdown + YAML-frontmatter files under deploy/config/subagents/*.md and loaded by SubagentLoader in services/agent-runtime/src/agent_runtime/subagents.py. Those definitions are surfaced to the main agent as an # Available subagents instruction block (built in agent_factory.py) that tells the model which subagents exist and when to delegate.

Spawning itself is performed natively by Codex through its multi-agent feature (features.multi_agent). That capability is config-gated for the agentic profile in services/agent-runtime/src/agent_runtime/codex_engine/policy.py; the default chat profile leaves it off. The child receives only the task prompt the main agent writes for it plus the allow-listed tools for its subagent type, returns one final result, and exits.

Steps​

1. Trigger delegation​

In the chat surface, ask:

Search for the latest Python release, then write a small Python snippet that prints my local Python version.

The main agent may delegate the search to a research-oriented subagent and use the sandbox directly, or hand the coding work to another subagent — its choice depends on the available subagent types and the task.

2. Read the timeline​

When Codex runs a subagent it emits a collabAgentToolCall event. Agent-runtime translates it into a subagent-kind event and surfaces it over SSE as a tool_result-shaped frontend event (chat_handler/streaming_loop.py). The tool timeline shows the subagent type and its returned summary; it does not show a separate top-level chat session for the child run.

3. Define a subagent type​

Subagent types live in deploy/config/subagents/*.md:

---
name: legal-reviewer
description: Reviews contracts for problematic clauses
tools: web_search, knowledge_search
model: default
color: blue
---
You are a legal-review specialist. Cite every clause you flag.

Restart the agent-runtime service so the new file is picked up:

make restart-service SERVICE=agent-runtime

4. What not to do​

Do not send agent_id: "coder" to /v1/chat expecting to target the coder subagent. The runtime maps legacy specialist IDs back to default; subagents are only reachable through Codex-native delegation, never as a top-level agent.

Verify​

  • The timeline includes at least one subagent step with the type you expected (the frontend renders it as a subagent: <type> pill).
  • A new file in deploy/config/subagents/ is loaded at startup after make restart-service SERVICE=agent-runtime (look for the Loaded subagent type: log line).

Troubleshooting​

  • No subagent ever fires — the task may be too small to warrant delegation, or the active profile is chat (lean) rather than agentic. Multi-agent is gated by features.multi_agent; set AIBOX_CODEX_PROFILE=agentic (or AIBOX_CODEX_MULTI_AGENT=1) on agent-runtime to enable it, then try a prompt that mixes deep research with execution.
  • New subagent type not visible — restart agent-runtime (step 3); the subagent registry is loaded at startup.

Next​

  • Agents reference — managed agents API, subagent registration, and the runtime's role mapping.
  • Skills reference — how SKILL.md packs interact with delegation.

Source files​

  • deploy/config/subagents/*.md — subagent type definitions
  • services/agent-runtime/src/agent_runtime/subagents.py — SubagentLoader / SubagentType
  • services/agent-runtime/src/agent_runtime/agent_factory.py — # Available subagents instruction block
  • services/agent-runtime/src/agent_runtime/codex_engine/policy.py — features.multi_agent gating
  • services/agent-runtime/src/agent_runtime/chat_handler/streaming_loop.py — subagent SSE event

Verified against commit 4facb2e1 (2026-06-10) · sources 663a7654f03a.