---
title: "Instrument multi-agent systems"
description: "Record delegation between a parent agent and child agents with the AI SDK, so every agent's events stay in one Agent Analytics session with the root agent and chain depth."
product: general
lang: en
last_updated: 2026-10-15
token_estimate: 796
---
# Instrument multi-agent systems

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

In a multi-agent system, a parent agent delegates work to child agents. Create child agents from the parent with the AI SDK and Agent Analytics records the delegation: child agents carry `[Agent] Parent Agent ID`, sessions record the root agent and chain depth, and provider wrappers suppress spurious user-message events inside delegated calls. The AI SDK sets `[Agent] Message Source` to `agent` on a delegated user message unless you set the source yourself. Every agent's events stay under one `[Agent] Session ID`.

Give every agent a stable, human-readable ID. Those IDs become the primary dimension for comparing quality and cost across your system.

## Declare and dispatch child agents

Declare children off the parent with `.child()`, then dispatch to them with `runAs()` (Node) or `arun_as()` (Python):

#### Node

```typescript
const orchestrator = ai.agent('shopping-agent', { description: 'Orchestrates shopping requests' });
const recipeAgent = orchestrator.child('recipe-agent', { description: 'Finds recipes' });

await orchestrator.session({ userId }).run(async (s) => {
  s.trackUserMessage(userInput);
  const result = await s.runAs(recipeAgent, async (cs) => {
    cs.trackUserMessage(delegatedQuery);
    return openai.chat.completions.create({ model: 'gpt-4o', messages: [...] });
  });
});
```

#### Python

```python
orchestrator = ai.agent("shopping-agent", description="Orchestrates shopping requests")
recipe_agent = orchestrator.child("recipe-agent", description="Finds recipes")

async with orchestrator.session(user_id=user_id) as s:
    s.track_user_message(user_input)
    async with s.arun_as(recipe_agent) as cs:
        cs.track_user_message(delegated_query)
        result = client.chat.completions.create(model="gpt-4o", messages=[...])
```

For the full delegation semantics (context inheritance, span wrapping, nested children, fan-out), refer to [Multi-agent architectures](https://amplitude.com/docs/sdks/agent-analytics/sdk#multi-agent-architectures) in the SDK reference.

## Analyze multi-agent sessions

Each `[Agent] Session Record` carries `[Agent] Root Agent Name` and `[Agent] Agent Chain Depth`. Depth is the number of agents on the longest delegation path: 1 is a single agent, 2 is one hop, and 3 or more is deeper nesting. When a parent fans out to several children, depth follows the deepest branch. Filter Session Records where chain depth is greater than 1 to find multi-agent sessions. Depth 2 means exactly one hop. Group any chart by `[Agent] Agent ID` to compare agents. Refer to [Data hierarchy](https://amplitude.com/docs/amplitude-ai/agent-analytics/taxonomy#data-hierarchy).

A span's parent span isn't the parent agent. On OpenTelemetry, set the span attribute `amplitude.parent.agent.id`. Across processes, propagate `x-amplitude-parent-agent-id` next to the existing agent-id header. A LangSmith forwarder stamps one configured agent: nested LangSmith runs stay tool calls or spans and don't become child agents.