Session

AgentSession ist der Unterhaltungsstatuscontainer, der über Agent-Ausführungen hinweg verwendet wird.

Was AgentSession enthält

Feld	Purpose
StateBag	Beliebiger Statuscontainer für diese Sitzung

C# AgentSession ist eine abstrakte Basisklasse. Konkrete Implementierungen (erstellt über CreateSessionAsync()) können zusätzlichen Zustand hinzufügen, z. B. eine ID für den Speicher des Remotechatverlaufs, wenn der vom Dienst verwaltete Verlauf verwendet wird.

Feld	Purpose
session_id	Lokaler eindeutiger Bezeichner für diese Sitzung
service_session_id	Remotedienst-Sitzungsbezeichner, z. B. eine Unterhaltungs- oder Antwort-ID, wenn ein vom Dienst verwalteter Verlauf verwendet wird
state	Veränderbares Wörterbuch, das mit Kontext-/Verlaufsanbietern geteilt wird

Feld	Purpose
agent.Session	Schlüssel-Wert-Statuscontainer, der an eine Unterhaltung gebunden ist

Sitzungen bieten einen typisierten Schlüssel-Wert-Speicher:

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

Bereichsdefinition für Dienstsitzungs-IDs

Wenn der vom Dienst verwaltete Verlauf verwendet wird, kann eine Sitzung einen vom Dienst ausgestellten Sitzungsbezeichner enthalten. OpenAI Responses können beispielsweise eine resp_* Response-ID als previous_response_id verwenden, und die OpenAI Conversations API kann eine conv_* Konversations-ID als Konversation verwenden.

OpenAI ordnet diese IDs standardmäßig dem zugrunde liegenden API-Schlüssel oder dem Projekt zu. Dies reicht normalerweise aus, wenn dieser Schlüssel oder Projekt bereits der Anwendungsgrenze entspricht, z. B. einer Einzelbenutzer-App oder einem separaten Schlüssel/Projekt pro Mandant. Das riskante gehostete Muster besteht darin, einen Sicherungsschlüssel oder ein Projekt für mehrere Endbenutzer zu verwenden, unformatierte dienstseitige IDs an Clients zurückzugeben und diese IDs ohne Überprüfung des Besitzes wieder zu akzeptieren. In gehosteten Apps oder Apps mit mehreren Benutzern, die einen zugrunde liegenden Schlüssel oder ein Projekt wiederverwenden, sollten service_session_id, previous_response_id oder conversation/conversation_id nicht als Autorisierungsgrenzen für Endbenutzer behandelt werden. Speichern Sie serverseitige IDs im vertrauenswürdigen Anwendungsspeicher, ordnen Sie für den Client sichtbare Sitzungs-IDs diesen serverseitigen IDs zu und überprüfen Sie den authentifizierten Benutzer oder Mandanten, bevor Sie eine Konversation wiederaufnehmen.

Integriertes Verwendungsmuster

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

Sitzungen mit dem Harness Agent verwenden

Der Harness Agent verwendet denselben oben beschriebenen AgentSession Lebenszyklus. Verwenden Sie über mehrere Dialogrunden hinweg dieselbe Sitzung, damit Chatverlauf und sitzungsgestützte Harness-Funktionen – z. B. Aufgaben, Betriebsmodus, Dateispeicher, Toolfreigaben und Status von Hintergrundaufgaben – verknüpft bleiben. Serialisieren Sie die Sitzung, wenn dieser Zustand einen Prozessneustart überleben muss.

Der Standardwert von HarnessAgent ist InMemoryChatHistoryProvider. Ersetzen Sie dies über HarnessAgentOptions.ChatHistoryProvider, wenn der Verlauf einen anderen Speicher verwenden muss. AsHarnessAgent(options) ist die Kurzform für das Erstellen von 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);

Das Harness speichert den lokalen Chatverlauf nach jedem Modellaufruf innerhalb einer Schleife von Toolaufrufen, nicht nur nach der äußeren Agent-Ausführung. Übergeben Sie weiterhin dieselbe Sitzung, um diesen In-Loop-Verlauf und den Status der Standardkontextanbieter beizubehalten.

create_harness_agent setzt history_provider standardmäßig auf InMemoryHistoryProvider(). Übergeben Sie einen benutzerdefinierten HistoryProvider über history_provider=, wenn der Verlauf einen anderen Speicher verwenden muss.

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)

Das Harness erfordert eine dauerhafte Speicherung des Verlaufs pro Dienstaufruf, sodass der konfigurierte Verlaufsanbieter jeden Modellaufruf innerhalb einer Toolschleife speichert. Eine Sitzung ist auch für die standardmäßige Tool-Genehmigungs-Middleware erforderlich; verwenden Sie sie erneut und stellen Sie sie wieder her, um den Genehmigungsstatus und den Status des Kontextanbieters beizubehalten.

Der Harness Agent ist derzeit nicht im Go-SDK verfügbar. Verwenden Sie das oben gezeigte normale Sitzungsmuster.

Erstellen einer Sitzung aus einer vorhandenen Service-Gesprächs-ID

Das Erstellen einer neuen Sitzung aus einer vorhandenen Unterhaltungs-ID variiert je nach Agent-Typ. Im Folgenden finden Sie einige Beispiele hierfür.

Bei der Verwendung von ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Bei Verwendung einer A2AAgent

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

Verwenden Sie dies, wenn der unterstützende Dienst bereits über einen Gesprächszustand verfügt.

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

Lösen Sie in gehosteten Apps <service-conversation-id> aus dem anwendungseigenen Speicher auf, nachdem Sie den aktuellen Benutzer oder Mandanten überprüft haben. Vermeiden Sie es, unformatierte dienstseitige IDs von einem Client zu akzeptieren, es sei denn, Sie überprüfen zuerst, ob der Aufrufer der Besitzer der Unterhaltung ist.

Serialisierung und Wiederherstellung

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

In einer selbstgehosteten Anwendung kann ein AgentSessionStore Sitzungen über eine Fortsetzungs-ID im Rahmen der Anforderungsverarbeitung laden und speichern. Dies unterscheidet sich von der manuellen dauerhaften Speicherung einer Sitzung und von der Konfiguration eines Anbieters für den Verlauf. Siehe Self-Host Agent Framework-Anwendungen.

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

Siehe das Beispiel für eine persistente Unterhaltung für ein vollständiges Beispiel.

Important

Sitzungen sind agent-/dienstspezifisch. Das Erneute Verwenden einer Sitzung mit einer anderen Agentkonfiguration oder einem anderen Anbieter kann zu ungültigem Kontext führen. Wenn die serialisierte Sitzung eine dienstseitige Sitzungs-ID enthält, stellen Sie sie nur für den Anwendungsbenutzer oder Mandanten wieder her, der diese ID besitzt.

Nächste Schritte

Kontextanbieter