Architektura przepływu agenta

Agenci w programie Microsoft Agent Framework używają architektury potoku warstwowego do przetwarzania żądań. Zrozumienie tej architektury ułatwia dostosowanie zachowania agenta przez dodanie oprogramowania pośredniczącego, dostawców kontekstu lub modyfikacji na poziomie klienta w odpowiedniej warstwie.

Potok danych ChatClientAgent

ChatClientAgent tworzy potok z trzema głównymi warstwami:

1. Oprogramowanie pośredniczące agenta — opcjonalne dekoratory, które mogą opakowywać agenta w celu rejestrowania, walidacji lub transformacji
2. Warstwa kontekstu — zarządza historią czatów (ChatHistoryProvider) i wprowadza dodatkowy kontekst (AIContextProviders)
3. Warstwa klienta czatu — IChatClient opcjonalne dekoratory oprogramowania pośredniczącego obsługujące komunikację LLM

Po wywołaniu RunAsync() żądanie przepływa przez każdą warstwę w kolejności.

Przepływ pracy agenta

Klasa Agent buduje pipeline poprzez kompozycję klas obejmującą dwa główne składniki:

Agent (składnik zewnętrzny):

1. Agent Middleware + Telemetry — klasy AgentMiddlewareLayer i AgentTelemetryLayer obsługują wywołania middleware oraz instrumentację OpenTelemetry
2. RawAgent — główna logika agenta, która wywołuje dostawców kontekstu
3. Dostawcy kontekstu — ujednolicona context_providers lista zarządza historią i dodatkowym kontekstem

ChatClient (oddzielny i zamienny składnik):

1. Oprogramowanie pośredniczące czatu i telemetria — opcjonalne łańcuchy oprogramowania pośredniczącego i warstwy instrumentacji
2. FunctionInvocation — obsługuje pętlę wywoływania narzędzi, wywołując Middleware funkcji i telemetrię dla każdego wywołania narzędzia
3. RawChatClient — implementacja specyficzna dla dostawcy (Azure OpenAI, OpenAI, Anthropic itp.), która komunikuje się z usługą LLM

Po wywołaniu run() żądanie przepływa przez warstwy agenta, a następnie do potoku ChatClient w celu komunikacji z LLM.

Warstwa oprogramowania pośredniczącego agenta

Oprogramowanie pośredniczące agenta przechwytuje każde wywołanie metody run agenta, co pozwala na inspekcję lub modyfikowanie danych wejściowych i wyjściowych.

Dodaj oprogramowanie pośredniczące przy użyciu wzorca konstruktora agenta:

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

Możesz również użyć MessageAIContextProvider jako pośrednika agenta do wstrzykiwania dodatkowych komunikatów do żądania. Działa to z dowolnym typem agenta, a nie tylko ChatClientAgent:

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

Ta warstwa opakowuje całe działanie agenta, w tym rozpoznawanie kontekstu i wywołania klienta chatu. Ma to korzyści, ponieważ te dekoratory mogą być używane z dowolnym typem agenta, np. A2AAgent lub GitHubCopilotAgent, a nie tylko ChatClientAgent. Oznacza to również, że dekoratory na tym poziomie nie mogą zakładać pewnych rzeczy dotyczących agenta, którego dekorują, co oznacza, że są ograniczone do dostosowywania lub wpływania na wspólne funkcje.

Dodaj oprogramowanie pośredniczące podczas tworzenia agenta:

from agent_framework import Agent

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

Klasa Agent dziedziczy z klasy AgentMiddlewareLayer, która obsługuje wywołanie middleware przed przekazaniem do podstawowej logiki agenta. Dziedziczy również z AgentTelemetryLayer, który obsługuje emitowanie zakresów, zdarzeń i metryk do skonfigurowanego zaplecza OpenTelemetry. Obie te warstwy nie robią nic, jeśli nie są skonfigurowane.

Aby uzyskać szczegółowe wzorce oprogramowania pośredniczącego i obserwowalności, zobacz Agent Middleware i Obserwowalność.

Warstwa kontekstu

Warstwa kontekstu jest uruchamiana przed każdym wywołaniem usługi LLM w celu utworzenia pełnej historii komunikatów i wstrzyknięcia dodatkowego kontekstu.

ChatClientAgent ma dwa odrębne typy dostawców:

• ChatHistoryProvider (pojedynczy) — zarządza przechowywaniem i pobieraniem historii konwersacji
• AIContextProviders (lista) — wprowadza dodatkowy kontekst, taki jak wspomnienia, pobrane dokumenty lub instrukcje dynamiczne

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

