openai/responses

10 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

OpenAI Responses API - basic generateText example

The OpenAI Responses API is called using `openai.responses(modelId)` instead of `openai(modelId)`. Basic usage: `const { text } = await generateText({ model: openai.responses('gpt-4o'), prompt: 'Explain the concept of quantum entanglement.' });`

OpenAI Responses API - structured output with schema

Structured data generation with Responses API using `Output.object()` and Zod schema: `const { output } = await generateText({ model: openai.responses('gpt-4o'), output: Output.object({ schema: z.object({ recipe: z.object({ name: z.string(), ingredients: z.array(z.object({ name: z.string(), amount: z.string() })), steps: z.array(z.string()) }) }) }), prompt: 'Generate a lasagna recipe.' });`

OpenAI Responses API - tool calling with agentic behavior

Tool calling with Responses API enables agentic behavior using `stopWhen: isStepCount(5)` parameter. Example: `const { text } = await generateText({ model: openai.responses('gpt-4o'), prompt: 'What is the weather like today in San Francisco?', tools: { getWeather: tool({ description: 'Get the weather in a location', inputSchema: z.object({ location: z.string().describe('The location to get the weather for') }), execute: async ({ location }) => ({ location, temperature: 72 + Math.floor(Math.random() * 21) - 10 }) }) }, stopWhen: isStepCount(5) });`

OpenAI webSearchPreview tool - basic usage

The Responses API includes a `webSearchPreview` tool for grounding responses. Basic usage: `const result = await generateText({ model: openai.responses('gpt-4o-mini'), prompt: 'What happened in San Francisco last week?', tools: { web_search_preview: openai.tools.webSearchPreview() } }); console.log(result.text); console.log(result.sources);`

OpenAI webSearchPreview tool - with search context options

The `webSearchPreview` tool accepts options for query-specific metadata: `openai.tools.webSearchPreview({ searchContextSize: 'high', userLocation: { type: 'approximate', city: 'San Francisco', region: 'California' } })`. This improves search result quality.

OpenAI MCP tool integration

The Responses API supports Model Context Protocol (MCP) servers via `openai.tools.mcp()`. Example: `const result = await generateText({ model: openai.responses('gpt-5-mini'), prompt: 'Search the web for the latest NYC mayoral election results', tools: { mcp: openai.tools.mcp({ serverLabel: 'web-search', serverUrl: 'https://mcp.exa.ai/mcp', serverDescription: 'A web-search API for AI agents' }) } });`

OpenAI Responses API - persistence with previousResponseId

The Responses API supports persistence using `previousResponseId` in `providerOptions.openai`. Example: `const result1 = await generateText({ model: openai.responses('gpt-4o-mini'), prompt: 'Invent a new holiday and describe its traditions.' }); const result2 = await generateText({ model: openai.responses('gpt-4o-mini'), prompt: 'Summarize in 2 sentences', providerOptions: { openai: { previousResponseId: result1.providerMetadata?.openai.responseId as string } } });`

OpenAI Responses API - persistence with Conversation ID

The Responses API supports persistence using OpenAI Conversation API. To continue a conversation created via OpenAI API, pass the conversation ID: `const result = await generateText({ model: openai.responses('gpt-4o-mini'), prompt: 'Summarize in 2 sentences', providerOptions: { openai: { conversation: 'conv_123' } } });`

OpenAI Responses API - key features

The OpenAI Responses API offers: persistent chat history, web search tool for grounding LLM responses, file search tool for finding relevant files, and computer use tool for building agents that can interact with and operate computers.

Migration from Completions API to Responses API

To migrate from Completions API to Responses API, change the provider instance from `openai(modelId)` to `openai.responses(modelId)`. The `providerOptions` structure remains the same for provider-specific options like `parallelToolCalls`.

Give your agent this brain