Agentpipelinearkitektur

Agenter i Microsoft Agent Framework använder en pipelinearkitektur i flera lager för att bearbeta begäranden. Genom att förstå den här arkitekturen kan du anpassa agentbeteendet genom att lägga till mellanprogram, kontextprovidrar eller ändringar på klientnivå på lämpligt lager.

ChatClientAgent-pipeline

Skapar ChatClientAgent en pipeline med tre huvudlager:

1. Agentmellanprogram – Valfria dekoratörer som omsluter agenten via .Use() för loggning, validering eller transformering
2. Kontextskikt – Hanterar chatthistorik (ChatHistoryProvider) och ingjuter ytterligare kontext (AIContextProviders)
3. Chattklientskikt – IChatClient med valfria mellanprogramsmoduler som hanterar LLM-kommunikation

När du anropar RunAsync()flödar din begäran genom varje lager i följd.

Agentpipeline

Klassen Agent skapar en pipeline via klasssammansättning med två huvudkomponenter:

Agent (yttre komponent):

1. Agentmellanprogram + telemetri – AgentMiddlewareLayer klasserna och AgentTelemetryLayer hanterar anrop av mellanprogram och OpenTelemetry-instrumentation
2. RawAgent – Kärnagentlogik som anropar kontextprovidrar
3. Kontextprovidrar – Enhetlig context_providers lista hanterar historik och ytterligare kontext

ChatClient (separat och utbytbar komponent):

1. FunctionInvocation – Hanterar verktygsanropsloop, anropar funktionsmellanprogram + telemetri per verktygsanrop
2. Chattmellanprogram + telemetri – Valfria mellanprogramskedja och instrumentationslager som körs per modellanrop
3. RawChatClient – Providerspecifik implementering (Azure OpenAI, OpenAI, Anthropic osv.) som kommunicerar med LLM

När du anropar run()flödar din begäran genom agentlagren och sedan till ChatClient-pipelinen för LLM-kommunikation.

Mellanprogramslager för agent

Agentmellanprogram fångar upp varje anrop till agentens körningsmetod så att du kan inspektera eller ändra indata och utdata.

Lägg till mellanprogram med hjälp av agentverktygets mönster:

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

Du kan också använda MessageAIContextProvider som agentmellanprogram för att mata in ytterligare meddelanden i begäran. Detta fungerar med alla agenttyper, inte bara ChatClientAgent:

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

Det här lagret omsluter hela agentkörningen, inklusive kontextmatchning och chattklientanrop. Detta har fördelar, eftersom dessa dekoratörer kan användas med alla typer av agent, t.ex. A2AAgent eller GitHubCopilotAgent, inte bara ChatClientAgent. Det innebär också att dekoratörer på den här nivån inte nödvändigtvis kan göra antaganden om agenten som den dekorerar, vilket innebär att den är begränsad till att anpassa eller påverka vanliga funktioner.

Lägg till mellanprogram när du skapar agenten:

from agent_framework import Agent

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

Klassen Agent ärver från AgentMiddlewareLayer, som hanterar anrop av mellanprogram innan delegering till kärnagentlogik. Den ärver också från AgentTelemetryLayer vilken hanterar utsändande intervall, händelser och mått till en konfigurerad OpenTelemetry-serverdel. Båda dessa lager gör ingenting när de inte har konfigurerats.

Detaljerade mönster för mellanprogram och observerbarhet finns i Agentmellanprogram och Observerbarhet.

Kontextskikt

Kontextlagret körs före varje LLM-anrop för att skapa hela meddelandehistoriken och mata in ytterligare kontext.

ChatClientAgent har två olika providertyper:

• ChatHistoryProvider (enkel) – Hanterar lagring och hämtning av konversationshistorik
• AIContextProviders (lista) – Ingjuter ytterligare kontext som minnen, hämtade dokument eller dynamiska instruktioner

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

Agenten anropar varje providers InvokingAsync() metod innan den skickar meddelanden till chattklienten med varje providers utdata som skickas som indata till nästa provider.

Klassen Agent använder en enhetlig context_providers lista som kan innehålla både historikprovidrar och kontextprovidrar:

from agent_framework import Agent, InMemoryHistoryProvider

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

Detaljerade mönster för kontextprovider finns i Kontextprovidrar.

Chattklientlager

Chattklientlagret hanterar den faktiska kommunikationen med LLM-tjänsten.

ChatClientAgent använder en IChatClient instans som kan dekoreras med ytterligare mellanprogram:

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

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

Du kan också använda AIContextProvider som chattklientmellanprogram för att utöka meddelanden, verktyg och instruktioner på klientnivå. Detta måste användas i kontexten för en exekvering AIAgent:

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

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

Som standardinställning ChatClientAgent omsluter den tillhandahållna chattklienten med funktionssamtalsstöd. Ange UseProvidedChatClientAsIs = true alternativ för att hoppa över standardomslutningen.

Klassen Agent accepterar alla klienter som implementerar SupportsChatGetResponse. ChatClient-pipelinen hanterar mellanprogram, telemetri, funktionsanrop och leverantörsspecifik 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.")

I RawChatClient ChatClient implementeras den providerspecifika logiken för kommunikation med olika LLM-tjänster.

Körningsflöde

När du anropar en agent flödar begäran via pipelinen:

1. Agentmellanprogram körs (om det är konfigurerat)
2. ChatHistoryProvider läser in konversationshistorik i listan med begärandemeddelanden
3. AIContextProviders lägger till meddelanden, verktyg eller instruktioner i begäran
4. IChatClient-mellanprogram körs (om det är dekorerat)
5. IChatClient skickar begäran till LLM
6. Svaret flödar tillbaka genom samma lager
7. ChatHistoryProvider och AIContextProviders meddelas om nya meddelanden

Agentpipeline:

1. Agent Middleware + Telemetry kör middleware (om det är konfigurerat) och registrerar dataomfång
2. RawAgent anropar kontextprovidrar för att läsa in historik och lägga till kontext
3. Begäran skickas till ChatClient

ChatClient-pipeline:

4. FunctionInvocation hanterar verktygsanropsloopen
   • För varje verktygsanrop körs funktionsmellanprogram + telemetri
5. Chat Middleware + Telemetry körs per modellanrop (om det är konfigurerat)
6. RawChatClient hanterar providerspecifik LLM-kommunikation
7. Svaret flödar tillbaka genom samma lager
8. Kontextprovidrar meddelas om nya meddelanden för lagring

Anmärkning

Specialiserade agenter kan fungera annorlunda än vad som beskrivs i pipelinen här.

Andra agenttyper

Alla agenter använder inte den fullständiga ChatClientAgent pipelinen. Agenter som A2AAgent, GitHubCopilotAgenteller CopilotStudioAgent kommunicerar med fjärrtjänster i stället för att använda en lokal IChatClient. De stöder dock fortfarande mellanprogram på agentnivå.

Eftersom dessa agenter härleds från AIAgentkan du använda samma mellanprogramsmönster för agenten:

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

Anmärkning

Du kan inte lägga till mellanprogram för chattklient till dessa agenter eftersom de inte använder IChatClient.

Nästa steg

Multimodal

Relaterat innehåll

• Mellanprogram – Lägga till övergripande beteende för dina agenter
• Kontextprovidrar – Detaljerade mönster för historik och kontextinmatning
• Köra agenter – Så här anropar du agenter