Skip to main content

Multi-Agent Tutorial

Goal: See how the main agent delegates focused work to a subagent.

Prerequisites: Quickstart completed, platform running.

Time: ~5 minutes

Model​

AI-in-a-Box 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 calls the Delegate tool:

Delegate(
  subagent_type="researcher",
  description="Look up the release history",
  prompt="Find the latest Python release and cite sources."
)

The child receives only the prompt and allowed tools for its subagent type, returns one final result, and exits.

1. Trigger Delegation​

In the chat UI, 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 researcher and use the sandbox directly, or delegate coding work to coder.

2. Read the Timeline​

The tool timeline shows the Delegate call, the subagent type, and the returned summary. It does not show a separate top-level chat session for the child.

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: openai/gpt-5.4
color: blue
---
You are a legal-review specialist. Cite every clause you flag.

Restart agent-runtime after changing subagent files.

What Not To Do​

Do not send agent_id: "coder" to /v1/chat expecting to target the coder subagent. Runtime maps legacy specialist IDs back to default; subagents are entered only through Delegate.

What You Learned​

  • /v1/agents lists top-level global/custom agents, not subagent types.
  • Subagents are isolated child runs launched through Delegate.
  • Subagent Markdown frontmatter controls description, tools, model hints, and display metadata.

See Agents Reference.