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()

Gunakan sesi dengan Harness Agent

Harness Agent menggunakan siklus hidup yang sama seperti yang AgentSession dijelaskan di atas. Gunakan kembali satu sesi antargiliran agar riwayat obrolan dan fitur harness berbasis sesi—seperti daftar tugas, mode operasi, memori file, persetujuan penggunaan 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 jika riwayat harus menggunakan penyimpanan lain. AsHarnessAgent(options) adalah singkatan untuk membentuk 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);

Sistem menyimpan riwayat percakapan lokal setelah setiap pemanggilan model di dalam perulangan pemanggilan alat, bukan hanya setelah eksekusi agen terluar. Teruskan penggunaan sesi yang sama untuk mempertahankan riwayat dalam loop tersebut dan status penyedia konteks bawaan.

create_harness_agent secara default menetapkan history_provider ke InMemoryHistoryProvider(). Teruskan HistoryProvider kustom melalui history_provider= saat 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 untuk setiap panggilan layanan, sehingga penyedia riwayat yang dikonfigurasi menyimpan setiap panggilan model di dalam loop alat. Sesi juga diperlukan oleh middleware persetujuan alat bawaan; gunakan kembali dan pulihkan sesi tersebut untuk mempertahankan status persetujuan dan 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 dihosting sendiri, AgentSessionStore dapat memuat dan menyimpan sesi menggunakan ID kelanjutan sebagai bagian dari pemrosesan permintaan. Ini berbeda dari mempertahankan sesi secara manual dan mengonfigurasi penyedia riwayat. Lihat aplikasi Agent Framework yang di-host sendiri.

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.

Penting

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