Boucle d’agent

Le bouclage de l’agent appelle à nouveau un agent jusqu’à ce qu’une condition d’achèvement soit satisfaite. Utilisez-le pour l’affinement itératif, la saisie semi-automatique, l’attente de tâches en arrière-plan ou l’évaluation si une réponse répond à des critères explicites.

Boucles autonomes toujours liées. Une condition d’achèvement peut échouer, un modèle peut se bloquer et un évaluateur peut être probabiliste.

Important

La boucle de l’agent est expérimentale.

Configurer manuellement la boucle

Utilisez l’API de composition directe lorsque vous souhaitez effectuer une boucle sans les autres paramètres par défaut de l’Agent Harness.

Importez les types de boucles et encapsulez-les AIAgent avec LoopAgent. Son maximum par défaut est 10 appels d’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 });

Importez AgentLoopMiddleware et ajoutez-le à un standard Agent. La valeur maximale par défaut est 10 exécutions de l’agent :

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

Le prédicat peut être synchrone ou asynchrone. Revenez True à continuer, False à arrêter ou (continue, feedback) à transmettre des commentaires à l’itération suivante.

Note

La fonctionnalité de bouclage empaquetée décrite dans cette page n’est actuellement pas disponible dans Go.

Choisir une condition d’achèvement

LoopAgent accepte un évaluateur ou une collection ordonnée :

Évaluateur	Continue pendant
CompletionMarkerLoopEvaluator	La dernière réponse ne contient pas le marqueur configuré.
TodoCompletionLoopEvaluator	Un élément résolu a toujours des éléments incomplets TodoProvider , éventuellement dans les modes d’agent sélectionnés.
BackgroundTaskCompletionLoopEvaluator	Une solution résolue a toujours des BackgroundAgentsProvider tâches en cours d’exécution.
AIJudgeLoopEvaluator	Un client de juge distinct indique que la demande d’origine n’est pas entièrement répondue.
DelegateLoopEvaluator	Votre rappel retourne LoopEvaluation.Continue(...).

Lorsque plusieurs évaluateurs sont configurés, ils s’exécutent dans l’ordre. Le premier évaluateur qui demande une autre itération fournit ses commentaires ; la boucle s’arrête uniquement lorsque tous les évaluateurs refusent de continuer.

Utiliser un juge IA

Le juge reçoit la demande d’origine et la dernière réponse de l’agent. S’il trouve un écart, son analyse devient des commentaires pour l’itération suivante :

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

Utilisez uniquement un point de terminaison de juge que vous approuvez avec la demande d’origine et la réponse générée.

Contexte de contrôle et sortie

Par défaut, LoopAgent réutilise une session et envoie les commentaires les plus récents de l’évaluateur gagnant comme entrée suivante. FreshContextPerIteration = true Regénère à la place chaque passe de la demande d’origine, ainsi qu’un journal de commentaires agrégé et réinitialise ou restaure la session.

Les exécutions en continu retournent une transcription agrégée par défaut. Définissez NonStreamingReturnsLastResponseOnly = true pour renvoyer uniquement la réponse finale. La diffusion en continu émet toujours toutes les itérations et tous les messages de commentaires visibles au nom de l’utilisateur.

Le prédicat reçoit des arguments de mot clé, notamment iteration, , last_resultoriginal_messagesmessages, session, agent, , , progresset .feedback Les assistances todos_remaining() et background_tasks_running() fournissent des conditions todo et des tâches en arrière-plan intégrées. Associez-les todos_remaining_message ou background_tasks_running_message générez une entrée suivante ciblée.

Utiliser un juge IA

AgentLoopMiddleware.with_judge crée une boucle basée sur un juge. Les boucles Juge sont par défaut de cinq itérations :

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

Le raisonnement du juge est renvoyé à l’agent lorsque davantage de travail est nécessaire. Utilisez uniquement un point de terminaison de juge que vous approuvez avec la demande d’origine et la réponse générée.

