Perulangan agen

Perulangan agen memanggil ulang agen hingga kondisi penyelesaian terpenuhi. Gunakan ini untuk penyempurnaan secara bertahap, menyelesaikan daftar tugas, menunggu tugas latar belakang selesai, atau mengevaluasi apakah suatu jawaban memenuhi kriteria yang eksplisit.

Selalu batasi loop otonom. Kondisi penyelesaian dapat gagal, model dapat macet, dan evaluator dapat bersifat probabilistik.

Penting

Pengulangan agen masih bersifat eksperimental.

Menyiapkan perulangan secara manual

Gunakan API komposisi langsung saat Anda ingin melakukan perulangan tanpa setelan default Harness Agent lainnya.

Impor jenis perulangan dan bungkus setiap AIAgent dengan LoopAgent. Maksimum defaultnya adalah 10 pemanggilan agen:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

AIAgent baseAgent = chatClient.AsAIAgent();
AIAgent agent = new LoopAgent(
    baseAgent,
    new CompletionMarkerLoopEvaluator("DONE"),
    new LoopAgentOptions { MaxIterations = 5 });

Impor AgentLoopMiddleware dan tambahkan ke reguler Agent. Maksimum secara default adalah 10 eksekusi agen:

from agent_framework import Agent, AgentLoopMiddleware


def needs_more_work(*, last_result, **kwargs):
    return "DONE" not in last_result.text


agent = Agent(
    client=client,
    middleware=[
        AgentLoopMiddleware(
            needs_more_work,
            max_iterations=5,
        )
    ],
)

Predikatnya bisa sinkron atau asinkron. Kembali True untuk melanjutkan, False untuk menghentikan, atau (continue, feedback) meneruskan umpan balik ke iterasi berikutnya.

Nota

Kemampuan perulangan paket yang dijelaskan di halaman ini saat ini tidak tersedia di Go.

Pilih kondisi penyelesaian

LoopAgent menerima satu evaluator atau koleksi yang dipesan:

Penilai	Berlanjut selama
CompletionMarkerLoopEvaluator	Respons terbaru tidak berisi penanda yang dikonfigurasi.
TodoCompletionLoopEvaluator	TodoProvider yang sudah diselesaikan masih memiliki item yang belum lengkap, opsional pada mode agen yang dipilih.
BackgroundTaskCompletionLoopEvaluator	Item BackgroundAgentsProvider yang sudah diselesaikan masih memiliki tugas yang berjalan.
AIJudgeLoopEvaluator	Klien hakim terpisah mengatakan permintaan asli tidak sepenuhnya dijawab.
DelegateLoopEvaluator	Panggilan balik Anda mengembalikan LoopEvaluation.Continue(...).

Ketika beberapa evaluator dikonfigurasi, semuanya berjalan secara berurutan. Evaluator pertama yang meminta iterasi lain memberikan umpan baliknya; perulangan berhenti hanya ketika semua evaluator menolak untuk melanjutkan.

Menggunakan hakim AI

Hakim menerima permintaan asli dan respons agen terbaru. Jika menemukan celah, analisisnya menjadi umpan balik untuk iterasi berikutnya:

var evaluator = new AIJudgeLoopEvaluator(
    judgeClient,
    new AIJudgeLoopEvaluatorOptions
    {
        Criteria =
        [
            "Answer every part of the request.",
            "Support conclusions with evidence.",
        ],
    });

AIAgent loopAgent = new LoopAgent(
    agent,
    evaluator,
    new LoopAgentOptions { MaxIterations = 4 });

Hanya gunakan endpoint penilai yang Anda percayai untuk permintaan asli dan respons yang dihasilkan.

Mengontrol konteks dan output

Secara default, LoopAgent menggunakan kembali satu sesi dan mengirim umpan balik terbaru evaluator pemenang sebagai input berikutnya. FreshContextPerIteration = true alih-alih membangun ulang setiap iterasi berdasarkan permintaan asli serta log umpan balik teragregasi, lalu mengatur ulang atau memulihkan sesi.

Proses non-streaming secara bawaan mengembalikan transkrip agregat. Atur NonStreamingReturnsLastResponseOnly = true untuk mengembalikan respons akhir saja. Streaming selalu mengirimkan setiap iterasi dan semua pesan umpan balik atas nama yang ditampilkan.

Predikat menerima argumen kata kunci termasuk iteration, , last_result, messages, original_messagessession, agent, progress, dan feedback. Pembantu todos_remaining() dan background_tasks_running() menyediakan kondisi tugas todo dan latar belakang bawaan. Pasangkan dengan todos_remaining_message atau background_tasks_running_message untuk menghasilkan input berikutnya yang ditargetkan.

Menggunakan hakim AI

AgentLoopMiddleware.with_judge membangun loop yang digerakkan oleh judge. Loop judge secara default ditetapkan ke lima iterasi:

from agent_framework import Agent, AgentLoopMiddleware

loop = AgentLoopMiddleware.with_judge(
    judge_client,
    criteria=[
        "Answer every part of the request.",
        "Support conclusions with evidence.",
    ],
    max_iterations=4,
)

agent = Agent(
    client=client,
    middleware=[loop],
)

