Arquitetura de pipeline de agente

ChatClientAgent Pipeline

ChatClientAgent constrói um pipeline com três camadas principais:

1. Middleware do agente – decoradores opcionais que encapsulam o agente para .Use() registro em log, validação ou transformação
2. Camada de contexto – gerencia o histórico de chat (ChatHistoryProvider) e injeta contexto adicional (AIContextProviders)
3. Camada de cliente de chat – O IChatClient com decoradores opcionais de middleware que lidam com a comunicação LLM

Quando você chama RunAsync(), sua solicitação flui por cada camada em sequência.

Pipeline do Agente

A classe Agent constrói um pipeline por meio da composição de classes com dois componentes principais:

Agente (componente externo):

1. Middleware do Agente + Telemetria – as classes AgentMiddlewareLayer e AgentTelemetryLayer lidam com a invocação de middleware e a instrumentação OpenTelemetry
2. RawAgent – Lógica do agente principal que invoca provedores de contexto
3. Provedores de Contexto – Lista unificada context_providers gerencia histórico e contexto adicional

ChatClient (componente separado e intercambiável):

1. Middleware de Chat + Telemetria – Camadas opcionais de middleware e de instrumentação
2. FunctionInvocation – Manipula o loop de chamadas de ferramenta, invocando Middleware de Função + Telemetria por chamada de ferramenta
3. RawChatClient – Implementação específica do provedor (Azure OpenAI, OpenAI, Antropic etc.) que se comunica com o LLM

Quando você chama run(), sua solicitação flui pelas camadas do Agente e, em seguida, entra no pipeline do ChatClient para comunicação com LLM.

Adicione middleware usando o padrão do construtor de agentes:

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

Você também pode usar MessageAIContextProvider como middleware de agente para injetar mensagens adicionais na solicitação. Isso funciona com qualquer tipo de agente, não apenas ChatClientAgent:

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

Essa camada encapsula toda a execução do agente, incluindo resolução de contexto e chamadas de cliente de chat. Isso tem benefícios, porque esses decoradores podem ser usados com qualquer tipo de agente, por exemplo A2AAgent , ou GitHubCopilotAgent, não apenas ChatClientAgent. Isso também significa que os decoradores nesse nível não podem necessariamente fazer suposições sobre o agente que eles estão decorando, o que significa que eles estão restritos a personalizar ou afetar a funcionalidade comum.

Adicione middleware ao criar o agente:

from agent_framework import Agent

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

A classe Agent herda de AgentMiddlewareLayer, que gerencia a invocação das funções de middleware antes de delegar para a lógica central do agente. Ele também herda do AgentTelemetryLayer, que lida com a emissão de intervalos, eventos e métricas para um back-end OpenTelemetry configurado. Essas duas camadas não fazem nada quando não estão configuradas.

ChatClientAgent tem dois tipos de provedor distintos:

• ChatHistoryProvider (único) – Gerencia o armazenamento e a recuperação do histórico de conversas
• AIContextProviders (lista) - Injeta contexto adicional, como memórias, documentos recuperados ou instruções dinâmicas

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

O agente invoca o método de cada provedor antes de enviar mensagens para o cliente de chat, fazendo com que a saída de cada provedor seja passada como entrada para o próximo provedor.

A Agent classe usa uma lista unificada context_providers que pode incluir provedores de histórico e provedores de contexto:

from agent_framework import Agent, InMemoryHistoryProvider

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

ChatClientAgent usa uma IChatClient instância, que pode ser decorada com middleware adicional:

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

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

Você também pode usar AIContextProvider como middleware de cliente de chat para enriquecer mensagens, ferramentas e instruções no nível do cliente. Isso deve ser usado no contexto de um AIAgent em execução:

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

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

Por padrão, ChatClientAgent encapsula o cliente de chat fornecido com suporte para chamadas de funções. Defina UseProvidedChatClientAsIs = true nas opções para ignorar esse encapsulamento padrão.

A Agent classe aceita qualquer cliente que implemente SupportsChatGetResponse. O pipeline do ChatClient manipula middleware, telemetria, invocação de funções e comunicação específica do provedor.

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.")

O RawChatClient do ChatClient implementa a lógica específica do provedor para se comunicar com diferentes serviços LLM.

1. O middleware do agente é executado (se configurado)
2. ChatHistoryProvider carrega o histórico de conversas na lista de mensagens de solicitação
3. AIContextProviders adicionam mensagens, ferramentas ou instruções à solicitação
4. O middleware IChatClient executa (caso esteja decorado)
5. O IChatClient envia a solicitação para a LLM
6. A resposta flui de volta pelas mesmas camadas
7. ChatHistoryProvider e AIContextProviders são notificados sobre novas mensagens

Pipeline do agente:

1. Middleware do Agente + Telemetria executa o middleware (se configurado) e registra spans
2. RawAgent invoca provedores de contexto para carregar o histórico e adicionar contexto
3. A solicitação é passada para o ChatClient

Pipeline do ChatClient:

4. Chat Middleware + Telemetria é executado (se configurado)
5. FunctionInvocation envia solicitação para o LLM e manipula loop de chamada de ferramenta
   • Para cada chamada de ferramenta, Middleware de Função + Telemetria é executado
6. RawChatClient gerencia a comunicação LLM específica do provedor
7. A resposta flui de volta pelas mesmas camadas
8. Os provedores de contexto são notificados sobre novas mensagens para armazenamento

Outros tipos de agente

Nem todos os agentes utilizam a totalidade do ChatClientAgent pipeline. Agentes como A2AAgent, GitHubCopilotAgentou CopilotStudioAgent se comunicam com serviços remotos em vez de usar um local IChatClient. No entanto, eles ainda dão suporte ao middleware no nível do agente.

Como esses agentes derivam de AIAgent, você pode usar os mesmos padrões de middleware de 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();