Looping de agente

O loop de agente reinvoca um agente até que uma condição de conclusão seja satisfeita. Use-o para refinamento iterativo, conclusão completa, aguardar tarefas em segundo plano ou avaliar se uma resposta atende a critérios explícitos.

Sempre delimite loops autônomos. Uma condição de conclusão pode falhar, um modelo pode parar e um avaliador pode ser probabilístico.

Important

O looping de agentes é experimental.

Configurar a repetição manualmente

Use a API de composição direta quando quiser fazer loop sem os outros padrões do Harness Agent.

Importe os tipos de laço e envolva qualquer AIAgent com LoopAgent. 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 });

Importe AgentLoopMiddleware e adicione-o a um regular Agent. O máximo padrão é de 10 execuções do 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. Volte True para continuar, False parar ou (continue, feedback) passar comentários para a próxima iteração.

Note

O recurso de loop empacotado descrito nesta página não está disponível no momento em Go.

Escolher uma condição de conclusão

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 item TodoProvider resolvido ainda possui itens incompletos, opcionalmente em modos de agente selecionados.
BackgroundTaskCompletionLoopEvaluator	Um item BackgroundAgentsProvider resolvido ainda tem tarefas em execução.
AIJudgeLoopEvaluator	Um cliente de juiz separado afirma que a solicitação original não foi totalmente atendida.
DelegateLoopEvaluator	Seu callback retorna LoopEvaluation.Continue(...).

Quando vários avaliadores são configurados, eles são executados em ordem. O primeiro avaliador que solicita outra iteração fornece seus comentários; o loop é interrompido somente quando todos os avaliadores se recusam a continuar.

Usar um juiz de IA

O juiz recebe a solicitação original e a resposta mais recente do agente. Se encontrar uma lacuna, sua análise se tornará um feedback para a próxima iteração:

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

Use apenas um endpoint de avaliação em que você confia para processar a requisição original e a resposta gerada.

Controle o contexto e a saída

Por padrão, LoopAgent reutiliza uma sessão e envia os comentários mais recentes do avaliador vencedor como a próxima entrada. FreshContextPerIteration = true em vez disso, recria cada iteração com base na solicitação original e em um registro consolidado de feedback, e reinicia ou restaura a sessão.

As execuções sem streaming retornam uma transcrição agregada por padrão. Defina NonStreamingReturnsLastResponseOnly = true para retornar apenas a resposta final. O streaming sempre emite cada iteração e quaisquer mensagens de feedback visíveis geradas em nome do processo.

O predicado recebe argumentos de palavra-chave, incluindo iteration, , last_result, messages, original_messages, session, , agent, progresse feedback. Os auxiliares todos_remaining() e background_tasks_running() fornecem condições integradas para tarefas pendentes e em segundo plano. Emparelhe-os com todos_remaining_message ou background_tasks_running_message para gerar uma próxima entrada direcionada.

Usar um juiz de IA

AgentLoopMiddleware.with_judge cria um ciclo conduzido por um juiz. Os loops do Judge têm cinco iterações por padrão:

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 é enviado de volta ao agente quando é necessário mais trabalho. Use apenas um endpoint de avaliação confiável com a solicitação original e a resposta gerada.

Contexto de controle, progresso e saída

Para loops avançados, construa AgentLoopMiddleware diretamente:

• record_feedback cria uma entrada de progresso concisa após cada iteração de trabalho.
• progress expõe 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 registro de progresso, e restaura uma sessão anexada ao seu snapshot anterior ao loop.
• return_final_only=True retorna apenas a última resposta para execuções sem streaming.

Passe max_iterations=None apenas quando houver garantia de que o predicado de conclusão terminará.

As condições de conclusão predefinidas e a integração com avaliadores descritas nesta página ainda não estão disponíveis em Go.

Use loops com o Harness Agent

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

Defina HarnessAgentOptions.LoopEvaluators. O harness aplica LoopAgent como seu decorador de agente 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();

Uma coleção vazia ou nullLoopEvaluators faz com que o harness opere em modo de disparo único.

Aprovação e comportamento de sessão

LoopAgent interrompe a execução antes de avaliar sua condição de conclusão quando uma iteração retorna uma solicitação pendente de aprovação de ferramenta. Ele retorna a solicitação ao chamador em vez de escondê-la atrás de outra iteração autônoma. Depois que o chamador fornecer a resposta de aprovação por meio do fluxo normal de aprovação da ferramenta , o agente poderá continuar.

LoopAgent não adiciona, por si só, o tratamento de aprovação. O Harness Agent aplica o loop externamente ToolApprovalAgent, permitindo que solicitações de aprovação pendentes saiam do loop.

Reutilize o mesmo AgentSession entre chamadas para continuar a conversa. As iterações de loop compartilham essa sessão por padrão. Com FreshContextPerIteration = true, LoopAgent redefine ou restaura o estado de sessão fornecido pelo chamador, onde há suporte. O armazenamento de conversas pertencente ao serviço pode manter o histórico quando a sessão serializada contém apenas um identificador remoto da conversa.

Forneça loop_should_continue a create_harness_agent; loop_max_iterations assume o valor padrão de 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 nenhum loop_should_continue, a fábrica não adiciona um loop e ignora os outros argumentos de loop.

Aprovação e comportamento de sessão

AgentLoopMiddleware para antes de avaliar seu predicado de continuação quando uma iteração retorna uma solicitação pendente de aprovação de ferramenta. Ele retorna a solicitação ao chamador em vez de escondê-la atrás de outra iteração autônoma. Depois que o chamador fornecer a resposta de aprovação por meio do fluxo normal de aprovação da ferramenta , o agente poderá continuar.

AgentLoopMiddleware não adiciona ToolApprovalMiddleware por si só. O Harness Agent posiciona o loop fora de seu middleware de aprovação, permitindo que solicitações de aprovação pendentes escapem do loop. Crie e transmita um AgentSession em cada execução do Harness Agent enquanto a aprovação automática de ferramentas estiver habilitada.

Reutilize o mesmo AgentSession entre chamadas para continuar a conversa. As iterações de loop compartilham essa sessão por padrão. Com fresh_context=True, o middleware restaura a sessão associada ao seu snapshot anterior ao loop entre as iterações. O armazenamento de conversas de propriedade do serviço pode manter o histórico quando a sessão serializada contém apenas um identificador de conversa remota.

Note

O looping do Harness Agent não está disponível atualmente em Go; portanto, o comportamento de aprovação e de sessão associado a ele não se aplica.

Próximas Etapas 

Delegar trabalho a agentes em segundo plano

Aprofunde-se

• Planejamento e tarefas
• Aprovação da ferramenta
• Arcabouço do agente