Session

AgentSession es el contenedor de estado de conversación que se usa en las ejecuciones del agente.

¿Qué contiene AgentSession?

Campo Propósito
StateBag Contenedor de estado arbitrario para esta sesión

C# AgentSession es una clase base abstracta. Las implementaciones concretas (creadas a través de CreateSessionAsync()) pueden agregar estado adicional, por ejemplo, un identificador para el almacenamiento del historial de chat remoto, cuando se utiliza el historial administrado por el servicio.

Campo Propósito
session_id Identificador único local para esta sesión
service_session_id Identificador de sesión del servicio remoto, como un ID de conversación o de respuesta, cuando se usa el historial gestionado por el servicio
state Diccionario mutable compartido con proveedores de contexto o historial
Campo Propósito
agent.Session Contenedor de estado clave-valor vinculado a una conversación

Las sesiones proporcionan almacenamiento tipado de pares clave-valor:

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

Ámbito del identificador de sesión de servicio

Cuando se usa el historial administrado por el servicio, una sesión puede contener un identificador de sesión emitido por el servicio. Por ejemplo, las respuestas de OpenAI pueden usar un resp_* identificador de respuesta como previous_response_idy la API de conversaciones de OpenAI puede usar un conv_* identificador de conversación como conversación.

OpenAI limita estos identificadores a la clave de API de respaldo o al proyecto de forma predeterminada. Esto suele ser suficiente cuando esa clave o proyecto ya coincide con el perímetro de la aplicación, como en una aplicación de un solo usuario o con una clave o un proyecto independiente por inquilino. El patrón de alojamiento arriesgado consiste en usar una única clave subyacente o un único proyecto para varios usuarios finales, devolver a los clientes ID sin procesar del servicio y aceptar de nuevo esos ID sin verificar su titularidad. En las aplicaciones hospedadas o multiusuario que reutilizan una clave de respaldo o proyecto, no traten service_session_id, previous_response_ido conversation/conversation_id como límites de autorización del usuario final. Almacene los identificadores del lado del servicio en el almacenamiento de aplicaciones de confianza, asigne identificadores de sesión visibles para el cliente a esos identificadores del lado del servicio y compruebe el usuario o inquilino autenticado antes de reanudar una conversación.

Patrón de uso integrado

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

Creación de una sesión a partir de un identificador de conversación de servicio existente

Crear una nueva sesión a partir de un identificador de conversación existente varía según el tipo de agente. Estos son algunos ejemplos.

Cuando se usa ChatClientAgent

AgentSession session = await chatClientAgent.CreateSessionAsync(conversationId);

Cuando se usa un A2AAgent

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

Úselo cuando el servicio de respaldo ya tenga el estado de conversación.

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

En las aplicaciones hospedadas, resuelva <service-conversation-id> desde el almacenamiento propiedad de la aplicación después de comprobar el usuario o inquilino actual. Evite aceptar IDs en bruto del lado del servicio procedentes de un cliente, a menos que primero compruebe que quien realiza la llamada es propietario de la conversación.

Serialización y restauración

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

Consulte el ejemplo de conversación persistente para obtener un ejemplo completo.

Importante

Las sesiones son específicas del agente o servicio. La reutilización de una sesión con una configuración o proveedor de agente diferente puede provocar un contexto no válido. Si la sesión serializada contiene un identificador de sesión del lado del servicio, restáurelo solo para el usuario de la aplicación o el inquilino que posee ese identificador.

Pasos siguientes

Proveedores de contexto

  • Last updated on