Tools
Tools let an Agent take actions – fetch data, call external APIs, execute code, or even use a computer. The JavaScript/TypeScript SDK supports three categories:
- Hosted tools – run alongside the model on OpenAI servers. (web search, file search, computer use, code interpreter, image generation)
- Function tools – wrap any local function with a JSON schema so the LLM can call it.
- Agents as tools – expose an entire Agent as a callable tool.
1. Hosted tools
Section titled “1. Hosted tools”When you use the OpenAIResponsesModel
you can add the following built‑in tools:
Tool | Type string | Purpose |
---|---|---|
Web search | 'web_search' | Internet search. |
File / retrieval search | 'file_search' | Query vector stores hosted on OpenAI. |
Computer use | 'computer' | Automate GUI interactions. |
Code Interpreter | 'code_interpreter' | Run code in a sandboxed environment. |
Image generation | 'image_generation' | Generate images based on text. |
import { Agent, webSearchTool, fileSearchTool } from '@openai/agents';
const agent = new Agent({ name: 'Travel assistant', tools: [webSearchTool(), fileSearchTool('VS_ID')],});
The exact parameter sets match the OpenAI Responses API – refer to the official documentation
for advanced options like rankingOptions
or semantic filters.
2. Function tools
Section titled “2. Function tools”You can turn any function into a tool with the tool()
helper.
import { tool } from '@openai/agents';import { z } from 'zod';
const getWeatherTool = tool({ name: 'get_weather', description: 'Get the weather for a given city', parameters: z.object({ city: z.string() }), async execute({ city }) { return `The weather in ${city} is sunny.`; },});
Options reference
Section titled “Options reference”Field | Required | Description |
---|---|---|
name | No | Defaults to the function name (e.g., get_weather ). |
description | Yes | Clear, human-readable description shown to the LLM. |
parameters | Yes | Either a Zod schema or a raw JSON schema object. Zod parameters automatically enable strict mode. |
strict | No | When true (default), the SDK returns a model error if the arguments don’t validate. Set to false for fuzzy matching. |
execute | Yes | (args, context) => string | Promise<string> – your business logic. The optional second parameter is theRunContext . |
errorFunction | No | Custom handler (context, error) => string for transforming internal errors into a user-visible string. |
Non‑strict JSON‑schema tools
Section titled “Non‑strict JSON‑schema tools”If you need the model to guess invalid or partial input you can disable strict mode when using raw JSON schema:
import { tool } from '@openai/agents';
interface LooseToolInput { text: string;}
const looseTool = tool({ description: 'Echo input; be forgiving about typos', strict: false, parameters: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: true, }, execute: async (input) => { // because strict is false we need to do our own verification if (typeof input !== 'object' || input === null || !('text' in input)) { return 'Invalid input. Please try again'; } return (input as LooseToolInput).text; },});
3. Agents as tools
Section titled “3. Agents as tools”Sometimes you want an Agent to assist another Agent without fully handing off the
conversation. Use agent.asTool()
:
import { Agent } from '@openai/agents';
const summarizer = new Agent({ name: 'Summarizer', instructions: 'Generate a concise summary of the supplied text.',});
const summarizerTool = summarizer.asTool({ toolName: 'summarize_text', toolDescription: 'Generate a concise summary of the supplied text.',});
const mainAgent = new Agent({ name: 'Research assistant', tools: [summarizerTool],});
Under the hood the SDK:
- Creates a function tool with a single
input
parameter. - Runs the sub‑agent with that input when the tool is called.
- Returns either the last message or the output extracted by
customOutputExtractor
.
Tool use behaviour
Section titled “Tool use behaviour”Refer to the Agents guide for controlling when and how a model
must use tools (tool_choice
, toolUseBehavior
, etc.).
Best practices
Section titled “Best practices”- Short, explicit descriptions – describe what the tool does and when to use it.
- Validate inputs – use Zod schemas for strict JSON validation where possible.
- Avoid side‑effects in error handlers –
errorFunction
should return a helpful string, not throw. - One responsibility per tool – small, composable tools lead to better model reasoning.
Next steps
Section titled “Next steps”- Learn about forcing tool use.
- Add guardrails to validate tool inputs or outputs.
- Dive into the TypeDoc reference for
tool()
and the various hosted tool types.