Session

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

Co AgentSession obsahuje

Pole	Účel
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	Účel
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	Účel
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()

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

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