Session

AgentSession é o contentor de estado de conversa usado entre execuções de agentes.

O que AgentSession contém

Campo Propósito
StateBag Contentor de estado arbitrário para esta sessão

O C# AgentSession é uma classe base abstrata. Implementações concretas (criadas via CreateSessionAsync()) podem adicionar estado adicional, por exemplo, um id para armazenamento remoto do histórico de chat, quando é usado histórico gerido por serviços.

Campo Propósito
session_id Identificador local único para esta sessão
service_session_id Identificador de sessão remota do serviço, como um ID de conversa ou de resposta, quando é utilizado o histórico gerido pelo serviço
state Dicionário mutável partilhado com fornecedores de contexto/história
Campo Propósito
agent.Session Contentor de estado de chave-valor associado a uma conversa

As sessões fornecem armazenamento chave-valor digitado:

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

Delimitação do ID da sessão de serviço

Quando o histórico gerido por serviços é utilizado, uma sessão pode conter um identificador de sessão emitido pelo serviço. Por exemplo, o OpenAI Responses pode usar um resp_* identificador de resposta como previous_response_id, e a API OpenAI Conversations pode usar um conv_* identificador de conversa como identificador da conversa.

Por defeito, a OpenAI associa estes IDs à chave da API subjacente ou ao projeto. Isto é geralmente suficiente quando essa chave ou projeto já corresponde ao limite da aplicação, como uma aplicação de utilizador único ou uma chave/projeto separado por inquilino. O padrão de alojamento arriscado consiste em usar uma única chave subjacente ou um único projeto para vários utilizadores finais, devolver diretamente aos clientes IDs internos brutos do serviço e aceitar esses IDs de volta sem confirmar a que utilizador pertencem. Em aplicações alojadas ou multiutilizadores que reutilizam uma chave de apoio ou projeto, não tratam service_session_id, previous_response_id, nem conversation/conversation_id como limites de autorização do utilizador final. Armazene os IDs internos do serviço num armazenamento fiável da aplicação, associe os IDs de sessão visíveis para o cliente a esses IDs internos do serviço e verifique o utilizador ou locatário autenticado antes de retomar uma conversa.

Padrão de uso incorporado

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

Criar uma sessão a partir de um ID de conversa de serviço existente

Criar uma nova sessão a partir de um ID de conversa existente varia consoante o tipo de agente. Eis alguns exemplos.

Ao usar ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Ao usar um A2AAgent

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

Use isto quando o serviço de suporte já tiver estado de conversação.

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

Em aplicações alojadas, resolva <service-conversation-id> a partir do armazenamento pertencente à aplicação, depois de verificar o utilizador ou inquilino atual. Evite aceitar IDs brutos do servidor provenientes de um cliente, a menos que verifique primeiro se o autor da chamada é o proprietário da conversa.

Serialização e restauro

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

Veja o exemplo de conversa persistente para um exemplo completo.

Importante

As sessões são específicas de cada agente/serviço. Usar novamente uma sessão com uma configuração de agente ou fornecedor diferente pode levar a um contexto inválido. Se a sessão serializada contiver um ID de sessão do lado do serviço, restaure-o apenas para o utilizador da aplicação ou inquilino que detém esse ID.

Próximos passos

Fornecedores de Contexto

  • Last updated on