Ajanın döngüye girmesi

Aracı döngü, tamamlanma koşulu karşılanana kadar aracıyı yeniden çağırır. Bunu yinelemeli iyileştirme, yapılacakları tamamlama, arka plan görevlerinin tamamlanmasını bekleme veya bir yanıtın açıkça tanımlanmış ölçütleri karşılayıp karşılamadığını değerlendirme için kullanın.

Otonom döngüleri her zaman sınırlandırın. Tamamlama koşulu başarısız olabilir, model duraklayabilir ve değerlendirici olasılıksal olabilir.

Önemli

Ajanın döngüye girmesi deneyseldir.

Döngüyü manuel olarak ayarlayın

Diğer Harness Agent varsayılanları olmadan döngüsel çalışma istediğinizde doğrudan kompozisyon API'sini kullanın.

Döngü türlerini içe aktarın ve tüm AIAgent öğelerini LoopAgent ile sarın. Varsayılan maksimum değer 10 aracı çağrısıdır:

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

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

AgentLoopMiddleware öğesini içeri aktarın ve bunu normal bir Agent öğesine ekleyin. Varsayılan maksimum 10 ajan çalıştırmadır:

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

Yüklem eşzamanlı veya eşzamansız olabilir. Devam etmek için True öğesine, durdurmak için False öğesine veya geri bildirimi bir sonraki yinelemeye aktarmak için (continue, feedback) öğesine geri dönün.

Go, agent/harness/loop aracılığıyla sınırlı yeniden çağırma sağlar. loop.New(loop.Config{...}) içinde agent.Config.Middlewares kaydolun. Ara yazılım aracıyı çalıştırır, yanıtını değerlendirir ve isteğe bağlı olarak başka bir yinelemeye geri bildirim gönderir.

Aşağıdaki Foundry örneği bir tamamlama işaretçisi kullanır. FOUNDRY_MODEL, FOUNDRY_PROJECT_ENDPOINT ve Azure kimlik bilgileri gerektirir:

// 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, isteğe bağlı bir *int'dir ve varsayılan olarak 10'dur. Göreviniz için açıkça tanımlanmış bir sınır ayarlayın. Birden çok değerlendirici ile, başka bir yineleme isteyen ilk değerlendirici geri bildirim sağlar; döngü yalnızca tüm değerlendiriciler durduğunda veya yineleme sınırına ulaşıldığında durur.

Kimlik bilgisi olmayan bir örnek için betikli döngü örneğine bakın. İşaretçi tamamlama, özel bir değerlendirici ve yineleme güvenlik sınırını gösterir.

Tamamlama koşulu seçme

LoopAgent bir değerlendiriciyi veya sıralı koleksiyonu kabul eder:

Değerlendirici	Devam ederken
CompletionMarkerLoopEvaluator	En son yanıt, yapılandırılmış işaretçiyi içermez.
TodoCompletionLoopEvaluator	Çözümlenmiş TodoProvider öğesinde, isteğe bağlı olarak seçili aracı modlarında hâlâ tamamlanmamış öğeler bulunuyor.
BackgroundTaskCompletionLoopEvaluator	Çözülmüş bir BackgroundAgentsProvider öğesinin hâlâ çalışan görevleri var.
AIJudgeLoopEvaluator	Ayrı bir hakim istemcisi özgün isteğin tam olarak yanıtlanmadığını söylüyor.
DelegateLoopEvaluator	Geri aramanız LoopEvaluation.Continue(...) geri döner.

Birden çok değerlendirici yapılandırıldığında sırayla çalışır. Başka bir yineleme talep eden ilk değerlendirici geri bildirimini sunar; döngü yalnızca tüm değerlendiriciler devam etmeyi reddettiğinde durur.

Yapay zeka hakimi kullanma

Hakim özgün isteği ve en son aracı yanıtını alır. Bir boşluk bulursa, analizi sonraki yineleme için geri bildirim haline gelir:

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

Yalnızca özgün istek ve oluşturulan yanıtta güvendiğiniz bir yargıç uç noktasını kullanın.

Bağlamı ve çıktıyı kontrol edin

Varsayılan olarak, LoopAgent bir oturumu yeniden kullanır ve kazanan değerlendiricinin en son geri bildirimlerini bir sonraki giriş olarak gönderir. FreshContextPerIteration = true bunun yerine, özgün istekten gelen her geçişi ve toplu geri bildirim günlüğünü yeniden oluşturur ve oturumu sıfırlar veya geri yükler.

Akış dışı çalıştırmalar varsayılan olarak toplu bir transkript döndürür. Yalnızca son yanıtı döndürecek şekilde ayarlayın NonStreamingReturnsLastResponseOnly = true . Akış her zaman tüm yinelemeleri ve başkası adına görünen tüm geri bildirim mesajlarını gönderir.

Yüklem, iteration, last_result, messages, original_messages, session, agent, progress ve feedback dâhil anahtar sözcük bağımsız değişkenlerini alır. todos_remaining() ve background_tasks_running() yardımcıları, yerleşik todo ve arka plan görevi koşulları sunar. Hedefli bir sonraki istem oluşturmak için bunları todos_remaining_message veya background_tasks_running_message ile eşleştirin.

Yapay zeka hakimi kullanma

AgentLoopMiddleware.with_judge değerlendirici odaklı bir döngü oluşturur. Judge döngüleri varsayılan olarak beş yinelemeye sahiptir:

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

Hakimin mantığı, daha fazla çalışma gerektiğinde temsilciye geri döner. Yalnızca özgün istek ve oluşturulan yanıtta güvendiğiniz bir yargıç uç noktasını kullanın.

