Conversation state

Purpose and Scope

Conversation state is the application memory that lets a model turn relate to earlier turns. In this SDK, there are two complementary patterns. You can replay the relevant prior input and output items into a new Responses API request, or you can use stored identifiers and Conversations-style item resources where the API owns more of the history. The practical decision is whether your application must inspect, edit, persist, or redact every item locally, or whether it can delegate continuation to an API-managed object and store only identifiers plus business metadata.

Sources: README.md, src/resources/conversations/index.ts

The README positions the Responses API as the primary model interaction surface and explicitly warns that manual history must preserve ordered output items, not only message text. That warning matters because Responses output can contain reasoning records, tool calls, and other replayable items that are part of the state the next request may need. The generated Conversations export then provides a separate namespace for persisted conversation items, making the distinction clear: Responses can be stateless with explicit replay, while Conversations resources expose item-level operations for API-managed state.

Sources: README.md, src/resources/conversations/index.ts

Relevant Source Files

• src/resources/conversations/index.ts — Barrel module for the Conversations resource family; it re-exports the conversations module and the Items resource plus conversation item request, response, list, delete, and page types.
• README.md — Documents the SDK’s Responses-first usage model and the manual multi-turn conversation guidance, including the recommendation to use the response item conversion helper or previous_response_id.
• examples/responses/manual-conversation-state.ts — Runnable TypeScript example that maintains a local input array, appends normalized output items, and sends a follow-up Responses request.
• examples/azure/responses.ts — Shows a continuation request using previous_response_id and highlights that instructions are not inherited through that continuation mechanism.

Core State Patterns

Use manual state when your application is the source of truth for the transcript. The official conversation-state guide describes building a multi-turn request by sending alternating user and assistant messages, and the SDK README adds the important Responses-specific refinement: preserve complete ordered output items. In practice, this means you start with a typed input list, send it to client.responses.create, convert the model output into replayable input items, append the next user turn, and call the model again. This approach is transparent and portable because the transcript can be stored in your own database.

Sources: README.md, examples/responses/manual-conversation-state.ts

Use stored continuation when you want a shorter next-turn request and do not need to replay the entire transcript. The README names previous_response_id as the simple continuation option, and the Azure Responses example demonstrates it in a follow-up request. That example also documents a subtle but important edge case: instructions are not inherited through previous_response_id. If your application depends on a developer instruction, safety policy, persona, or task framing, include it again on the follow-up request rather than assuming the prior request’s instructions carry forward.

Sources: README.md, examples/azure/responses.ts

Use Conversations resources when your design revolves around addressable conversation items rather than a purely local array. The generated Conversations index exports an Items resource and item-specific types such as ConversationItem, ConversationItemList, ItemCreateParams, ItemRetrieveParams, ItemListParams, and ItemDeleteParams. Those names indicate the public SDK contract at this boundary: application code can create, retrieve, list, and delete items associated with conversations through the generated resource family. Treat those item records as stateful API objects, not just strings to concatenate.

Sources: src/resources/conversations/index.ts

System-to-Code Mapping

The source mapping is intentionally small because src/resources/conversations/index.ts is a generated barrel. It marks the Conversations resource family as OpenAPI-generated by Stainless, exports the underlying conversations module, and exposes the typed item surface that downstream TypeScript code imports. This is useful for readers because it identifies the stable import names to search in the generated API reference and in editor autocomplete. When you see ConversationItemsPage, for example, expect paginated list behavior; when you see ItemDeleteParams, expect a delete operation to require a structured parameter object.

Sources: src/resources/conversations/index.ts

Concern	SDK surface	What to preserve
Local replay	Responses input array plus converted output items	Complete ordered replayable items, including non-message output
Stored response continuation	previous_response_id on a new Responses request	The prior response identifier and any instructions needed again
API-managed conversation items	Conversations Items resource and item types	Conversation item identifiers, list pagination, create/retrieve/delete parameters

Execution Flow

A reliable manual flow begins before the first model call. Create an input array that contains the user’s first request and any required context items, then send it to the Responses API. After receiving the response, display output_text if the user only needs the final text, but do not use that display string as the sole stored state. Instead, normalize the complete response output into response input items, append those items to the same ordered history, then append the user’s next turn. The example uses this pattern for a coding task followed by “Add type hints.”

Sources: examples/responses/manual-conversation-state.ts

A reliable stored-continuation flow is shorter but has different responsibilities. Save the response identifier from the first call, then send the next user input with previous_response_id. This avoids sending a growing transcript on each turn, but it also means your code should be explicit about any request settings that must remain stable. The Azure example repeats the model deployment and includes instructions on the initial request, then comments that instructions are not inherited for the follow-up. That comment is a practical guardrail for production assistants and tutor-style workflows.

Sources: examples/azure/responses.ts

API Components

The Conversations barrel exports Items as the concrete item resource and several named TypeScript types for its request and response shapes. ConversationItem represents an item object, ConversationItemList represents a list response, and ConversationItemsPage is the paginated page type. The parameter types split operations by intent: ItemCreateParams for creating an item, ItemRetrieveParams for fetching one, ItemListParams for enumerating items, and ItemDeleteParams for removal. Import these generated types when you want compile-time checks around conversation item workflows.

Sources: src/resources/conversations/index.ts

For Responses-driven state, the example imports toResponseInputItems from the SDK’s response input item helper and ResponseInputItem from the generated Responses resource types. The important behavior shown by the example is not merely appending text; it is preserving the complete ordered output, including reasoning and tool-call items. That makes the next request a faithful continuation of the model-visible state. If an application filters the output down to assistant messages, it can accidentally discard items required by the API or by the model’s next reasoning step.

Sources: README.md, examples/responses/manual-conversation-state.ts

Implementation Notes and Next Steps

Choose the smallest state strategy that still satisfies your product requirements. For a simple chat box, previous_response_id can reduce request payload size and implementation complexity, as long as the application repeats non-inherited settings that matter. For auditability, moderation, sync across devices, or custom transcript editing, maintain local replayable history and store each normalized item in order. For workflows that need API-addressable conversation records, explore the Conversations item surface and its create, retrieve, list, and delete parameter types. Next, read the Responses API and Streaming pages to understand how output items are produced incrementally before they become state.

Sources: README.md, src/resources/conversations/index.ts