Penalaran hakim disalurkan kembali ke agen ketika diperlukan lebih banyak pekerjaan. Gunakan hanya endpoint penilai yang tepercaya untuk menangani permintaan asli dan respons yang dihasilkan.

Mengontrol konteks, kemajuan, dan output

Untuk perulangan lanjutan, buat AgentLoopMiddleware secara langsung:

• record_feedback membuat entri kemajuan ringkas setelah setiap perulangan kerja.
• progress meneruskan entri yang terakumulasi kepada fungsi callback.
• inject_progress=True menambahkan progres ke input iterasi berikutnya.
• fresh_context=True memulai ulang dari tugas asli dan log kemajuan serta memulihkan sesi yang terlampir ke cuplikan sebelum loop dimulai.
• return_final_only=True hanya mengembalikan respons terakhir untuk eksekusi non-streaming.

Berikan max_iterations=None hanya jika predikat penyelesaian dipastikan akan selesai.

Kondisi penyelesaian paket dan integrasi hakim yang dijelaskan di halaman ini saat ini tidak tersedia di Go.

Gunakan perulangan dengan Harness Agent

Gunakan penyiapan Agen Harness saat Anda juga menginginkan riwayat, perencanaan, memori, persetujuan, dan alur pengamatan yang telah dikonfigurasi sebelumnya.

Atur HarnessAgentOptions.LoopEvaluators. Harness menerapkan LoopAgent sebagai dekorator agen terluar:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var options = new HarnessAgentOptions
{
    LoopEvaluators =
    [
        new CompletionMarkerLoopEvaluator("DONE"),
    ],
    LoopAgentOptions = new LoopAgentOptions
    {
        MaxIterations = 5,
    },
};

HarnessAgent agent = chatClient.AsHarnessAgent(options);
// Equivalent construction: new HarnessAgent(chatClient, options)
AgentSession session = await agent.CreateSessionAsync();

Koleksi yang kosong atau nullLoopEvaluators membuat harness tetap single-shot.

Persetujuan dan perilaku sesi

LoopAgent berhenti sebelum mengevaluasi kondisi selesai saat suatu iterasi mengembalikan permintaan persetujuan untuk alat yang tertunda. Ini mengembalikan permintaan ke pemanggil alih-alih menyembunyikannya di balik iterasi otonom lainnya. Setelah pemanggil memberikan respons persetujuan melalui alur persetujuan alat normal, agen dapat melanjutkan.

LoopAgent sendiri tidak menambahkan penanganan persetujuan. Harness Agent menempatkan loop di luar ToolApprovalAgent, sehingga permintaan persetujuan yang tertunda dapat lolos dari loop.

Gunakan kembali AgentSession yang sama di berbagai panggilan untuk melanjutkan percakapan. Iterasi loop berbagi sesi tersebut secara bawaan. Dengan FreshContextPerIteration = true, LoopAgent mereset atau memulihkan status sesi yang disediakan pemanggil jika didukung. Penyimpanan percakapan yang dimiliki layanan dapat mempertahankan riwayat ketika sesi yang diserialkan hanya berisi pengenal percakapan jarak jauh.

Masukkan loop_should_continue ke create_harness_agent; loop_max_iterations defaultnya 10:

from agent_framework import create_harness_agent


def needs_more_work(*, last_result, **kwargs):
    return "DONE" not in last_result.text


agent = create_harness_agent(
    client=client,
    loop_should_continue=needs_more_work,
    loop_max_iterations=5,
)
session = agent.create_session()

loop_next_message menyesuaikan input berikutnya. Tanpa loop_should_continue, fungsi factory tidak menambahkan loop dan mengabaikan argumen loop lainnya.

Persetujuan dan perilaku sesi

AgentLoopMiddleware berhenti sebelum mengevaluasi predikat kelanjutan saat iterasi menghasilkan permintaan persetujuan alat yang tertunda. Ini mengembalikan permintaan ke pemanggil alih-alih menyembunyikannya di balik iterasi otonom lainnya. Setelah pemanggil memberikan respons persetujuan melalui alur persetujuan alat normal, agen dapat melanjutkan.

AgentLoopMiddleware tidak menambahkan ToolApprovalMiddleware secara otomatis. Agen Harness menempatkan loop di luar middleware persetujuan, sehingga permintaan persetujuan yang tertunda dapat keluar dari loop. Buat dan teruskan AgentSession pada setiap proses eksekusi Harness Agent saat persetujuan otomatis alat diaktifkan.

Gunakan kembali AgentSession yang sama di beberapa panggilan untuk melanjutkan percakapan. Iterasi loop berbagi sesi tersebut secara bawaan. Dengan fresh_context=True, middleware memulihkan sesi yang terlampir ke snapshot sebelum loop di setiap iterasi. Penyimpanan percakapan yang dimiliki layanan dapat mempertahankan riwayat ketika sesi yang diserialisasi hanya berisi pengenal percakapan jarak jauh.

Nota

Looping Agent Harness saat ini belum tersedia untuk Go, sehingga perilaku persetujuan dan sesinya tidak berlaku.

Langkah berikutnya

Mendelegasikan pekerjaan ke agen latar belakang

Mempelajari secara lebih mendalam

• Perencanaan dan daftar tugas
• Persetujuan alat
• Agen Harness