Pelaksana Agen

Saat Anda menambahkan agen AI ke alur kerja, agen tersebut perlu dibungkus dalam pelaksana sehingga mesin alur kerja dapat merutekan pesan ke dalamnya, mengelola status sesinya, dan menangani outputnya. Pelaksana Agen adalah eksekutor bawaan yang menangani adaptasi ini.

Ikhtisar

Agen Executor menjembatani kesenjangan antara abstraksi agen dan model eksekusi alur kerja. Hal itu:

Menerima pesan yang diketik dari grafik alur kerja dan meneruskannya ke agen yang mendasar.
Mengelola sesi agen dan keadaan percakapan di antara siklus eksekusi.
Menyesuaikan perilakunya berdasarkan mode eksekusi alur kerja (streaming atau non-streaming).
Menghasilkan peristiwa output (AgentResponse atau AgentResponseUpdate) ke pemanggil alur kerja untuk pengamatan.
Mengirim pesan ke pelaksana hilir yang tersambung untuk pemrosesan berkelanjutan dalam grafik.
Mendukung titik pemeriksaan untuk alur kerja yang berjalan lama.

Cara Kerjanya

Di C#, mesin alur kerja secara internal membuat AIAgentHostExecutor untuk setiap AIAgent yang ditambahkan ke alur kerja. Pelaksana ChatProtocolExecutor khusus ini memperluas dan menggunakan pola token giliran :

Cache pesan — ketika pesan datang dari pelaksana lainnya, agen pelaksana mengumpulkan pesan tersebut. Jika ForwardIncomingMessages diaktifkan (default), pesan masuk juga diteruskan ke pelaksana hilir.
Ubah pemicu token — agen memproses pesan yang di-cache hanya setelah menerima TurnToken.
Pemanggilan agen — pelaksana memanggil RunAsync (non-streaming) atau RunStreamingAsync (streaming) pada agen yang mendasari.
Output yang dihasilkan — jika peristiwa streaming diaktifkan, setiap inkremental AgentResponseUpdate dihasilkan sebagai output alur kerja. Jika EmitAgentResponseEvents diaktifkan, agregat AgentResponse juga dihasilkan sebagai output alur kerja.
Pengiriman pesan hilir — pesan respons agen dikirim ke pelaksana hilir yang tersambung.
Operasikan token pass-through — setelah menyelesaikan gilirannya, pelaksana meneruskan TurnToken ke hilir sehingga agen berikutnya dalam rantai dapat mulai memproses.

Petunjuk / Saran

Beberapa skenario mungkin memerlukan pelaksana agen yang lebih khusus; misalnya, orkestrasi handoff menggunakan pelaksana khusus HandoffAgentExecutor dengan logika perutean yang disesuaikan.

Pembuatan Implisit vs Eksplisit

Ketika Anda meneruskan AIAgent ke WorkflowBuilder, kerangka kerja secara otomatis membungkusnya dalam AIAgentBinding, yang mendasari AIAgentHostExecutor. Anda tidak perlu membuat instans pelaksana agen secara langsung.

AIAgent writerAgent = /* create your agent */;
AIAgent reviewerAgent = /* create your agent */;

// Agents are automatically wrapped — no manual executor creation required
var workflow = new WorkflowBuilder(writerAgent)
    .AddEdge(writerAgent, reviewerAgent)
    .Build();

Anda juga dapat menggunakan metode pembantu pada AgentWorkflowBuilder untuk pola umum.

// Build a sequential pipeline of agents
var workflow = AgentWorkflowBuilder.BuildSequential(writerAgent, reviewerAgent);

Konfigurasi Kustom

Untuk menyesuaikan bagaimana eksekutor agen berperilaku, gunakan BindAsExecutor dengan AIAgentHostOptions:

var options = new AIAgentHostOptions
{
    EmitAgentUpdateEvents = true,
    EmitAgentResponseEvents = true,
    ReassignOtherAgentsAsUsers = true,
    ForwardIncomingMessages = true,
};

ExecutorBinding writerBinding = writerAgent.BindAsExecutor(options);
var workflow = new WorkflowBuilder(writerBinding)
    .AddEdge(writerBinding, reviewerAgent)
    .Build();

Jenis Input

