Session

AgentSession is de gespreksstatuscontainer die wordt gebruikt voor agentruns.

Wat AgentSession bevat

Veld	Purpose
StateBag	Willekeurige statuscontainer voor deze sessie

De C# AgentSession is een abstracte basisklasse. Concrete implementaties (gemaakt via CreateSessionAsync()) kunnen extra statussen toevoegen, bijvoorbeeld een id voor externe chatgeschiedenisopslag wanneer servicebeheerde geschiedenis wordt gebruikt.

Veld	Purpose
session_id	Lokale unieke id voor deze sessie
service_session_id	Id van een externe servicesessie, zoals een gespreks-id of respons-id, wanneer door de service beheerde geschiedenis wordt gebruikt
state	Veranderlijke woordenlijst die wordt gedeeld met context-/geschiedenisproviders

Veld	Purpose
agent.Session	Sleutelwaardestatuscontainer gekoppeld aan een gesprek

Sessies bieden getypte sleutel-waardeopslag:

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

Afbakening van de sessie-id van de service

Wanneer de door de service beheerde geschiedenis wordt gebruikt, kan een sessie een door de service uitgegeven sessie-id bevatten. OpenAI-antwoorden kunnen bijvoorbeeld een resp_* antwoord-id gebruiken als previous_response_id, en de OpenAI Conversations-API kan een conv_* gespreks-id als gesprek gebruiken.

OpenAI beperkt deze ID's standaard tot de onderliggende API-sleutel of het project. Dit is meestal voldoende wanneer die sleutel of het project al overeenkomt met de toepassingsgrens, zoals een app met één gebruiker of een afzonderlijk sleutel/project per tenant. Het risicovolle gehoste patroon gebruikt één onderliggende sleutel of één project voor meerdere eindgebruikers, geeft ruwe service-ID's door aan cliënten en accepteert die ID's vervolgens weer zonder te controleren of ze wel van de betreffende gebruiker zijn. Behandel in gehoste apps of apps voor meerdere gebruikers die één onderliggende sleutel of project hergebruiken, service_session_id, previous_response_id of conversation/conversation_id niet als autorisatiegrenzen voor eindgebruikers. Sla ID's aan de serverzijde op in vertrouwde applicatieopslag, koppel client-zichtbare sessie-ID's aan die ID's aan de serverzijde en controleer de geauthenticeerde gebruiker of tenant voordat u een gesprek hervat.

Ingebouwd gebruikspatroon

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

Sessies gebruiken met Harness Agent

Harness Agent maakt gebruik van dezelfde AgentSession levenscyclus die hierboven wordt beschreven. Gebruik één sessie om de beurt opnieuw, zodat functies voor chatgeschiedenis en functies voor het gebruik van sessies, zoals todos, bedrijfsmodus, bestandsgeheugen, goedkeuringen van hulpprogramma's en status van achtergrondtaken, verbonden blijven. Serialiseer de sessie wanneer die status moet overleven tijdens het opnieuw opstarten van een proces.

HarnessAgent wordt standaard ingesteld op InMemoryChatHistoryProvider. Vervang deze door HarnessAgentOptions.ChatHistoryProvider wanneer de geschiedenis een andere winkel moet gebruiken. AsHarnessAgent(options) is afkorting voor constructie 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);

Het harnas blijft de lokale chatgeschiedenis behouden na elke modelaanroep binnen een lus voor het aanroepen van hulpprogramma's, niet alleen nadat de buitenste agent is uitgevoerd. Ga door met het doorgeven van dezelfde sessie om die in-loopgeschiedenis en de status van de standaardcontextproviders te behouden.

create_harness_agent is history_provider standaard ingesteld op InMemoryHistoryProvider(). Geef een aangepaste HistoryProvider door history_provider= wanneer de geschiedenis een andere winkel moet gebruiken.

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)

De harnas vereist persistentie per service-oproepgeschiedenis, dus de geconfigureerde geschiedenisprovider slaat elke modeloproep op in een toollus. Een sessie is ook vereist voor de standaard middleware voor het goedkeuren van hulpprogramma's; hergebruik en herstel deze om de status van goedkeuring en contextprovider te behouden.

Harness Agent is momenteel niet beschikbaar in de Go SDK. Gebruik het normale sessiepatroon dat hierboven wordt weergegeven.

Een sessie maken op basis van een bestaande servicegespreks-id

Het maken van een nieuwe sessie op basis van een bestaande gespreks-id verschilt per agenttype. Dit zijn enkele voorbeelden.

Bij het gebruik van ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Wanneer u een A2AAgent

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

Gebruik deze optie wanneer de back-upservice al de gespreksstatus heeft.

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

In gehoste apps haalt u <service-conversation-id> op uit opslag die eigendom is van de toepassing nadat u de huidige gebruiker of tenant hebt gecontroleerd. Accepteer geen ruwe service-side-ID's van een client, tenzij u eerst verifieert dat de aanroeper eigenaar is van de conversatie.

Serialisatie en herstel

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

Zie het persistente gespreksvoorbeeld voor een volledig voorbeeld.

Important

Sessies zijn agent/servicespecifiek. Het opnieuw gebruiken van een sessie met een andere agentconfiguratie of -provider kan leiden tot ongeldige context. Als de geserialiseerde sessie-id een sessie-id aan de servicezijde bevat, herstelt u deze alleen voor de toepassingsgebruiker of tenant die eigenaar is van die id.

Volgende stappen 

Contextproviders