Storage

El almacenamiento controla dónde reside el historial de conversaciones, cuánto historial se carga y cómo se pueden reanudar las sesiones de forma confiable.

Modos de almacenamiento integrados

Agent Framework admite dos modos de almacenamiento normales:

Mode	Qué se almacena	Uso típico
Estado de sesión local	Historial de chat completo en AgentSession.state (por ejemplo, a través de InMemoryHistoryProvider)	Servicios que no requieren persistencia de conversación del lado servidor
Almacenamiento administrado por el servicio	Estado de conversación en el servicio; AgentSession.service_session_id apunta a él	Servicios con soporte de conversaciones persistentes nativas

Almacenamiento del historial de chat en memoria

Cuando un proveedor no requiere el historial de chat del lado servidor, Agent Framework mantiene el historial localmente en la sesión y envía mensajes pertinentes en cada ejecución.

AIAgent agent = new OpenAIClient("<your_api_key>")
    .GetChatClient(modelName)
    .AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));

// Works when in-memory storage is active.
IList<ChatMessage>? messages = session.GetService<IList<ChatMessage>>();

from agent_framework import InMemoryHistoryProvider
from agent_framework.openai import OpenAIChatClient

agent = OpenAIChatClient().as_agent(
    name="StorageAgent",
    instructions="You are a helpful assistant.",
    context_providers=[InMemoryHistoryProvider("memory", load_messages=True)],
)

session = agent.create_session()
await agent.run("Remember that I like Italian food.", session=session)

Reducción del tamaño del historial en memoria

Si el historial crece demasiado grande para los límites del modelo, aplique un reductor.

AIAgent agent = new OpenAIClient("<your_api_key>")
    .GetChatClient(modelName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "Assistant",
        ChatOptions = new() { Instructions = "You are a helpful assistant." },
        ChatHistoryProviderFactory = (ctx, ct) => new ValueTask<ChatHistoryProvider>(
            new InMemoryChatHistoryProvider(
                new MessageCountingChatReducer(20),
                ctx.SerializedState,
                ctx.JsonSerializerOptions,
                InMemoryChatHistoryProvider.ChatReducerTriggerEvent.AfterMessageAdded))
    });

Nota:

La configuración del reducer se aplica a los proveedores de historial en memoria. En el caso del historial administrado por el servicio, el comportamiento de reducción es específico del proveedor o servicio.

Almacenamiento administrado por el servicio

Cuando el servicio administra el historial de conversaciones, la sesión almacena un identificador de conversación remota.

AIAgent agent = new OpenAIClient("<your_api_key>")
    .GetOpenAIResponseClient(modelName)
    .AsAIAgent(instructions: "You are a helpful assistant.", name: "Assistant");

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate.", session));

# Rehydrate when the service already has the conversation state.
session = agent.get_session(service_session_id="<service-conversation-id>")
response = await agent.run("Continue this conversation.", session=session)

Patrón de almacenamiento de terceros

En el caso del historial respaldado por bases de datos, Redis y blob, implemente un proveedor de historial personalizado.

Guía clave:

• Almacene mensajes en una clave con ámbito de sesión.
• Mantenga el historial devuelto dentro de los límites del contexto del modelo.
• Conservar identificadores específicos del proveedor en session.state.
• En Python, solo un proveedor de historial debe usar load_messages=True.

from agent_framework.openai import OpenAIChatClient

history = DatabaseHistoryProvider(db_client)
agent = OpenAIChatClient().as_agent(
    name="StorageAgent",
    instructions="You are a helpful assistant.",
    context_providers=[history],
)

session = agent.create_session()
await agent.run("Store this conversation.", session=session)

Conservación de sesiones entre reinicios

Conserve el texto completo AgentSession, no solo del mensaje.

JsonElement serialized = agent.SerializeSession(session);
// Store serialized payload in durable storage.
AgentSession resumed = await agent.DeserializeSessionAsync(serialized);

serialized = session.to_dict()
# Store serialized payload in durable storage.
resumed = AgentSession.from_dict(serialized)

Importante

Trate AgentSession como un objeto de estado opaco y restáurelo con la misma configuración del agente o proveedor que la creó.

Sugerencia

Emplee un proveedor adicional de historial de auditoría/evaluación (load_messages=False, store_context_messages=True) para capturar un contexto enriquecido, además de entrada/salida, sin afectar la carga del historial principal.

Pasos siguientes

Agentes en ejecución