Bağlamı, ilerlemeyi ve çıkışı denetleme

Gelişmiş döngüler için AgentLoopMiddleware’i doğrudan oluşturun:

• record_feedback her çalışma yinelemesi sonrasında kısa bir ilerleme girdisi oluşturur.
• progress birikmiş kayıtları geri çağırma işlevlerine sunar.
• inject_progress=True bir sonraki yinelemenin girdisine ilerleme ekler.
• fresh_context=True orijinal görev ve ilerleme günlüğünden yeniden başlatılır ve ekli bir oturumu döngü öncesi anlık görüntüsüne geri yükler.
• return_final_only=True akışsız çalıştırmalarda yalnızca son yanıtı döndürür.

max_iterations=None öğesini yalnızca tamamlanma yükleminin sonlanacağı garanti edildiğinde geçirin.

En son yanıt yapılandırılmış bir işaretçi içerdiğinde durdurmak için kullanın loop.NewCompletionMarkerEvaluator . Uygulamaya özgü tamamlama için loop.Continue(feedback) uygulayın veya loop.Stop() kullanın; loop.Evaluator, loop.ContinueWithMessages(messages) ya da loop.EvaluatorFunc döndürün.

FreshContextPerIteration özgün girdiden ve birikmiş geri bildirimden yeniden başlar. NonStreamingReturnsLastResponseOnly akışsız bir sonucu yalnızca son yinelemeyle sınırlar.

Go, C# örneklerinde gösterilen yerleşik AI-judge değerlendiricisini içermez. Tamamlama için başka bir model veya dış denetim gerekiyorsa kendi değerlendiricinizi sağlayın.

Harness Agent ile döngü kullanımı

Önceden yapılandırılmış geçmişini, planlama, bellek, onay ve gözlemlenebilirlik işlem hattını da kullanmak istiyorsanız Harness Agent kurulumunu kullanın.

HarnessAgentOptions.LoopEvaluatorsayarlayın. Koşum, en dıştaki aracı dekoratörü olarak LoopAgent öğesini uygular:

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

Boş bir koleksiyon ya da nullLoopEvaluators koleksiyonu, test düzeneğini tek seferlik hâle getirir.

Onay ve oturum davranışı

LoopAgent bir yineleme bekleyen bir araç onay isteği döndürdüğünde, tamamlanma koşulunu değerlendirmeye geçmeden durur. İsteği başka bir otonom yinelemenin arkasına gizlemek yerine çağıran tarafa döndürür. Çağrıyı yapan taraf, normal araç onayı akışı üzerinden onay yanıtını ilettikten sonra ajan devam edebilir.

LoopAgent kendisi onay işleme desteği eklemez. Harness Agent, döngüyü ToolApprovalAgent dışında uygular ve bekleyen onay isteklerinin döngüden çıkmasına izin verir.

AgentSession Konuşmaya devam etmek için aynı işlemi çağrılar arasında yeniden kullanabilirsiniz. Döngü yinelemeleri bu oturumu varsayılan olarak paylaşır. ile FreshContextPerIteration = true, LoopAgent desteklenen durumlarda çağıran tarafından sağlanan oturum durumunu sıfırlar veya geri yükler. Hizmete ait konuşma depolama alanı, serileştirilmiş oturum yalnızca uzak konuşma tanımlayıcısı içerdiğinde geçmişi koruyabilir.

loop_should_continue öğesini create_harness_agent öğesine sağlayın; loop_max_iterations varsayılan olarak 10'dur:

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 sonraki girişi özelleştirir. loop_should_continue olmadan, fabrika bir döngü eklemez ve diğer döngü argümanlarını yok sayar.

Onay ve oturum davranışı

AgentLoopMiddleware , bir yineleme bekleyen bir araç onay isteği döndürdüğünde, devam koşulunu değerlendirmeden durur. İsteği başka bir otonom yinelemenin arkasına gizlemek yerine çağıran tarafa döndürür. Çağrıyı yapan taraf, normal araç onayı akışı üzerinden onay yanıtını ilettikten sonra ajan devam edebilir.

AgentLoopMiddleware ToolApprovalMiddleware öğesini kendiliğinden eklemez. Koşum Aracısı, döngüyü onay ara yazılımının dışına yerleştirerek bekleyen onay isteklerinin döngüden çıkmasına olanak tanır. Araçlar için otomatik onay etkinken, her Harness Agent çalıştırmasında bir AgentSession oluşturup iletin.

AgentSession Konuşmaya devam etmek için aynı işlemi çağrılar arasında yeniden kullanabilirsiniz. Döngü yinelemeleri bu oturumu varsayılan olarak paylaşır. fresh_context=True ile, ara yazılım bağlı oturumu yinelemeler arasında döngü öncesindeki anlık görüntüsüne geri yükler. Hizmete ait konuşma depolama alanı, serileştirilmiş oturum yalnızca uzak konuşma tanımlayıcısı içerdiğinde geçmişi koruyabilir.

Go harness.AgentConfig yardımcısı varsayılan olarak bir döngü eklemez. Yapılandırılan aracıyı sınırlı yeniden çağırma ile sarmak için arayanın loop.New(...) öğesine agent.Config.Middlewares ekleyin.

Döngü, bir yineleme bekleyen araç onayı istekleri ürettiğinde geri döner. Araçları otomatik olarak onaylamaz. Ana bilgisayardaki istekleri işleyip devam etmeden önce aynı oturum aracılığıyla eşleşen onay yanıtlarını döndürün.

Sonraki Adımlar

İşi arka plan aracılarına devredin

Daha derine git

• Planlama ve yapılacaklar
• Araç onayı
• Aracı Koşum