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 – jádrová logika agenta, která vyvolává zprostředkovatele kontextu a shromažďuje middleware přidaný poskytovateli.
3. Zprostředkovatelé kontextu – Sjednocený context_providers seznam spravuje historii, další kontext a middleware pro chat a funkce při spuštění

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. Chatové middleware + telemetrie – volitelný řetězec middlewaru a instrumentačních vrstev, včetně jakéhokoli chatového middleware přidaného poskytovateli kontextu, spouštěného 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.

Architektura potrubí agenta

V Go agenti používají vrstvený řetězec middlewarových vrstev. Middleware obalují funkci agenta Run, přičemž každý middleware volá next, aby předal řízení další vrstvě.

Když je agent spuštěn, jeho životní cyklus se uplatní v tomto pořadí:

1. Vlastní middleware agenta – vaše zaregistrované agent.Config.Middlewares, použité v pořadí deklarace v celém životním cyklu agenta
2. Zprostředkovatel historie – Načte předchozí zprávy a později ukládá zprávy požadavků a odpovědí.
3. Zprostředkovatelé kontextu – Vložení kontextu, možností a stavu z registrovaných agent.ContextProvider instancí
4. middleware poskytovatele - middleware registrovaný poskytovatelem, například automatické volání nástrojů, strukturované výstupy a vytváření odpovědí
5. Zprostředkovatel – základní poskytovatel LLM, například OpenAI nebo Anthropic

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é.

Přidejte middleware implementací Middleware rozhraní nebo použitím agent.MiddlewareFunc pro jednoduchý middleware:

type Middleware interface {
    Run(next RunFunc, ctx context.Context, messages []*message.Message,
        options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error]
}

Každý middleware obdrží v řetězci funkci next a před voláním next může upravovat zprávy nebo možnosti, po volání next zpracovávat odpovědi nebo předčasně ukončit pipeline.

timing := agent.MiddlewareFunc(
    func(next agent.RunFunc, ctx context.Context, messages []*message.Message, options ...agent.Option) iter.Seq2[*agent.ResponseUpdate, error] {
        start := time.Now()
        return func(yield func(*agent.ResponseUpdate, error) bool) {
            defer log.Printf("agent run completed in %s", time.Since(start))
            for update, err := range next(ctx, messages, options...) {
                if !yield(update, err) {
                    return
                }
            }
        }
    },
)

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Middlewares: []agent.Middleware{timing},
    },
})

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(),
    ],
)

Poskytovatelé kontextu mohou také při jednom vyvolání připojit middleware pro chat nebo funkci.SessionContext.extend_middleware() Agent tyto přídavky zploští v pořadí podle poskytovatele před vstupem do potrubí ChatClient.

Poskytovatelé kontextu se spouštějí v rámci životního cyklu agenta poté, co vlastní middleware vstoupí do běhu, a předtím, než middleware poskytovatele zavolá model. Zprostředkovatelé kontextu můžou přidat zprávy nebo možnosti před voláním poskytovatele a zachovat stav po spuštění.

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        ContextProviders: []agent.ContextProvider{memoryProvider},
    },
})

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 AIProjectClient(endpoint, credential)
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName)
    .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 AIProjectClient(endpoint, credential)
    .GetProjectOpenAIClient()
    .GetProjectResponsesClient()
    .AsIChatClient(deploymentName)
    .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.foundry import FoundryChatClient

client = FoundryChatClient(
    credential=credential,
    project_endpoint=endpoint,
    model=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.

Middleware zprostředkovatele běží po poskytovatelích historie a kontextu, bezprostředně před podkladovým poskytovatelem LLM. Pomocné nástroje na úrovni agenta, jako jsou OpenTelemetry a záznam běhu, jsou registrovány jako vlastní middleware agenta a obalují předchozí kroky životního cyklu.

Součást	Registration	Vrstva	Purpose
Automatické volání	agent/harness/toolautocall	Middleware pro poskytovatele	Automaticky vyvolá nástroje funkcí
Strukturovaný výstup	agent.WithStructuredOutput	Middleware pro poskytovatele	Podporuje parsování strukturovaného výstupu.
OpenTelemetry	provider/otelprovider	Middleware agenta	Trasuje volání agenta
Záznamník běhu	agent.Config.Logger	Middleware agenta	Zaznamenává interakce agentů

agent.ContextProvider hodnoty jsou součásti životního cyklu, nikoli agent.Middleware implementace. Spouští se mezi vlastním middlewarem agenta a middlewarem poskytovatele.

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, přidání kontextu a shromáždění middlewaru chatu nebo funkce přidaného poskytovatelem.
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í middleware funkcí + telemetrie, včetně jakéhokoli middleware funkcí přidaného poskytovateli kontextu.
5. Chat Middleware + Telemetrie se spouští na volání modelu (pokud je nakonfigurované), včetně jakéhokoli middlewaru chatu přidaného poskytovateli kontextu.
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í.

Note

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

1. Vlastní middleware agenta se spustí nejdříve a obaluje celý životní cyklus agenta.
2. Modul historie načítá historii konverzace pro aktuální relaci, když je aktivní místní historie.
3. Poskytovatelé kontextu před voláním poskytovatele přidávají zprávy, možnosti nebo stav.
4. Middleware poskytovatele se spouští, včetně middlewaru pro automatické volání nástrojů a zpracování strukturovaného výstupu, pokud je povoleno.
5. Poskytovatel odešle požadavek do modelu.
6. Aktualizace odpovědí proudí zpět prostřednictvím middlewaru poskytovatele a vlastního middlewaru agenta.
7. Poskytovatelé historie a zprostředkovatelé kontextu ukládají stav odpovědi po úspěšném spuštění.

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

Note

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

Jiné typy agentů

Ne každý agent Pythonu používá celý Agent + ChatClient kanál. GitHubCopilotAgentNapříklad odesílá žádosti prostřednictvím rozhraní příkazového řádku GitHub Copilot místo místního chatovacího klienta.

I tak Python GitHubCopilotAgent stále podporuje middleware agenta a nyní běží context_providers při každém spuštění. Zprávy a pokyny přidané poskytovatelem jsou zahrnuty do výzvy odeslané do Copilotu a zprostředkovatelé obdrží odpovídající after_run zpětné volání, jakmile bude odpověď k dispozici.

Note

Protože GitHubCopilotAgent nepoužívá místního chatovacího klienta, middleware chatovacího klienta stále není použit.

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