Smyčka agenta

Opakované spouštění agenta opakovaně spouští agenta, dokud není splněna podmínka dokončení. Můžete ho použít pro iterativní upřesnění, dokončení úkolů, čekání na úkoly na pozadí nebo vyhodnocení, jestli odpověď splňuje explicitní kritéria.

Autonomní smyčky vždy omezte. Podmínka dokončení může selhat, model může uvíznout a vyhodnocovač může být stochastický.

Důležité

Opakované běhy agenta jsou experimentální.

Nastavte opakování ručně

Použijte rozhraní API pro přímou kompozici, když chcete opakování bez ostatních výchozích nastavení agenta Harness.

Importujte typy smyček a obalte každý prvek AIAgent prvkem LoopAgent. Výchozí maximum je 10 volání agentů:

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

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

Importujte AgentLoopMiddleware a přidejte jej do běžného Agent. Výchozí maximum je 10 spuštění agenta:

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

Predikát může být synchronní nebo asynchronní. Stisknutím True pokračujte, False zastavte nebo (continue, feedback) předejte zpětnou vazbu do další iterace.

Go poskytuje omezenou opětovnou aktivaci prostřednictvím agent/harness/loop. Zaregistrujte se loop.New(loop.Config{...}) v agent.Config.Middlewares. Middleware spouští agenta, vyhodnotí jeho odpověď a volitelně odešle zpětnou vazbu do jiné iterace.

Následující ukázka Foundry používá značku dokončení. Vyžaduje FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL a přihlašovací údaj 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 je volitelná *int a výchozí hodnota je 10. Nastavte explicitní mez pro váš úkol. Při více vyhodnocovačích poskytne zpětnou vazbu první vyhodnocovač, který požádá o další iteraci; smyčka se zastaví pouze v případech, kdy se zastaví všechny vyhodnocovače nebo je dosažen limit iterací.

Příklad bez přihlašovacích údajů najdete v ukázce skriptované smyčky. Ukazuje dokončování značek, vlastní vyhodnocovač a bezpečnostní limit iterace.

Volba podmínky dokončení

LoopAgent přijímá jeden vyhodnocovače nebo seřazenou kolekci:

Vyhodnocovač	Pokračuje, dokud
CompletionMarkerLoopEvaluator	Nejnovější odpověď neobsahuje nakonfigurovanou značku.
TodoCompletionLoopEvaluator	Vyřešené TodoProvider stále obsahuje neúplné položky, volitelně ve vybraných režimech agenta.
BackgroundTaskCompletionLoopEvaluator	Vyřešený BackgroundAgentsProvider má stále běžící úlohy.
AIJudgeLoopEvaluator	Samostatný klient rozhodčí služby uvádí, že původní žádost není plně zodpovězena.
DelegateLoopEvaluator	Vaše zpětné volání vrátí LoopEvaluation.Continue(...).

Pokud je nakonfigurovaných více vyhodnocovačů, spustí se v pořadí. První hodnotitel, který požádá o další iteraci, poskytne svou zpětnou vazbu; smyčka se zastaví teprve tehdy, když všichni hodnotitelé odmítnou pokračovat.

Použití soudce AI

Soudce obdrží původní žádost a nejnovější odpověď agenta. Pokud najde mezeru, její analýza se stane zpětnou vazbou pro další iteraci:

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

Používejte pouze endpoint pro posuzování, kterému svěříte původní požadavek i vygenerovanou odpověď.

Kontext a výstup ovládacího prvku

Ve výchozím nastavení LoopAgent opakovaně používá jednu relaci a odešle jako další vstup nejnovější zpětnou vazbu vítězného hodnotitele. FreshContextPerIteration = true místo toho znovu sestaví každé spuštění z původního požadavku spolu se souhrnným protokolem zpětné vazby a resetuje nebo obnoví relaci.

Nestreamovací běhy ve výchozím nastavení vracejí souhrnný přepis. Nastavte NonStreamingReturnsLastResponseOnly = true tak, aby se vrátila pouze konečná odpověď. Streamování vždy odesílá každou iteraci a všechny viditelné zástupné zprávy zpětné vazby.

Predikát přijímá argumenty klíčových slov, včetně iteration, last_result, messagesoriginal_messages, session, , agentprogressa feedback. Pomocníci todos_remaining() a background_tasks_running() poskytují vestavěné podmínky pro úkoly TODO a úlohy na pozadí. Spárujte je s todos_remaining_message nebo background_tasks_running_message a vygenerujte cílený další vstup.

Použití soudce AI

AgentLoopMiddleware.with_judge vytvoří smyčku řízenou hodnotitelem. Ve výchozím nastavení mají Judge loops pět iterací:

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

Odůvodnění hodnotitele se předává zpět agentovi, když je potřeba další práce. Používejte pouze endpoint pro posuzování, kterému svěříte původní požadavek i vygenerovanou odpověď.

Řízení kontextu, průběhu a výstupu

U pokročilých smyček vytvořte AgentLoopMiddleware přímo:

