Skip to main content

Tool policy resolution and lifecycle

The effective generation configuration selects the tool policy. Read approval and call limits, run timeouts and current stop-rule limitations on their models; this page explains precedence and how clients observe the resulting work.

Tool execution policy​

toolPolicy (a ToolExecutionPolicy object) on GenerationConfig configures approval, waiting and supported tool-call limits during a generation run. Retry, ordering, per-loop cap and stop-on-failure settings are accepted and stored but are not currently enforced; see the tool policy model for the boundary of each control. Because it lives on the generation config, the same field works as a per-request override, on an agent profile, or as the conversation default — resolved most-specific-first, see Which policy applies.

ConversationSettings.toolPolicy is the deprecated predecessor. It still works as the final fallback, but it is thread-only and cannot be set on a profile or an override.

Observing client-tool waits​

Subscribe to llm.tool_call_started. It fires the moment a call is dispatched, including client-side ones. Two things to know: the payload does not flag which calls are yours, so match on the tool names you declared in clientTools; and it does not carry the deadline, so read that from list-pending-client-tools. Read the tool-call-started payload. An approval wait is reported separately by tool-call-approval-required; inspect the pending approval before dispatching an action.

Or poll list-pending-client-tools. Simpler, needs no endpoint to receive webhooks, and it is the same call you would make on reconnect. Pick an interval well inside your clientToolTimeoutMs — the default answer window is five minutes, so a ten-minute poll interval can miss the entire wait. A result submitted after the call’s deadline is rejected.

Run status and model finish reason​

  • Treat unknown status values as an unknown outcome. COMPLETED, FAILED, CANCELLED and TIMED_OUT, with the AGENT_STATUS_ prefix, are recognized terminal run outcomes. Run status has no SUCCESS alias; that legacy alias belongs only to tool execution status. An unknown value means the outcome is not understood; reconcile it rather than declaring success, failure or indefinite activity.
  • Read finishReason on the assistant message if you want to know why the model stopped. It is an open string that preserves provider values; examples include stop, tool_calls, length, content_filter and error, and historical messages can leave it empty. Preserve unfamiliar values instead of treating this illustrative list as a closed enum. It answers a different question from status — status is what the run is doing, finishReason is why the model stopped talking.

Policy precedence​

Put new rules on the generation configuration that owns the task. A per-turn overrideGenerationConfig.toolPolicy takes precedence, followed by the active profile's policy, the conversation's defaultGenerationConfig.toolPolicy, and finally the deprecated conversationSettings.toolPolicy fallback.

An explicitly empty policy selects no rules and stops that fallback. When testing a sensitive action, inspect the effective configuration for the actual agent and turn; a rule saved on the thread does not prove that a more specific policy requires approval.