Looping do agente

O looping do agente reinvoca um agente até que uma condição de conclusão seja satisfeita. Use-o para refinamento iterativo, conclusão de tudo, espera de tarefas em segundo plano ou avaliação se uma resposta cumpre critérios explícitos.

Sempre laços autónomos limitados. Uma condição de completude pode falhar, um modelo pode parar, e um avaliador pode ser probabilístico.

Importante

O looping de agentes é experimental.

Configurar o looping manualmente

Usa a API de composição direta quando quiseres looping sem os outros padrões do Harness Agent.

Importa os tipos de loop e envolve qualquer um AIAgent com LoopAgent. O seu máximo padrão é de 10 invocações de agente:

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

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

Importa AgentLoopMiddleware e adiciona a um arquivo normal Agentde . O máximo padrão é de 10 execuções de agente:

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

O predicado pode ser síncrono ou assíncrono. Voltar True para continuar, False para parar ou (continue, feedback) para passar feedback para a próxima iteração.

Observação

A funcionalidade de looping empacotada descrita nesta página não está atualmente disponível no Go.

Escolha uma condição de completude

LoopAgent aceita um avaliador ou uma coleção ordenada:

Avaliador	Continua enquanto
CompletionMarkerLoopEvaluator	A resposta mais recente não contém o marcador configurado.
TodoCompletionLoopEvaluator	Um resolvido TodoProvider ainda tem itens incompletos, opcionalmente em modos de agente selecionados.
BackgroundTaskCompletionLoopEvaluator	Uma resolução BackgroundAgentsProvider continua a ter tarefas em curso.
AIJudgeLoopEvaluator	Outro juiz cliente diz que o pedido original não foi totalmente respondido.
DelegateLoopEvaluator	O seu retorno LoopEvaluation.Continue(...)de chamada regressa.

Quando múltiplos avaliadores são configurados, executam-se por ordem. O primeiro avaliador que solicita outra iteração fornece o seu feedback; O ciclo só termina quando todos os avaliadores recusam continuar.

Usa um juiz IA

O juiz recebe o pedido original e a resposta mais recente do agente. Se encontrar uma lacuna, a sua análise torna-se feedback para a iteração seguinte:

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

Usa apenas um endpoint de juiz em que confies com o pedido original e a resposta gerada.

Contexto de controlo e saída

Por defeito, reutiliza LoopAgent uma sessão e envia o feedback mais recente do avaliador vencedor como próxima entrada. FreshContextPerIteration = true em vez disso, reconstrói cada passagem a partir do pedido original mais um registo agregado de feedback e reinicia ou restaura a sessão.

As corridas não-streaming devolvem uma transcrição agregada por defeito. Configurado NonStreamingReturnsLastResponseOnly = true para devolver apenas a resposta final. O streaming emite sempre todas as iterações e quaisquer mensagens de feedback visíveis em nome do utilizador.

O predicado recebe argumentos de palavras-chave incluindo iteration, last_result, messages, original_messages, session, agent, progress, , e feedback. Os auxiliares todos_remaining() fornecem background_tasks_running() tarefas incorporadas e condições de tarefas em segundo plano. Emparelha-os com todos_remaining_message ou background_tasks_running_message para gerar um próximo input direcionado.

Usa um juiz IA

AgentLoopMiddleware.with_judge constrói um ciclo conduzido pelos juízes. Os ciclos de juízes por defeito têm cinco iterações:

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

O raciocínio do juiz é devolvido ao agente quando é necessário mais trabalho. Usa apenas um endpoint de juiz em que confies com o pedido original e a resposta gerada.

Controla o contexto, o progresso e a saída

Para laços avançados, constrói AgentLoopMiddleware diretamente:

• record_feedback cria uma entrada concisa de progresso após cada iteração de trabalho.
• progress expõe as entradas acumuladas a callbacks.
• inject_progress=True Adiciona progresso à entrada da próxima iteração.
• fresh_context=True reinicia a partir da tarefa original e do registo de progresso e restaura uma sessão anexada ao seu snapshot pré-ciclo.
• return_final_only=True devolve apenas a última resposta para corridas não em streaming.

Passe max_iterations=None apenas quando o predicado de conclusão estiver garantido a terminar.

As condições de conclusão embaladas e a integração com juízes descritas nesta página não estão atualmente disponíveis no Go.

Usar o looping com o Harness Agent

Use a configuração do Harness Agent quando também quiser o seu histórico pré-configurado, planeamento, memória, aprovação e pipeline de observabilidade.

Defina HarnessAgentOptions.LoopEvaluators. O arnês aplica-se LoopAgent como o seu agente decorativo mais externo:

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

Um arnês vazio ou nullLoopEvaluators de coleção deixa o arnês com um único disparo.

Aprovação e comportamento da sessão

LoopAgent pára antes de avaliar a sua condição de conclusão quando uma iteração devolve um pedido pendente de aprovação de ferramenta. Devolve o pedido ao chamador em vez de o esconder atrás de outra iteração autónoma. Depois de o chamador fornecer a resposta de aprovação através do fluxo normal de aprovação da ferramenta , o agente pode continuar.

LoopAgent não acrescenta a gestão da aprovação em si. O Harness Agent aplica o loop fora ToolApprovalAgentde , permitindo que pedidos de aprovação pendentes escapem do loop.

Reutiliza o mesmo AgentSession entre chamadas para continuar a conversa. As iterações do ciclo partilham essa sessão por defeito. Com , LoopAgent reinicia ou restaura o FreshContextPerIteration = trueestado de sessão fornecido pelo chamador quando suportado. O armazenamento de conversas propriedade do serviço pode reter o histórico quando a sessão serializada contém apenas um identificador remoto de conversa.

Fornecer loop_should_continue para create_harness_agent; loop_max_iterations por defeito é 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 Personaliza a próxima entrada. Sem loop_should_continue, a fábrica não adiciona um loop e ignora os outros argumentos do loop.

Aprovação e comportamento da sessão

AgentLoopMiddleware para antes de avaliar o seu predicado de continuação quando uma iteração retorna um pedido pendente de aprovação de ferramenta. Devolve o pedido ao chamador em vez de o esconder atrás de outra iteração autónoma. Depois de o chamador fornecer a resposta de aprovação através do fluxo normal de aprovação da ferramenta , o agente pode continuar.

AgentLoopMiddleware não se soma ToolApprovalMiddleware . O Agente de Harness coloca o loop fora do seu middleware de aprovação, permitindo que pedidos de aprovação pendentes escapem desse ciclo. Criar e passar um AgentSession em cada execução do Harness Agent enquanto a aprovação automática da ferramenta está ativada.

Reutiliza o mesmo AgentSession entre chamadas para continuar a conversa. As iterações do ciclo partilham essa sessão por defeito. Com fresh_context=True, o middleware restaura a sessão associada ao seu snapshot pré-ciclo entre iterações. O armazenamento de conversas propriedade do serviço pode reter o histórico quando a sessão serializada contém apenas um identificador remoto de conversa.

Observação

Harness Agent looping não está atualmente disponível no Go, por isso o seu comportamento de aprovação e sessão não se aplicam.

Passos seguintes

Delegar trabalho aos agentes de fundo

Aprofunde-se

• Planeamento e tarefas
• Aprovação de ferramentas
• Arnês de Agente