Session

AgentSession adalah kontainer status percakapan yang digunakan di seluruh proses eksekusi agen.

Apa yang AgentSession berisi

Ladang	Kegunaan
StateBag	Kontainer status arbitrer untuk sesi ini

C# AgentSession adalah kelas dasar abstrak. Implementasi konkret (dibuat melalui CreateSessionAsync()) dapat menambahkan status tambahan misalnya id untuk penyimpanan riwayat obrolan jarak jauh, ketika riwayat yang dikelola layanan digunakan.

Ladang	Kegunaan
session_id	Pengidentifikasi unik lokal untuk sesi ini
service_session_id	Pengidentifikasi sesi layanan jarak jauh, seperti ID percakapan atau respons, saat riwayat yang dikelola layanan digunakan
state	Kamus yang dapat diubah dibagikan dengan penyedia konteks/riwayat

Ladang	Kegunaan
agent.Session	Kontainer status nilai kunci yang terkait dengan percakapan

Sesi menyediakan penyimpanan kunci-nilai yang ditik:

type UserPrefs struct {
    Theme    string `json:"theme"`
    Language string `json:"language"`
}

session.Set("user_prefs", UserPrefs{Theme: "dark", Language: "en"})

var prefs UserPrefs
session.Get("user_prefs", &prefs)

session.Delete("user_prefs")

Lingkup ID sesi layanan

Jika riwayat yang dikelola oleh layanan digunakan, sesi dapat berisi ID sesi yang diterbitkan oleh layanan. Misalnya, OpenAI Responses dapat menggunakan ID respons resp_* sebagai previous_response_id, dan OpenAI Conversations API dapat menggunakan ID percakapan conv_* sebagai percakapan tersebut.

Secara default, OpenAI membatasi ID ini ke kunci API atau proyek yang mendasarinya. Ini biasanya cukup ketika kunci atau proyek tersebut sudah cocok dengan batas aplikasi, seperti aplikasi pengguna tunggal atau kunci/proyek terpisah per penyewa. Pola hosting yang berisiko adalah menggunakan satu kunci atau proyek backend untuk beberapa pengguna akhir, meneruskan ID mentah dari sisi layanan ke klien, dan menerima kembali ID tersebut tanpa memeriksa kepemilikannya. Pada aplikasi yang di-hosting atau aplikasi multi-pengguna yang menggunakan kembali satu kunci pendukung atau proyek yang sama, jangan perlakukan service_session_id, previous_response_id, atau conversation/conversation_id sebagai batas otorisasi bagi pengguna akhir. Simpan ID sisi layanan di penyimpanan aplikasi tepercaya, petakan ID sesi yang terlihat klien ke ID sisi layanan tersebut, dan verifikasi pengguna atau penyewa yang diautentikasi sebelum melanjutkan percakapan.

Pola penggunaan bawaan

AgentSession session = await agent.CreateSessionAsync();

var first = await agent.RunAsync("My name is Alice.", session);
var second = await agent.RunAsync("What is my name?", session);

session = agent.create_session()

first = await agent.run("My name is Alice.", session=session)
second = await agent.run("What is my name?", session=session)

session, err := a.CreateSession(ctx)
if err != nil {
    panic(err)
}

resp, _ := a.RunText(ctx, "Hello!", agent.WithSession(session)).Collect()
resp, _ = a.RunText(ctx, "Follow-up question.", agent.WithSession(session)).Collect()

Menggunakan sesi dengan Agen Harness

Harness Agent menggunakan siklus hidup yang sama seperti yang AgentSession dijelaskan di atas. Gunakan kembali satu sesi di seluruh giliran sehingga riwayat obrolan dan fitur harness yang didukung sesi—seperti todo, mode operasi, memori file, persetujuan alat, dan status tugas latar belakang—tetap terhubung. Menserialisasi sesi ketika status tersebut harus bertahan dari proses mulai ulang.

HarnessAgent defaultnya adalah InMemoryChatHistoryProvider. Ganti melalui HarnessAgentOptions.ChatHistoryProvider ketika riwayat harus menggunakan penyimpanan lain. AsHarnessAgent(options) singkatan untuk membangun new HarnessAgent(chatClient, options).

