Architettura della pipeline dell'agente

Gli agenti in Microsoft Agent Framework usano un'architettura della pipeline a più livelli per elaborare le richieste. Comprendere questa architettura consente di personalizzare il comportamento dell'agente aggiungendo middleware, modifiche a livello di client o provider di contesto al livello appropriato.

ChatClientAgent Pipeline

Costruisce una ChatClientAgent pipeline con tre livelli principali:

1. Middleware dell'agente : elementi Decorator facoltativi che esecuno l'agente tramite .Use() per la registrazione, la convalida o la trasformazione
2. Livello contesto : gestisce la cronologia delle chat (ChatHistoryProvider) e inserisce contesto aggiuntivo (AIContextProviders)
3. Livello client chat : IChatClient elemento con elementi decorator middleware facoltativi che gestiscono la comunicazione LLM

Quando si chiama RunAsync(), la richiesta scorre attraverso ogni livello in sequenza.

Pipeline dell'agente

La Agent classe compila una pipeline tramite la composizione di classi con due componenti principali:

Agente (componente esterno):

1. Agent Middleware + Telemetria - le classi AgentMiddlewareLayer e AgentTelemetryLayer gestiscono l'invocazione del middleware e la strumentazione OpenTelemetry
2. RawAgent - Logica dell'agente core che richiama i provider di contesto
3. Provider di contesto - Elenco unificato context_providers gestisce la cronologia e il contesto aggiuntivo

ChatClient (componente separato e intercambiabile):

1. Middleware chat e telemetria - Catena middleware facoltativa e livelli di strumentazione
2. FunctionInvocation - Gestisce il ciclo di chiamata dello strumento, richiamando il middleware della funzione + telemetria per ogni chiamata allo strumento
3. RawChatClient - Implementazione specifica del provider (Azure OpenAI, OpenAI, Anthropic e così via) che comunica con LLM

Quando si chiama run(), la richiesta passa attraverso i livelli dell'agente, quindi nella pipeline ChatClient per la comunicazione LLM.

Livello agente middleware

Il middleware agente intercetta ogni chiamata al metodo di esecuzione dell'agente, consentendo di esaminare o modificare input e output.

Aggiungere middleware usando il modello di generatore di agenti:

var middlewareAgent = originalAgent
    .AsBuilder()
    .Use(runFunc: MyAgentMiddleware, runStreamingFunc: MyStreamingMiddleware)
    .Build();

È anche possibile usare MessageAIContextProvider come middleware agente per inserire messaggi aggiuntivi nella richiesta. Funziona con qualsiasi tipo di agente, non solo ChatClientAgent:

var contextAgent = originalAgent
    .AsBuilder()
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

Questo livello avvolge l'intera esecuzione dell'agente, inclusa la risoluzione del contesto e le chiamate al client della chat. Ciò offre vantaggi, in quanto questi decoratori possono essere usati con qualsiasi tipo di agente, ad esempio A2AAgent o GitHubCopilotAgent, non solo ChatClientAgent. Ciò significa anche che i decoratori a questo livello non possono necessariamente fare ipotesi sull'agente che sta decorando, significa che è limitato alla personalizzazione o all'impatto sulle funzionalità comuni.

Aggiungere middleware durante la creazione dell'agente:

from agent_framework import Agent

agent = Agent(
    client=my_client,
    instructions="You are helpful.",
    middleware=[my_middleware_func],
)

La Agent classe eredita da AgentMiddlewareLayer, che gestisce la chiamata middleware prima di delegare alla logica dell'agente principale. Eredita inoltre da AgentTelemetryLayer che gestisce l'emissione di intervalli, eventi e metriche in un back-end OpenTelemetry configurato. Entrambi questi livelli non eseguono alcuna operazione quando non sono configurati.

Per informazioni dettagliate sui modelli di middleware e osservabilità, vedere Middleware dell'agente e Observability.

Livello contesto

Il livello di contesto viene eseguito prima di ogni chiamata LLM per compilare la cronologia dei messaggi completa e inserire un contesto aggiuntivo.

ChatClientAgent ha due tipi di provider distinti:

• ChatHistoryProvider (single) - Gestisce l'archiviazione e il recupero della cronologia delle conversazioni
• AIContextProviders (elenco): inserisce un contesto aggiuntivo come memorie, documenti recuperati o istruzioni dinamiche

var agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    ChatHistoryProvider = new InMemoryChatHistoryProvider(),
    AIContextProviders = [new MyMemoryProvider(), new MyRagProvider()],
});

L'agente chiama il metodo di ciascun provider prima di inviare messaggi al client di chat, passando l'output di ogni provider come input al provider successivo.

La Agent classe usa un elenco unificato context_providers che può includere provider di cronologia e provider di contesto:

