Session

AgentSession je kontejner stavu konverzace používaný napříč spuštěními agenta.

Co AgentSession obsahuje

Pole	Purpose
StateBag	Kontejner libovolného stavu pro tuto relaci

Jazyk C# AgentSession je abstraktní základní třída. Konkrétní implementace (vytvořené prostřednictvím CreateSessionAsync()) můžou dodat další stav, například ID pro úložiště historie vzdáleného chatu, když je použita služba spravovaná historie.

Pole	Purpose
session_id	Místní jedinečný identifikátor pro tuto relaci
service_session_id	Identifikátor relace vzdálené služby, například ID konverzace nebo odpovědi, při použití historie spravované službou
state	Proměnlivý slovník sdílený s poskytovateli kontextu/historie

Pole	Purpose
agent.Session	Kontejner stavu typu klíč–hodnota vázaný na konverzaci

Relace poskytují úložiště typu klíč-hodnota:

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

Vymezení rozsahu ID relace služby

Při použití historie spravované službou může relace obsahovat identifikátor relace vystavený službou. Například OpenAI Responses může používat ID odpovědi ve formátu resp_* jako previous_response_id a rozhraní OpenAI Conversations API může jako konverzaci používat ID konverzace conv_*.

OpenAI ve výchozím nastavení váže tato ID na příslušný klíč rozhraní API nebo projekt. To obvykle stačí, když tento klíč nebo projekt už odpovídají hranici aplikace, jako je aplikace s jedním uživatelem nebo samostatný klíč nebo projekt na tenanta. Rizikovým hostovaným vzorem je používání jednoho podkladového klíče nebo projektu pro více koncových uživatelů, vracení nezpracovaných ID ze strany služby klientům a přijímání těchto ID zpět bez ověření vlastnictví. V hostovaných nebo víceuživatelových aplikacích, které opakovaně používají jeden záložní klíč nebo projekt, nezachází s service_session_idprevious_response_idhranicemi autorizace koncového uživatele ani conversation/conversation_id jako s hranicemi autorizace koncového uživatele. Uložte identifikátory na straně služby do důvěryhodného úložiště aplikace, přiřaďte identifikátory relací viditelné pro klienta k těmto identifikátorům na straně služby a před obnovením konverzace ověřte autentizovaného uživatele nebo tenanta.

Předdefinovaný vzor použití

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

Použití relací s agentem Harness

Harness Agent používá stejný AgentSession životní cyklus popsaný výše. Opakovaně používejte jednu relaci najednou, takže historie chatu a funkce založené na relacích – například todos, provozní režim, paměť souborů, schválení nástrojů a stav úloh na pozadí – zůstanou připojené. Serializujte relaci, pokud má daný stav přetrvat restart procesu.

Výchozí hodnotou HarnessAgent je InMemoryChatHistoryProvider. Nahraďte jej pomocí HarnessAgentOptions.ChatHistoryProvider, když má historie používat jiné úložiště. AsHarnessAgent(options) je zkratka pro vytváření 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);

Po každém volání modelu ve smyčce pro volání nástrojů zůstane po každém volání modelu zachována místní historie chatu, a to nejen po spuštění vnějšího agenta. Pokračujte předáním stejné relace, aby se zachovala historie in-loop a stav výchozích zprostředkovatelů kontextu.

create_harness_agent nastaví history_provider na InMemoryHistoryProvider() jako výchozí. Předejte vlastní HistoryProvider přes history_provider=, když historie musí používat jiné úložiště.

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)

Tento nástroj vyžaduje trvalost historie volání jednotlivých služeb, takže nakonfigurovaný poskytovatel historie ukládá každé volání modelu do smyčky nástrojů. Výchozí middleware pro schvalování nástrojů také vyžaduje relaci; znovu ji použijte a obnovte, aby se zachoval stav schválení a poskytovatele kontextu.

Harness Agent není v sadě Go SDK momentálně k dispozici. Použijte vzorec běžné relace uvedený výše.

Vytvoření relace z existujícího ID konverzace služby

Vytvoření nové relace z existujícího ID konverzace se liší podle typu agenta. Tady je několik příkladů.

Při použití ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Při použití A2AAgent

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

Tuto možnost použijte, pokud již backingová služba má stav konverzace.

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

V hostovaných aplikacích po ověření aktuálního uživatele nebo tenanta načtěte <service-conversation-id> z úložiště vlastněného aplikací. Vyhněte se přijímání nezpracovaných identifikátorů služby od klienta, pokud jste nejprve neověřili, že volající je vlastníkem dané konverzace.

Serializace a obnovení

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

V samostatně hostované aplikaci může AgentSessionStore v rámci zpracování požadavku načítat a ukládat relace pomocí ID pokračování. To se liší od ručního uchovávání relace a konfigurace poskytovatele historie. Viz samostatně hostované aplikace Agent Framework.

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

Úplný příklad najdete v ukázce perzistentní konverzace.

Důležité

Relace jsou specifické pro konkrétní agenty a služby. Opětovné použití relace s jinou konfigurací agenta nebo poskytovatelem může vést k neplatnému kontextu. Pokud serializovaná relace obsahuje ID relace na straně služby, obnovte ji pouze pro uživatele aplikace nebo tenanta, který vlastní toto ID.

Další kroky

Zprostředkovatelé kontextu