1.10 Multi-Agent Delegation, Handoff & Budget Assertions

How to assert which agent delegates to which, what context actually crosses a handoff, and how to cap hops, tool calls, or wall-clock time per agent.

Why “It Called the Right Tool” Is Not Enough for a Swarm

Multi-Agent DAG & OTel Tracing (1.6) already reconstructs the delegation graph and lets ASSERT_AGENT_TOPOLOGY check overall hop depth and cycle-freedom. Once a swarm has more than one hand-off, three more specific questions come up: did agent A actually delegate to agent B (not some other agent that happened to run), what did B receive when A handed off, and did any one agent blow through a hop/tool-call/latency budget on its own? These three step actions answer those questions directly instead of requiring you to eyeball the DAG.

Action	Answers	Key Parameters
EXPECT_DELEGATION_TO	Did agent A delegate to agent B at least once (and no more than a cap, if set)?	agentName (the delegated-to agent), minInvocations (default 1), maxInvocations, optional fromAgent to require a specific delegating parent
EXPECT_HANDOFF_CONTEXT	What did B actually receive when A handed off – not just that a handoff happened?	fromAgent, toAgent, and a judge rubric (rubricType + inlineRubric or judgeRubricId) graded against the receiving span’s captured input content
EXPECT_AGENT_BUDGET	Did one agent’s own subtree (its turn plus every tool/LLM call under it) exceed a token, duration, or tool-call ceiling?	agentName, and one or more of maxTokens, maxDurationMs, maxToolCalls

All three read the delegation DAG built by the most recently run ASSERT_AGENT_TOPOLOGY step in the same case – they don’t build their own, so a case using any of them needs an ASSERT_AGENT_TOPOLOGY step earlier in its steps list.

- action: ASSERT_AGENT_TOPOLOGY
  source: FILE
  otelSpansFile: ./traces/refund-swarm.json

- action: EXPECT_DELEGATION_TO
  agentName: refund_specialist
  minInvocations: 1
  fromAgent: orchestrator        # optional: also require this specific parent

- action: EXPECT_HANDOFF_CONTEXT
  fromAgent: orchestrator
  toAgent: refund_specialist
  rubricType: GROUNDEDNESS
  inlineRubric: >
    The handoff payload must include the order id and the customer's stated reason,
    and must not include the customer's payment details.

- action: EXPECT_AGENT_BUDGET
  agentName: refund_specialist
  maxTokens: 8000
  maxDurationMs: 15000
  maxToolCalls: 6

Live Spans, Not Just Exported Files

ASSERT_AGENT_TOPOLOGY (and, through it, the three actions above) can read from a pre-exported OTel spans file (source: FILE, the original behavior) or from spans captured live during the run itself (source: LIVE) via the run’s embedded OTLP/HTTP receiver – the same one –otel-live starts for topology assertions (see 1.6). LIVE means you don’t need a separate trace-analyze pass before these assertions can run; FILE is still there for a spans export you already have from a previous run or another tool.

All three actions need a preceding ASSERT_AGENT_TOPOLOGY step in the same case – they read its most recently built DAG rather than fetching spans themselves.
EXPECT_HANDOFF_CONTEXT is judge-graded, not a deterministic matcher – it reads the receiving span’s content through a fallback chain of attribute keys (gen_ai.prompt and four others, since no single GenAI exporter convention has won) and, if none are present, fails with a message naming the likely cause – content capture disabled on the exporter – rather than a rubric verdict, so you don’t go hunting a prompt bug that’s actually an exporter config gap.
EXPECT_AGENT_BUDGET sums the named agent’s whole subtree (every node reachable from it in the DAG, including tool and LLM-call children) – it’s a per-agent-and-its-work ceiling, not a per-case one, so a case that fans out to five agents each safely under budget can still fail if a sixth, unrelated agent in the same DAG spikes.