from agent_framework import Agent, InMemoryHistoryProvider

agent = Agent(
    client=my_client,
    context_providers=[
        InMemoryHistoryProvider(),
        MyMemoryProvider(),
        MyRagProvider(),
    ],
)

Per informazioni dettagliate sui modelli di provider di contesto, vedere Provider di contesto.

Livello del client di chat

Il livello client di chat gestisce la comunicazione effettiva con il servizio LLM.

ChatClientAgent usa un'istanza IChatClient, che può essere decorata con middleware aggiuntivo.

var chatClient = new AzureOpenAIClient(endpoint, credential)
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .Use(CustomChatClientMiddleware)
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

È anche possibile usare AIContextProvider come middleware client di chat per arricchire messaggi, strumenti e istruzioni a livello di client. Deve essere usato all'interno del contesto di un AIAgent in esecuzione:

var chatClient = new AzureOpenAIClient(endpoint, credential)
    .GetChatClient(deploymentName)
    .AsIChatClient()
    .AsBuilder()
    .UseAIContextProviders(new MyContextProvider())
    .Build();

var agent = new ChatClientAgent(chatClient, instructions: "You are helpful.");

Per impostazione predefinita, ChatClientAgent avvolge il client di chat fornito con supporto per le chiamate di funzione. Impostare UseProvidedChatClientAsIs = true nelle opzioni per ignorare il wrapping predefinito.

La Agent classe accetta qualsiasi client che implementa SupportsChatGetResponse. La pipeline di ChatClient gestisce il middleware, la telemetria, la chiamata di funzione e la comunicazione specifica del provider.

from agent_framework import Agent
from agent_framework.azure import AzureOpenAIResponsesClient

client = AzureOpenAIResponsesClient(
    credential=credential,
    project_endpoint=endpoint,
    deployment_name=model,
)

agent = Agent(client=client, instructions="You are helpful.")

L'oggetto RawChatClient all'interno di ChatClient implementa la logica specifica del provider per la comunicazione con diversi servizi LLM.

Flusso di esecuzione

Quando si richiama un agente, la richiesta passa attraverso la pipeline:

1. Il middleware dell'agente esegue (se configurato)
2. ChatHistoryProvider carica la cronologia delle conversazioni nell'elenco dei messaggi di richiesta
3. AIContextProviders aggiunge messaggi, strumenti o istruzioni alla richiesta
4. Il middleware IChatClient viene eseguito (se decorato)
5. IChatClient invia la richiesta all'LLM
6. La risposta scorre indietro attraverso gli stessi livelli.
7. ChatHistoryProvider e AIContextProviders ricevono una notifica dei nuovi messaggi

Pipeline dell'agente:

1. Agent Middleware e Telemetria esegue il middleware (se configurato) e registra gli span
2. RawAgent richiama i provider di contesto per caricare la cronologia e aggiungere contesto
3. La richiesta viene passata a ChatClient

Pipeline chatClient:

4. Il middleware di chat e telemetria viene eseguito (se configurato)
5. FunctionInvocation invia una richiesta al ciclo LLM e gestisce il ciclo di chiamata dello strumento
   • Per ogni chiamata di strumento, vengono eseguiti il middleware della funzione e la telemetria
6. RawChatClient gestisce la comunicazione LLM specifica del provider
7. La risposta fluisce indietro attraverso gli stessi livelli
8. I provider di contesto ricevono una notifica dei nuovi messaggi per l'archiviazione

Annotazioni

Gli agenti specializzati possono funzionare in modo diverso rispetto alla pipeline descritta qui.

Altri tipi di agente

Non tutti gli agenti usano la pipeline completa ChatClientAgent. Agenti come A2AAgent, GitHubCopilotAgento CopilotStudioAgent comunicano con servizi remoti invece di usare un oggetto locale IChatClient. Tuttavia, supportano comunque il middleware a livello di agente.

Poiché questi agenti derivano da AIAgent, è possibile usare gli stessi modelli middleware dell'agente:

// Agent middleware works with any AIAgent
var a2aAgent = originalA2AAgent
    .AsBuilder()
    .Use(runFunc: LoggingMiddleware)
    .UseAIContextProviders(new MyMessageContextProvider())
    .Build();

// Same pattern works for GitHubCopilotAgent
var copilotAgent = originalCopilotAgent
    .AsBuilder()
    .Use(runFunc: AuditMiddleware)
    .Build();

Annotazioni

Non è possibile aggiungere middleware client di chat a questi agenti perché non usano IChatClient.

Passaggi successivi

Multimodale

Contenuti correlati

• Middleware - Aggiungere un comportamento trasversale agli agenti
• Provider di contesto - Modelli dettagliati per la cronologia e l'inserimento del contesto
• Esecuzione di agenti - Come richiamare gli agenti