Multi-agent Patterns
Persistence and Testing
Persist, replay, and test multi-agent streaming runs.
Multi-agent streams are useful live, but production systems often need replay, support inspection, and regression coverage. Persist events when users may refresh, support teams need a run history, or child-agent progress is part of the product record.
Persist Events for Replay
Add an event store when nested progress must be replayed after the run, inspected in support tools, or attached to a product audit trail.
import { AgentBuilder, type AgentEventStore } from "@anvia/core";
import { supportAgent } from "./specialists";
import { model } from "./model";
declare const eventStore: AgentEventStore;
export const coordinatorWithEvents = new AgentBuilder("incident-coordinator", model)
.instructions("Delegate support triage, then produce a short final brief.")
.tool(supportAgent.asTool({ name: "ask_support_agent", stream: true }))
.eventStore(eventStore, { include: "all" })
.defaultMaxTurns(3)
.build();The final stream event includes runId. Use that id to load saved parent and child events from the event store.
Failure Modes
| Failure | Fix |
|---|---|
| child progress never appears | check parent .stream(), stream: true, and child model streaming support |
| nested events are hard to group | group by internalCallId, then label with agentName or toolName |
| coordinator calls too many specialists | tighten instructions, lower max turns, or reduce available specialist tools |
| tool results leak sensitive data | render safe status labels and persist sensitive details only in protected storage |
| parallel calls overload services | lower .withToolConcurrency(...) or add service-level limits |
| progress disappears after refresh | attach an event store and replay by runId |
Test Checklist
- Test specialist agents directly with representative prompts.
- Test coordinator tool registration includes
stream: truefor visible specialists. - Test stream handling for
agent_tool_event,tool_result,text_delta,final, anderror. - Test UI grouping when the same specialist is called more than once.
- Test event-store replay with saved parent and child events.
- Inspect a provider-backed run in Studio or traces before exposing nested progress to users.