Arquitetura de linha de produção de agentes

ChatClientAgent Pipeline

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

1. Middleware do agente - Decoradores opcionais que envolvem o agente em .Use() para registo, validação ou transformação
2. Camada de contexto - Gerir o histórico de chat (ChatHistoryProvider) e injetar contexto adicional (AIContextProviders)
3. Camada cliente de chat - Que utilizam decoradores de middleware opcionais que tratam da comunicação com modelos de linguagem extensos (LLMs)

Quando chama RunAsync(), o seu pedido flui por cada camada em sequência.

Pipeline de Agentes

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

Agente (componente exterior):

1. Agent Middleware + Telemetria - as AgentMiddlewareLayer classes e AgentTelemetryLayer tratam da invocação de middleware e da instrumentação OpenTelemetry
2. RawAgent - Lógica do agente central que invoca fornecedores de contexto
3. Fornecedores de Contexto - A lista unificada gere o histórico e os contextos adicionais

ChatClient (componente separado e intercambiável):

1. Chat Middleware + Telemetria - Cadeia opcional de middleware e camadas de instrumentação
2. FunctionInvocation - Gere o ciclo de chamadas de ferramentas, invocando o Function Middleware + Telemetria por cada chamada de ferramenta
3. RawChatClient - Implementação específica do fornecedor (Azure OpenAI, OpenAI, Anthropic, etc.) que comunica com o LLM

Quando chama run(), o seu pedido flui através das camadas do Agente, depois para o pipeline ChatClient para comunicação com LLM.

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

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

Também pode usar MessageAIContextProvider como agente middleware para injetar mensagens adicionais na requisição. Isto funciona com qualquer tipo de agente, não só ChatClientAgent:

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

Esta camada envolve toda a execução do agente, incluindo resolução de contexto e chamadas de cliente de chat. Isto tem vantagens, pois estes decoradores podem ser usados com qualquer tipo de agente, como A2AAgent ou GitHubCopilotAgent, não apenas ChatClientAgent. Isto também significa que os decoradores a este nível não podem necessariamente fazer suposições sobre o agente que estão a decorar, estando limitado a personalizar ou influenciar funcionalidades comuns.

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 Agent classe herda de AgentMiddlewareLayer, que trata da invocação do middleware antes de delegar à lógica do agente central. Também herda de AgentTelemetryLayer, que gere a emissão de spans, eventos e métricas para um backend OpenTelemetry configurado. Ambas estas camadas não fazem nada quando não estão configuradas.

ChatClientAgent tem dois tipos distintos de prestadores:

• ChatHistoryProvider (único) - Gere 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 InvokingAsync() de cada fornecedor antes de enviar mensagens ao cliente de chat, passando a saída de cada fornecedor como entrada para o próximo fornecedor.

A Agent classe utiliza uma lista unificada context_providers que pode incluir tanto fornecedores de história como de contexto:

from agent_framework import Agent, InMemoryHistoryProvider

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

ChatClientAgent utiliza 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.");

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

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 envolve o cliente de chat fornecido com suporte para chamadas de funções. Defina UseProvidedChatClientAsIs = true nas opções para saltar este encaixotamento padrão.

A Agent classe aceita qualquer cliente que implemente SupportsChatGetResponse. O pipeline do ChatClient gere 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.")

RawChatClient dentro do ChatClient implementa a lógica específica do fornecedor para comunicando com os diferentes serviços LLM.

1. O middleware do agente executa (se configurado)
2. O ChatHistoryProvider carrega o histórico de conversas na lista de mensagens de pedidos
3. O AIContextProviders adiciona mensagens, ferramentas ou instruções ao pedido
4. O middleware IChatClient executa (se estiver decorado)
5. O IChatClient envia o pedido para o LLM
6. A resposta flui de volta pelas mesmas camadas
7. ChatHistoryProvider e AIContextProviders são notificados de novas mensagens

Pipeline de agentes:

1. O Agent Middleware + Telemetry executa middleware (se configurado) e regista spans
2. O RawAgent invoca fornecedores de contexto para carregar o histórico e adicionar contexto
3. O pedido é encaminhado para o ChatClient

Pipeline ChatClient:

4. Middleware de Chat + Telemetria executa (se configurado)
5. O FunctionInvocation envia pedidos para o LLM e gere o ciclo de chamada de ferramentas
   • Para cada chamada de ferramenta, Function Middleware + Telemetry é executado
6. O RawChatClient gere a comunicação de LLM específica do fornecedor
7. A resposta flui de volta pelas mesmas camadas
8. Os fornecedores de contexto são notificados de novas mensagens para armazenamento

Outros tipos de agentes

Nem todos os agentes usam o pipeline completo ChatClientAgent. Agentes como A2AAgent, GitHubCopilotAgent ou CopilotStudioAgent comunicam-se com serviços remotos em vez de usarem um IChatClient local. No entanto, continuam a suportar middleware a nível de agente.

Como estes agentes derivam de AIAgent, pode usar os mesmos padrões de middleware de agentes:

// 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();