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.

Go menyediakan pemanggilan ulang terbatas melalui agent/harness/loop. Daftar loop.New(loop.Config{...}) di agent.Config.Middlewares. Middleware menjalankan agen, mengevaluasi responsnya, dan secara opsional mengirim umpan balik ke iterasi lain.

Sampel Foundry berikut menggunakan penanda penyelesaian. Ini memerlukan FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, dan kredensial Azure:

// Copyright (c) Microsoft. All rights reserved.

package main

import (
    "context"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/agent/harness/loop"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)

var logger = demo.NewLogger(
    "Loop Harness",
    "This sample shows how the loop harness keeps re-invoking an agent until it "+
        "signals completion with a marker, so the agent can work across several turns "+
        "on its own before returning.",
    "Model", demo.FoundryModel,
)

// completionMarker is the token the agent is asked to emit once the task is
// fully done; the loop stops as soon as it appears in a response.
const completionMarker = "TASK COMPLETE"

func main() {
    token := demo.FoundryTokenCredential()

    // Wrap the agent with the loop harness: after each iteration the
    // completion-marker evaluator decides whether to run the agent again.
    a := foundryprovider.NewAgent(
        demo.FoundryProjectEndpoint,
        token,
        foundryprovider.ModelDeployment(demo.FoundryModel),
        foundryprovider.AgentConfig{
            Instructions: "You are a diligent assistant. Work on the request step by step across " +
                "multiple turns. End your final message with the marker '" + completionMarker +
                "' once, and only once, the request is fully complete.",
            Config: agent.Config{
                Name: "Worker",
                Middlewares: []agent.Middleware{
                    // The loop re-invokes the agent (and everything below it,
                    // including the logger) until an evaluator stops the loop.
                    loop.New(loop.Config{
                        Evaluators: []loop.Evaluator{
                            loop.NewCompletionMarkerEvaluator(loop.CompletionMarkerConfig{Marker: completionMarker}),
                        },
                    }),
                    logger, // for logging each agent iteration
                },
            },
        },
    )

    ctx := context.Background()
    resp, err := a.RunText(ctx, "Draft a short checklist for planning a small birthday party, "+
        "then review it once for anything missing, and finish.").Collect()
    demo.Response(resp, err)
}

MaxIterations adalah opsional *int dan default ke 10. Atur batas eksplisit untuk tugas Anda. Dengan beberapa evaluator, evaluator pertama yang meminta iterasi lain memberikan umpan baliknya; perulangan berhenti hanya ketika semua evaluator berhenti atau batas iterasi tercapai.

Untuk contoh bebas kredensial, lihat sampel perulangan berskrip. Ini menunjukkan penyelesaian penanda, evaluator kustom, dan batas keamanan iterasi.

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. Hanya gunakan endpoint penilai yang Anda percayai untuk 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.

Gunakan loop.NewCompletionMarkerEvaluator untuk berhenti ketika respons terbaru berisi penanda yang dikonfigurasi. Untuk penyelesaian khusus aplikasi, terapkan loop.Evaluator atau gunakan loop.EvaluatorFunc, mengembalikan loop.Stop(), loop.Continue(feedback), atau loop.ContinueWithMessages(messages).

FreshContextPerIteration dimulai ulang dari input asli ditambah akumulasi umpan balik. NonStreamingReturnsLastResponseOnly membatasi hasil non-streaming ke perulangan akhir.

Go tidak menyertakan evaluator AI-judge bawaan yang ditampilkan dalam contoh C#. Berikan evaluator Anda sendiri jika penyelesaian memerlukan model lain atau pemeriksaan eksternal.

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 berbagai 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 diserialkan hanya berisi pengenal percakapan jarak jauh.

helper Go harness.AgentConfig tidak menambahkan perulangan secara default. Sertakan loop.New(...) dalam pemanggil agent.Config.Middlewares untuk membungkus agen yang dikonfigurasi dengan pemanggilan ulang terbatas.

Perulangan berhenti ketika iterasi menghasilkan permintaan persetujuan alat yang tertunda. Tidak menyetujui alat secara otomatis. Tangani permintaan di host dan kembalikan respons persetujuan yang cocok melalui sesi yang sama sebelum melanjutkan.

Langkah berikutnya

Mendelegasikan pekerjaan ke agen latar belakang

Mempelajari secara lebih mendalam

  • Terakhir diperbarui pada