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 dan mengumpulkan middleware yang ditambahkan penyedia
3. Penyedia Konteks - Daftar terpadu context_providers mengelola riwayat, konteks tambahan, dan middleware untuk obrolan/fungsi setiap kali dijalankan

ChatClient (komponen terpisah dan dapat dipertukarkan):

1. FunctionInvocation - Mengelola perulangan pemanggilan alat, memanggil Middleware Fungsi dan Telemetri untuk setiap panggilan alat
2. Chat Middleware + Telemetri - Rantai middleware opsional dan lapisan instrumentasi, termasuk middleware obrolan apa pun yang ditambahkan oleh penyedia konteks, berjalan per panggilan model
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.

Kemampuan Agent Hooks opsional menginstal satu bundel middleware di seluruh lapisan agen, obrolan, dan fungsi. Gerbang streaming dan persistensi inti memperluas batas tersebut sehingga output tidak dirilis atau disimpan sebelum putusan yang berlaku mengizinkannya.

Arsitektur alur agen

Di Go, agen menggunakan alur middleware berlapis. Middleware membungkus fungsi agen Run, masing-masing memanggil next untuk meneruskan kontrol ke lapisan berikutnya.

Saat agen berjalan, siklus hidupnya diterapkan dalam urutan berikut:

1. Middleware agen kustom - agent.Config.Middlewares terdaftar Anda, diterapkan sesuai urutan deklarasi di sepanjang seluruh siklus hidup agen
2. Penyedia riwayat - Memuat pesan sebelumnya dan menyimpan pesan permintaan/respons yang lebih baru
3. Penyedia konteks - Menyuntikkan konteks, opsi, dan status dari instans terdaftar agent.ContextProvider
4. Middleware yang terdaftar pada penyedia - Middleware yang terdaftar pada penyedia seperti pemanggilan alat otomatis, output terstruktur, dan penyusunan respons
5. Penyedia - Penyedia LLM yang mendasarinya, seperti OpenAI atau Anthropic

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.

Tambahkan middleware dengan mengimplementasikan antarmuka Middleware atau menggunakan agent.MiddlewareFunc untuk middleware ringan:

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

Setiap middleware menerima fungsi next dalam rangkaian dan dapat memodifikasi pesan atau opsi sebelum memanggil next, memproses respons setelah memanggil next, atau menghentikan alur lebih awal.

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},
    },
})

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

Penyedia konteks juga dapat menghubungkan middleware obrolan atau fungsi ke satu pemanggilan melalui SessionContext.extend_middleware(). Agen meratakan penambahan tersebut dalam urutan penyedia sebelum memasuki alur ChatClient.

Penyedia konteks berjalan dalam siklus hidup agen setelah middleware kustom masuk ke dalam proses eksekusi dan sebelum middleware penyedia memanggil model. Penyedia konteks dapat menambahkan pesan atau opsi sebelum panggilan penyedia dan mempertahankan status setelah eksekusi.

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

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

client = FoundryChatClient(
    credential=credential,
    project_endpoint=endpoint,
    model=model,
)

agent = Agent(client=client, instructions="You are helpful.")

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

Middleware provider dijalankan setelah provider riwayat dan konteks, tepat sebelum provider LLM yang mendasari. Pembantu tingkat agen seperti OpenTelemetry dan pengelogan eksekusi terdaftar sebagai middleware agen kustom dan membungkus langkah-langkah siklus hidup sebelumnya.

Komponen	Registration	Lapisan	Kegunaan
Panggilan otomatis	agent/harness/toolautocall	Middleware penyedia	Secara otomatis memanggil alat fungsi
Output terstruktur	agent.WithStructuredOutput	Middleware penyedia	Menangani parsing keluaran terstruktur
OpenTelemetry	provider/otelprovider	Middleware agen	Melacak pemanggilan agen
Jalankan pencatat	agent.Config.Logger	Middleware agen	Mencatat interaksi agen

agent.ContextProvider value adalah komponen siklus hidup, bukan implementasi agent.Middleware. Mereka berjalan antara middleware agen kustom dan middleware penyedia.

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, menambahkan konteks, dan mengumpulkan middleware obrolan/fungsi yang ditambahkan penyedia
3. Permintaan diteruskan ke ChatClient

Alur Proses ChatClient:

4. FunctionInvocation mengelola perulangan panggilan alat
   • Untuk setiap panggilan alat, Function Middleware + Telemetry dieksekusi, termasuk fungsi middleware apa pun yang ditambahkan oleh penyedia konteks
5. Chat Middleware + Telemetri dieksekusi untuk setiap panggilan model (jika dikonfigurasi), termasuk middleware obrolan yang ditambahkan oleh penyedia konteks
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.

1. Middleware agen kustom dieksekusi terlebih dahulu dan mencakup seluruh siklus hidup agen.
2. Penyedia riwayat memuat riwayat percakapan untuk sesi saat ini ketika riwayat lokal aktif.
3. Penyedia konteks menambahkan pesan, opsi, atau status sebelum panggilan penyedia.
4. Middleware penyedia dijalankan, termasuk middleware pemanggilan alat otomatis dan penanganan keluaran terstruktur saat diaktifkan.
5. Penyedia mengirimkan permintaan ke model.
6. Pembaruan respons mengalir kembali melalui middleware penyedia dan middleware agen kustom.
7. Penyedia riwayat dan penyedia konteks menyimpan status respons setelah berhasil dijalankan.

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.

Jenis agen lainnya

Tidak setiap agen Python menggunakan alur lengkap Agent + ChatClient . GitHubCopilotAgent, misalnya, mengirim permintaan melalui GitHub Copilot CLI alih-alih klien obrolan lokal.

Meski begitu, Python GitHubCopilotAgent masih mendukung middleware agen dan sekarang berjalan context_providers di setiap pemanggilan. Pesan dan instruksi yang ditambahkan oleh penyedia disertakan dalam perintah yang dikirim ke Copilot, dan penyedia menerima callback yang sesuai after_run setelah respons tersedia.

Nota

Karena GitHubCopilotAgent tidak menggunakan klien obrolan lokal, middleware klien obrolan masih tidak berlaku.

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