• record_feedback vytvoří stručnou položku průběhu po každé iteraci práce.
• progress zpřístupňuje nashromážděné položky funkcím zpětného volání.
• inject_progress=True přidá průběžný výsledek ke vstupu další iterace.
• fresh_context=True se znovu spustí z původního úkolu a protokolu průběhu a obnoví připojenou relaci do stavu zachyceného ve snímku před smyčkou.
• return_final_only=True vrátí pouze poslední odpověď pro nestreamovaná spuštění.

Předávejte max_iterations=None pouze tehdy, je-li zaručeno, že predikát dokončení skončí.

Pomocí loop.NewCompletionMarkerEvaluator zastavíte, když nejnovější odpověď obsahuje nakonfigurovanou značku. Pro dokončení specifické pro aplikaci implementujte loop.Evaluator nebo použijte loop.EvaluatorFunc, vraťte loop.Stop(), loop.Continue(feedback) nebo loop.ContinueWithMessages(messages).

FreshContextPerIteration restartuje z původního vstupu plus kumulovanou zpětnou vazbu. NonStreamingReturnsLastResponseOnly omezuje výsledek bez streamování na poslední iteraci.

Go neobsahuje integrovaný evaluátor AI-judge, který je zobrazen v příkladech jazyka C#. Pokud dokončení vyžaduje jiný model nebo externí kontrolu, zadejte vlastní vyhodnocovač.

Použití opakování s Harness Agent

Pokud chcete využít také předkonfigurovanou historii, plánování, paměť, schvalování a pipeline pro observabilitu agenta Harness, použijte jeho nastavení.

Nastavte HarnessAgentOptions.LoopEvaluators. Tento postroj se použije LoopAgent jako nejkrajnější dekorátor:

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

Prázdná nebo nullLoopEvaluators kolekce způsobí, že postroj bude jednorázový.

Schválení a chování relace

LoopAgent se zastaví před vyhodnocením podmínky dokončení, pokud iterace vrátí nevyřízenou žádost o schválení nástroje. Vrátí požadavek volajícímu namísto toho, aby jej skryl za další autonomní iterací. Poté, co volající poskytne odpověď ke schválení prostřednictvím běžného procesu schválení nástroje, může agent pokračovat.

LoopAgent nepřidá samotné zpracování schválení. Harness Agent použije smyčku mimo ToolApprovalAgent, což umožní žádostem o schválení, které čekají na vyřízení, obejít smyčku.

Používejte stejné AgentSession napříč voláními, abyste mohli pokračovat v konverzaci. Iterace smyčky ve výchozím nastavení sdílejí danou relaci. Pomocí FreshContextPerIteration = trueLoopAgent resetuje nebo obnoví stav relace zadaný volajícím, je-li to podporováno. Úložiště konverzací vlastněných službou může uchovávat historii, pokud serializovaná relace obsahuje pouze identifikátor vzdálené konverzace.

Zadejte loop_should_continue až create_harness_agent; loop_max_iterations má výchozí hodnotu 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 přizpůsobí další zadání. Bez loop_should_continue továrna nepřidá cyklus a ignoruje ostatní argumenty cyklu.

Schválení a chování relace

AgentLoopMiddleware se zastaví před vyhodnocením podmínky pokračování, když iterace vrátí nevyřízený požadavek na schválení nástroje. Vrátí požadavek volajícímu namísto toho, aby jej skryl za další autonomní iterací. Poté, co volající poskytne odpověď ke schválení prostřednictvím běžného procesu schválení nástroje, může agent pokračovat.

AgentLoopMiddleware samo nepřidává ToolApprovalMiddleware. Harness Agent umisťuje smyčku mimo svou vrstvu middlewaru pro schvalování, takže čekající žádosti o schválení mohou smyčku obejít. Vytvořte a předejte AgentSession při každém běhu agenta Harness, když je povoleno automatické schvalování nástrojů.

Používejte stejné AgentSession napříč voláními, abyste mohli pokračovat v konverzaci. Iterace smyčky ve výchozím nastavení sdílejí danou relaci. Pomocí fresh_context=True middleware mezi jednotlivými iteracemi obnoví připojenou relaci do stavu zachyceného ve snímku pořízeném před smyčkou. Úložiště konverzací vlastněných službou může uchovávat historii, pokud serializovaná relace obsahuje pouze identifikátor vzdálené konverzace.

Pomocník Go harness.AgentConfig ve výchozím nastavení nepřidá smyčku. Zahrňte loop.New(...) do agent.Config.Middlewares volajícího, aby se nakonfigurovaný agent zabalil s ohraničeným opětovným vyvoláním.

Smyčka skončí, když iterace vytvoří čekající žádosti o schválení nástrojů. Neschválí nástroje automaticky. Před pokračováním zpracujte požadavky v hostu a vraťte odpovídající odpovědi na schválení prostřednictvím stejné relace.

Další kroky

Předejte práci agentům na pozadí

Zjistit více

• Plánování a úkoly
• Schválení nástroje
• Zprostředkovatel agentů