Pelaksana agen di C# menerima beberapa jenis input: string, , ChatMessagedan IEnumerable<ChatMessage>. Input string secara otomatis dikonversi menjadi instans ChatMessage dengan peran User. Semua pesan masuk diakumulasikan sampai TurnToken diterima, di mana pelaksana memproses batch. Ketika ReassignOtherAgentsAsUsers diaktifkan (default), pesan dari agen lain ditetapkan ulang ke peran User sehingga model yang mendasar memperlakukannya sebagai input pengguna, sementara pesan dari agen saat ini mempertahankan peran Assistant.

Output dan Rantai Proses

Setelah agen menyelesaikan tugasnya, pelaksana:

Mengirim pesan respons agen ke semua pelaksana hilir yang terhubung.
Meneruskan TurnToken baru sehingga agen berikutnya dalam rantai dapat mulai memproses.

Ini membuat agen rantai mudah - cukup hubungkan dengan tepi:

var workflow = new WorkflowBuilder(frenchTranslator)
    .AddEdge(frenchTranslator, spanishTranslator)
    .AddEdge(spanishTranslator, englishTranslator)
    .Build();

Perilaku Streaming

Perilaku streaming dikontrol oleh EmitAgentUpdateEvents opsi pada AIAgentHostOptions, atau secara dinamis melalui TurnToken:

Saat diaktifkan — eksekutor memanggil RunStreamingAsync agen dan menghasilkan masing-masing AgentResponseUpdate sebagai peristiwa output alur kerja. Ini menyediakan pembaruan secara real-time per token.
Saat dinonaktifkan — pelaksana RunAsync memanggil dan menghasilkan satu respons lengkap.

// Enable streaming events at the configuration level
var options = new AIAgentHostOptions
{
    EmitAgentUpdateEvents = true,
};

// Or enable streaming dynamically via TurnToken
await run.TrySendMessageAsync(new TurnToken(emitEvents: true));

Sesi Bersama

Setiap pelaksana agen mempertahankan sesinya sendiri secara default. Untuk berbagi sesi antar agen, konfigurasikan agen dengan penyedia sesi umum sebelum menambahkannya ke alur kerja.

Opsi Konfigurasi

AIAgentHostOptions mengontrol perilaku pelaksana agen:

Option	Default	Deskripsi
`EmitAgentUpdateEvents`	`null`	Mengeluarkan peristiwa pembaruan streaming selama pelaksanaan. `TurnToken` akan lebih diutamakan jika ditetapkan. Jika keduanya adalah `null`, streaming dinonaktifkan.
`EmitAgentResponseEvents`	`false`	Keluarkan respons agen agregat sebagai peristiwa output alur kerja.
`InterceptUserInputRequests`	`false`	Mencegat `UserInputRequestContent` dan merutekannya sebagai pesan proses kerja agar dapat ditangani.
`InterceptUnterminatedFunctionCalls`	`false`	Mencegat `FunctionCallContent` tanpa hasil yang sesuai dan mengarahkannya sebagai pesan alur kerja.
`ReassignOtherAgentsAsUsers`	`true`	Menugaskan kembali pesan dari agen lain ke peran `User` sehingga model memperlakukannya sebagai input pengguna.
`ForwardIncomingMessages`	`true`	Teruskan pesan masuk ke eksekutor downstream sebelum pesan yang dihasilkan oleh agen.

Titik Pemeriksaan

Pelaksana agen mendukung titik pemeriksaan untuk alur kerja yang berjalan lama. Ketika titik pemeriksaan diambil, pelaksana menserialisasikan:

Status sesi agen (melalui SerializeSessionAsync).
Konfigurasi emisi peristiwa giliran saat ini (hanya ada saat permintaan tertunda dan pelaksana belum menghasilkan yang masuk TurnToken).
Setiap permintaan input pengguna yang tertunda dan permintaan panggilan fungsi.

Saat proses pemulihan, pelaksana mendeserialisasi sesi dan status permintaan yang tertunda, sehingga alur kerja dapat dilanjutkan dari titik terakhir.

Cara Kerjanya

Kelas AgentExecutor membungkus agen yang mengimplementasikan protokol SupportsAgentRun. Saat pelaksana menerima pesan:

