You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Sessions give the Agents SDK a **persistent memory layer**. All you need is any
13
-
object that implements the `Session` interface—pass it to `Runner.run` and the
14
-
SDK will handle the rest. When a session is present, the runner automatically:
12
+
Sessions give the Agents SDK a **persistent memory layer**. Provide any object that implements the `Session` interface to `Runner.run`, and the SDK handles the rest. When a session is present, the runner automatically:
15
13
16
14
1. Fetches previously stored conversation items and prepends them to the next turn.
17
15
2. Persists new user input and assistant output after each run completes.
18
-
3. Keeps the session available for future turns, whether you call the runner with
19
-
new user text or resume from an interrupted `RunState`.
16
+
3. Keeps the session available for future turns, whether you call the runner with new user text or resume from an interrupted `RunState`.
20
17
21
-
This removes the need to manually call `toInputList()` or stitch history together
22
-
between turns. The TypeScript SDK currently ships with one ready-to-use
23
-
`OpenAIConversationsSession`, and the same `Session` interface lets you bring your
24
-
own storage. For inspiration beyond the OpenAI Conversations API, browse the
25
-
sample session backends under `examples/memory/` (Prisma, file-backed, and more).
18
+
This removes the need to manually call `toInputList()` or stitch history between turns. The TypeScript SDK ships with two implementations: `OpenAIConversationsSession` for the Conversations API and `MemorySession`, which is intended for local development. Because they share the `Session` interface, you can plug in your own storage backend. For inspiration beyond the Conversations API, explore the sample session backends under `examples/memory/` (Prisma, file-backed, and more).
26
19
27
-
> Tip: To run the `OpenAIConversationsSession` examples on this page, set the
28
-
> `OPENAI_API_KEY` environment variable (or provide an `apiKey` when constructing
29
-
> the session) so the SDK can call the Conversations API.
20
+
> Tip: To run the `OpenAIConversationsSession` examples on this page, set the `OPENAI_API_KEY` environment variable (or provide an `apiKey` when constructing the session) so the SDK can call the Conversations API.
30
21
31
22
---
32
23
33
24
## Quick start
34
25
35
-
Use an `OpenAIConversationsSession` (or any other `Session` implementation) to sync memory with the
Use `OpenAIConversationsSession` to sync memory with the [Conversations API](https://platform.openai.com/docs/api-reference/conversations), or swap in any other `Session` implementation.
37
27
38
28
<Code
39
29
lang="typescript"
40
30
code={sessionsQuickstart}
41
31
title="Use the Conversations API as session memory"
42
32
/>
43
33
44
-
When you reuse the same session instance, the agent receives the full conversation
45
-
history before every turn and writes new items back automatically.
46
-
47
-
Swap `OpenAIConversationsSession` with any other `Session` implementation—no other
48
-
code changes are required.
34
+
Reusing the same session instance ensures the agent receives the full conversation history before every turn and automatically persists new items. Switching to a different `Session` implementation requires no other code changes.
49
35
50
36
---
51
37
52
38
## How the runner uses sessions
53
39
54
-
-**Before each run** the runner retrieves the session history, merges it with the
55
-
new turn’s input, and passes the combined list to your agent.
56
-
-**After a non-streaming run** a single call to `session.addItems()` persists both
57
-
the original user input and the model outputs from the latest turn.
58
-
-**For streaming runs** the runner writes the user input up front and appends
59
-
streamed outputs once the turn completes.
60
-
-**When resuming from `RunResult.state`** (for approval flows or other interruptions)
61
-
continue passing the same `session`. The resumed turn is added to memory without
62
-
re-preparing the input.
40
+
-**Before each run** it retrieves the session history, merges it with the new turn's input, and passes the combined list to your agent.
41
+
-**After a non-streaming run** one call to `session.addItems()` persists both the original user input and the model outputs from the latest turn.
42
+
-**For streaming runs** it writes the user input first and appends streamed outputs once the turn completes.
43
+
-**When resuming from `RunResult.state`** (for approvals or other interruptions) keep passing the same `session`. The resumed turn is added to memory without re-preparing the input.
63
44
64
45
---
65
46
66
47
## Inspecting and editing history
67
48
68
-
Sessions expose simple CRUD helpers so you can build “undo”, “clear chat”, or audit
69
-
features.
49
+
Sessions expose simple CRUD helpers so you can build "undo", "clear chat", or audit features.
70
50
71
51
<Code
72
52
lang="typescript"
73
53
code={manageHistory}
74
54
title="Read and edit stored items"
75
55
/>
76
56
77
-
`session.getItems()` returns the stored `AgentInputItem[]`. Call `popItem()` to
78
-
remove the last entry—useful for user corrections before you rerun the agent.
57
+
`session.getItems()` returns the stored `AgentInputItem[]`. Call `popItem()` to remove the last entry—useful for user corrections before you rerun the agent.
79
58
80
59
---
81
60
82
61
## Bring your own storage
83
62
84
-
Implement the `Session` interface to back memory with Redis, DynamoDB,
85
-
SQLite, or another datastore. Only five asynchronous methods are required.
63
+
Implement the `Session` interface to back memory with Redis, DynamoDB, SQLite, or another datastore. Only five asynchronous methods are required.
86
64
87
65
<Code
88
66
lang="typescript"
89
67
code={customSession}
90
68
title="Custom in-memory session implementation"
91
69
/>
92
70
93
-
Custom sessions let you enforce retention policies, add encryption, or attach
94
-
metadata to each conversation turn before persisting it.
71
+
Custom sessions let you enforce retention policies, add encryption, or attach metadata to each conversation turn before persisting it.
95
72
96
73
---
97
74
98
75
## Control how history and new items merge
99
76
100
-
When you pass an array of `AgentInputItem`s as the run input, provide a
101
-
`sessionInputCallback` to merge them with stored history deterministically.
102
-
The runner loads the existing history, calls your callback **before the model
103
-
invocation**, and hands the returned array to the model as the turn’s complete
104
-
input. This hook is ideal for trimming old items, deduplicating tool results, or
105
-
highlighting only the context you want the model to see.
77
+
When you pass an array of `AgentInputItem`s as the run input, provide a `sessionInputCallback` to merge them with stored history deterministically. The runner loads the existing history, calls your callback **before the model invocation**, and hands the returned array to the model as the turn’s complete input. This hook is ideal for trimming old items, deduplicating tool results, or highlighting only the context you want the model to see.
106
78
107
79
<Code
108
80
lang="typescript"
109
81
code={sessionInputCallback}
110
82
title="Truncate history with sessionInputCallback"
111
83
/>
112
84
113
-
For string inputs the runner can merge history automatically, so you can omit the
114
-
callback.
85
+
For string inputs the runner merges history automatically, so the callback is optional.
115
86
116
87
---
117
88
@@ -132,8 +103,4 @@ if (result.requiresApproval) {
132
103
}
133
104
```
134
105
135
-
Because sessions now work when resuming from a previous `RunState`, the continued
136
-
turn is appended to the same memory record, maintaining a single coherent history
137
-
for the conversation. This keeps human-in-the-loop (HITL) flows fully compatible—
138
-
your approval checkpoints continue to round-trip through `RunState` while the
139
-
session keeps the transcript complete.
106
+
When you resume from a previous `RunState`, the new turn is appended to the same memory record to preserve a single conversation history. Human-in-the-loop (HITL) flows stay fully compatible—approval checkpoints still round-trip through `RunState` while the session keeps the transcript complete.
title="Truncate history with sessionInputCallback"
82
+
title="sessionInputCallback で履歴を切り詰め"
87
83
/>
88
84
89
-
文字列入力の場合、ランナーは履歴を自動的にマージできるため、コールバックを省略できます。
85
+
文字列入力ではランナーが自動で履歴をマージするため、コールバックは任意です。
90
86
91
87
---
92
88
93
89
## 承認と再開可能な実行の取り扱い
94
90
95
-
Human in theloop (人間の介入) フローでは、承認待ちのために実行を一時停止することがよくあります。
91
+
Human-in-the-loop フローでは、承認待ちのために実行を一時停止することがあります:
96
92
97
93
```typescript
98
94
const result =awaitrunner.run(agent, 'Search the itinerary', {
@@ -107,4 +103,4 @@ if (result.requiresApproval) {
107
103
}
108
104
```
109
105
110
-
セッションは以前の`RunState`からの再開時にも機能するため、継続したターンは同じメモリレコードに追加され、会話の一貫した単一の履歴が維持されます。これにより Human in the loop (人間の介入) (HITL) フローとの完全な互換性が保たれます。承認チェックポイントは引き続き `RunState`を往復しつつ、セッションが全文書を完全に保ちます。
106
+
以前の`RunState`から再開する場合、新しいターンは同じメモリレコードに追記され、単一の会話履歴が維持されます。Human in the loop (人間の介入)（HITL）フローとの互換性は完全に保たれ、承認チェックポイントは引き続き `RunState`を経由して往復しつつ、セッションが完全なトランスクリプトを保持します。
0 commit comments