Agent-Pipeline-Architektur

Agents in Microsoft Agent Framework verwenden eine mehrschichtige Pipelinearchitektur zum Verarbeiten von Anforderungen. Wenn Sie diese Architektur verstehen, können Sie das Verhalten des Agents anpassen, indem Sie Middleware, Kontextanbieter oder Änderungen auf Clientebene auf der entsprechenden Ebene hinzufügen.

ChatClientAgent-Pipeline

Die ChatClientAgent erstellt eine Pipeline mit drei Hauptschichten:

1. Agent-Middleware – Optionale Dekoratoren, die den Agenten über .Use() zur Protokollierung, Validierung oder Transformation umschließen
2. Kontextebene – Verwaltet den Chatverlauf (ChatHistoryProvider) und fügt zusätzlichen Kontext ein (AIContextProviders)
3. Chat-Clientebene – Die IChatClient mit optionalen Middleware-Dekoratoren, die die LLM-Kommunikation verarbeiten

Wenn Sie aufrufen RunAsync(), fließt Ihre Anforderung in Sequenz über die einzelnen Ebenen.

Agentpipeline

Die Agent Klasse erstellt eine Pipeline über die Klassenkomposition mit zwei Hauptkomponenten:

Agent (äußere Komponente):

1. Agent Middleware + Telemetrie – die AgentMiddlewareLayer Und AgentTelemetryLayer Klassen behandeln Middleware-Aufrufe und OpenTelemetry-Instrumentierung
2. RawAgent – Kern-Agent-Logik, die Kontextanbieter aufruft
3. Kontextanbieter – Einheitliche context_providers Liste verwaltet Verlauf und zusätzlichen Kontext

ChatClient (separate und austauschbare Komponente):

1. Chat Middleware + Telemetrie – Optionale Middleware-Kette und Instrumentierungsebenen
2. FunctionInvocation – Behandelt die Toolaufrufschleife, ruft pro Werkzeugaufruf die Funktions-Middleware und Telemetrie auf
3. RawChatClient – anbieterspezifische Implementierung (Azure OpenAI, OpenAI, Anthropic usw.), die mit der LLM kommuniziert

Wenn Sie anrufen run(), fließt Ihre Anforderung über die Agent-Ebenen und dann in die ChatClient-Pipeline für die LLM-Kommunikation.

Agent-Middleware-Ebene

Agent Middleware fängt jeden Aufruf der Ausführungsmethode des Agents ab, sodass Sie Eingaben und Ausgaben prüfen oder ändern können.

Fügen Sie Middleware mithilfe des Agent-Generator-Musters hinzu:

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

Sie können auch als Agent-Middleware verwenden MessageAIContextProvider , um zusätzliche Nachrichten in die Anforderung einzufügen. Dies funktioniert mit jedem Agenttyp, nicht nur ChatClientAgent:

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

Diese Ebene umschließt die gesamte Agentenausführung, einschließlich Kontextauflösung und Chat-Client-Anrufe. Dies hat Vorteile, da diese Dekoratoren mit jeder Art von Agent verwendet werden können, z. B. A2AAgent oder GitHubCopilotAgentnicht nur ChatClientAgent. Dies bedeutet auch, dass Dekorateure auf dieser Ebene nicht unbedingt Annahmen über den Agenten machen können, den sie dekorieren, sodass sie auf das Anpassen oder Beeinflussen allgemeiner Funktionen beschränkt sind.

Fügen Sie Middleware hinzu, wenn Sie den Agent erstellen:

from agent_framework import Agent

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

Die Agent Klasse erbt von AgentMiddlewareLayer, die Middleware-Aufrufe behandelt, bevor sie an die Kern-Agent-Logik delegiert werden. Sie erbt auch von AgentTelemetryLayer, das für die Emission von Spans, Ereignissen und Metriken an ein konfiguriertes OpenTelemetry-Back-End zuständig ist. Beide Ebenen tun nichts, wenn sie nicht konfiguriert sind.

Ausführliche Middleware- und Observability-Muster finden Sie unter Agent Middleware und Observability.

Kontextebene

Die Kontextebene wird vor jedem LLM-Aufruf ausgeführt, um den vollständigen Nachrichtenverlauf zu erstellen und zusätzlichen Kontext einzugeben.

ChatClientAgent weist zwei unterschiedliche Anbietertypen auf:

