External tools

External tools are functions that your application offers to the agent. The agent decides when to call them, and your application runs them. Use them when an action has to happen on your side, for example showing a form, reading local data or calling a system the service cannot reach.

Flow

sequenceDiagram
    participant App as Your application
    participant RT as Agent Runtime
    App->>RT: messages + tools
    RT-->>App: finish_reason = tool_calls
    App->>App: Run the function
    App->>RT: messages + assistant tool_calls + tool result
    RT-->>App: Final answer

1. Send the tool definitions in OpenAI function-calling format in tools.
2. If the agent wants to use a tool, the response has finish_reason: "tool_calls" and a tool_calls list.
3. Run the function in your application.
4. Send the next request with the assistant message that contains the tool_calls, plus one tool message per call with the matching tool_call_id.

Example

First request:

{
  "model": "support-ticket.agent.support-ticket-agent",
  "messages": [
    { "id": "msg-001", "role": "user", "content": "The packaging line camera is misaligned." }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "create_service_ticket",
        "description": "Create a support ticket in the customer service system.",
        "parameters": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "priority": { "type": "string", "enum": ["low", "medium", "high"] }
          },
          "required": ["title", "priority"]
        }
      }
    }
  ]
}

Response with a tool call:

{
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "create_service_ticket",
              "arguments": "{\"title\":\"Packaging line camera misalignment\",\"priority\":\"high\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Follow-up request with the result:

{
  "model": "support-ticket.agent.support-ticket-agent",
  "messages": [
    { "id": "msg-001", "role": "user", "content": "The packaging line camera is misaligned." },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "create_service_ticket",
            "arguments": "{\"title\":\"Packaging line camera misalignment\",\"priority\":\"high\"}"
          }
        }
      ]
    },
    { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"ticket_id\":\"INC-2026-001\",\"status\":\"created\"}" }
  ],
  "tools": [ "… same tool definitions as before …" ]
}

Send the tool definitions with every request.

Rules

• Return results for all pending tool calls. If only some are returned, the request fails with 400.
• If no results are returned at all, the service inserts a placeholder stating that the tools were not run.
• tool_choice must be an object that names one function, for example {"type": "function", "function": {"name": "create_service_ticket"}}. The strings auto, required and none are not supported, and tool_choice is not supported for teams.
• If one turn uses both tools of the service and external tools, only the external calls are returned to you. The service continues with its own tools after you send the results.
• External tools work with and without sessions.

Tips

• Write clear description texts. The agent decides based on them when to call a tool.
• Keep parameters simple and use enum where possible.
• Return results as short JSON that the agent can understand, including errors such as {"status": "failed", "reason": "…"}.