Armazenamento

Controles de armazenamento determinam onde o histórico de conversas reside, quanto do histórico é carregado e quão confiavelmente as sessões podem ser retomadas.

Modos de armazenamento internos

O Agent Framework dá suporte a dois modos de armazenamento regulares:

Modo	O que é armazenado	Uso típico
Estado da sessão local	Histórico de chat completo em AgentSession.state (por exemplo, via InMemoryHistoryProvider)	Serviços que não exigem persistência de conversa do lado do servidor
Armazenamento gerenciado pelo serviço	Estado da conversa no serviço; AgentSession.service_session_id aponta para ele	Serviços com suporte de conversa persistente nativa

Armazenamento de histórico de chat na memória

Quando um provedor não requer o histórico de chat do lado do servidor, o Agent Framework mantém o histórico localmente na sessão e envia mensagens relevantes em cada execução.

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)

Reduzindo o tamanho do histórico na memória

Se o histórico crescer além dos limites do modelo, aplique um redutor.

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))
    });

Observação

A configuração do redutor se aplica a provedores de histórico na memória. Para o histórico gerenciado pelo serviço, o comportamento de redução é específico do provedor/serviço.

Armazenamento gerenciado pelo serviço

Quando o serviço gerencia o histórico de conversas, a sessão armazena um identificador de conversa 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)

Padrão de armazenamento de terceiros

Para um histórico suportado por banco de dados/Redis/blob, implemente um provedor de histórico personalizado.

Diretrizes principais:

• Armazene mensagens em uma chave com escopo de sessão.
• Mantenha o histórico retornado dentro dos limites de contexto do modelo.
• Persistir identificadores específicos do provedor em session.state.
• No Python, apenas um provedor de histórico deve 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)

Persistência de sessões entre reinicializações

Persista o conteúdo completo do AgentSession, não apenas o texto da mensagem.

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 um objeto de estado opaco e restaure-o com a mesma configuração de agente/provedor que o criou.

Dica

Use um provedor de histórico de auditoria/avaliação adicional (load_messages=False, store_context_messages=True) para capturar contexto enriquecido mais entrada/saída sem afetar o carregamento do histórico primário.

Próximas etapas

Agentes em execução