Normalisasi pesan — input dinormalisasi ke dalam daftar Message objek dan ditambahkan ke cache internal pelaksana. Pelaksana menerima beberapa jenis input — str, Message, list[str | Message], AgentExecutorRequest, dan AgentExecutorResponse — setiap dirutekan ke handler khusus yang menormalkan input sebelum caching.
Pemanggilan agen — eksekutor memanggil agent.run() dengan pesan yang telah di-cache, secara otomatis memilih antara mode streaming atau non-streaming berdasarkan mode eksekusi alur kerja.
Emisi output — dalam mode streaming, masing-masing AgentResponseUpdate dihasilkan sebagai peristiwa keluaran alur kerja. Dalam mode non-streaming, satu AgentResponse dihasilkan.
Pengiriman hilir — setelah agen selesai, pelaksana mengirim AgentExecutorResponse kepada semua pelaksana hilir yang terhubung. Respons ini mencakup riwayat percakapan lengkap, memungkinkan penautan yang mulus.
Cache reset — cache pesan internal dari eksekutor dibersihkan setelah agen dipanggil, memastikan bahwa setiap kali agen dipanggil hanya memproses pesan baru yang diterima sejak pemanggilan terakhir.

Petunjuk / Saran

Beberapa skenario mungkin memerlukan pelaksana agen yang lebih khusus; misalnya, orkestrasi penyerahan menggunakan pelaksana yang khusus dengan logika perutean kustom.

Pembuatan Implisit vs Eksplisit

Secara otomatis, WorkflowBuilder mengelola agen dalam AgentExecutor instance ketika Anda meneruskan agen secara langsung. Untuk sebagian besar alur kerja, pembuatan implisit sudah cukup:

from agent_framework import WorkflowBuilder

writer_agent = client.as_agent(name="Writer", instructions="...")
reviewer_agent = client.as_agent(name="Reviewer", instructions="...")

# Agents are automatically wrapped — no manual AgentExecutor creation required
workflow = (
    WorkflowBuilder(start_executor=writer_agent)
    .add_edge(writer_agent, reviewer_agent)
    .build()
)

Pembuatan Eksplisit

Buat AgentExecutor secara eksplisit saat Anda membutuhkannya.

Bagikan sesi antara beberapa agen.
Berikan ID pelaksana kustom untuk perutean dan kwarg runtime yang ditargetkan.
Gunakan referensi instans pelaksana yang sama di beberapa tepi.

from agent_framework import AgentExecutor

writer_executor = AgentExecutor(writer_agent, id="my-writer")
reviewer_executor = AgentExecutor(reviewer_agent, id="my-reviewer")

workflow = (
    WorkflowBuilder(start_executor=writer_executor)
    .add_edge(writer_executor, reviewer_executor)
    .build()
)

Parameter konstruktor:

Parameter	Tipe	Deskripsi
`agent`	`SupportsAgentRun`	Agen untuk dibungkus.
`session`	`AgentSession \\| None`	Sesi yang digunakan untuk menjalankan agen. Jika `None`, sesi baru dibuat oleh agen.
`id`	`str \\| None`	ID pelaksana unik. Default ke nama agen jika tersedia.
`context_mode`	`"full" \\| "last_agent" \\| "custom" \\| None`	Mengontrol bagaimana konteks percakapan ditangani saat menerima `AgentExecutorResponse` dari agen upstream. Secara default ke `"full"`, yang menyediakan percakapan lengkap agen upstream (input + respons). Lihat Mode Konteks.
`context_filter`	`Callable[[list[Message]], list[Message]] \\| None`	Fungsi filter kustom untuk memilih pesan mana yang akan disertakan. Diperlukan saat `context_mode` adalah `"custom"`.

Petunjuk / Saran

ID pelaksana juga merupakan kunci yang digunakan saat Anda menargetkan workflow.run(function_invocation_kwargs=...) atau client_kwargs= pada agen individual. Jika Anda menghilangkan id, alur kerja menggunakan nama agen yang dibungkus.

Jenis Input

AgentExecutor mendefinisikan berbagai metode handler, yang masing-masing menerima jenis input berbeda. Mesin alur kerja secara otomatis mengirimkan handler yang benar berdasarkan jenis pesan. Semua jenis input memicu agen untuk segera berjalan, kecuali AgentExecutorRequest di mana should_respond bendera mengontrol apakah agen berjalan atau hanya menyimpan pesan:

Jenis input	Pengendali	Agen Pemicu	Deskripsi
`AgentExecutorRequest`	`run`	Bersyarat	Jenis input kanonis. Berisi daftar pesan dan `should_respond` flag yang mengontrol apakah agen berjalan.
`str`	`from_str`	Selalu	Menerima perintah string mentah.
`Message`	`from_message`	Selalu	Menerima satu `Message` objek.
`list[str \\| Message]`	`from_messages`	Selalu	Menerima daftar string atau `Message` objek sebagai konteks percakapan.
`AgentExecutorResponse`	`from_response`	Selalu	Menerima respons pelaksana agen sebelumnya, memungkinkan penautan langsung.

