Session

AgentSession 是跨代理執行的對話狀態容器。

包含什麼內容AgentSession

領域 目標
StateBag 此會話的任意狀態容器

C# AgentSession 是一個抽象基底類別。 具體實作（透過 CreateSessionAsync() 建立）可能會新增額外狀態，例如在使用服務管理的聊天歷史時，為遠端聊天歷史儲存的 ID。

領域 目標
session_id 此會話的本地唯一識別碼
service_session_id 當使用服務管理歷史時，遠端服務會話識別碼，例如對話或回應 ID。
state 與上下文/歷史提供者共享的可變字典
領域 目標
agent.Session 綁定於對話的鍵值狀態容器

會話提供有型別的鍵值儲存：

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

服務會話識別碼範圍

當使用服務管理歷史時，會話可以包含服務發出的會話識別碼。 例如，OpenAI 回應可能會使用 resp_* 回應 ID 為 previous_response_id，而 OpenAI 對話 API 則可能使用 conv_* 對話 ID 作為對話內容。

OpenAI 預設會將這些 ID 範圍設定為支援的 API 金鑰或專案。 當該金鑰或專案已經與應用程式邊界相符時，這通常就足夠了，例如單一使用者應用程式或每個租戶的獨立金鑰/專案。 風險較高的託管模式是為多個終端使用者使用同一組後備金鑰或專案，將原始服務端 ID 傳達給客戶端，然後在不檢查擁有權的情況下接受這些 ID。 在重用單一後備金鑰或專案的託管或多使用者應用程式中，不會將 service_session_id、 previous_response_id或 conversation/conversation_id 視為終端使用者授權邊界。 將服務端 ID 儲存在受信任的應用程式儲存中，將客戶端可見的會話 ID 對應到這些服務端 ID，並在恢復對話前驗證已認證的使用者或租戶。

內建使用模式

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

從現有的服務對話 ID 建立會話

從現有的對話識別碼建立新的會話，會因代理類型而有所不同。 以下是一些範例。

使用 ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

當使用 A2AAgent

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

當備份服務已經有對話狀態時，使用這個方法。

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

在託管應用程式中，請在檢查目前使用者或租戶後，從應用程式自有儲存裝置解析 <service-conversation-id> 。 除非你先驗證呼叫端是否擁有該對話，否則應避免接受來自用戶端的原始伺服器端 ID。

序列化與還原

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

完整範例請參考 持續對話範例 。

這很重要

會話是針對特定代理或服務的。 重複使用不同代理設定或提供者的會話可能會導致上下文無效。 如果序列化會話包含服務端會話 ID，則僅還原擁有該 ID 的應用程式使用者或租戶的 ID。

後續步驟

情境提供者

  • Last updated on