Architectuur van agentpijplijn

Agents in Microsoft Agent Framework gebruiken een gelaagde pijplijnarchitectuur om aanvragen te verwerken. Als u deze architectuur begrijpt, kunt u het gedrag van agents aanpassen door middleware, contextproviders of wijzigingen op clientniveau toe te voegen op de juiste laag.

ChatClientAgent Pipeline

ChatClientAgent bouwt een pijplijn met drie hoofdlagen.

1. Middleware voor agenten : optionele decorators die de agent .Use() omwikkelen voor logboekregistratie, validatie of transformatie
2. Contextlaag : beheert de chatgeschiedenis (ChatHistoryProvider) en injecteert extra context (AIContextProviders)
3. Chatclientlaag - IChatClient met optionele middleware-decorators die de LLM-communicatie verwerken

Wanneer u aanroept RunAsync(), loopt uw aanvraag in volgorde door elke laag.

Agent-pijplijn

De Agent klasse bouwt een pijplijn via klassesamenstelling met twee hoofdonderdelen:

Agent (outer component):

1. Agent Middleware + Telemetry - de AgentMiddlewareLayer en AgentTelemetryLayer klassen verwerken middleware-aanroep en OpenTelemetry-instrumentatie
2. RawAgent - Kernagentlogica die contextproviders aanroept
3. Contextproviders - Geïntegreerde context_providers lijst beheert geschiedenis en aanvullende context

ChatClient (afzonderlijk en uitwisselbaar onderdeel):

1. Chat Middleware + telemetrie - Optionele middlewareketen- en instrumentatielagen
2. FunctionInvocation - Behandelt de oproeplus voor hulpmiddelen, het aanroepen van functionele middleware + telemetrie per hulpmiddeloproep
3. RawChatClient - Providerspecifieke implementatie (Azure OpenAI, OpenAI, Antropic, enzovoort) die communiceert met de LLM

Wanneer u run() belt, stroomt uw aanvraag door de agentlagen en vervolgens in de ChatClient-pijplijn voor LLM-communicatie.

Middlewarelaag van agent

Agent-middleware onderschept elke aanroep naar de uitvoeringsmethode van de agent, zodat u invoer en uitvoer kunt inspecteren of wijzigen.

Middleware toevoegen met behulp van het opbouwpatroon voor agents:

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

U kunt ook als agent-middleware gebruiken MessageAIContextProvider om extra berichten in de aanvraag te injecteren. Dit werkt met elk agenttype, niet alleen ChatClientAgent:

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

Deze laag verpakt de volledige uitvoering van de agent, inclusief contextomzetting en chatclientgesprekken. Dit heeft voordelen, omdat deze decorators kunnen worden gebruikt met elk type agent, bijvoorbeeld A2AAgent of GitHubCopilotAgent, niet alleen ChatClientAgent. Dit betekent ook dat decorators op dit niveau niet noodzakelijkerwijs veronderstellingen kunnen doen over de agent die het decoreert, wat betekent dat het beperkt is tot het aanpassen of beïnvloeden van algemene functionaliteit.

Middleware toevoegen bij het maken van de agent:

from agent_framework import Agent

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

De Agent klasse neemt over van AgentMiddlewareLayer, waarmee middlewareaanroep wordt verwerkt voordat deze wordt gedelegeert aan de kernagentlogica. Het erft ook van AgentTelemetryLayer, die verantwoordelijk is voor het verzenden van traces, gebeurtenissen en metingen naar een geconfigureerde OpenTelemetry-back-end. Beide lagen doen niets wanneer ze niet zijn geconfigureerd.

Zie Agent Middleware en Waarneembaarheidspatronen voor gedetailleerde middleware en waarneembaarheid.

Contextlaag

De contextlaag wordt uitgevoerd vóór elke LLM-aanroep om de volledige berichtgeschiedenis te bouwen en extra context in te voeren.

ChatClientAgent heeft twee verschillende providertypen:

• ChatHistoryProvider (enkel) - Beheert opslag van gespreksgeschiedenis en ophalen
• AIContextProviders (lijst) - Injecteert extra context zoals herinneringen, opgehaalde documenten of dynamische instructies

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