HarnessAgent agent = chatClient.AsHarnessAgent();
AgentSession session = await agent.CreateSessionAsync();

await agent.RunAsync("Plan the migration.", session);
await agent.RunAsync("Continue with the next step.", session);

var serialized = await agent.SerializeSessionAsync(session);
AgentSession resumed = await agent.DeserializeSessionAsync(serialized);

Harness mempertahankan riwayat obrolan lokal setelah setiap panggilan model di dalam perulangan panggilan alat, tidak hanya setelah agen luar berjalan. Lanjutkan melewati sesi yang sama untuk mempertahankan riwayat dalam perulangan dan status penyedia konteks default.

create_harness_agent history_provider default ke InMemoryHistoryProvider(). Teruskan kustom HistoryProvider saat history_provider= riwayat harus menggunakan penyimpanan lain.

agent = create_harness_agent(client)
session = agent.create_session()

await agent.run("Plan the migration.", session=session)
await agent.run("Continue with the next step.", session=session)

serialized = session.to_dict()
resumed = AgentSession.from_dict(serialized)

Harness memerlukan persistensi riwayat per panggilan layanan, sehingga penyedia riwayat yang dikonfigurasi menyimpan setiap panggilan model di dalam perulangan alat. Sesi juga diperlukan oleh middleware persetujuan alat default; gunakan kembali dan pulihkan untuk mempertahankan persetujuan dan status penyedia konteks.

Agen Harness saat ini tidak tersedia di Go SDK. Gunakan pola sesi reguler yang ditunjukkan di atas.

Membuat sesi dari ID percakapan layanan yang sudah ada

Buat sesi baru dari id percakapan yang sudah ada bervariasi menurut jenis agen. Berikut adalah beberapa contoh.

Saat menggunakan ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Saat menggunakan A2AAgent

AgentSession session = await a2aAgent.CreateSessionAsync(contextId, taskId);

Gunakan ini ketika layanan pendukung sudah memiliki status percakapan.

session = agent.get_session(service_session_id="<service-conversation-id>")
response = await agent.run("Continue this conversation.", session=session)

Di aplikasi yang dihosting, atasi <service-conversation-id> dari penyimpanan milik aplikasi setelah memeriksa pengguna atau penyewa saat ini. Hindari menerima ID mentah dari sisi layanan dari klien kecuali Anda terlebih dahulu memverifikasi bahwa pemanggil adalah pemilik percakapan.

Serialisasi dan pemulihan

var serialized = agent.SerializeSession(session);
AgentSession resumed = await agent.DeserializeSessionAsync(serialized);

Dalam aplikasi yang dihost sendiri, dapat AgentSessionStore memuat dan menyimpan sesi dengan ID kelanjutan sebagai bagian dari pemrosesan permintaan. Ini berbeda dari mempertahankan sesi secara manual dan mengonfigurasi penyedia riwayat. Lihat Aplikasi Kerangka Kerja Agen host mandiri.

serialized = session.to_dict()
resumed = AgentSession.from_dict(serialized)

data, err := json.Marshal(session)
if err != nil {
    panic(err)
}

// Save to disk, database, etc.
if err := os.WriteFile("session.json", data, 0o644); err != nil {
    panic(err)
}

// Later, restore the session.
loaded, err := os.ReadFile("session.json")
if err != nil {
    panic(err)
}

var resumedSession agent.Session
if err := json.Unmarshal(loaded, &resumedSession); err != nil {
    panic(err)
}

resp, _ := a.RunText(ctx, "Continue from where we left off.", agent.WithSession(&resumedSession)).Collect()

Tip

Lihat contoh percakapan persisten untuk contoh lengkap.

Important

Sesi bersifat spesifik untuk agen/layanan. Menggunakan kembali sesi dengan konfigurasi agen atau penyedia yang berbeda dapat menyebabkan konteks yang tidak valid. Jika sesi yang diserialisasi berisi ID sesi di sisi layanan, pulihkan sesi tersebut hanya untuk pengguna aplikasi atau penyewa yang memiliki ID tersebut.

Langkah berikutnya

Penyedia Konteks