Session

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

Apa yang AgentSession berisi

Bidang Tujuan
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.

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

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

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 selanjutnya

Penyedia Konteks

  • Last updated on