• ChatHistoryProvider (single) – Verwalten der Speicherung und des Abrufs des Gesprächsverlaufs
• AIContextProviders (liste) – Fügt zusätzlichen Kontext wie Erinnerungen, abgerufene Dokumente oder dynamische Anweisungen ein.

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

Der Agent ruft die Methode jedes Anbieters InvokingAsync() auf, bevor Nachrichten an den Chatclient gesendet werden, wobei die Ausgabe jedes Anbieters als Eingabe an den nächsten Anbieter übergeben wird.

Die Agent Klasse verwendet eine einheitliche context_providers Liste, die sowohl Verlaufsanbieter als auch Kontextanbieter enthalten kann:

from agent_framework import Agent, InMemoryHistoryProvider

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

Ausführliche Kontextanbietermuster finden Sie unter "Kontextanbieter".

Chat-Client-Ebene

Die Chatclientebene verarbeitet die tatsächliche Kommunikation mit dem LLM-Dienst.

ChatClientAgent verwendet eine IChatClient Instanz, die mit zusätzlicher Middleware versehen werden kann:

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

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

Sie können AIContextProvider auch als Chatclient-Middleware verwenden, um Nachrichten, Tools und Anweisungen auf Clientebene zu erweitern. Dies muss im Kontext einer laufenden AIAgent-Ausführung verwendet werden:

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

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

Umschließt standardmäßig ChatClientAgent den bereitgestellten Chatclient mit Unterstützung für Funktionsanrufe. Setzen Sie UseProvidedChatClientAsIs = true in den Optionen ein, um diesen Standardumbruch zu überspringen.

Die Agent Klasse akzeptiert jeden Client, der SupportsChatGetResponse implementiert. Die ChatClient-Pipeline verarbeitet Middleware, Telemetrie, Funktionsaufrufe und anbieterspezifische Kommunikation:

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

Der ChatClient RawChatClient implementiert die anbieterspezifische Logik für die Kommunikation mit verschiedenen LLM-Diensten.

Ausführungsfluss

Wenn Sie einen Agent aufrufen, fließt die Anforderung über die Pipeline:

1. Agent Middleware wird ausgeführt (falls konfiguriert)
2. ChatHistoryProvider lädt den Unterhaltungsverlauf in die Anforderungsnachrichtenliste.
3. AIContextProviders fügen Nachrichten, Tools oder Anweisungen zur Anforderung hinzu
4. IChatClient-Middleware wird ausgeführt (falls dekoriert)
5. IChatClient sendet die Anforderung an die LLM
6. Die Antwort fließt zurück durch dieselben Ebenen
7. ChatHistoryProvider und AIContextProviders werden über neue Nachrichten benachrichtigt

Agentpipeline:

1. Agent Middleware + Telemetrie führt Middleware aus (falls konfiguriert) und zeichnet Spannen auf.
2. RawAgent ruft Kontextanbieter auf, um den Verlauf zu laden und Kontext hinzuzufügen
3. Anforderung wird an den ChatClient übergeben

ChatClient-Pipeline:

4. Chat Middleware + Telemetrie wird ausgeführt (falls konfiguriert)
5. FunctionInvocation sendet anforderung an die LLM und behandelt Toolaufrufschleife
   • Für jeden Toolaufruf wird Function Middleware + Telemetrie ausgeführt.
6. RawChatClient verarbeitet die anbieterspezifische LLM-Kommunikation
7. Die Antwort fließt zurück durch dieselben Ebenen
8. Kontextanbieter werden über neue Nachrichten für den Speicher benachrichtigt.

Hinweis

Spezialisierte Agents funktionieren möglicherweise anders als die Pipeline, die hier beschrieben wird.

Andere Agenttypen

Nicht alle Agenten verwenden die vollständige ChatClientAgent-Pipeline. Agents wie A2AAgent, GitHubCopilotAgent oder CopilotStudioAgent kommunizieren mit Remotediensten, anstatt eine lokale IChatClient zu verwenden. Sie unterstützen jedoch weiterhin Middleware auf Agentebene.

Da diese Agents von AIAgentabgeleitet werden, können Sie dieselben Agent-Middleware-Muster verwenden:

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

Hinweis

Sie können diesen Agenten keine Chatclient-Middleware hinzufügen, da sie nicht IChatClient verwendet werden.

Nächste Schritte

Multimodale

Verwandte Inhalte

• Middleware – Querschnittsverhalten zu Ihren Akteuren hinzufügen
• Kontextanbieter – Detaillierte Muster für Historie- und Kontexteinspeisung
• Ausführen von Agenten – Aufrufen von Agenten