Architecture du pipeline d’agent

ChatClientAgent Pipeline

Le ChatClientAgent construit un pipeline avec trois couches principales :

1. Agent middleware - Décorateurs facultatifs qui encapsulent l’agent pour .Use() la journalisation, la validation ou la transformation
2. Couche de contexte : gère l’historique des conversations (ChatHistoryProvider) et injecte un contexte supplémentaire (AIContextProviders)
3. Client de chat : IChatClient avec des décorateurs d’intergiciels facultatifs qui gèrent la communication LLM

Lorsque vous appelez RunAsync(), votre demande transite par chaque couche en séquence.

Pipeline d’agent

La Agent classe génère un pipeline par le biais de la composition de classes avec deux composants principaux :

Agent (composant externe) :

1. Intergiciel Agent + télémétrie : les classes AgentMiddlewareLayer et AgentTelemetryLayer gèrent les appels d'intergiciels et l'instrumentation OpenTelemetry.
2. RawAgent - Logique de l’agent principal qui appelle des fournisseurs de contexte
3. Fournisseurs de contexte - La liste unifiée context_providers gère l’historique et le contexte supplémentaire

ChatClient (composant distinct et interchangeable) :

1. Intergiciel de conversation + télémétrie - Couches d’intergiciels et d’instrumentation facultatives
2. FunctionInvocation - Gère la boucle d’appel de l’outil, en invoquant le middleware de fonction + la télémétrie pour chaque appel d’outil
3. RawChatClient - Implémentation spécifique au fournisseur (Azure OpenAI, OpenAI, Anthropic, etc.) qui communique avec le LLM

Lorsque vous appelez run(), votre requête transite par les couches Agent, puis dans le pipeline ChatClient pour la communication LLM.

Ajoutez un intergiciel à l’aide du modèle de générateur d’agents :

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

Vous pouvez également utiliser MessageAIContextProvider comme intergiciel agent pour injecter des messages supplémentaires dans la demande. Cela fonctionne avec n’importe quel type d’agent, pas seulement ChatClientAgent:

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

Cette couche encapsule l’intégralité de l’exécution de l’agent, y compris la résolution de contexte et les appels clients de conversation. Cela présente des avantages, car ces décorateurs peuvent être utilisés avec n’importe quel type d’agent, par exemple A2AAgent , ou GitHubCopilotAgentpas seulement ChatClientAgent. Cela implique également que les décorateurs à ce niveau ne peuvent pas nécessairement faire des suppositions concernant l'agent qu'ils décorent, ce qui limite leur capacité à personnaliser ou à modifier les fonctionnalités communes.

Ajoutez un intergiciel lors de la création de l’agent :

from agent_framework import Agent

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

La Agent classe hérite de AgentMiddlewareLayer, qui gère l’appel d’intergiciel avant de déléguer à la logique de l’agent principal. Il hérite également de AgentTelemetryLayer, ce qui gère l’émission d’étendues, d’événements et de métriques vers un back-end OpenTelemetry configuré. Ces deux couches, ne font rien quand elles ne sont pas configurées.

ChatClientAgent a deux types de fournisseurs distincts :

• ChatHistoryProvider (unique) - Gère le stockage et la récupération de l’historique des conversations
• AIContextProviders (liste) : injecte un contexte supplémentaire comme des souvenirs, des documents récupérés ou des instructions dynamiques

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

L’agent appelle la méthode de InvokingAsync() de chaque fournisseur avant d’envoyer des messages au client de messagerie, en passant la sortie de chaque fournisseur comme entrée au fournisseur suivant.

La Agent classe utilise une liste unifiée context_providers qui peut inclure à la fois des fournisseurs d’historique et des fournisseurs de contexte :

from agent_framework import Agent, InMemoryHistoryProvider

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

ChatClientAgent utilise une IChatClient instance, qui peut être décorée avec un intergiciel supplémentaire :

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

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

Vous pouvez également utiliser AIContextProvider comme intergiciel client de conversation pour enrichir les messages, les outils et les instructions au niveau du client. Cela doit être utilisé dans le contexte d’une exécution AIAgent:

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

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

Par défaut, ChatClientAgent encapsule le client de conversation fourni avec la prise en charge des appels de fonction. Définissez UseProvidedChatClientAsIs = true dans les options pour ignorer cet enveloppement par défaut.

La Agent classe accepte tout client qui implémente SupportsChatGetResponse. Le pipeline ChatClient gère les intergiciels, les données de télémétrie, l’appel de fonction et la communication spécifique au fournisseur :

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

Le RawChatClient dans le ChatClient implémente la logique spécifique au fournisseur pour communiquer avec différents services LLM.

1. L’intergiciel de l’agent s’exécute (s’il est configuré)
2. ChatHistoryProvider charge l’historique des conversations dans la liste des messages de requête
3. AIContextProviders ajoute des messages, des outils ou des instructions à la demande
4. L’intergiciel IChatClient s’exécute (s’il est décoré)
5. IChatClient envoie la requête au LLM
6. La réponse revient à travers les mêmes couches
7. ChatHistoryProvider et AIContextProviders sont avertis des nouveaux messages

Pipeline d’agent :

1. L’agent Middleware + Télémétrie exécute l’intergiciel (s’il est configuré) et enregistre les spans
2. RawAgent appelle les fournisseurs de contexte pour charger l’historique et ajouter du contexte
3. La demande est transmise à ChatClient

Pipeline ChatClient :

4. Intergiciel de conversation + Télémétrie s’exécute (s’il est configuré)
5. FunctionInvocation envoie la requête au LLM et gère la boucle d'appel de l'outil.
   • Pour chaque appel d’outil, l’intergiciel de fonction + télémétrie s’exécute
6. RawChatClient gère la communication LLM spécifique au fournisseur
7. La réponse revient à travers les mêmes couches
8. Les fournisseurs de contexte sont avertis des nouveaux messages en vue de leur stockage

Autres types d’agents

Tous les agents n’utilisent pas le pipeline complet ChatClientAgent . Les agents tels que A2AAgent, GitHubCopilotAgentou CopilotStudioAgent communiquent avec des services distants plutôt que d’utiliser un agent local IChatClient. Toutefois, ils prennent toujours en charge les intergiciels au niveau de l’agent.

Étant donné que ces agents dérivent de AIAgent, vous pouvez utiliser les mêmes modèles de middleware d'agent :

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