Menggunakan AgentExecutorRequest

AgentExecutorRequest adalah jenis input kanonis dan memberikan kontrol terbanyak:

from agent_framework import AgentExecutorRequest, Message

# Create a request with messages
request = AgentExecutorRequest(
    messages=[Message(role="user", contents=["Hello, world!"])],
    should_respond=True,
)

# Run the workflow
result = await workflow.run(request)

Bendera should_respond mengontrol apakah agen segera memproses pesan atau hanya menyimpannya untuk nanti:

True (default) — agen menjalankan dan menghasilkan respons.
False — pesan ditambahkan ke cache tetapi agen tidak berjalan. Ini berguna untuk memuat konteks percakapan sebelumnya sebelum memicu respons.

Output dan Rantai Proses

Setelah agen selesai, pelaksana mengirimkan AgentExecutorResponse ke hilir. Klasifikasi data ini berisi:

Ladang	Tipe	Deskripsi
`executor_id`	`str`	ID pelaksana yang menghasilkan respons.
`agent_response`	`AgentResponse`	Respons agen dasar (tanpa perubahan dari sisi klien).
`full_conversation`	`list[Message]`	Konteks percakapan lengkap (input sebelumnya + output agen) untuk penerusan.

Saat merangkaikan eksekutor agen, eksekutor hilir menerima AgentExecutorResponse melalui handler from_response. Secara bawaan, menggunakan bidang full_conversation untuk mempertahankan riwayat percakapan lengkap, mencegah agen pemrosesan berikutnya kehilangan konteks sebelumnya. Anda dapat mengubah perilaku ini dengan mode konteks:

spam_detector = AgentExecutor(create_spam_detector_agent())
email_assistant = AgentExecutor(create_email_assistant_agent())

# The email_assistant receives the spam_detector's full conversation context
workflow = (
    WorkflowBuilder(start_executor=spam_detector)
    .add_edge(spam_detector, email_assistant)
    .build()
)

Perilaku Streaming

AgentExecutor Secara otomatis beradaptasi dengan mode eksekusi alur kerja:

stream=True — panggilan agent.run(stream=True) dan menghasilkan masing-masing AgentResponseUpdate sebagai peristiwa output alur kerja. Setelah streaming selesai, pembaruan dikumpulkan menjadi format lengkap AgentResponse untuk pengiriman ke hilir.
stream=False (default) — memanggil agent.run(stream=False) dan menghasilkan satu AgentResponse sebagai peristiwa output alur kerja.

# Streaming mode — receive incremental updates
events = workflow.run("Write a story about a cat.", stream=True)
async for event in events:
    if event.type == "output" and isinstance(event.data, AgentResponseUpdate):
        print(event.data.text, end="", flush=True)

# Non-streaming mode — receive complete response
result = await workflow.run("Write a story about a cat.")

# Retrieve AgentResponse objects from the result
outputs = result.get_outputs()
for output in outputs:
    if isinstance(output, AgentResponse):
        print(output.text)

Mode Konteks

Ketika agen dirangkai bersama-sama, context_mode parameter pada AgentExecutor mengontrol konteks percakapan yang digunakan oleh agen ketika menerima AgentExecutorResponse dari agen hulu melalui pengendali from_response.

Mode yang tersedia

Modus	Behavior
`"full"` (standar)	Agen mengonsumsi seluruh percakapan dari agen upstream — baik pesan input yang diberikan kepada agen upstream maupun pesan respons dari agen tersebut.
`"last_agent"`	Agen hanya mengonsumsi pesan respons dari agen upstream, tidak termasuk input yang diberikan kepada agen upstream.
`"custom"`	Fungsi yang disediakan pengguna `context_filter` menentukan pesan mana yang dikonsumsi agen. Memerlukan `context_filter` parameter .

Menggunakan mode `last_agent`

Gunakan "last_agent" ketika setiap agen harus fokus hanya pada transformasi output agen sebelumnya tanpa dipengaruhi oleh giliran percakapan sebelumnya. Ini berguna untuk alur terjemahan, penyempurnaan progresif, dan transformasi berurutan serupa:

from agent_framework import AgentExecutor, WorkflowBuilder

# Each agent consumes only the previous agent's response messages
french_executor = AgentExecutor(french_agent, context_mode="last_agent")
spanish_executor = AgentExecutor(spanish_agent, context_mode="last_agent")

