Multi-agent Patterns
Consume Nested Events
Group parent and child stream events from streaming agent tools.
When a coordinator runs with .stream(), normal parent events and nested child-agent events arrive in the same stream. Render coordinator text directly and group child progress by internalCallId.
Render Parent and Child Events
import type { AgentStreamEvent } from "@anvia/core";
function renderEvent(event: AgentStreamEvent): void {
switch (event.type) {
case "text_delta":
renderCoordinatorText(event.delta);
break;
case "tool_call":
renderDelegation(event.toolCall.function.name);
break;
case "agent_tool_event":
renderSpecialistEvent({
groupId: event.internalCallId,
agentLabel: event.agentName ?? event.agentId,
toolName: event.toolName,
event: event.event,
});
break;
case "final":
saveFinalResponse(event);
break;
case "error":
renderStreamError(event.error);
break;
}
}Group nested progress by internalCallId when the same specialist can be called more than once. Use agentId, agentName, and toolName for labels.
Render Specialist Progress
import type { AgentStreamEvent } from "@anvia/core";
type SpecialistEvent = Extract<AgentStreamEvent, { type: "agent_tool_event" }>;
function renderSpecialistEvent(input: {
groupId: string;
agentLabel: string;
toolName: string;
event: SpecialistEvent["event"];
}) {
if (input.event.type === "text_delta") {
appendSpecialistText(input.groupId, input.agentLabel, input.event.delta);
}
if (input.event.type === "tool_call") {
showSpecialistToolCall(input.groupId, input.event.toolCall.function.name);
}
if (input.event.type === "tool_result") {
markSpecialistToolDone(input.groupId, input.event.toolName);
}
if (input.event.type === "final") {
markSpecialistComplete(input.groupId, input.event.output);
}
}Do not render raw tool results, sensitive retrieved context, or internal reasoning in a user-facing UI unless the product intentionally exposes those details. Prefer status labels and safe summaries for customer-facing screens.
Event Mapping
| Event | UI use |
|---|---|
tool_call | coordinator is delegating to a specialist |
agent_tool_event.text_delta | specialist is streaming visible progress |
agent_tool_event.tool_call | specialist is using one of its tools |
agent_tool_event.tool_result | specialist tool completed |
agent_tool_event.final | specialist returned final output to the coordinator |
tool_result | coordinator received the specialist's final output |
text_delta | coordinator is streaming the final answer |
final | persist final messages, usage, trace, and run id |