Put human approval between agents and risky tool calls

An agent that can suggest an action is different from an agent that can perform it. Sending an email, changing an account, or calling a production service moves beyond generated text into an external effect.

Human approval is useful at that boundary—but only if the action actually passes through a control that can hold it. A prompt saying “ask first” is not the same as an enforced authorization decision.

This guide uses a fictional support-email workflow. The example is a design exercise, not evidence from a customer deployment.

Put the boundary in the integration

Suppose a support agent drafts a reply and wants to send it. Keep drafting separate from sending. Route the supported send action through the Robots Center gateway and give the agent a scoped credential rather than an unrestricted credential to the external system.

The gateway evaluates actions that reach it. It does not intercept arbitrary network calls or remove credentials your runtime already possesses. If the agent can also send mail through a separate, unrestricted path, the approval boundary is incomplete.

Write down three things before configuring policies:

1. The connector and action that create the external effect.
2. The agent identity allowed to request that action.
3. The conditions under which an operator must review it.

The gateway reference describes the machine-facing authorization and tool-action endpoints. The governance overview explains how credentials, grants, policies, and audit records fit together.

Separate permission from review

A permission grant and an approval policy solve different problems. A grant defines access to a connector action. A policy determines when the requested action requires review. A denied action should not be treated as a request that the client may simply retry until somebody approves it.

Workspace administrators configure access and approval policies in the gateway consoles. Choose explicit action patterns and appropriate reviewer roles. Where the policy uses environment, amount, or risk inputs, verify what your integration actually submits; conditions cannot protect information the request never supplies correctly.

For the support workflow, begin with a narrow send action and a test destination. Avoid enabling a broad set of production actions just to make a first demonstration easier.

Test the decision without executing the action

Use the policy simulator before connecting the live workflow. It reports the authorization decision and an explanation without executing the connector.

Try cases that would reveal a mistake, not just the example you expect to pass:

• The intended agent requests the intended action.
• A different agent requests the same action.
• The request comes from a different environment.
• A relevant condition is absent or outside its allowed range.
• A scoped freeze is active.

An owner or administrator can use the simulator console or its operator endpoint. Follow the policy simulator guide for accepted fields and access requirements. A successful simulation is evidence about that submitted request—not a guarantee about every future payload.

Treat “pending” as a real state

An action that needs approval must stop at the boundary. When POST /api/v1/tool_actions requires review, it returns HTTP 202 with status: "pending_approval", an approval_request_id, and a status_url. Keep that response and pause the workflow; HTTP 202 is not proof that the external action succeeded.

The returned status URL supports read-only polling with the requesting machine credential and gateway:execute scope. Respect Retry-After while waiting. Polling does not approve, enqueue, retry, or execute an action.

The status response distinguishes the pending review from execution progress and outcome. Follow its next_action: keep polling when instructed, continue after success, stop on a failure or rejection, and route cases requiring review to an operator. Do not resubmit the original action merely because polling takes longer than expected; that can create a second request rather than resolve the first one.

Give the reviewer a decision they can make

A reviewer needs more than “the agent wants to send an email.” Provide enough context to understand the intended recipient, purpose, and consequence, while keeping secrets and unnecessary customer data out of payloads.

For our fictional workflow, the operator checks whether the reply matches the ticket, whether the destination is correct, and whether the action stays within the agreed support scope. If the evidence is missing, rejection is a useful outcome—not an obstacle to work around.

After approval, check execution status separately. Approval and successful delivery are different facts. If an external effect has an uncertain outcome, investigate before retrying; an unknown result is not evidence that nothing happened.

Keep an explicit stop procedure

When an integration behaves unexpectedly, a scoped freeze can stop subsequent authorization decisions or machine access, depending on its scope. Record a reason and identify who will verify the issue before lifting it.

Read the freeze guide for workspace, connector, and service-agent behavior. A gateway freeze is not a physical robot emergency stop and does not undo an action that has already happened or guarantee interruption of one already running.

Approval is a handoff with evidence, not a decorative confirmation dialog. The integration must pause, the reviewer must understand the action, and the workflow must check the result.

Start with one supported action, a test destination, and a small reviewer group. Expand only after you have observed allow, deny, pending, rejection, and execution-failure paths in the actual integration.