Contrôler le contexte, la progression et la sortie

Pour les boucles avancées, construisez AgentLoopMiddleware directement :

• record_feedback crée une entrée de progression concise après chaque itération de travail.
• progress expose les entrées cumulées aux rappels.
• inject_progress=True ajoute la progression à l’entrée de l’itération suivante.
• fresh_context=True redémarre à partir de la tâche d’origine et du journal de progression et restaure une session attachée à son instantané de pré-boucle.
• return_final_only=True retourne uniquement la dernière réponse pour les exécutions sans diffusion en continu.

max_iterations=None Passez uniquement lorsque le prédicat d’achèvement est garanti pour se terminer.

Les conditions d’achèvement empaquetées et l’intégration de juge décrites dans cette page ne sont pas actuellement disponibles dans Go.

Utiliser la boucle avec l’agent Harness

Utilisez la configuration de l’agent Harness lorsque vous souhaitez également que son historique préconfiguré, sa planification, sa mémoire, son approbation et son pipeline d’observabilité.

Définissez HarnessAgentOptions.LoopEvaluators. Le harnais s’applique LoopAgent comme décorateur d’agent le plus extérieur :

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

Une collection vide nullLoopEvaluators laisse le harnais unique.

Comportement d’approbation et de session

LoopAgent s’arrête avant d’évaluer sa condition d’achèvement lorsqu’une itération retourne une demande d’approbation d’outil en attente. Elle retourne la requête à l’appelant au lieu de la masquer derrière une autre itération autonome. Une fois que l’appelant fournit la réponse d’approbation par le biais du flux d’approbation de l’outil normal, l’agent peut continuer.

LoopAgent n’ajoute pas de gestion des approbations elle-même. L’agent Harness applique la boucle en dehors ToolApprovalAgent, ce qui permet aux demandes d’approbation en attente d’échapper à la boucle.

Réutilisez les mêmes AgentSession appels pour poursuivre la conversation. Les itérations de boucle partagent cette session par défaut. Avec FreshContextPerIteration = true, LoopAgent réinitialise ou restaure l’état de session fourni par l’appelant, où il est pris en charge. Le stockage de conversation appartenant au service peut conserver l’historique lorsque la session sérialisée contient uniquement un identificateur de conversation distant.

Fournir loop_should_continue à create_harness_agent; loop_max_iterations la valeur par défaut est 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 personnalise l’entrée suivante. loop_should_continueSans cela, la fabrique n’ajoute pas de boucle et ignore les autres arguments de boucle.

Comportement d’approbation et de session

AgentLoopMiddleware s’arrête avant d’évaluer son prédicat de continuation lorsqu’une itération retourne une demande d’approbation d’outil en attente. Elle retourne la requête à l’appelant au lieu de la masquer derrière une autre itération autonome. Une fois que l’appelant fournit la réponse d’approbation par le biais du flux d’approbation de l’outil normal, l’agent peut continuer.

AgentLoopMiddleware ne s’ajoute ToolApprovalMiddleware pas. L’agent Harness place la boucle en dehors de son intergiciel d’approbation, ce qui permet aux demandes d’approbation en attente d’échapper à la boucle. Créez et transmettez une AgentSession exécution à chaque exécution de l’Agent Harness pendant que l’approbation automatique de l’outil est activée.

Réutilisez les mêmes AgentSession appels pour poursuivre la conversation. Les itérations de boucle partagent cette session par défaut. Avec fresh_context=True, l’intergiciel restaure la session attachée à son instantané de pré-boucle entre les itérations. Le stockage de conversation appartenant au service peut conserver l’historique lorsque la session sérialisée contient uniquement un identificateur de conversation distant.

Note

Le bouclage de l’agent Harness n’est pas disponible actuellement dans Go. Par conséquent, son comportement d’approbation et de session ne s’applique pas.

Étapes suivantes

Déléguer le travail aux agents en arrière-plan

Approfondir la question

• Planification et todos
• Approbation de l’outil
• Agent Harnais