Skip to main content

Tool policy resolution and lifecycle

Section ID: Guide/jepgcbs2rq#overview

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​

Section ID: Guide/jepgcbs2rq#using-tools-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​

Section ID: Guide/jepgcbs2rq#using-tools-knowing-a-call-is-waiting

When your integration observes the declared tool-call-started lifecycle, inspect the embedded ToolCall. It can represent begun execution or a wait for human approval. Use isClientTool to identify client execution, match the tool name against the client tools you declared, and enforce clientToolDeadlineAt when submitting a client result.

For approval waits, inspect status and requiresApprovalAt and reconcile pending approvals before dispatching an action. This deadline is not the time the call started waiting. No separate approval-required Event is declared by the selected catalog.

Poll the pending-client-tools operation to reconcile work on reconnect or when no event observation is available. Choose an interval within your client tool timeout; zero or omission selects the five-minute default answer window. A ten-minute polling interval can miss that entire wait. A result submitted after its deadline is rejected. Read the deadline and pending state before retrying.

Run status and model finish reason​

Section ID: Guide/jepgcbs2rq#using-tools-two-rules-for-clients

  • 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​

Section ID: Guide/jepgcbs2rq#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.

Document ID: Guide/jepgcbs2rq