Approvals and client tools
Pause a run until a person approves a tool call, or hand a tool call to your own application to execute and answer.
Two features pause a run until something outside the agent responds. An approval holds a tool call until a person approves or rejects it. A client tool hands the tool call to the application that submitted the run, which executes it and sends the result back. Use approvals for actions that need a human decision. Use client tools for actions that only your application can perform, such as reading device state or showing a confirmation screen.
Both put the run in a waiting status, and you resume it through the runtime API.
Approvals
When a run asks for approval
A tool call needs approval when the tool policy that applies to it, or the tool's default policy action, resolves to require_approval. When the model makes such a call:
- The run moves to
waiting-for-approval. - The tool call moves to
waiting, withpolicyAction: "require-approval". - The platform creates an approval with status
pendingand emits anapproval.requestedevent on the thread stream.
The approval's request describes the call with toolName, effect, inputSummary, and requiredScopes. The approval also carries runId, toolCallId, and an optional expiresAt. For a customer run it names the deployment in requestedByAgentDeploymentId. For a preview run it names the execution binding in executionBindingId.
Resolve an approval
POST /v1/runs/{runId}/approvals/{approvalId}/resolve takes decision (approved or rejected) and the run's threadId. The CLI sends the decision for you with approval approve and approval reject.
| Decision | Approval status | Tool call | Run |
|---|---|---|---|
approved | approved | Returns to pending and executes | Returns to queued and resumes |
rejected | rejected | failed with "Tool approval was rejected." | failed |
Any decision after expiresAt passed | expired | failed with "Tool approval expired." | failed |
Resolving is safe to repeat. Sending the recorded decision again returns the same result. Sending the other decision fails with 409 approval_already_resolved.
Canceling a run that waits for approval also resolves the approval. The approval becomes rejected, the tool call fails, and the run becomes canceled.
| Error | Status | Cause |
|---|---|---|
approval_not_found, run_not_found, tool_call_not_found | 404 | The approval, run, or tool call does not exist in your scope. |
approval_already_resolved | 409 | The approval already has a different decision. |
run_not_waiting_for_approval, tool_call_not_waiting_for_approval | 409 | The run or tool call is no longer waiting for this approval. |
evaluation_approval_unsupported | 409 | Evaluation runs reject approval-gated tool calls instead of waiting. |
execution_binding_expired | 409 | The preview that owns the run has expired, so the run cannot resume. |
thread_publication_pending | 409 | The thread still has run activity that the platform has not finished publishing. |
GET /v1/approvals lists approvals in the environment, and the status filter accepts pending, approved, rejected, or expired. Reading approvals needs the approvals:read scope, and resolving needs approvals:write.
Audit callback dispatches
When an HTTP callback tool dispatches, the platform stores callback dispatch evidence under the tool call's ID. The evidence records the policy decision (allow or require-approval), the approval that allowed the call with who resolved it, a hash of the input, and the release and deployment that made the call. Read it with GET /v1/callback-dispatch-evidence/{evidenceId}, using the tool call ID as evidenceId. The route needs approvals:read.
Client tools
Register a client tool
A client tool is an extension tool whose execution.type is client. The worker never calls it. Instead, the platform hands the call to your application.
| Field | Rules |
|---|---|
execution.type | client. |
execution.timeoutMs | How long your application has to answer, from 1,000 to 3,600,000 milliseconds. Default 900,000 (15 minutes). |
inputSchema | Required JSON schema with type: "object". The worker validates the model's input against it before pausing. |
outputSchema | Optional JSON schema that a completed result must satisfy. |
effect, defaultPolicyAction, requiredScopes | The same as for other extension tools. |
To use the tool, declare it in the manifest's spec.capabilities.tools and list it in spec.runtime.modelTools. A client tool needs a caller that can answer, so the manifest must restrict spec.triggers to ["api"]. Otherwise publishing, deploying, retargeting, starting a canary, and promoting all fail with client_tool_on_autonomous_trigger. See Tool capabilities.
Availability
Client tools work only in runs with an interactive caller. In a workflow, a client tool call fails at once, and evaluation runs deny client tool calls instead of pausing.
Answer a client tool call
- Submit a run as usual. See Threads and runs.
- When the model calls the client tool, the run moves to
waiting-for-tool. The tool call hasexecutionType: "client",status: "running", the model'sinput, anexpiresAtdeadline, and the tool'soutputSchemawhen it has one. - Find the call. The thread stream emits a
tool.runningevent whosepayload.clientToolcarriesinput,expiresAt, andoutputSchema. You can also pollGET /v1/runs/{runId}/tool-callsand select calls withexecutionType: "client"andstatus: "running". - Execute the tool in your application.
- Send the result with
POST /v1/runs/{runId}/tool-calls/{toolCallId}/results.
The result body has these fields:
| Field | Rules |
|---|---|
threadId | Required. The run's thread. |
outcome | Required. completed or failed. |
output | Required when outcome is completed. A JSON object of at most 96 KiB that matches outputSchema. |
outputSummary | Optional text the model sees, at most 1,000 characters. Use it to explain a failure. |
externalOperationId | Optional for client tools. It defaults to the tool call ID. |
Both outcomes resume the run. With failed, the model sees the failure and can try another approach.
If no result arrives by expiresAt, the platform fails the tool call with "Client tool did not return a result before it expired." and resumes the run. A completed result that arrives after expiresAt fails with 409 tool_call_expired, or with 409 tool_call_already_resolved once the platform has failed the call.
Sending the same result twice is safe and returns the recorded result. A different result for a call that already has one fails with 409 tool_call_already_resolved.
| Error | Status | Cause |
|---|---|---|
invalid_tool_output | 400 | output is missing for a completed call, is not an object, exceeds 96 KiB, or does not match outputSchema. |
invalid_tool_output_schema | 400 | The tool's outputSchema cannot be compiled. |
external_operation_mismatch | 409 | externalOperationId does not match the call. |
run_not_waiting_for_tool | 409 | The run is no longer waiting for this call. |
tool_call_expired | 409 | The deadline passed before the result arrived. |
tool_call_already_resolved | 409 | The call already has a different result. |
Listing tool calls needs runs:read, and sending a result needs runs:write.
Use it
-
Register a client tool. The example gives the application two minutes to answer.
deployments extension create --name weather.lookup --description "Look up the current weather on the user's device." --effect read --execution '{"type":"client","timeoutMs":120000}' --input-schema '{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}' --scopes '[]' --default-action allow -
Add
weather.lookupto the manifest's tools andmodelTools, setspec.triggersto["api"], then publish and deploy. Submit a run and wait for the tool call.deployments tool-call list --run $RUN_ID -
Answer the call with the tool's output.
deployments tool-call result $TOOL_CALL_ID --run $RUN_ID --thread $THREAD_ID --outcome completed --output '{"temperatureC":18}' -
For tools behind a
require_approvalpolicy, list pending approvals and decide.deployments approval list --status pending deployments approval approve $APPROVAL_ID --run $RUN_ID --thread $THREAD_ID deployments approval reject $APPROVAL_ID --run $RUN_ID --thread $THREAD_ID -
Check what authorized an HTTP callback dispatch.
deployments callback-evidence show $TOOL_CALL_ID
A client loop through the SDK reads the pending calls of a run and answers each one:
import {
createClient,
createConfig,
listRunToolCalls,
resolveToolResult,
} from "@deployments-ai/sdk";
const client = createClient(
createConfig({
baseUrl: "https://api.example.com",
headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
}),
);
const runId = process.env.RUN_ID!;
const threadId = process.env.THREAD_ID!;
async function runClientTool(name: string, input: Record<string, unknown>) {
if (name === "weather.lookup") return { temperatureC: 18, city: String(input.city) };
throw new Error(`Unknown client tool ${name}`);
}
const { data } = await listRunToolCalls({ client, path: { runId } });
const pending = (data?.toolCalls ?? []).filter(
(call) => call.executionType === "client" && call.status === "running",
);
for (const call of pending) {
try {
const output = await runClientTool(call.toolName, call.input ?? {});
await resolveToolResult({
client,
path: { runId, toolCallId: call.id },
body: { threadId, outcome: "completed", output },
});
} catch (cause) {
await resolveToolResult({
client,
path: { runId, toolCallId: call.id },
body: { threadId, outcome: "failed", outputSummary: String(cause).slice(0, 1000).trim() },
});
}
}