Multi-Agent Systems

When one agent passes work to another, DecimalAI records it in one of two shapes. Which one you have decides what you can see and train per sub-agent.

How It Works

	Handoff	Delegation
Control	Agent A passes the run to agent B, and may not get it back	The orchestrator starts B as its own run and gets a result back
Traces	One trace, filed under the agent that started the run	One trace per agent. Each child’s `parent_trace_id` points at the orchestrator’s trace
Comes from	OpenAI Agents SDK `handoffs=[...]`, Google ADK `sub_agents`	A run given a `parent_trace_id`, or started inside `decimalai.start_trace()`

An orchestrator is a role, not a setting: any agent whose manifest lists sub-agents, or whose traces have children. One agent can be both an orchestrator and another’s sub-agent.

Setup

Handoffs (OpenAI Agents SDK)
Child traces
Declare sub-agents

from agents import Agent

import decimalai
from decimalai.openai_agents import instrument

flight_agent = Agent(name="flight_agent", instructions="You search for flights.")
hotel_agent = Agent(name="hotel_agent", instructions="You search for hotels.")

orchestrator = Agent(
    name="travel-planner",
    instructions="You coordinate travel planning.",
    handoffs=[flight_agent, hotel_agent],
)

decimalai.init(api_key="dai_sk_...")
instrument(agent=orchestrator)

instrument() reads agent.handoffs and lists each target as a sub-agent in the orchestrator’s manifest.

import decimalai

decimalai.init(api_key="dai_sk_...")

with decimalai.start_trace(
    agent_name="travel-planner",
    subagents=[{"name": "flight_agent"}],
) as parent:
    parent.set_input("Plan a trip to Tokyo")

    with decimalai.start_trace(
        agent_name="flight_agent",
        parent_trace_id=parent.get_trace_id(),
    ) as child:
        child.set_input("Find flights from SFO to NRT")
        child.log_llm_call(
            model="gpt-4o",
            input=[{"role": "user", "content": "Find flights from SFO to NRT"}],
            output={"content": "Found 3 flights."},
        )
        child.set_output("Found 3 flights.")

    parent.set_output("Here is your trip.")

subagents= lists the child in the orchestrator’s manifest. parent_trace_id= links this run to it. The order they arrive in doesn’t matter.

For a framework DecimalAI can’t read sub-agents from, name them yourself:

import decimalai

decimalai.init(api_key="dai_sk_...")

decimalai.register_manifest(
    agent_name="travel-planner",
    prompts={"system": "You coordinate travel planning."},
    models={"default": {"provider": "openai", "model": "gpt-4o"}},
    subagents=[
        {"name": "flight_agent"},
        {"name": "hotel_agent"},
    ],
)

What Gets Captured

	OpenAI Agents SDK handoff	ADK `sub_agents` in one run	Child trace
Traces	One	One	One per agent
Sub-agent’s LLM calls are filed under	The root agent	The agent that made the call	The child agent
On the Agents page and topology graph	Only if it also runs on its own	Yes	Yes
Sub-Agent Health	Listed, with 0 traces	Listed, with 0 traces	Full numbers
Delegation Patterns	Not counted	Not counted	Counted
Status and scores roll up to the parent	No	No	Yes
Its own dataset	No: a build finds 0 rows	Yes	Yes

On OpenAI Agents SDK handoffs, every LLM call carries the root agent’s name. The sub-agent’s name is on its agent span and in a handoff:travel-planner->flight_agent span (type other), which show on the run’s timeline. It has no calls of its own to count or train on. For per-sub-agent numbers or training data, run it as a child trace instead.

Each framework reads sub-agents and links child runs its own way:

Framework	Sub-agents come from	A child run links through
OpenAI Agents SDK	`agent.handoffs`, read by `instrument(agent=...)` and from agent spans	`set_parent_trace(id)` in `decimalai.openai_agents`
Google ADK	`agent.sub_agents`	`DecimalAIPlugin(parent_trace_id=...)`, or running inside `start_trace()`
LangChain	`CallbackHandler(subagents=[...])`	`CallbackHandler(parent_trace_id=...)`, or running inside `start_trace()`
Claude Agent SDK	`agents` in `ClaudeAgentOptions`	`trace_stream(..., parent_trace_id=...)`
CrewAI, OpenAI, Anthropic, Gemini, Pydantic AI	`register_manifest(subagents=[...])`	Running inside `start_trace()`
Your own code	`start_trace(subagents=[...])` or `register_manifest(subagents=[...])`	`start_trace(parent_trace_id=...)`, `@decimalai.trace(parent_trace_id=...)`

On LangChain, an LLM call takes the name of its nearest enclosing chain run.

Dashboard

Agents Page

