Session

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

Che cosa AgentSession contiene

Campo	Finalità
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	Finalità
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	Finalità
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 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. Un modello ospitato rischioso consiste nell'usare un'unica chiave o un unico progetto sottostante per più utenti finali, restituire ai client gli ID lato servizio non elaborati e accettare nuovamente tali ID senza verificarne la proprietà. 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()

Usare le sessioni con Harness Agent

Harness Agent usa lo stesso AgentSession ciclo di vita descritto in precedenza. Riutilizzare una sessione tra turni in modo che la cronologia delle chat e le funzionalità di harness supportate dalla sessione, ad esempio todos, modalità operativa, memoria file, approvazioni degli strumenti e stato dell'attività in background, rimangano connessi. Serializzare la sessione quando tale stato deve sopravvivere a un riavvio del processo.

Il valore predefinito di HarnessAgent è InMemoryChatHistoryProvider. Sostituirlo tramite HarnessAgentOptions.ChatHistoryProvider quando la cronologia deve usare un altro archivio. AsHarnessAgent(options) è una sintassi abbreviata per creare 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);

L'harness rende persistente la cronologia della chat locale dopo ogni chiamata al modello all'interno di un ciclo di chiamata agli strumenti, non solo dopo l'esecuzione esterna dell'agente. Continuare a passare la stessa sessione per mantenere la cronologia all'interno del ciclo e lo stato dei provider di contesto predefiniti.

create_harness_agent imposta history_provider su InMemoryHistoryProvider() per impostazione predefinita. Passare un elemento HistoryProvider personalizzato tramite history_provider= quando la cronologia deve usare un altro archivio.

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)

L'harness richiede la persistenza della cronologia per chiamata al servizio, quindi il provider di cronologia configurato salva ogni chiamata al modello all'interno di un ciclo degli strumenti. Una sessione è richiesta anche dal middleware predefinito di approvazione degli strumenti; riutilizzarla e ripristinarla per mantenere lo stato delle approvazioni e dei provider di contesto.

L'agente Harness non è attualmente disponibile in Go SDK. Usare il modello di sessione normale illustrato in precedenza.

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, risolvere <service-conversation-id> dall'archiviazione di proprietà dell'applicazione dopo aver verificato l'utente o il tenant corrente. Evitare di accettare da un client ID lato servizio non elaborati senza prima verificare che il chiamante sia il proprietario della conversazione.

Serializzazione e ripristino

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

In un'applicazione ospitata autonomamente, un AgentSessionStore può caricare e salvare le sessioni tramite un ID di continuazione durante l'elaborazione della richiesta. Questa operazione è diversa dalla persistenza manuale di una sessione e dalla configurazione di un provider di cronologia. Vedere Applicazioni Agent Framework self-hosted.

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