Armazenamento

O armazenamento controla onde reside o histórico das conversas, quanto histórico é carregado e com que fiabilidade as sessões podem ser retomadas.

Modos de armazenamento incorporados

O Agent Framework suporta dois modos regulares de armazenamento:

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

Armazenamento do histórico de bate-papo na memória

Quando um fornecedor não exige 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)

Redução do tamanho do histórico em memória

Se o histórico crescer demasiado para os 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 aplica-se a fornecedores de histórico em memória. Para o histórico de gestão de serviços, o comportamento de redução é específico do fornecedor/serviço.

Armazenamento gerido por serviços

Quando o serviço gere o histórico de conversas, a sessão armazena um identificador remoto de conversa.

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 histórico suportado por bases de dados/Redis/blobs, implemente um provedor de histórico personalizado.

Orientações principais:

• Armazenar mensagens sob uma chave com âmbito de sessão.
• Mantenha o histórico devolvido dentro dos limites do contexto do modelo.
• Persistir identificadores específicos do fornecedor em session.state.
• Em Python, apenas um fornecedor 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)

Sessões persistentes ao longo dos reinícios

Mantenha o texto completo AgentSession, não apenas 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/fornecedor que o criou.

Sugestão

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

Próximos passos

Agentes em execução