Architektura potrubí agenta

Agenti v rozhraní Microsoft Agent Framework používají k zpracování požadavků architekturu vrstvených kanálů. Porozumění této architektuře vám pomůže přizpůsobit chování agenta přidáním middlewaru, zprostředkovatelů kontextu nebo úprav na úrovni klienta na příslušné vrstvě.

Potrubí ChatClientAgent

Vytvoří ChatClientAgent kanál se třemi hlavními vrstvami:

1. Middleware agenta – volitelné dekorátory, které agenta obalují pomocí .Use() pro účely protokolování, ověřování nebo transformace
2. Kontextová vrstva – spravuje historii chatu (ChatHistoryProvider) a vloží další kontext (AIContextProviders)
3. Vrstva klienta chatu – IChatClient s volitelnými dekorátory middlewaru, které zpracovávají komunikaci LLM

Když voláte RunAsync(), požadavek prochází jednotlivými vrstvami postupně.

Kanál agenta

Třída Agent sestaví kanál prostřednictvím složení třídy se dvěma hlavními komponentami:

Agent (vnější komponenta):

1. Middelware agenta + telemetrie – třídy AgentMiddlewareLayer a AgentTelemetryLayer zpracovávají volání middlewaru a instrumentaci OpenTelemetry
2. RawAgent – logika agenta Core, která vyvolává zprostředkovatele kontextu
3. Zprostředkovatelé kontextu – Sjednocený context_providers seznam spravuje historii a další kontext

ChatClient (samostatná a zaměnitelná komponenta):

1. FunctionInvocation - Obsluhuje smyčku volání nástroje, volání prostředí Function Middleware + Telemetrie při každém volání nástroje
2. Chat middleware + telemetrie – Volitelný řetězec middlewaru a vrstvy instrumentace, spuštěné při každém volání modelu
3. RawChatClient – implementace specifická pro poskytovatele (Azure OpenAI, OpenAI, Anthropic atd.), která komunikuje s LLM

Když zavoláte run(), vaše žádost prochází vrstvami agenta a pak do kanálu ChatClient pro komunikaci LLM.

Vrstva agenta middlewaru

Middleware agenta zachytí každé volání metody spuštění agenta, což vám umožní kontrolovat nebo upravovat vstupy a výstupy.

Přidejte middleware pomocí vzoru tvůrce agentů:

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

Jako middleware agenta můžete také použít MessageAIContextProvider k vložení dalších zpráv do požadavku. To funguje s libovolným typem agenta, nejen ChatClientAgent.

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

Tato vrstva obaluje celý běh agenta, včetně řešení kontextu a volání chatového klienta. To má výhody v tom, že tyto dekorátory lze použít s jakýmkoli typem agenta, např. A2AAgent, GitHubCopilotAgent, a nejen ChatClientAgent. To také znamená, že dekorátory na této úrovni nemohou nutně dělat předpoklady o agentovi, kterého zdobí, což je omezuje na přizpůsobení nebo ovlivňování běžných funkcí.

Při vytváření agenta přidejte middleware:

from agent_framework import Agent

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

Třída Agent dědí z AgentMiddlewareLayer, který zpracovává vyvolání middleware před delegováním do základní agentské logiky. Také dědí z AgentTelemetryLayer, který zpracovává generování rozsahů, událostí a metrik do nakonfigurovaného backendu OpenTelemetry. Obě tyto vrstvy nedělají nic, když nejsou nakonfigurované.

Podrobné vzory middlewaru a pozorovatelnosti najdete v tématu Agent Middleware a Pozorovatelnost.

Kontextová vrstva

Kontextová vrstva se spustí před každým voláním LLM, aby se sestavila úplná historie zpráv a vkážou se další kontext.

ChatClientAgent má dva různé typy zprostředkovatelů:

• ChatHistoryProvider (single) – Spravuje ukládání a načítání historie konverzací.
• AIContextProviders (list) – Vloží další kontext, jako jsou vzpomínky, načtené dokumenty nebo dynamické pokyny.

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

