Arsitektur alur agen

Agen di Microsoft Agent Framework menggunakan arsitektur alur berlapis untuk memproses permintaan. Memahami arsitektur ini membantu Anda menyesuaikan perilaku agen dengan menambahkan middleware, penyedia konteks, atau modifikasi tingkat klien pada lapisan yang sesuai.

Jalur Pemrosesan ChatClientAgent

Membangun ChatClientAgent pipeline dengan tiga lapisan utama:

1. Middleware agen - Dekorator opsional yang membungkus agen melalui .Use() untuk pengelogan, validasi, atau transformasi
2. Lapisan konteks - Mengelola riwayat obrolan (ChatHistoryProvider) dan menyuntikkan konteks tambahan (AIContextProviders)
3. Lapisan klien obrolan - IChatClient dengan dekorator middleware opsional yang menangani komunikasi LLM

Saat Anda memanggil RunAsync(), permintaan Anda mengalir melalui setiap lapisan secara berurutan.

Rangkaian Agen

Kelas Agent ini membangun alur melalui komposisi kelas dengan dua komponen utama:

Agen (komponen luar):

1. Agent Middleware + Telemetry - AgentMiddlewareLayer kelas-kelas dan AgentTelemetryLayer menangani pemanggilan middleware dan instrumentasi OpenTelemetry
2. RawAgent - Logika agen inti yang memanggil penyedia konteks
3. Penyedia Konteks - Daftar terpadu context_providers mengelola riwayat dan konteks tambahan

ChatClient (komponen terpisah dan dapat dipertukarkan):

1. Chat Middleware + Telemetry - Rantai middleware opsional dan lapisan instrumentasi
2. FunctionInvocation - Mengelola perulangan pemanggilan alat, memanggil Middleware Fungsi dan Telemetri untuk setiap panggilan alat
3. RawChatClient - Implementasi khusus penyedia (Azure OpenAI, OpenAI, Anthropic, dll.) yang berkomunikasi dengan LLM

Saat Anda memanggil run(), permintaan Anda mengalir melalui lapisan Agen, lalu ke alur ChatClient untuk komunikasi LLM.

Lapisan agen middleware

Middleware agen mencegat setiap panggilan ke metode run agen, memungkinkan Anda untuk memeriksa atau memodifikasi input dan output.

Tambahkan middleware menggunakan pola pembangun agen.

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

Anda juga dapat menggunakan MessageAIContextProvider sebagai middleware agen untuk menyuntikkan pesan tambahan ke dalam permintaan. Ini berfungsi dengan jenis agen apa pun, bukan hanya ChatClientAgent:

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

Lapisan ini membungkus seluruh eksekusi agen, termasuk resolusi konteks dan panggilan klien obrolan. Ini memiliki manfaat, karena dekorator ini dapat digunakan dengan semua jenis agen, misalnya A2AAgent atau GitHubCopilotAgent, bukan hanya ChatClientAgent. Ini juga berarti bahwa dekorator pada tingkat ini tidak selalu dapat membuat asumsi tentang agen yang sedang didekorasi, artinya hanya dapat menyesuaikan atau memengaruhi fungsionalitas umum.

Tambahkan middleware saat membuat agen:

from agent_framework import Agent

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

Kelas Agent mewarisi dari AgentMiddlewareLayer, yang menangani pemanggilan middleware sebelum mendelegasikan ke logika agen inti. Ini juga mewarisi dari AgentTelemetryLayer, yang menangani mengalirkan rentang, peristiwa, dan metrik ke backend OpenTelemetry yang dikonfigurasi. Kedua lapisan ini, tidak melakukan apa pun ketika tidak dikonfigurasi.

Untuk pola middleware dan observabilitas terperinci, lihat Middleware Agen dan Observabilitas.

Lapisan konteks

Lapisan konteks berjalan sebelum setiap panggilan LLM untuk membangun riwayat pesan lengkap dan menyuntikkan konteks tambahan.

ChatClientAgent memiliki dua jenis penyedia yang berbeda:

