openai · seratch · Aug 28, 2025 · Aug 28, 2025 · Aug 28, 2025 · Aug 28, 2025
diff --git a/.changeset/thin-plants-hear.md b/.changeset/thin-plants-hear.md
@@ -0,0 +1,6 @@
+---
+'@openai/agents-openai': patch
+'@openai/agents-core': patch
+---
+
+#366 Add conversations API support
diff --git a/examples/basic/conversations.ts b/examples/basic/conversations.ts
@@ -0,0 +1,40 @@
+import { Agent, run } from '@openai/agents';
+import OpenAI from 'openai';
+
+async function main() {
+  const client = new OpenAI();
+
+  console.log('### New conversation:\n');
+  const newConvo = await client.conversations.create({});
+  console.log(`New conversation: ${JSON.stringify(newConvo, null, 2)}`);
+  const conversationId = newConvo.id;
+
+  const agent = new Agent({
+    name: 'Assistant',
+    instructions: 'You are a helpful assistant. be VERY concise.',
+  });
+
+  // Set the conversation ID for the runs
+  console.log('\n### Agent runs:\n');
+  const runOptions = { conversationId };
+  let result = await run(
+    agent,
+    'What is the largest country in South America?',
+    runOptions,
+  );
+  console.log(`First run: ${result.finalOutput}`); // e.g., Brazil
+  result = await run(agent, 'What is the capital of that country?', runOptions);
+  console.log(`Second run: ${result.finalOutput}`); // e.g., Brasilia
+
+  console.log('\n### Conversation items:\n');
+  const convo = await client.conversations.items.list(conversationId);
+  for await (const page of convo.iterPages()) {
+    for (const item of page.getPaginatedItems()) {
+      // desc order
+      console.log(JSON.stringify(item, null, 2));
+    }
+  }
+}
+if (require.main === module) {
+  main().catch(console.error);
+}
diff --git a/examples/basic/package.json b/examples/basic/package.json
@@ -26,6 +26,7 @@
     "start:tool-use-behavior": "tsx tool-use-behavior.ts",
     "start:tools": "tsx tools.ts",
     "start:reasoning": "tsx reasoning.ts",
-    "start:local-file": "tsx local-file.ts"
+    "start:local-file": "tsx local-file.ts",
+    "start:conversations": "tsx conversations.ts"
   }
 }
diff --git a/packages/agents-core/src/model.ts b/packages/agents-core/src/model.ts
@@ -177,6 +177,14 @@ export type ModelRequest = {
    */
   previousResponseId?: string;
 
+  /**
+   * The ID of stored conversation to use for the model.
+   *
+   * see https://platform.openai.com/docs/guides/conversation-state?api-mode=responses#openai-apis-for-conversation-state
+   * see https://platform.openai.com/docs/api-reference/conversations/create
+   */
+  conversationId?: string;
+
   /**
    * The model settings to use for the model.
    */

diff --git a/packages/agents-core/src/run.ts b/packages/agents-core/src/run.ts
@@ -136,6 +136,7 @@ type SharedRunOptions<TContext = undefined> = {
   maxTurns?: number;
   signal?: AbortSignal;
   previousResponseId?: string;
+  conversationId?: string;
 };
 
 export type StreamRunOptions<TContext = undefined> =
@@ -393,6 +394,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               prompt: await state._currentAgent.getPrompt(state._context),
               input: turnInput,
               previousResponseId: options.previousResponseId,
+              conversationId: options.conversationId,
               modelSettings,
               tools: serializedTools,
               outputType: convertAgentOutputTypeToSerializable(
@@ -757,6 +759,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
             prompt: await currentAgent.getPrompt(result.state._context),
             input: turnInput,
             previousResponseId: options.previousResponseId,
+            conversationId: options.conversationId,
             modelSettings,
             tools: serializedTools,
             handoffs: serializedHandoffs,

diff --git a/packages/agents-openai/src/openaiResponsesModel.ts b/packages/agents-openai/src/openaiResponsesModel.ts
@@ -853,6 +853,7 @@ export class OpenAIResponsesModel implements Model {
       include,
       tools,
       previous_response_id: request.previousResponseId,
+      conversation: request.conversationId,
       prompt,
       temperature: request.modelSettings.temperature,
       top_p: request.modelSettings.topP,