Agent volá metodu InvokingAsync() jednotlivých poskytovatelů před odesláním zpráv do chatovacího klienta s výstupem každého zprostředkovatele předaným jako vstup dalšímu poskytovateli.

Třída Agent používá jednotný context_providers seznam, který může obsahovat poskytovatele historie i zprostředkovatele kontextu:

from agent_framework import Agent, InMemoryHistoryProvider

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

Podrobné vzory zprostředkovatele kontextu najdete v tématu Zprostředkovatelé kontextu.

Vrstva chatovacího klienta

Vrstva chatovacího klienta zpracovává skutečnou komunikaci se službou LLM.

ChatClientAgent IChatClient používá instanci, která může být zdobena dalším middlewarem:

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

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

Jako middleware chatovacího klienta můžete také použít AIContextProvider k obohacení zpráv, nástrojů a pokynů na úrovni klienta. Musí se použít v kontextu spuštěného AIAgent:

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

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

Ve výchozím nastavení ChatClientAgent zabalí poskytnutý chatovací klient s podporou volání funkcí. Nastavte UseProvidedChatClientAsIs = true v možnostech pro přeskočení výchozího zabalení.

Třída Agent přijímá všechny klienty, kteří implementují SupportsChatGetResponse. Kanál ChatClient zpracovává middleware, telemetrii, vyvolání funkcí a komunikaci specifickou pro poskytovatele:

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

V RawChatClient rámci ChatClient implementuje logiku specifickou pro poskytovatele pro komunikaci s různými službami LLM.

Tok provádění

Když vyvoláte agenta, požadavek projde potrubím:

1. Spustí se middleware agenta (pokud je nakonfigurovaný).
2. ChatHistoryProvider načte historii konverzací do seznamu zpráv žádosti.
3. AIContextProviders přidá do požadavku zprávy, nástroje nebo pokyny.
4. Middleware IChatClient se spustí (pokud je dekorován)
5. IChatClient odešle požadavek do LLM.
6. Odezva prochází zpět stejnými vrstvami.
7. ChatHistoryProvider a AIContextProviders jsou upozorněni na nové zprávy

Kanál agenta:

1. Agent Middleware + Telemetrie provádí middleware (pokud je nakonfigurován) a zaznamenává rozsahy.
2. RawAgent vyvolá zprostředkovatele kontextu za účelem načtení historie a přidání kontextu.
3. Žádost se předá do ChatClient.

Pipeline ChatClient:

4. FunctionInvocation spravuje volající smyčku nástroje.
   • Pro každé volání nástroje se spustí Function Middleware + Telemetry.
5. Chat Middleware + Telemetrie je spuštěno při každém volání modelu (pokud je nakonfigurováno)
6. RawChatClient zpracovává komunikaci LLM specifickou pro poskytovatele
7. Odezva prochází zpět stejnými vrstvami.
8. Zprostředkovatelé kontextu jsou upozorněni na nové zprávy k uložení.

Poznámka:

Specializované agenty můžou fungovat jinak než pipelina popsaná tady.

Jiné typy agentů

Ne všichni agenti používají celý ChatClientAgent kanál. Agenti jako A2AAgent, GitHubCopilotAgent nebo CopilotStudioAgent komunikují se vzdálenými službami, a tím pádem nepoužívají místní IChatClient. Stále však podporují middleware na úrovni agenta.

Protože tito agenti vycházejí z AIAgent, můžete použít stejné vzory agentového middlewaru:

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

Poznámka:

Do těchto agentů není možné přidat middleware chatovacího klienta, protože nepoužívají IChatClient.

Další kroky

Multimodální

Související obsah

• Middleware – Přidejte průřezové chování svým agentům
• Zprostředkovatelé kontextu – podrobné vzory pro historii a injektáž kontextu
• Spouštění agentů – jak spouštět agenty