Augment Conversations with Web Search and Summarization
OpenAI guide introducing the stateful, multi-tool, multimodal Responses API versus Chat Completions and Assistants.
Why it matters
Leverage the Responses API to create sophisticated, multimodal conversations that seamlessly integrate web search results and summarize findings.
Outcomes
What it gets done
Perform web searches directly within API calls.
Summarize search results and other content.
Handle multimodal inputs including images and audio.
Simplify complex interactions into single API calls.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/oai-responsesexample | bash Overview
Responses Example
OpenAI guide introducing the Responses API - a stateful alternative to Chat Completions and Assistants that manages conversation history automatically and supports hosted tools (file_search, web_search) and multimodal, tool-augmented interactions in a single call. Use when building multi-turn, tool-using, or multimodal applications that need automatic conversation-state and tool-orchestration management.
What it does
This OpenAI guide introduces the Responses API, a newer way to interact with OpenAI models designed to be simpler and more flexible than the Chat Completions API (built mainly for text) or the Assistants API (which can require heavy setup). It is built for seamless multi-turn interactions within a single API call, easy access to hosted tools like file_search, web_search, and code interpreter, and fine-grained control over the context sent to the model - meeting the needs of increasingly complex, long-running, asynchronous and stateful reasoning workflows. On the basics, it explains that the Responses API looks similar to the Completions API on the surface but is stateful by design: you don't need to manage conversation state yourself, since retrieving a response at any time returns the full conversation history, and you can continue a conversation by referencing the previous response or fork it at any point to branch the conversation - while still being able to manage context manually if you prefer. It covers hosted tools, where instead of manually calling tools like file_search and web_search, you simply pass them to the API and it decides which to use, illustrated with an example of incorporating live web-search results into a response. Finally it demonstrates a fully multimodal, tool-augmented interaction in a single API call - analyzing an image, performing a web search related to that image via the web_search hosted tool, and summarizing the results - contrasted against the multiple separate round trips (image analysis, then a manual web-search step, then a re-submission for summarization) that the same task would require under the Chat Completions API.
When to use - and when NOT to
Use the Responses API when building applications that need multi-turn conversation state managed automatically, hosted tool use (file search, web search, code interpreter) without manual orchestration, or multimodal (text, image, audio) tool-augmented interactions in a single call. It is not the right fit if you need the fine-grained manual control over every tool call and message that Chat Completions offers, or if your application is a simple single-turn text completion with no need for hosted tools or state persistence.
Inputs and outputs
Input is a user query, optionally with image or audio content and a previous response ID to continue or fork a conversation. Output is a stateful response object retrievable at any time, including the full conversation history, generated using whichever hosted tools (file_search, web_search) the API determines are needed.
Integrations
Built on OpenAI's Responses API and its hosted tools - file_search, web_search, and code interpreter - as an alternative to the Chat Completions API and the Assistants API.
Who it's for
Developers building multi-turn, tool-using, or multimodal AI applications who want OpenAI to manage conversation state and tool orchestration automatically instead of building that logic themselves on top of Chat Completions.
Source README
What is the Responses API?
The Responses API is a new way to interact with OpenAI models, designed to be simpler and more flexible than previous APIs. It makes it easy to build advanced AI applications that use multiple tools, handle multi-turn conversations, and work with different types of data (not just text).
Unlike older APIs-such as Chat Completions, which were built mainly for text, or the Assistants API, which can require a lot of setup-the Responses API is built from the ground up for:
- Seamless multi-turn interactions (carry on a conversation across several steps in a single API call)
- Easy access to powerful hosted tools (like file search, web search, and code interpreter)
- Fine-grained control over the context you send to the model
As AI models become more capable of complex, long-running reasoning, developers need an API that is both asynchronous and stateful. The Responses API is designed to meet these needs.
In this guide, you'll see some of the new features the Responses API offers, along with practical examples to help you get started.
Basics
By design, on the surface, the Responses API is very similar to the Completions API.
One key feature of the Response API is that it is stateful. This means that you do not have to manage the state of the conversation by yourself, the API will handle it for you. For example, you can retrieve the response at any time and it will include the full conversation history.
You can continue the conversation by referring to the previous response.
You can of course manage the context yourself. But one benefit of OpenAI maintaining the context for you is that you can fork the response at any point and continue the conversation from that point.
Hosted Tools
Another benefit of the Responses API is that it adds support for hosted tools like file_search and web_search. Instead of manually calling the tools, simply pass in the tools and the API will decide which tool to use and use it.
Here is an example of using the web_search tool to incorporate web search results into the response.
Multimodal, Tool-augmented conversation
The Responses API natively supports text, images, and audio modalities.
Tying everything together, we can build a fully multimodal, tool-augmented interaction with one API call through the responses API.
In the above example, we were able to use the web_search tool to search the web for news related to the image in one API call instead of multiple round trips that would be required if we were using the Chat Completions API.
With the responses API
🔥 a single API call can handle:
✅ Analyze a given image using a multimodal input.
✅ Perform web search via the web_search hosted tool
✅ Summarize the results.
In contrast, With Chat Completions API would require multiple steps, each requiring a round trip to the API:
1️⃣ Upload image and get analysis → 1 request
2️⃣ Extract info, call external web search → manual step + tool execution
3️⃣ Re-submit tool results for summarization → another request
See the following diagram for a side by side visualized comparison!
We are very excited for you to try out the Responses API and see how it can simplify your code and make it easier to build complex, multimodal, tool-augmented interactions!
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.