Arquitectura de canalización del agente

Los agentes de Microsoft Agent Framework usan una arquitectura de canalización superpuesta para procesar solicitudes. Comprender esta arquitectura le ayuda a personalizar el comportamiento del agente agregando middleware, proveedores de contexto o modificaciones de nivel de cliente en la capa adecuada.

Pipeline de ChatClientAgent

Compila ChatClientAgent una canalización con tres capas principales:

1. Middleware del agente : decoradores opcionales que encapsulan el agente mediante .Use() para el registro, la validación o la transformación
2. Capa de contexto: administra el historial de chat (ChatHistoryProvider) e inserta contexto adicional (AIContextProviders)
3. Capa de cliente de chat - IChatClient con decoradores de middleware opcionales que gestionan la comunicación de LLM

Al llamar a RunAsync(), la solicitud fluye a través de cada capa en secuencia.

Canalización del agente

La Agent clase construye un pipeline mediante la composición de clases con dos componentes principales.

Agente (componente externo):

1. Middleware del agente + Telemetría: las clases AgentMiddlewareLayer y AgentTelemetryLayer gestionan la invocación de middleware y la instrumentación de OpenTelemetry
2. RawAgent : lógica del agente principal que invoca proveedores de contexto
3. Proveedores de contexto : la lista unificada context_providers administra el historial y el contexto adicional

ChatClient (componente independiente e intercambiable):

1. FunctionInvocation : controla el bucle de llamada de herramientas, invocando middleware de función + telemetría por llamada de herramienta
2. Middleware de chat + Telemetría : capas opcionales de cadena de middleware e instrumentación, que se ejecutan por llamada de modelo
3. RawChatClient - implementación específica del proveedor (Azure OpenAI, OpenAI, Anthropic, etc.) que se comunica con el LLM.

Cuando llama a run(), su solicitud fluye a través de las capas del Agente y luego a la canalización ChatClient para la comunicación LLM.

Capa intermedia del agente

El middleware del agente intercepta todas las llamadas al método de ejecución del agente, lo que le permite inspeccionar o modificar entradas y salidas.

Agregue middleware mediante el patrón del generador de agentes:

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

También puede usar MessageAIContextProvider como middleware del agente para insertar mensajes adicionales en la solicitud. Esto funciona con cualquier tipo de agente, no solo ChatClientAgent:

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

Esta capa encapsula toda la ejecución del agente, incluida la resolución de contexto y las llamadas de cliente de chat. Esto tiene ventajas, en que estos decoradores se pueden usar con cualquier tipo de agente, por ejemplo A2AAgent , o GitHubCopilotAgent, no solo ChatClientAgent. Esto también significa que los decoradores en este nivel no pueden necesariamente hacer suposiciones sobre el agente que están decorando, lo que significa que están restringidos a personalizar o afectar a la funcionalidad común.

Agregue middleware al crear el agente:

from agent_framework import Agent

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

La Agent clase hereda de AgentMiddlewareLayer, que controla la invocación de middleware antes de delegarla en la lógica del agente principal. También hereda de AgentTelemetryLayer, que controla la emisión de spans, eventos y métricas en un back-end de OpenTelemetry configurado. Ambas capas, no hacen nada cuando no están configurados.

Para obtener patrones detallados de middleware y observabilidad, consulte Middleware del agente y Observabilidad.

Capa de contexto

La capa de contexto se ejecuta antes de cada llamada LLM para compilar el historial completo de mensajes e insertar contexto adicional.

ChatClientAgent tiene dos tipos de proveedor distintos:

• ChatHistoryProvider (único): administra el almacenamiento y la recuperación del historial de conversaciones.
• AIContextProviders (lista): inserta contexto adicional como recuerdos, documentos recuperados o instrucciones dinámicas

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

El agente llama al método de InvokingAsync() de cada proveedor antes de enviar mensajes al cliente de chat, utilizando la salida de cada proveedor como entrada para el siguiente proveedor.

La Agent clase usa una lista unificada context_providers que puede incluir proveedores de historial y proveedores de contexto:

from agent_framework import Agent, InMemoryHistoryProvider

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

Para obtener patrones de proveedor de contexto detallados, consulte Proveedores de contexto.

Capa de cliente de chat

El nivel de cliente de chat controla la comunicación real con el servicio LLM.

ChatClientAgent utiliza una instancia de IChatClient, que se puede decorar con middleware adicional.

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

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

También puede usar AIContextProvider como middleware de cliente de chat para enriquecer mensajes, herramientas e instrucciones en el nivel de cliente. Debe usarse en el contexto de un objeto en ejecución AIAgent:

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

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

De forma predeterminada, ChatClientAgent ajusta el cliente de chat proporcionado con soporte para invocación de funciones. Establezca UseProvidedChatClientAsIs = true en opciones para omitir este envuelto predeterminado.

La Agent clase acepta cualquier cliente que implemente SupportsChatGetResponse. La canalización chatClient controla el middleware, la telemetría, la invocación de funciones y la comunicación específica del proveedor:

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

Dentro RawChatClient de ChatClient se implementa la lógica específica del proveedor para comunicarse con diferentes servicios LLM.

Flujo de ejecución

Al invocar un agente, la solicitud fluye a través de la canalización:

1. El middleware del agente se ejecuta (si está configurado)
2. ChatHistoryProvider carga el historial de conversaciones en la lista de mensajes de solicitud
3. AIContextProviders agrega mensajes, herramientas o instrucciones a la solicitud
4. El middleware IChatClient se ejecuta (solo si está decorado)
5. IChatClient envía la solicitud al LLM
6. La respuesta fluye hacia atrás a través de las mismas capas
7. ChatHistoryProvider y AIContextProviders reciben una notificación de nuevos mensajes

Pipeline de agente:

1. Middleware del agente + Telemetría ejecuta middleware (si está configurado) y registra las trazas
2. RawAgent invoca proveedores de contexto para cargar el historial y agregar contexto
3. La solicitud se pasa a ChatClient

Canalización de ChatClient:

4. FunctionInvocation administra el bucle de llamada de herramienta
   • Para cada llamada de herramienta, se ejecuta Function Middleware + Telemetry
5. Middleware de chat + Telemetría se ejecuta con cada llamada al modelo (si está configurada)
6. RawChatClient controla la comunicación LLM específica del proveedor
7. La respuesta fluye hacia atrás a través de las mismas capas
8. Los proveedores de contexto reciben una notificación de nuevos mensajes para el almacenamiento

Nota:

Los agentes especializados pueden funcionar de forma diferente a la canalización descrita aquí.

Otros tipos de agente

No todos los agentes usan la canalización completa ChatClientAgent . Los agentes como A2AAgent, GitHubCopilotAgento CopilotStudioAgent se comunican con servicios remotos en lugar de usar un local IChatClient. Sin embargo, todavía admiten middleware de nivel de agente.

Dado que estos agentes derivan de AIAgent, puede usar los mismos patrones de middleware del 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();

Nota:

No puede agregar middleware de cliente de chat a estos agentes porque no usan IChatClient.

Pasos siguientes

Multimodal

Contenido relacionado

• Middleware - Añade comportamiento transversal a tus agentes
• Proveedores de contexto : patrones detallados para el historial y la inserción de contexto
• Ejecución de agentes : cómo invocar agentes