Tool Calls

When an agent invokes multiple tools (database queries, external APIs) before producing its answer, the SDK automatically groups consecutive tool-call messages into a Tool Call Group. Each entry can be expanded to inspect its parameter and result.

Switch between scenarios below to see the pending, completed, and error states.

Tool Call States

Agents often call multiple tools before answering. The SDK groups consecutive tool calls together and lets users expand each one to inspect its parameters and result. Use renderToolCallGroup to hide or customize the display.

Usage Examples

// No prop needed — uses built-in UI
<Chatbot
  config={{ botProviderEndpoint: '...' }}
  customChannelId="my-channel"
/>

Loading chatbot...

Message Shape

Tool calls are not a template — they are a standalone ConversationMessage type:

type ConversationToolCallMessage = {
  type: "tool-call";
  messageId: string; // `${processId}-${callSeq}`
  eventType: EventType.TOOL_CALL_START | EventType.TOOL_CALL_COMPLETE;
  processId: string;
  callSeq: number;
  toolName: string;
  reason?: string; // backend-provided call reason; the tool-call group label and consent modal title prefer reason || toolName
  toolsetName: string;
  parameter: Record<string, unknown>;
  result?: Record<string, unknown>;
  isError?: boolean; // backend-reported failure flag (0.3.x / F-009); undefined until complete
  toolUseId?: string; // this call's correlation id; an Agent tool's toolUseId becomes a subagent key (F-012)
  parentToolUseId?: string; // non-empty means this call belongs to a subagent (F-012)
  isComplete: boolean;
  time: Date;
  traceId?: string;
};

In real usage these messages are written into the Conversation automatically when EventType.TOOL_CALL_START / EventType.TOOL_CALL_COMPLETE events arrive — you never have to construct them by hand.

State Detection

State	Condition
pending	isComplete === false
completed	isComplete === true && !(isError || result?.error)
error	isComplete === true && (isError || result?.error)

Since 0.3.x, backend isError is the primary driver

Failure detection now relies on the backend-reported isError flag (F-009); result.error is kept only as a legacy fallback.

Built-in Tool Presentation (labels, icons, diff)

Since 0.3.x, the Tool Call Group synthesizes human-readable labels for built-in tools and pairs each with an identity icon (variant):

Tool	Example label
Read / Write / Edit	Read {file} / Wrote {file} / Edited {file}
Skill	Ran skill {skill}
WebFetch / WebSearch	Fetched {host} / Searched "{query}"

• Write / Edit also render a +/- line diff when expanded (the items[].diff field, F-007).
• Labels, the group summary ({n} steps · …), and the expanded Initial / Result titles all follow the locale prop (en-US / ja-JP / zh-TW, F-004 / F-005 / F-008):

<Chatbot locale="en-US" config={{ botProviderEndpoint: '...' }} customChannelId="my-channel" />

Further Reading

For the SSE event specs behind tool calls, see the Asgard developer docs:

• asgard.tool_call.start event
• asgard.tool_call.complete event