workflow = (
    WorkflowBuilder(start_executor=writer_agent)
    .add_edge(writer_agent, french_executor)
    .add_edge(french_executor, spanish_executor)
    .build()
)

Dengan context_mode="last_agent", penerjemah Prancis hanya menggunakan pesan respons penulis (tidak termasuk permintaan pengguna asli yang dimasukkan ke penulis), dan penerjemah Spanyol hanya menggunakan pesan respons penerjemah Prancis.

Menggunakan `custom` modus

Untuk kontrol terperinci atas konteks yang dikonsumsi agen, gunakan context_mode="custom" dengan fungsi context_filter. Filter menerima percakapan lengkap sebagai list[Message] dan mengembalikan subset yang difilter:

from agent_framework import AgentExecutor, Message

def keep_user_and_last_agent(messages: list[Message]) -> list[Message]:
    """Keep only user messages and the last agent's response."""
    user_msgs = [m for m in messages if m.role == "user"]
    agent_msgs = [m for m in messages if m.role == "assistant"]
    return user_msgs + agent_msgs[-1:] if agent_msgs else user_msgs

executor = AgentExecutor(
    my_agent,
    context_mode="custom",
    context_filter=keep_user_and_last_agent,
)

Mode konteks dalam SequentialBuilder

Orkestrasi SequentialBuilder menyediakan parameter nyaman chain_only_agent_responses yang mengonfigurasi semua peserta agen untuk menggunakan context_mode="last_agent", sehingga setiap agen hanya menggunakan pesan respons agen sebelumnya:

from agent_framework.orchestrations import SequentialBuilder

workflow = SequentialBuilder(
    participants=[writer, translator, reviewer],
    chain_only_agent_responses=True,
).build()

Untuk contoh lengkapnya, lihat sequential_chain_only_agent_responses.py di repositori Kerangka Kerja Agen.

Sesi Bersama

Secara default, masing-masing AgentExecutor membuat sesinya sendiri. Untuk berbagi sesi antara beberapa agen (misalnya, untuk mempertahankan utas percakapan umum), buat sesi secara eksplisit dan teruskan ke setiap eksekutor:

from agent_framework import AgentExecutor

# Create a shared session from one agent
shared_session = writer_agent.create_session()

# Both executors share the same session
writer_executor = AgentExecutor(writer_agent, session=shared_session)
reviewer_executor = AgentExecutor(reviewer_agent, session=shared_session)

Nota

Tidak semua agen mendukung sesi bersama. Biasanya, hanya agen dengan jenis penyedia yang sama yang dapat berbagi sesi.

Titik Pemeriksaan

Mendukung checkpoint AgentExecutor untuk menyimpan dan memulihkan status dalam alur kerja yang berlangsung lama. Ketika titik pemeriksaan diambil, pelaksana menserialisasikan:

Cache pesan internal.
Riwayat percakapan lengkap.
Status sesi agen.
Setiap permintaan dan respons input pengguna yang tertunda.

Saat dipulihkan, pelaksana mendeserialisasi status ini, memungkinkan alur kerja dilanjutkan dari tempat yang ditinggalkannya.

Peringatan

Checkpointing dengan agen yang menggunakan sesi di sisi server (seperti FoundryAgent) memiliki batasan. Status sesi sisi server tidak diambil di titik pemeriksaan dan dapat dimodifikasi dengan eksekusi berikutnya. Pertimbangkan untuk menerapkan eksekutor kustom jika Anda memerlukan titik pemeriksaan yang andal dengan sesi di sisi server.

Langkah berikutnya

Agen dalam Alur Kerja

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-11

Pelaksana Agen

Ikhtisar

Cara Kerjanya

Pembuatan Implisit vs Eksplisit

Konfigurasi Kustom

Jenis Input

Output dan Rantai Proses

Perilaku Streaming

Sesi Bersama

Opsi Konfigurasi

Titik Pemeriksaan

Cara Kerjanya

Pembuatan Implisit vs Eksplisit

Pembuatan Eksplisit

Jenis Input

Menggunakan AgentExecutorRequest

Output dan Rantai Proses

Perilaku Streaming

Mode Konteks

Mode yang tersedia

Menggunakan mode last_agent

Menggunakan custom modus

Mode konteks dalam SequentialBuilder

Sesi Bersama

Titik Pemeriksaan

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan:

Menggunakan mode `last_agent`

Menggunakan `custom` modus