The Agents page lists sub-agents under their orchestrator, behind Show N sub-agents. An agent is listed there when the orchestrator’s active manifest names it and it has traces or LLM calls of its own.

Topology Graph

An agent’s More menu has Structure, with three panels. Each hides when it has nothing to show.

Panel	What it shows	What it reads
Multi-Agent Topology	The orchestrator and its sub-agents, with call or trace counts and drift	The active manifest’s sub-agents, leaving out any with no traces or calls
Sub-Agent Health	Traces, errors, average latency and drift per sub-agent, over 7, 14 or 30 days. At least 90% success reads as healthy	The manifest’s sub-agents, plus any agent with child traces
Delegation Patterns	How often each sub-agent runs, sub-agents per run, error rate and runs per day	Child traces only

The graph comes from the manifest, not from handoff spans, and hides when no listed sub-agent has traces or calls of its own.

Status and Score Roll-Up

A child trace’s result reaches its parent:

Children	Parent status
Some are `error`	`degraded`
All are `error`	`error`
None is `error` any more	A `degraded` parent returns to `success`

A parent’s eval_score blends its own score (weight 1) with each child’s (weight 0.5), and only ever goes down. A failing child turns a parent’s pass into review.

Per-Sub-Agent Datasets

Build a dataset with the sub-agent as its target, and only that agent’s LLM calls go in, even calls inside another agent’s trace:

curl -X POST https://api.decimal.ai/api/v1/datasets \
  -H "Authorization: Bearer $DECIMAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "flight-agent-sft", "training_target_agent": "flight_agent", "dataset_type": "sft"}'

Then POST /api/v1/datasets/{id}/build with an empty body. Datasets has the dashboard steps and every filter. For child traces, /api/v1/multi-agent-training/{orchestrator} has three more routes: GET /fault-attribution ranks the sub-agents that failed in the runs where the orchestrator failed, GET /subagent-dataset/{subagent} previews a sub-agent’s rows, and POST /launch starts one training job per sub-agent.

Handoff Markers

A row can hold calls from more than one agent when a build has no single agent to filter to: a trace_ids build, or a dataset with no target agent. Then each change of agent adds a marker, and each assistant message names its agent:

{"messages": [
  {"role": "system", "content": "You coordinate travel planning."},
  {"role": "user", "content": "Plan a trip to Tokyo"},
  {"role": "assistant", "content": "Searching flights first.", "name": "travel-planner"},
  {"role": "system", "content": "[HANDOFF: flight_agent]"},
  {"role": "assistant", "content": "Found 3 flights.", "name": "flight_agent"}
]}

OpenAI Agents SDK handoffs never produce these, because all their calls share one name.

Version Drift Detection

Each agent with its own manifest has its own version timeline. The orchestrator’s manifest lists sub-agents by name, so a change inside flight_agent registers a new flight_agent version and leaves the orchestrator’s manifest alone. Adding or removing a sub-agent registers a new orchestrator version. If you declare a version on a sub-agent, a major bump counts as an incompatible change for the orchestrator, and a smaller one as repairable. Manifests covers what those verdicts do. The Structure panels show one of these for each sub-agent:

Status	Meaning
Untracked (? None in the health table)	It has no manifest of its own
Current	It has a manifest, and nothing contradicts it
Drifted	The orchestrator’s manifest pins a `manifest_ref`, and the sub-agent’s active manifest is a different one

The SDK doesn’t set manifest_ref, so Drifted appears only for a manifest you post to POST /api/v1/manifests with one.

Best Practices

Choose child traces if you want per-sub-agent data. Handoffs put the whole run on one timeline, but give no numbers or datasets per sub-agent.
Declare sub-agents in the manifest. The topology graph and the Agents page read the manifest, not the traces.
Build one dataset per sub-agent, fine-tuned on its own calls.

Start here

Tutorial: a support agent

Use skills

Manage and measure

Publish a skill

More

Multi-Agent Systems

How It Works

Setup

What Gets Captured

Dashboard

Agents Page

Topology Graph

Status and Score Roll-Up

Per-Sub-Agent Datasets

Handoff Markers

Version Drift Detection

Best Practices

Next Steps

Read a run

Datasets

​How It Works

​Setup

​What Gets Captured

​Dashboard

​Agents Page

​Topology Graph

​Status and Score Roll-Up

​Per-Sub-Agent Datasets

​Handoff Markers

​Version Drift Detection

​Best Practices

​Next Steps

Read a run

Datasets

How It Works

Setup

What Gets Captured

Dashboard

Agents Page

Topology Graph

Status and Score Roll-Up

Per-Sub-Agent Datasets

Handoff Markers

Version Drift Detection

Best Practices

Next Steps