Skip to main content
POST
/
api
/
v1
/
agent
/
{agent_id}
/
tools
/
{tool_id}
/
run
Execute Tool
curl --request POST \
  --url https://api.example.com/api/v1/agent/{agent_id}/tools/{tool_id}/run
Run a tool outside of an agent execution loop. Direct runs enforce the same tenant authorization, tool assignment, permissions, and approval gates as agent-initiated tool calls.

​
Path Parameters

ParameterTypeDescription
agent_idstringThe agent that owns the tool
tool_idstringThe tool’s persisted ID or name

​
Request Body

Send a ToolCallRequest envelope. Tool-specific inputs go under arguments. 
{
  "arguments": {
    "x": 10,
    "y": 5,
    "operation": "+"
  },
  "conversation_id": "conv_calc_001",
  "message_id": "msg_calc_001",
  "idempotency_key": "calc-001",
  "stream": true
}
FieldTypeRequiredDescription
argumentsobjectyesArguments matching the tool’s parameter schema
conversation_idstringyesConversation ID used for execution context
message_idstringyesMessage ID used for execution context
idempotency_keystringnoStable key used to reject duplicate in-flight direct executions
streambooleannoWhen true, return SSE events; when false, return collected JSON events
Raw REST requests must pass both conversation_id and message_id. SDK helpers mint them when omitted, but production integrations should pass stable IDs. For side-effecting tools, pass an idempotency_key so duplicate submissions while the first request is still running return 409 instead of starting a second execution.

​
Response

With stream: true, the endpoint returns text/event-stream: 
retry: 5000

id: 0
data: {"type":"start","call_id":"call_tool_1","parent_call_id":null,"root_call_id":"call_tool_1","content":{"name":"calculator","role":"tool","input":"{\"x\":10,\"y\":5,\"operation\":\"+\"}"},"timestamp":"2026-04-28T14:30:00Z","seq":0,"metadata":null}

id: 1
data: {"type":"end","call_id":"call_tool_1","parent_call_id":null,"root_call_id":"call_tool_1","content":{"result":15},"timestamp":"2026-04-28T14:30:00Z","seq":1,"metadata":null}
With stream: false, the endpoint returns the same event payloads in JSON: 
{
  "events": [
    {
      "type": "start",
      "call_id": "call_tool_1",
      "parent_call_id": null,
      "root_call_id": "call_tool_1",
      "content": {
        "name": "calculator",
        "role": "tool",
        "input": "{\"x\":10,\"y\":5,\"operation\":\"+\"}"
      },
      "timestamp": "2026-04-28T14:30:00Z",
      "seq": 0,
      "metadata": null
    },
    {
      "type": "end",
      "call_id": "call_tool_1",
      "parent_call_id": null,
      "root_call_id": "call_tool_1",
      "content": {
        "result": 15
      },
      "timestamp": "2026-04-28T14:30:00Z",
      "seq": 1,
      "metadata": null
    }
  ]
}