De agent roept de methode van elke provider aan voordat berichten naar de chatclient worden verzonden. De uitvoer van elke provider wordt als invoer doorgegeven aan de volgende provider.

De Agent klasse maakt gebruik van een uniforme context_providers lijst die zowel geschiedenisproviders als contextproviders kan bevatten:

from agent_framework import Agent, InMemoryHistoryProvider

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

Zie Contextproviders voor gedetailleerde patronen van contextproviders.

Chatclient-laag

De chatclientlaag verwerkt de werkelijke communicatie met de LLM-service.

ChatClientAgent gebruikt een IChatClient exemplaar, dat kan worden ingericht met extra middleware:

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

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

U kunt ook als chatclient-middleware gebruiken AIContextProvider om berichten, hulpprogramma's en instructies op clientniveau te verrijken. Dit moet worden gebruikt binnen de context van een actieve AIAgent:

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

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

ChatClientAgent Verpakt standaard de meegeleverde chatclient met ondersteuning voor functie-aanroep. Stel UseProvidedChatClientAsIs = true in de opties in om deze standaardomsluiting over te slaan.

De Agent klasse accepteert elke client die implementeert SupportsChatGetResponse. De ChatClient-pijplijn verwerkt middleware, telemetrie, functie-aanroep en providerspecifieke communicatie:

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

De RawChatClient binnen chatclient implementeert de providerspecifieke logica voor communicatie met verschillende LLM-services.

Uitvoeringsstroom

Wanneer u een agent aanroept, loopt de aanvraag via de pijplijn:

1. Agent-middleware wordt uitgevoerd (indien geconfigureerd)
2. ChatHistoryProvider laadt de gespreksgeschiedenis in de berichtenlijst van de aanvraag
3. AIContextProviders voegt berichten, hulpprogramma's of instructies toe aan de aanvraag
4. IChatClient middleware wordt uitgevoerd (indien voorzien van decoraties)
5. IChatClient verzendt de aanvraag naar de LLM
6. Reactie loopt terug door dezelfde lagen
7. ChatHistoryProvider en AIContextProviders worden op de hoogte gesteld van nieuwe berichten

Agent-pijplijn:

1. Agent Middleware + Telemetry voert middleware uit (indien geconfigureerd) en neemt spans op
2. RawAgent roept contextproviders aan om de geschiedenis te laden en context toe te voegen
3. Aanvraag wordt doorgegeven aan de ChatClient

ChatClient-pijplijn:

4. Chat Middleware + Telemetrie wordt uitgevoerd (indien geconfigureerd)
5. FunctionInvocation verzendt een aanvraag naar de LLM en verwerkt de aanroepende lus van het hulpprogramma
   • Voor elke aanroep van het hulpprogramma wordt Functie Middleware + Telemetrie uitgevoerd
6. RawChatClient verwerkt providerspecifieke LLM-communicatie
7. Reactie loopt terug door dezelfde lagen
8. Contextproviders worden op de hoogte gesteld van nieuwe berichten voor opslag

Opmerking

Gespecialiseerde agents werken mogelijk anders dan de pijplijn die hier wordt beschreven.

Andere agenttypen

Niet alle agents gebruiken de volledige ChatClientAgent pijplijn. Agents zoals A2AAgent, GitHubCopilotAgentof CopilotStudioAgent communiceren met externe services in plaats van een lokale IChatClient. Ze ondersteunen echter nog steeds middleware op agentniveau.

Aangezien deze agents zijn afgeleid van AIAgent, kunt u dezelfde middlewarepatronen voor agents gebruiken:

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

Opmerking

U kunt geen middleware voor chatclients toevoegen aan deze agents omdat ze geen gebruik maken van IChatClient.

Volgende stappen 

Multimodal

Verwante inhoud

• Middleware : cross-cutting behavior toevoegen aan uw agents
• Contextproviders - Gedetailleerde patronen voor geschiedenis en contextinjectie
• Agents uitvoeren - Agents aanroepen