Repository Public Research preview
1# Tools and agents23## Function tools (Responses API)45```json6{7 "type": "function",8 "name": "get_weather",9 "description": "Get the current weather for a city. Use it for any weather question. Returns a short text summary.",10 "strict": true,11 "parameters": {12 "type": "object",13 "properties": {"city": {"type": "string", "description": "City name"}},14 "required": ["city"],15 "additionalProperties": false16 }17}18```1920The description decides whether the tool gets used. `strict: true` guarantees schema-valid21arguments and needs a strict-clean schema. Arguments arrive as a **JSON string**: parse and22validate them; they are model output.2324## The loop25261. Send `input` + `tools`.272. Append **every** item of `response.output` to your input (reasoning items included).283. For each `function_call` item, run the function and append29 `{"type": "function_call_output", "call_id": <its call_id>, "output": "<string>"}`. Several30 calls can arrive in one turn: answer all of them. Report failures as output text; never drop one.314. Call again. Stop when no `function_call` item comes back. Always cap the number of turns.3233With `previous_response_id` you may send only the new `function_call_output` items instead of the34whole history.3536`tool_choice`: `"auto"`, `"required"`, `"none"`, or `{"type": "function", "name": "…"}` — all37accepted by every probed model for function tools. `"any"` is not an OpenAI value.38`parallel_tool_calls: false` limits the model to one call per turn.3940## Hosted tools (Responses API only, billed per call)4142| Tool | Declaration | Notes |43|---|---|---|44| Web search | `{"type": "web_search"}` | Answers carry `url_citation` annotations; show the sources |45| Code interpreter | `{"type": "code_interpreter", "container": {"type": "auto"}}` | Rejected by `gpt-5-pro`, `gpt-5.2-pro` |46| File search | `{"type": "file_search", "vector_store_ids": ["vs_…"]}` | Needs a vector store |47| Image generation | `{"type": "image_generation"}` | Costs far more than text |48| Remote MCP | `{"type": "mcp", "server_label": "…", "server_url": "https://…"}` | The server's tools become callable; review what it can do |4950`o3` and `o3-pro` accept only `tool_choice: "auto"` when a hosted tool is present.5152## Agents SDK5354A separate package (`@openai/agents`, `openai-agents`) that runs the loop for you and records55traces. TypeScript: `tool({name, description, parameters: z.object({…}), execute})`,56`new Agent({name, instructions, model, tools})`, `await run(agent, input, {maxTurns})` →57`result.finalOutput`. Python: `@function_tool`, `Agent(...)`, `Runner.run_sync(agent, input,58max_turns=…)` → `result.final_output`. It also provides handoffs between agents, guardrails and59sessions; those were not exercised by this skill's tests.6061## Which architecture6263| Approach | You write | Good for |64|---|---|---|65| Single Responses call | A request | Bounded tasks |66| Function-calling loop | The loop and the tools | Full control, custom flows |67| Agents SDK | Tools and agent definitions | Multi-step agents, handoffs, tracing |68| Hosted tools | A tool declaration | Search, code execution, retrieval without infrastructure |6970Before building an agent, check: is the task open-ended, worth the cost, within the model's71ability, and are errors recoverable? If not, use a single call or a fixed workflow.72