Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

Some agent actions — deploying to production, restarting a service, deleting data — should not happen without explicit user consent. Human in the Loop lets the gateway pause the agent before executing a sensitive tool call, show the tool name and arguments to the user, and resume only after an approval decision. This keeps the agent autonomous for safe operations while giving users a checkpoint before anything destructive or irreversible runs.

​
How it works

When the agent requests a tool call that requires approval, the gateway does not execute the tool immediately. Instead, it emits tool.approval_required and stops the response until the client sends a tool.approval message. Approvals are based on the tool metadata exposed by the MCP server. Tools marked as destructive or not read-only can require approval before execution.

​
When to use Tool Call Approvals

Use approvals for tools where user confirmation matters:
  • Deploying, restarting, or deleting applications.
  • Updating infrastructure or configuration.
  • Sending external messages or notifications.
  • Mutating production data.
  • Running expensive or irreversible operations.
Approvals are especially useful when the agent can discover the right action but should not perform it without explicit user consent.

​
When not to use Tool Call Approvals

Do not use approvals for safe read-only tools, such as listing resources, fetching metrics, searching docs, or reading application status. Approvals also do not replace authorization. The user still needs permission to call the underlying tool; approval only controls whether the pending tool call should proceed.

​
Streaming events

The client should watch for two things:
  • An agent.message event with a tool call where tool_info.is_approval_required is true. This contains the tool name and arguments to show the user.
  • A tool.approval_required event. This tells the client that execution has paused and an approval decision is required.

​
Tool call

{
  "type": "agent.message",
  "role": "assistant",
  "finish_reason": "tool_calls",
  "tool_calls": [
    {
      "id": "call_restart_billing",
      "type": "function",
      "function": {
        "name": "restart_application",
        "arguments": "{\"workspace_fqn\":\"prod-us\",\"application_name\":\"billing\"}"
      },
      "tool_info": {
        "mcp_server_id": "truefoundry-mcp",
        "mcp_server_name": "truefoundry-mcp",
        "original_tool_name": "restart_application",
        "is_approval_required": true
      }
    }
  ],
  "execution_id": "exec-root",
  "sequence_id": 6
}

​
tool.approval_required

{
  "type": "tool.approval_required",
  "execution_id": "exec-root",
  "tool_calls": [
    { "id": "call_restart_billing" }
  ],
  "sequence_id": 7
}
After this event, send a new turn with previous_response_id and a tool.approval input. Allow the tool call: 
{
  "type": "tool.approval",
  "execution_id": "exec-root",
  "tool_call_id": "call_restart_billing",
  "approval": { "status": "allow" }
}
Deny the tool call: 
{
  "type": "tool.approval",
  "execution_id": "exec-root",
  "tool_call_id": "call_restart_billing",
  "approval": {
    "status": "deny",
    "reason": "Do not restart production during business hours."
  }
}
If the user allows the call, the gateway executes the tool and the agent continues. If the user denies it, the gateway returns the denial as the tool result and the agent continues from that result.

​
Example

User

Restart the billing service in prod-us.

Assistant

I found the billing service in prod-us. Restarting it is a production change, so I need approval before running the tool.

restart_application

Tool Call
{
  "workspace_fqn": "prod-us",
  "application_name": "billing"
}

System

The stream emits tool.approval_required and pauses.
{
  "type": "tool.approval_required",
  "execution_id": "exec-root",
  "tool_calls": [{ "id": "call_restart_billing" }],
  "sequence_id": 7
}

User

Approve.

Assistant

Tool Response
{
  "status": "success",
  "message": "Restart triggered for billing in prod-us."
}
The restart has been triggered for the billing service in prod-us.

​
Client example

Collect pending approval tool calls, display the tool arguments, and resume with an approval decision. For the full working example, see Using API — Human in the Loop.