Agent wywołuje metodę każdego dostawcy InvokingAsync() przed wysłaniem wiadomości do klienta czatu z danymi wyjściowymi każdego dostawcy przekazanymi jako dane wejściowe do następnego dostawcy.

Klasa Agent używa ujednoliconej context_providers listy, która może zawierać zarówno dostawców historii, jak i dostawców kontekstu:

from agent_framework import Agent, InMemoryHistoryProvider

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

Aby uzyskać szczegółowe wzorce dostawcy kontekstu, zobacz Dostawcy kontekstu.

Warstwa klienta czatu

Warstwa klienta czatu obsługuje rzeczywistą komunikację z usługą LLM.

ChatClientAgent IChatClient używa instancji, które można rozszerzyć o dodatkowe oprogramowanie pośredniczące:

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

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

Możesz również użyć AIContextProvider jako pośredniczącego oprogramowania klienta czatu, aby wzbogacać wiadomości, narzędzia oraz instrukcje na poziomie klienta. Należy to użyć w kontekście uruchomionego elementu AIAgent:

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

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

Domyślnie ChatClientAgent opakowuje dostarczonego klienta czatu z obsługą wywołań funkcji. Ustaw UseProvidedChatClientAsIs = true w opcjach, aby pominąć to domyślne zawijanie.

Klasa Agent akceptuje dowolnego klienta, który implementuje SupportsChatGetResponse. Potok ChatClient obsługuje oprogramowanie pośredniczące, dane telemetryczne, wywołanie funkcji i komunikację specyficzną dla dostawcy:

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

Obiekt RawChatClient w programie ChatClient implementuje specyficzną dla dostawcy logikę komunikacji z różnymi usługami LLM.

Przepływ wykonania

Podczas wywoływania agenta żądanie przechodzi przez potok:

1. Oprogramowanie pośredniczące agenta uruchamia się (jeśli zostało skonfigurowane)
2. ChatHistoryProvider ładuje historię konwersacji do listy wiadomości żądania
3. AIContextProviders dodaj komunikaty, narzędzia lub instrukcje do żądania
4. Oprogramowanie pośredniczące IChatClient jest wykonywane (jeśli jest oznaczone)
5. Klient IChatClient wysyła żądanie do usługi LLM
6. Odpowiedź przepływa z powrotem przez te same warstwy
7. ChatHistoryProvider i AIContextProviders są powiadamiane o nowych komunikatach

Potok agenta:

1. Agent Middleware + Telemetria wykonuje oprogramowanie pośredniczące (jeśli zostało skonfigurowane) i rejestruje spany
2. Funkcja RawAgent wywołuje dostawców kontekstu w celu załadowania historii i dodania kontekstu
3. Żądanie jest przekazywane do obiektu ChatClient

Potok ChatClient:

4. Oprogramowanie pośredniczące czatu i telemetria jest wykonywane (jeśli zostało skonfigurowane)
5. WywołanieFunkcji wysyła żądanie do LLM i obsługuje pętlę wywołań narzędzi.
   • Dla każdego wywołania narzędzia Funkcja Middleware + Telemetria jest wykonywana
6. RawChatClient obsługuje komunikację LLM specyficzną dla dostawcy
7. Odpowiedź przepływa z powrotem przez te same warstwy
8. Dostawcy kontekstu są powiadamiani o nowych wiadomościach do przechowywania

Uwaga / Notatka

Wyspecjalizowani agenci mogą działać inaczej w potoku opisanym tutaj.

Inne typy agentów

Nie wszyscy agenci używają pełnego ChatClientAgent potoku. Agenci, tacy jak A2AAgent, GitHubCopilotAgent lub CopilotStudioAgent, komunikują się z usługami zdalnymi zamiast używać lokalnego programu IChatClient. Jednak nadal obsługują oprogramowanie pośredniczące na poziomie agenta.

Ponieważ ci agenci pochodzą z AIAgent, można użyć tych samych wzorców pośredniczących agenta.

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

Uwaga / Notatka

Nie można dodać middleware klienta czatu do tych agentów, ponieważ nie używają IChatClient.

Następne kroki

Multimodalny

Treści powiązane

• Oprogramowanie pośredniczące — dodawanie przekrojowego zachowania do agentów
• Dostawcy kontekstu — szczegółowe wzorce dotyczące wstrzykiwania historii i kontekstu
• Uruchamianie agentów — jak wywoływać agentów