Session

AgentSession ist der Unterhaltungszustandscontainer, der über Agentendurchläufe hinweg verwendet wird.

Was AgentSession enthält

Feld Zweck
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 Zweck
session_id Lokaler eindeutiger Bezeichner für diese Sitzung
service_session_id Kennung einer Remote-Dienstsitzung, z. B. eine Konversations- oder Antwort-ID, wenn ein dienstseitig verwalteter Verlauf verwendet wird
state Für Kontext-/Verlaufsanbieter freigegebenes änderbares Wörterbuch
Feld Zweck
agent.Session Schlüsselwertstatuscontainer, der an eine Unterhaltung gebunden ist

Sitzungen bieten typgesteuerten Schlüsselwertspeicher:

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

Gültigkeitsbereich der Dienst-Sitzungs-ID

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 riskobehaftete Hosting-Muster verwendet einen gemeinsamen zugrunde liegenden Schlüssel oder ein Projekt für mehrere Endnutzer, gibt unveränderte serverseitige IDs an Clients zurück und nimmt diese IDs anschließend wieder entgegen, ohne ihre Zugehörigkeit zu prüfen. 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()

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

Erstellen einer neuen Sitzung aus einer vorhandenen Unterhaltungs-ID variiert je nach Agenttyp. Hier sind einige Beispiele.

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> im anwendungseigenen Speicher auf, nachdem der aktuelle Benutzer oder Mandant überprüft wurde. Akzeptieren Sie keine rohen serverseitigen IDs von einem Client, es sei denn, Sie verifizieren zuvor, dass dem Aufrufer die Konversation gehört.

Serialisierung und Wiederherstellung

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

Tipp

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

Von Bedeutung

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

  • Last updated on