Skip to main content

ToolCallStartedEvent

Section ID: DOC-API-EVENT-u22bdqd1kd#overview

Event for a tool call that has begun execution or is waiting for human approval. Check the event name and tool-call status to distinguish these cases; the event context identifies the conversation. Use this in a guide: Event catalog · Tool policy resolution and lifecycle

Payload​

Section ID: DOC-API-EVENT-u22bdqd1kd#payload

Payload fields: ToolCallStartedEvent.

Payload examples​

Section ID: DOC-API-EVENT-u22bdqd1kd#examples

These are illustrations of the selected payload Schema, not complete delivery envelopes. Transport metadata is supplied by the platform.

event-llm-tool-call-started​

Section ID: DOC-API-EVENT-u22bdqd1kd#example-event-llm-tool-call-started

Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.

API JSON uses JSON field names (camelCase).

{
  "toolCall": {
    "id": "call_123",
    "name": "send_briefing",
    "serverId": "briefing-tools",
    "argumentsJson": {
      "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
    },
    "status": "TOOL_EXECUTION_STATUS_EXECUTING"
  }
}

event-llm-tool-call-approval-required​

Section ID: DOC-API-EVENT-u22bdqd1kd#example-event-llm-tool-call-approval-required

Illustrative payload, not a captured delivery. Identifiers, tool names and outcomes are examples; omitted fields depend on the event.

API JSON uses JSON field names (camelCase).

{
  "toolCall": {
    "id": "call_123",
    "name": "send_briefing",
    "serverId": "briefing-tools",
    "argumentsJson": {
      "conversation_id": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
    },
    "status": "TOOL_EXECUTION_STATUS_REQUIRES_CONFIRMATION",
    "requiresApprovalAt": "2026-09-16T12:05:00Z"
  }
}

Notes​

Section ID: DOC-API-EVENT-u22bdqd1kd#notes

In the live view, this event replaces the current tool activity view for the conversation. The payload can represent execution starting or a request for human approval; use the event name and tool-call status to distinguish these cases.

Event-specific delivery guarantees, ordering, retention and lifecycle status are unspecified.

Audiences​

Section ID: DOC-API-EVENT-u22bdqd1kd#audiences

  • Audience: Live view Current conversation client projection.

  • Audience: Tenant webhook Sent to subscribed tenant webhook endpoints.

Delivery and lifecycle​

Section ID: DOC-API-EVENT-u22bdqd1kd#declared-intent

  • Live write intent: Replace

Live destination meaning​

Section ID: DOC-API-EVENT-u22bdqd1kd#live-destination-meaning

Current tool activity view for the conversation.

Document ID: DOC-API-EVENT-u22bdqd1kd