Agent Architecture

A chat session runs one root agent. That agent can call named subagents when its configuration grants access to them. Delegation is optional: the root agent can also query APIs and use tools directly.

Define specialists

A subagent is authored under agents/<name>/ with an AGENT.md prompt and resource declarations in agent.json or agent.ts. It receives its own instructions and declared tools.

The parent calls specialists through call_subagent:

{
  "calls": [
    { "subagent": "ticket-reader", "task": "Read ticket T-100 and report its status." },
    { "subagent": "policy-reader", "task": "Find the refund policy for an annual plan." }
  ]
}

Both specialists must exist in the project and be available to the parent. A call accepts up to 12 entries and runs at most 5 concurrently. Nested dispatch beyond depth 5 is rejected.

See Agents & Subagents for configuration and resource grants.

Context isolation

Each specialist runs a separate conversation. Its intermediate messages and raw tool results stay in that conversation; its returned text becomes a tool result for the parent.

Pass the facts needed for the task in task or the optional input field. A specialist does not inherit the parent's full conversation or compiled prompt. It needs its own declared resources to load skills, read knowledge, or query connections.

There is no fixed summary length. If the parent needs a short result or a specific structure, state that in the specialist's instructions.

Permissions

Grant each specialist the resources it needs. Store writes require write access, and connection calls follow the applicable connection policy. Subagents do not have a connected user to answer an ordinary confirmation prompt.

Custom handlers must enforce permissions for their own side effects. Root-session guardrail hooks are not propagated into the headless subagent loop. See Guardrails and Hooks before delegating writes.

Background work

Scheduled and webhook-triggered runs are managed by the platform. They can run without an open chat client. Use Agent Workflows for work that must pause, resume, or coordinate durable steps.