> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Systems

> Orchestrators, sub-agents, delegation vs handoff, and drift detection.

DecimalAI supports multi-agent architectures where one agent delegates work to others.

## How Multi-Agent Tracing Works

```mermaid theme={null}
%%{init: {'theme':'base','themeVariables':{'primaryColor':'#f5f5f4','primaryBorderColor':'#a8a29e','primaryTextColor':'#44403c','lineColor':'#a8a29e'}}}%%
graph TD
    OT["Orchestrator Trace"] --> CT1["Sub-agent: search-agent"]
    OT --> CT2["Sub-agent: fact-checker"]
    OT --> CT3["Sub-agent: summarizer"]

    CT1 -.->|parent_trace_id| OT
    CT2 -.->|parent_trace_id| OT
    CT3 -.->|parent_trace_id| OT

    CT1 -->|status: success| P1["✅"]
    CT2 -->|status: error| P2["❌"]
    CT3 -->|status: success| P3["✅"]

    P2 -->|propagation| DEG["Orchestrator → degraded"]

    style OT fill:#44403c,stroke:#292524,color:#fafaf9
    style CT1 fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style CT2 fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
    style CT3 fill:#d6d3d1,stroke:#78716c,color:#1c1917
    style P1 fill:#dcfce7,stroke:#22c55e,color:#14532d
    style P2 fill:#fee2e2,stroke:#ef4444,color:#7f1d1d
    style P3 fill:#dcfce7,stroke:#22c55e,color:#14532d
    style DEG fill:#fef9c3,stroke:#eab308,color:#713f12
```

## Orchestrator

An **orchestrator** is an agent that delegates work to other agents. DecimalAI infers orchestrator status from two signals:

1. The manifest contains `component_type="subagent"` components
2. Other traces reference this agent's traces via `parent_trace_id`

There is no explicit "is\_orchestrator" flag — it's a derived role. An agent can be both a sub-agent of one orchestrator AND an orchestrator of other sub-agents (nested delegation).

## Sub-agent

A **sub-agent** is an agent that receives delegated work. Identified by a trace having `parent_trace_id` set, pointing to the orchestrator's trace.

## Delegation vs Handoff

These are two distinct multi-agent patterns:

|                  | Delegation                                                       | Handoff                                                         |
| ---------------- | ---------------------------------------------------------------- | --------------------------------------------------------------- |
| **Control flow** | Orchestrator calls sub-agent, gets result back, stays in control | Agent A transfers control to Agent B — A may not regain control |
| **Relationship** | Parent → child (hierarchical)                                    | Peer → peer (lateral)                                           |
| **Parent trace** | Sub-agent trace has `parent_trace_id` pointing to orchestrator   | Both traces share `session_id` but neither is "parent"          |
| **Frameworks**   | LangGraph subgraphs, Google ADK                                  | OpenAI Swarm, Agents SDK handoffs                               |

<Note>
  **Orchestrator vs Parent Trace:** These operate at different levels. An *orchestrator* is an agent (a role). A *parent trace* is a specific trace record that child traces link back to (a data relationship). An orchestrator agent produces many parent traces over time.
</Note>

## Status Propagation

When a sub-agent trace fails:

| Scenario                              | Parent Status                   |
| ------------------------------------- | ------------------------------- |
| Some children errored, some succeeded | `degraded` (partial failure)    |
| All children errored                  | `error` (escalated)             |
| A failing child retries and succeeds  | Auto-recovery back to `success` |

## Drift

**Drift** occurs when a sub-agent's actual configuration diverges from what the orchestrator's manifest expects. For example, the orchestrator's manifest references `search-agent v1.0` but recent traces show `search-agent` using different tools. The Sub-Agent Health Dashboard flags this.

## Next

<CardGroup cols={2}>
  <Card title="Skills & Data Pipeline" icon="database" href="/concepts/skills-and-data">
    How DecimalAI turns evaluated, compatible traces into training data.
  </Card>

  <Card title="Multi-Agent Guide" icon="network-wired" href="/guides/multi-agent">
    Hands-on guide to instrumenting multi-agent systems.
  </Card>
</CardGroup>