Session

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

包含什麼內容`AgentSession`

Field	Purpose
`StateBag`	此會話的任意狀態容器

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

Field	Purpose
`session_id`	此會話的本地唯一識別碼
`service_session_id`	當使用服務管理歷史時，遠端服務會話識別碼，例如對話或回應 ID。
`state`	與上下文/歷史提供者共享的可變字典

Field	Purpose
`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()

使用與 Harness Agent 的會話

Harness Agent 採用上述 AgentSession 相同的生命週期。跨回合重複使用同一會話，確保聊天歷史與會話支援的束縛功能——如待辦事項、操作模式、檔案記憶體、工具核准及背景任務狀態——都能保持連結。當該狀態必須在程序重新啟動後存活時，序列化該會話。

HarnessAgent 預設為 InMemoryChatHistoryProvider。當歷史必須使用另一家店時，再替換它 HarnessAgentOptions.ChatHistoryProvider 。 AsHarnessAgent(options) 是構造 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);

該工具套路會在每次模型呼叫後，持續保留本地聊天歷史，而非僅在外部代理執行後。繼續傳遞同一個會話，以保留該迴圈歷史及預設上下文提供者的狀態。

create_harness_agent 預設為 history_providerInMemoryHistoryProvider()。當歷史必須使用另一家店時，將一個傳統 HistoryProvider 轉讓 history_provider= 過去。

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 Agent 目前還沒有在 Go SDK 裡提供。請使用上述常見的會談模式。

從現有的服務對話 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

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

Important

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

下一步

情境提供者

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-13