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.

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}`
  processId: string;
  callSeq: number;
  toolName: string;
  toolsetName: string;
  parameter: Record<string, unknown>;
  result?: Record<string, unknown>;
  isComplete: boolean;
  time: Date;
};

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 && !result?.error
error	isComplete === true && result?.error