Session

AgentSession è il contenitore dello stato della conversazione usato tra le esecuzioni dell'agente.

Che cosa AgentSession contiene

Campo Scopo
StateBag Contenitore di stato arbitrario per questa sessione

C# AgentSession è una classe base astratta. Le implementazioni concrete (create tramite CreateSessionAsync()) possono aggiungere uno stato aggiuntivo, ad esempio un ID per l'archiviazione della cronologia di chat remota, quando viene usata la cronologia gestita dal servizio.

Campo Scopo
session_id Identificatore univoco locale per questa sessione
service_session_id Identificatore di sessione del servizio remoto, ad esempio una conversazione o un ID risposta, quando viene usata la cronologia gestita dal servizio
state Dizionario modificabile condiviso con provider di contesto/cronologia
Campo Scopo
agent.Session Contenitore di stato chiave-valore associato a una conversazione

Le sessioni forniscono un'archiviazione tipizzata di coppie chiave-valore:

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

Definizione dell'ambito dell'ID di sessione del servizio

Quando si usa la cronologia gestita dal servizio, una sessione può contenere un identificatore di sessione rilasciato dal servizio. Ad esempio, le risposte di OpenAI possono usare un resp_* ID della risposta come previous_response_id, e l'API OpenAI Conversations può usare un conv_* ID della conversazione come la conversazione.

OpenAI associa questi ID, per impostazione predefinita, alla chiave API o al progetto sottostante. Questo è in genere sufficiente quando tale chiave o progetto corrisponde già al limite dell'applicazione, ad esempio un'app a utente singolo o una chiave/progetto separato per tenant. La configurazione hosted rischiosa consiste nell’usare un’unica chiave sottostante o un unico progetto per più utenti finali, nel restituire ai client ID grezzi del servizio e nell’accettare tali ID di ritorno senza verificarne l’appartenenza. Nelle app ospitate o multiutente che riutilizzano un'unica chiave o progetto sottostante, non considerare service_session_id, previous_response_id o conversation/conversation_id come confini di autorizzazione per l'utente finale. Archiviare gli ID lato servizio in un'archiviazione attendibile dell'applicazione, associare gli ID di sessione visibili al client a tali ID lato servizio e verificare l'utente o il tenant autenticato prima di riprendere una conversazione.

Modello di utilizzo predefinito

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

Creare una sessione da un ID di conversazione di servizio esistente

La creazione di una nuova sessione da un ID conversazione esistente varia in base al tipo di agente. Ecco alcuni esempi.

Quando si utilizza ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Quando si usa un oggetto A2AAgent

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

Usare questa opzione quando il servizio di backup ha già lo stato della conversazione.

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

Nelle app ospitate, recupera <service-conversation-id> dall'archivio di proprietà dell'applicazione dopo aver verificato l'utente o il tenant corrente. Evitare di accettare ID lato servizio non elaborati da un client, a meno che non si verifichi prima di tutto che il chiamante sia proprietario della conversazione.

Serializzazione e ripristino

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

Per un esempio completo, vedere l'esempio di conversazione persistente .

Importante

Le sessioni sono specifiche dell'agente o del servizio. Il riutilizzo di una sessione con una configurazione o un provider dell'agente diverso può causare un contesto non valido. Se la sessione serializzata contiene un ID sessione lato servizio, ripristinarlo solo per l'utente dell'applicazione o il tenant proprietario di tale ID.

Passaggi successivi

Provider di contesto

  • Last updated on