Instrument multi-agent systems

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 the parent reference, sessions record the root agent and chain depth, and provider wrappers suppress spurious user-message events inside delegated calls. 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):

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: [...] });
  });
});

For the full delegation semantics (context inheritance, span wrapping, nested children, fan-out), refer to Multi-agent architectures in the SDK reference.

Analyze multi-agent sessions

Each [Agent] Session Record carries [Agent] Root Agent Name (the agent that started the session) and [Agent] Agent Chain Depth (how deep the delegation went). To compare agents, group any chart by [Agent] Agent ID. To analyze multi-agent sessions, filter Session Records where chain depth is greater than 1. Refer to Data hierarchy.