fix: #425 improve the compatibility for conversationId / previousResponseId + tool calls

.changeset/heavy-foxes-sit.md

@@ -0,0 +1,7 @@
+---
+'@openai/agents-core': patch
+---
+
+fix: improve the compatibility for conversationId / previousResponseId + tool calls
+
+ref: https://github.com/openai/openai-agents-python/pull/1827

docs/src/content/docs/guides/running-agents.mdx

@@ -8,6 +8,8 @@ import helloWorldWithRunnerExample from '../../../../../examples/docs/hello-worl
 import helloWorldExample from '../../../../../examples/docs/hello-world.ts?raw';
 import runningAgentsExceptionExample from '../../../../../examples/docs/running-agents/exceptions1.ts?raw';
 import chatLoopExample from '../../../../../examples/docs/running-agents/chatLoop.ts?raw';
+import conversationIdExample from '../../../../../examples/docs/running-agents/conversationId.ts?raw';
+import previousResponseIdExample from '../../../../../examples/docs/running-agents/previousResponseId.ts?raw';
 
 Agents do nothing by themselves – you **run** them with the `Runner` class or the `run()` utility.
 
@@ -95,6 +97,32 @@ Each call to `runner.run()` (or `run()` utility) represents one **turn** in your
 
 See [the chat example](https://github.com/openai/openai-agents-js/tree/main/examples/basic/chat.ts) for an interactive version.
 
+### Server-managed conversations
+
+You can let the OpenAI Responses API persist conversation history for you instead of sending your entire local transcript on every turn. This is useful when you are coordinating long conversations or multiple services. See the [Conversation state guide](https://platform.openai.com/docs/guides/conversation-state?api-mode=responses) for details.
+
+OpenAI exposes two ways to reuse server-side state:
+
+#### 1. `conversationId` for an entire conversation
+
+You can create a conversation once using [Conversations API](https://platform.openai.com/docs/api-reference/conversations/create) and then reuse its ID for every turn. The SDK automatically includes only the newly generated items.
+
+<Code
+  lang="typescript"
+  code={conversationIdExample}
+  title="Reusing a server conversation"
+/>
+
+#### 2. `previousResponseId` to continue from the last turn
+
+If you want to start only with Responses API anyway, you can chain each request using the ID returned from the previous response. This keeps the context alive across turns without creating a full conversation resource.
+
+<Code
+  lang="typescript"
+  code={previousResponseIdExample}
+  title="Chaining with previousResponseId"
+/>
+
 ## Exceptions
 
 The SDK throws a small set of errors you can catch:

examples/basic/conversations.ts

@@ -1,5 +1,6 @@
-import { Agent, run } from '@openai/agents';
+import { Agent, run, tool } from '@openai/agents';
 import OpenAI from 'openai';
+import z from 'zod';
 
 async function main() {
   const client = new OpenAI();
@@ -9,22 +10,47 @@ async function main() {
   console.log(`New conversation: ${JSON.stringify(newConvo, null, 2)}`);
   const conversationId = newConvo.id;
 
+  const getWeatherTool = tool({
+    name: 'get_weather',
+    description: 'Get the weather for a given city',
+    parameters: z.object({ city: z.string() }),
+    strict: true,
+    async execute({ city }) {
+      return `The weather in ${city} is sunny.`;
+    },
+  });
+
   const agent = new Agent({
     name: 'Assistant',
     instructions: 'You are a helpful assistant. be VERY concise.',
+    tools: [getWeatherTool],
   });
 
   // Set the conversation ID for the runs
   console.log('\n### Agent runs:\n');
-  const runOptions = { conversationId };
+  const options = { conversationId };
   let result = await run(
     agent,
     'What is the largest country in South America?',
-    runOptions,
+    options,
+  );
+  // First run: The largest country in South America is Brazil.
+  console.log(`First run: ${result.finalOutput}`);
+  result = await run(agent, 'What is the capital of that country?', options);
+  // Second run: The capital of Brazil is Brasília.
+  console.log(`Second run: ${result.finalOutput}`);
+
+  result = await run(agent, 'What is the weather in the city today?', options);
+  // Thrid run: The weather in Brasília today is sunny.
+  console.log(`Thrid run: ${result.finalOutput}`);
+
+  result = await run(
+    agent,
+    `Can you share the same information about the smallest country's capital in South America?`,
+    options,
   );
-  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
+  // Fourth run: The smallest country in South America is Suriname. Its capital is Paramaribo. The weather in Paramaribo today is sunny.
+  console.log(`Fourth run: ${result.finalOutput}`);
 
   console.log('\n### Conversation items:\n');
   const convo = await client.conversations.items.list(conversationId);

examples/docs/running-agents/conversationId.ts

@@ -0,0 +1,25 @@
+import { Agent, run } from '@openai/agents';
+import { OpenAI } from 'openai';
+
+const agent = new Agent({
+  name: 'Assistant',
+  instructions: 'Reply very concisely.',
+});
+
+async function main() {
+  // Create a server-managed conversation:
+  const client = new OpenAI();
+  const { id: conversationId } = await client.conversations.create({});
+
+  const first = await run(agent, 'What city is the Golden Gate Bridge in?', {
+    conversationId,
+  });
+  console.log(first.finalOutput);
+  // -> "San Francisco"
+
+  const second = await run(agent, 'What state is it in?', { conversationId });
+  console.log(second.finalOutput);
+  // -> "California"
+}
+
+main().catch(console.error);

examples/docs/running-agents/previousResponseId.ts

@@ -0,0 +1,21 @@
+import { Agent, run } from '@openai/agents';
+
+const agent = new Agent({
+  name: 'Assistant',
+  instructions: 'Reply very concisely.',
+});
+
+async function main() {
+  const first = await run(agent, 'What city is the Golden Gate Bridge in?');
+  console.log(first.finalOutput);
+  // -> "San Francisco"
+
+  const previousResponseId = first.lastResponseId;
+  const second = await run(agent, 'What state is it in?', {
+    previousResponseId,
+  });
+  console.log(second.finalOutput);
+  // -> "California"
+}
+
+main().catch(console.error);