Steer
Send tool approvals
Approve or deny the tool calls the agent holds for a human decision.
POST
/
api
/
v2
/
sessions
/
{id}
/
tool_approvals
from hai_agents import Client, SendSessionToolApprovalsRequestBody_ToolApprovalResponse
client = Client()
client.sessions.send_session_tool_approvals(
session_id,
request=SendSessionToolApprovalsRequestBody_ToolApprovalResponse(call_id="call_1", action="approve"),
)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
await client.sessions.sendSessionToolApprovals({
id: sessionId,
body: { type: "tool_approval_response", callId: "call_1", action: "approve" },
});
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_approvals \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "tool_approval_response", "call_id": "call_1", "action": "approve"}'
Behavior
A held tool call waits onawaiting_tool_results and is listed in pending_approvals until you approve or deny it. An approved call runs exactly once; an approved custom tool call then moves to pending_tool_calls for you to run. A denied call is refused, and the rest of its step is skipped.
Each decision is reported as a ToolApprovalDecidedEvent. Deciding a call on a paused session leaves it paused, so resume it separately.
Path parameters
string
required
The session ID.
Request body
Send either a single decision or a batch, discriminated bytype.
Decision
string
default:"tool_approval_response"
"tool_approval_response".string
required
The held call’s
tool_req.id, from pending_approvals.string
required
"approve" runs the call and the rest of its step. "deny" refuses it and skips the rest.string | null
Why the call is denied, as the model reads it. Up to 2,000 characters. Send files or images as a user message.
Batch
string
required
"batch".object[]
required
At least one decision.
Response
202 Accepted.
from hai_agents import Client, SendSessionToolApprovalsRequestBody_ToolApprovalResponse
client = Client()
client.sessions.send_session_tool_approvals(
session_id,
request=SendSessionToolApprovalsRequestBody_ToolApprovalResponse(call_id="call_1", action="approve"),
)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
await client.sessions.sendSessionToolApprovals({
id: sessionId,
body: { type: "tool_approval_response", callId: "call_1", action: "approve" },
});
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_approvals \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "tool_approval_response", "call_id": "call_1", "action": "approve"}'
More examples
Decide a batch of calls
from hai_agents import Client, SendSessionToolApprovalsRequestBody_Batch, ToolApprovalResponseEvent
client = Client()
client.sessions.send_session_tool_approvals(
session_id,
request=SendSessionToolApprovalsRequestBody_Batch(
responses=[
ToolApprovalResponseEvent(call_id="call_1", action="approve"),
ToolApprovalResponseEvent(call_id="call_2", action="deny", message="Do not email customers."),
],
),
)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
await client.sessions.sendSessionToolApprovals({
id: sessionId,
body: {
type: "batch",
responses: [
{ callId: "call_1", action: "approve" },
{ callId: "call_2", action: "deny", message: "Do not email customers." },
],
},
});
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_approvals \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "batch",
"responses": [
{"call_id": "call_1", "action": "approve"},
{"call_id": "call_2", "action": "deny", "message": "Do not email customers."}
]
}'
Errors
| Status | Cause |
|---|---|
404 | Not found, or not in your organization. |
409 | The session already finished. Its held calls were decided when it ended. |
422 | Malformed request body. |
Was this page helpful?
⌘I
from hai_agents import Client, SendSessionToolApprovalsRequestBody_ToolApprovalResponse
client = Client()
client.sessions.send_session_tool_approvals(
session_id,
request=SendSessionToolApprovalsRequestBody_ToolApprovalResponse(call_id="call_1", action="approve"),
)
import { HaiAgentsClient } from "hai-agents";
const client = new HaiAgentsClient();
await client.sessions.sendSessionToolApprovals({
id: sessionId,
body: { type: "tool_approval_response", callId: "call_1", action: "approve" },
});
curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION_ID/tool_approvals \
-H "Authorization: Bearer $HAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "tool_approval_response", "call_id": "call_1", "action": "approve"}'