Looping do agente

O looping do agente invoca novamente um agente até que uma condição de conclusão seja atendida. 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 acoplado loops autônomos. Uma condição de conclusão pode falhar, um modelo pode parar e um avaliador pode ser probabilístico.

Importante

O looping do agente é experimental.

Configurar o looping manualmente

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

Importe os tipos de loop e embrulhe qualquer AIAgent um 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 é 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. Volte True para continuar, False parar ou (continue, feedback) passar comentários para a próxima iteração.

Note

O recurso de looping empacotado descrito nesta página não está disponível atualmente no 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 resolvido TodoProvider ainda tem itens incompletos, opcionalmente em modos de agente selecionados.
BackgroundTaskCompletionLoopEvaluator	Um resolvido BackgroundAgentsProvider ainda tem tarefas em execução.
AIJudgeLoopEvaluator	Um cliente juiz separado diz que o pedido original não é totalmente respondido.
DelegateLoopEvaluator	O retorno de chamada 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 ponto de extremidade de juiz em que você confia com a solicitaçã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 passagem da solicitação original mais um log de comentários agregado e redefine ou restaura a sessão.

As execuções que não são de streaming retornam uma transcrição agregada por padrão. Defina NonStreamingReturnsLastResponseOnly = true para retornar apenas a resposta final. O streaming sempre emite todas as iterações e quaisquer mensagens de comentários visíveis em nome de comentários.

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 internas e de tarefa 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 loop orientado pelo juiz. O juiz faz loops padrão para 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 é alimentado de volta ao agente quando mais trabalho é necessário. Use apenas um ponto de extremidade de juiz em que você confia 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 retornos de chamada.
• inject_progress=True adiciona progresso à entrada da próxima iteração.
• fresh_context=True reinicia da tarefa original e do log de progresso e restaura uma sessão anexada ao instantâneo de pré-loop.
• return_final_only=True retorna apenas a última resposta para execuções que não são de streaming.

Passe max_iterations=None somente quando o predicado de conclusão tiver a garantia de terminar.

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

Usar looping com o Harness Agent

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

Defina HarnessAgentOptions.LoopEvaluators. O arreio se 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();

Um vazio ou nullLoopEvaluators uma coleção deixa o arreio com tiro único.

Aprovação e comportamento de sessão

LoopAgent para antes de avaliar sua condição de conclusão quando uma iteração retorna uma solicitação de aprovação de ferramenta pendente. 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 a manipulação de aprovação em si. O Harness Agent aplica o loop externo ToolApprovalAgent, permitindo que solicitações de aprovação pendentes escapem 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 conversa de propriedade do serviço pode reter o histórico quando a sessão serializada contém apenas um identificador de conversa remota.

O fornecimento loop_should_continue para create_harness_agent; loop_max_iterations usa como padrão 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 de aprovação de ferramenta pendente. 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 se adiciona ToolApprovalMiddleware . O Harness Agent coloca o loop fora de seu middleware de aprovação, permitindo que solicitações de aprovação pendentes escapem do loop. Crie e transmita cada execução AgentSession do Harness Agent enquanto a aprovação automática da ferramenta está 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=Trueo middleware, o middleware restaura a sessão anexada ao instantâneo pré-loop entre iterações. O armazenamento de conversa de propriedade do serviço pode reter 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 no momento no Go, portanto, seu comportamento de aprovação e sessão não se aplica.

Próximas Etapas 

Delegar trabalho a agentes em segundo plano

Aprofunde-se

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