Introduction
OpenAI announced the Responses API, their most advanced and versatile interface for building intelligent AI applications. Supporting both text and image inputs with rich text outputs, this API enables dynamic, stateful conversations that remember and build on previous interactions, making AI experiences more natural and context-aware. It also unlocks powerful capabilities through built-in tools such as web search, file search, code interpreter, and more, while enabling seamless integration with external systems via function calling. Its event-driven design delivers clear, structured updates at every step, making it easier than ever to create sophisticated, multi-step AI workflows.
Key features include:
- Stateful conversations via the previous response ID
- Built-in tools like web search, file search, code interpreter, MCP, and others
- Access to advanced models available exclusively, such as o1-pro
- Enhanced support for reasoning models with reasoning summaries and efficient context management through previous response ID or encrypted reasoning items
- Clear, event-based outputs that simplify integration and control
While the Chat Completions API remains fully supported and widely used, OpenAI plans to retire the Assistants API in the first half of 2026.
To support the adoption of the Responses API, two new Snaps have been introduced:
OpenAI Chat Completions ⇒ OpenAI Responses API Generation
OpenAI Tool Calling ⇒ OpenAI Responses API Tool Calling
Both Snaps are fully compatible with existing upstream and downstream utility Snaps, including the OpenAI Prompt Generator, OpenAI Multimodal Content Generator, all Function Generators (Multi-Pipeline, OpenAPI, and APIM), the Function Result Generator, and the Message Appender. This allows existing pipelines and familiar development patterns to be reused while gaining access to the advanced features of the Responses API.
OpenAI Responses API Generation
|
The OpenAI Responses API Generation Snap is designed to support OpenAI’s newest Responses API, enabling more structured, stateful, and tool-augmented interactions. While it builds upon the familiar interface of the Chat Completions Snap, several new properties and behavioral updates have been introduced to align with the Responses API’s capabilities.
New properties
- Message: The input sent to the LLM. This field replaces the previous Use message payload, Message payload, and Prompt properties in the OpenAI Chat Completions Snap, consolidating them into a single input. It removes ambiguity between "prompt" as raw text and as a template, and supports both string and list formats.
- Previous response ID: The unique ID of the previous response to the model. Use this to create multi-turn conversations.
- Model parameters
- Reasoning summary: For reasoning models, provides a summary of the model’s reasoning process, aiding in debugging and understanding the model's reasoning process. The property can be none, auto, or detailed.
- Advanced prompt configurations
- Instructions: Applied only to the current response, making them useful for dynamically swapping instructions between turns. To persist instructions across turns when using previous_response_id, the developer message in the OpenAI Prompt Generator Snap should be used.
- Advanced response configurations
- Truncation: Defines how to handle input that exceeds the model’s context window. auto allows the model to truncate the middle of the conversation to fit, while disabled (default) causes the request to fail with a 400 error if the context limit is exceeded.
- Include reasoning encrypted content: Includes an encrypted version of reasoning tokens in the output, allowing reasoning items to persist when the store is disabled.
- Built-in tools
- Web search: Enables the model to access up-to-date information from the internet to answer queries beyond its training data.
- Web search type
- Search context size
- User location: an approximate user location including city, region, country, and timezone to deliver more relevant search results.
- File search: Allows the model to retrieve information from documents or files.
- Vector store IDs
- Maximum number of results
- Include search results: Determines whether raw search results are included in the response for transparency or debugging.
- Ranker
- Score threshold
- Filters: Additional metadata-based filters to refine search results. For more details on using filters, see Metadata Filtering.
- Web search: Enables the model to access up-to-date information from the internet to answer queries beyond its training data.
- Advanced tool configuration
- Tool choice: A new option, SPECIFY A BUILT-IN TOOL, allows specifying that the model should use a built-in tool to generate a response.
Note that the OpenAI Responses API Generation Snap does not support the response count or stop sequences properties, as these are not available in the Responses API. Additionally, the message user name, which may be specified in the Prompt Generator Snap, is not supported and will be ignored if included.
Model response of Chat Completions vs Responses API
Chat Completions API | Responses API |
|
The Responses API introduces an event-driven output structure that significantly enhances how developers build and manage AI-powered applications compared to the traditional Chat Completions API. While the Chat Completions API returns a single, plain-text response within the choices array, the Responses API provides an output array containing a sequence of semantic event items—such as reasoning, message, function_call, web_search_call, and more—that clearly delineate each step in the model's reasoning and actions. This structured approach allows developers to easily track and interpret the model's behavior, facilitating more robust error handling and smoother integration with external tools. Moreover, the response from the Responses API includes the model parameters settings, providing additional context for developers.
Pipeline examples
Built-in tool: web search
This example demonstrates how to use the built-in web search tool. In this pipeline, the user’s location is specified to ensure the web search targets relevant geographic results.
System prompt: You are a friendly and helpful assistant. Please use your judge to decide whether to use the appropriate tools or not to answer questions from the user.
Prompt: Can you recommend 2 good sushi restaurants near me?
Output:
As a result, the output contains both a web search call and a message. The model uses the web search to find and provide recommendations based on current data, tailored to the specified location.
Built-in tool: File search
This example demonstrates how the built-in file search tool enables the model to retrieve information from documents stored in a vector store during response generation. In this case, the file wildfire_stats.pdf has been uploaded. You can create and manage vector stores through the Vector Store management page.
Prompt: What is the number of Federal wildfires in 2018
Output:
The output array contains a file_search_call event, which includes search results in its results field. These results provide matched text, metadata, and relevance scores from the vector store. This is followed by a message event, where the model uses the retrieved information to generate a grounded response. The presence of detailed results in the file_search_call is enabled by selecting the Include file search results option.
OpenAI Responses API Tool Calling
|
|
The OpenAI Responses API Tool Calling Snap is designed to support function calling using OpenAI’s Responses API. It works similarly to the OpenAI Tool Calling Snap (which uses the Chat Completions API), but is adapted to the event-driven response structure of the Responses API and supports stateful interactions via the previous response ID. While it shares much of its configuration with the Responses API Generation Snap, it is purpose-built for workflows involving function calls.
Existing LLM agent pipeline patterns and utility Snaps—such as the Function Generator and Function Result Generator—can continue to be used with this Snap, just as with the original OpenAI Tool Calling Snap. The primary difference lies in adapting the Snap configuration to accommodate the Responses API’s event-driven output, particularly the structured function_call event item in the output array.
The Responses API Tool Calling Snap provides two output views, similar to the OpenAI Tool Calling Snap, with enhancements to simplify building agent pipelines and support stateful interactions using the previous response ID:
- Model response view: The complete API response, including extra fields:
- messages: an empty list if store is enabled, or the full message history—including messages payload and model response—if disabled (similar to the OpenAI Tool Calling Snap). When using stateful workflows, message history isn’t needed because the previous response ID is used to maintain context.
- has_tool_call: a boolean indicating whether the response includes a tool call. Since the Responses API no longer includes the finish_reason: "tool_calls" field, this new field makes it easier to create stop conditions in the pipeloop Snap within the agent driver pipeline.
- Tool call view: Displays the list of function calls made by the model during the interaction.
Tool Call View of Chat Completions vs Responses API
Uses id as the function call identifier when sending back the function result. Tool call properties (name, arguments) are nested inside the function field.
|
Each tool call includes: The tool call structure is flat — name and arguments are top-level fields. |
Building LLM Agent Pipelines
To build LLM agent pipelines with the OpenAI Responses API Tool Calling Snap, you can reuse the same agent pipeline pattern described in Introducing Tool Calling Snaps and LLM Agent Pipelines. Only minor configuration changes are needed to support the Responses API.
Agent Driver Pipeline
The primary change is in the PipeLoop Snap configuration, where the stop condition should now check the has_tool_call field, since the Responses API no longer includes the finish_reason:"tool_calls".
Agent Worker Pipeline
Fields mapping
A Mapper Snap is used to prepare the related fields for the OpenAI Responses API Tool Calling Snap.
OpenAI Responses API Tool Calling
The key changes are in this Snap’s configuration to support the Responses API’s stateful interactions. There are two supported approaches:
Option 1: Use Store (Recommended)
Leverages the built-in state management of the Responses API.
- Enable Store
- Use Previous Response ID
- Send only the function call results as the input messages for the next round. (messages field in the Snap’s output will be an empty array, so you can still use it in the Message Appender Snap to collect tool results.)
Option 2: Maintain Conversation History in Pipeline
Similar to the approach used in the Chat Completions API.
- Disable Store
- Include the full message history in the input (messages field in the Snap’s output contains message history)
- (Optional) Enable Include Reasoning Encrypted Content (for reasoning models) to preserve reasoning context efficiently
OpenAI Function Result Generator
As explained in Tool Call View of Chat Completions vs Responses API section, the Responses API includes both an id and a call_id. You must use the call_id to construct the function call result when sending it back to the model.
Conclusion
The OpenAI Responses API makes AI workflows smarter and more adaptable, with stateful interactions and built-in tools. SnapLogic’s OpenAI Responses API Generation and Tool Calling Snaps bring these capabilities directly into your pipelines, letting you take advantage of advanced features like built-in tools and event-based outputs with only minimal adjustments. By integrating these Snaps, you can seamlessly enhance your workflows and fully unlock the potential of the Responses API.