• ChatHistoryProvider (tunggal) - Mengelola penyimpanan dan pengambilan riwayat percakapan
• AIContextProviders (list) - Menyuntikkan konteks tambahan seperti memori, dokumen yang diambil, atau instruksi dinamis

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

Agen memanggil metode setiap penyedia InvokingAsync() sebelum mengirim pesan ke klien obrolan dengan output setiap penyedia yang diteruskan sebagai input ke penyedia berikutnya.

Kelas Agent menggunakan daftar terpadu context_providers yang dapat mencakup penyedia riwayat dan penyedia konteks:

from agent_framework import Agent, InMemoryHistoryProvider

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

Untuk pola penyedia konteks terperinci, lihat Penyedia Konteks.

Lapisan klien chat

Lapisan antarmuka klien chat menangani komunikasi nyata dengan layanan LLM.

ChatClientAgent menggunakan instans IChatClient , yang dapat dihiasi dengan middleware tambahan:

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

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

Anda juga dapat menggunakan AIContextProvider sebagai middleware klien obrolan untuk memperkaya pesan, alat, dan instruksi di tingkat klien. Ini harus digunakan dalam konteks menjalankan AIAgent:

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

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

Secara default, ChatClientAgent membungkus klien obrolan yang disediakan dengan dukungan panggilan fungsi. Atur UseProvidedChatClientAsIs = true dalam opsi untuk melewati pembungkusan default ini.

Kelas Agent menerima klien apa pun yang mengimplementasikan SupportsChatGetResponse. Alur ChatClient menangani middleware, telemetri, pemanggilan fungsi, dan komunikasi khusus penyedia:

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

Dalam RawChatClient, ChatClient mengimplementasikan logika khusus untuk penyedia dalam berkomunikasi dengan berbagai layanan LLM.

Alur Pelaksanaan

Saat Anda memanggil agen, permintaan mengalir melalui alur:

1. Middleware agen dijalankan (jika dikonfigurasi)
2. ChatHistoryProvider memuat riwayat percakapan ke dalam daftar pesan permintaan
3. AIContextProviders menambahkan pesan, alat, atau instruksi ke permintaan
4. Middleware IChatClient dijalankan (jika didekorasi)
5. IChatClient mengirimkan permintaan ke LLM
6. Respons mengalir kembali melalui lapisan yang sama
7. ChatHistoryProvider dan AIContextProviders diberi tahu tentang pesan baru

Jalur proses agen:

1. Agent Middleware + Telemetry menjalankan middleware (jika dikonfigurasi) dan merekam rentang
2. RawAgent memanggil penyedia konteks untuk memuat riwayat dan menambahkan konteks
3. Permintaan diteruskan ke ChatClient

Alur Proses ChatClient:

4. Chat Middleware + Telemetri dijalankan (jika dikonfigurasi)
5. FunctionInvocation mengirim permintaan ke LLM dan menangani perulangan panggilan alat
   • Untuk setiap panggilan alat, Function Middleware + Telemetry dijalankan
6. RawChatClient menangani komunikasi LLM khusus penyedia
7. Respons mengalir kembali melalui lapisan yang sama
8. Penyedia konteks diberi tahu tentang pesan baru untuk penyimpanan

Nota

Agen khusus dapat bekerja secara berbeda dengan alur yang dijelaskan di sini.

Jenis agen lainnya

Tidak semua agen menggunakan alur lengkap ChatClientAgent . Agen seperti A2AAgent, , GitHubCopilotAgentatau CopilotStudioAgent berkomunikasi dengan layanan jarak jauh daripada menggunakan lokal IChatClient. Namun, mereka masih mendukung middleware tingkat agen.

Karena agen ini berasal dari AIAgent, Anda dapat menggunakan pola middleware agen yang sama:

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

Nota

Anda tidak dapat menambahkan middleware klien obrolan ke agen ini karena mereka tidak menggunakan IChatClient.

Langkah berikutnya

Multimodal

Konten terkait

• Middleware - Tambahkan fungsionalitas lintas aspek ke agen Anda
• Penyedia Konteks - Pola terperinci untuk riwayat dan injeksi konteks
• Menjalankan Agen - Cara menjalankan agen