Search Agent Sky
← Back to search Memory Lane Recent answers
Cited source trail

help me understand openai tool_call schema, how does harness emit it and process it

Next step

Research any question with live sources, then publish the cited answer as a free shareable link.

# OpenAI `tool_call` schema & how a harness emits/processes it ## 1. The schema (Chat Completions / Responses API) OpenAI's function calling (a.k.a. tool calling) is a multi-step loop between your app and the model. The official guide defines three related objects ([OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling)): **Tool definition** — what you send *to* the model (a function tool is defined by a JSON schema): ```json { "type": "function", "function": { "name": "get_horoscope", "description": "Get today's horoscope for an astrological sign.", "parameters": { "type": "object", "properties": { "sign": { "type": "string", "description": "An astrological sign like Taurus or Aquarius" } }, "required": ["sign"], "additionalProperties": false }, "strict": true } } ``` **Tool call** — what the model returns *to you* when it decides it needs a tool. It lives on the assistant message as `message.tool_calls[]`, and each entry has this shape: ```json { "id": "call_abc123", "type": "function", "function": { "name": "get_horoscope", "arguments": "{\"sign\":\"Aquarius\"}" // JSON-encoded string, NOT an object } } ``` Key points: `arguments` is a **JSON string** you must parse; `id` is the unique `call_id` you echo back. **Tool output** — what you send back to the model, as a `role: "tool"` message that references the original call by id: ```json { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"horoscope\":\"...\"}" } ``` The official 5-step flow is: (1) request with tools → (2) receive tool call → (3) execute code with the call's input → (4) second request with the tool output → (5) final response (or more tool calls) ([OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling)). ## 2. How a harness emits and processes tool calls A "harness" is the agent loop that owns this orchestration. The [Agent-Harness repo](https://github.com/michaellaret7/Agent-Harness) is a concrete example — it "streams tokens from a chat-completions endpoint, parses tool calls, executes them, and feeds the results back — until the model stops asking for tools and returns a final answer." Here's how it works: ### Emitting (sending tool definitions + the request) The harness builds the `tools` list (the schema above) and passes it with `messages` to `client.chat.completions.create(...)`. Its `messages.py` constructors produce plain dicts in the exact wire shape the SDK expects — including `assistant_msg(content, tool_calls)` which attaches `tool_calls` to an assistant message, and `tool_msg(tool_call_id, content)` which builds the `role: "tool"` result message ([messages.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py)). ### Processing (the loop) The load-bearing file is `loop.py`. Because streaming responses arrive in fragments, the loop: 1. **Streams** the completion, surfacing content/reasoning deltas to a Sink. 2. **Reassembles fragmented `tool_calls`** — tool-call fragments arrive keyed by index, with the function name on the first fragment and `arguments` dribbling in across many chunks; the loop does an index-keyed merge, concatenating argument fragments into one complete dict ([loop.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py)). 3. **Classifies** the iteration outcome (`answer_ready`, `tool_calls`, `cancelled`, `partial_cancelled`). 4. **Dispatches** each complete tool call to `ToolHandler.execute()`, which unpacks `tc['id']`, `tc['function']['name']`, and `tc['function']['arguments']`, parses the JSON args, runs the matching Python callable, and returns `tool_msg(tc['id'], result)` messages ([tool_handler.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py)). 5. **Appends** the assistant message (with its `tool_calls`) and the `role: "tool"` results to `messages`, then calls the model again — repeating until the model returns plain content. The handler also supports **parallel dispatch** (tools marked `safe_parallel` run concurrently via a `ThreadPoolExecutor`, while non-parallel tools act as barriers) and **cancellation** (interrupted tool calls are synthesized as `[interrupted]` results so the `tool_call`/`tool_result` pairing stays well-formed in history) ([tool_handler.py](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py)). ## TL;DR - **Schema**: `tools[]` (definitions you send) → `message.tool_calls[]` (calls the model returns, with `id`, `type`, `function.name`, and JSON-string `function.arguments`) → `role:"tool"` messages (results you send back, keyed by `tool_call_id`). - **Harness emit**: builds the `tools` list + messages, calls the API, and attaches any returned `tool_calls` to the assistant message in history. - **Harness process**: reassembles streamed fragments into complete calls, parses `arguments`, executes the matching function, and feeds results back as `role:"tool"` messages — looping until the model answers. Sources: - [OpenAI Function calling guide](https://developers.openai.com/api/docs/guides/function-calling) - [Agent-Harness README](https://github.com/michaellaret7/Agent-Harness) - [loop.py (streaming loop + tool-call reassembly)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py) - [tool_handler.py (dispatch/execution)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py) - [messages.py (message constructors)](https://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py)
1searchOpenAI tool_call schema function calling API documentation
2searchOpenAI tool calling harness emit process tool_calls response
3navigatehttps://developers.openai.com/api/docs/guides/function-calling
4navigatehttps://github.com/michaellaret7/Agent-Harness
5get_text
6navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/loop.py
7get_text
8navigatehttps://developers.openai.com/api/docs/guides/function-calling
9ddm--text --find tool_calls
10get_text
11navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/messages.py
12navigatehttps://raw.githubusercontent.com/michaellaret7/Agent-Harness/main/packages/agent_harness/src/agent_harness/tool_handler.py
Shared by Proto Státis · Aug 23, 2026

Ask your own question

Search live sources for a question you choose. You can publish the cited answer as a free link.