Storage

L'archiviazione controlla la posizione della cronologia delle conversazioni, quanta cronologia viene caricata e come le sessioni possono essere riprese in modo affidabile.

Modalità di archiviazione predefinite

Agent Framework supporta due normali modalità di archiviazione:

Modalità	Cosa viene archiviato	Utilizzo tipico
Stato locale della sessione	Cronologia completa della chat in AgentSession.state (ad esempio tramite InMemoryHistoryProvider)	Servizi che non richiedono la persistenza della conversazione sul lato server
Archiviazione gestita dal servizio	Stato della conversazione nel servizio; AgentSession.service_session_id fa riferimento a esso	Servizi con supporto per conversazioni persistenti native

Archiviazione della cronologia delle chat in memoria

Quando un provider non richiede la cronologia delle chat sul lato server, Agent Framework mantiene la cronologia in locale nella sessione e invia messaggi pertinenti in ogni esecuzione.

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)

Riduzione delle dimensioni della cronologia in memoria

Se la cronologia aumenta troppo per i limiti del modello, applicare un riduttore.

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

Annotazioni

La configurazione del reducer si applica ai provider di cronologia in memoria. Per la cronologia gestita dal servizio, il comportamento di riduzione è specifico del provider o del servizio.

Archiviazione gestita dal servizio

Quando il servizio gestisce la cronologia delle conversazioni, la sessione archivia un identificatore di conversazione 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)

Modello di archiviazione di terze parti

Per la cronologia basata su database/Redis/BLOB, implementare un provider di cronologia personalizzato.

Indicazioni chiave:

• Archiviare i messaggi all'interno di una chiave con ambito sessione.
• Mantenere la cronologia restituita entro i limiti del contesto del modello.
• Rendere persistenti gli identificatori specifici del provider in session.state.
• In Python, un solo provider di cronologia deve usare 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)

Mantenimento delle sessioni tra riavvii

Rendere persistente l'intero AgentSession, non solo il testo del messaggio.

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

Considerarlo AgentSession come oggetto di stato opaco e ripristinarlo con la stessa configurazione agente/provider che l'ha creata.

Suggerimento

Utilizzare un provider di cronologia audit/eval supplementare (load_messages=False, store_context_messages=True) per acquisire il contesto arricchito e le informazioni di input/output senza influenzare il caricamento della cronologia principale.

Passaggi successivi

Esecuzione di agenti