에이전트 반복 실행

에이전트 루프는 완료 조건이 충족될 때까지 에이전트를 다시 호출합니다. 반복적인 구체화, 할 일 완료, 백그라운드 작업 대기 또는 답변이 명시적 조건을 충족하는지 여부를 평가하는 데 사용합니다.

자율적 루프에는 항상 제한을 두세요. 완료 조건이 실패하고, 모델이 중단될 수 있으며, 평가자가 확률적일 수 있습니다.

중요합니다

에이전트 루핑은 실험적입니다.

수동으로 반복 설정

다른 Harness 에이전트 기본값 없이 반복하려는 경우 직접 컴퍼지션 API를 사용합니다.

루프 유형을 가져온 다음, 모든 AIAgent를 LoopAgent로 래핑합니다. 기본 최대값은 10개의 에이전트 호출입니다.

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

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

AgentLoopMiddleware를 가져와 일반 Agent에 추가합니다. 기본 최대값은 10개의 에이전트 실행입니다.

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

조건자는 동기 또는 비동기일 수 있습니다. 계속하려면 True를, 중지하려면 False를, 또는 피드백을 다음 반복으로 전달하려면 (continue, feedback)를 누르세요.

비고

이 페이지에 설명된 패키지된 루핑 기능은 현재 Go에서 사용할 수 없습니다.

완료 조건 선택

LoopAgent 는 하나의 계산기 또는 정렬된 컬렉션을 허용합니다.

평가자	다음 동안 계속됨:
CompletionMarkerLoopEvaluator	최신 응답에는 구성된 표식이 포함되어 있지 않습니다.
TodoCompletionLoopEvaluator	해결된 TodoProvider에도 선택한 에이전트 모드에서는 여전히 미완료 항목이 있을 수 있습니다.
BackgroundTaskCompletionLoopEvaluator	해결된 BackgroundAgentsProvider 작업에는 여전히 실행 중인 작업이 있습니다.
AIJudgeLoopEvaluator	별도의 판사 클라이언트는 원래 요청이 완전히 응답되지 않는다고 말합니다.
DelegateLoopEvaluator	콜백이 반환됩니다 LoopEvaluation.Continue(...).

여러 계산기가 구성된 경우 순서대로 실행됩니다. 다른 반복을 요청하는 첫 번째 평가기는 피드백을 제공합니다. 루프는 모든 평가자가 계속하기를 거부하는 경우에만 중지됩니다.

AI 판사 사용

판사는 원래 요청 및 최신 에이전트 응답을 받습니다. 간격을 찾으면 해당 분석은 다음 반복에 대한 피드백이 됩니다.

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

원래 요청 및 생성된 응답을 신뢰하는 판사 엔드포인트만 사용합니다.

컨텍스트 및 출력 제어

기본적으로 LoopAgent 한 세션을 다시 사용하고 우승 평가자의 최신 피드백을 다음 입력으로 보냅니다. FreshContextPerIteration = true 대신 원래 요청의 각 패스와 집계된 피드백 로그를 다시 빌드하고 세션을 다시 설정하거나 복원합니다.

비 스트리밍 실행은 기본적으로 집계된 대본을 반환합니다. 최종 응답만 반환하도록 설정합니다 NonStreamingReturnsLastResponseOnly = true . 스트리밍은 항상 모든 반복과 표시되는 모든 대리 피드백 메시지를 내보냅니다.

조건자는 iteration, last_result, messages, original_messages, session, agent, progress, 및 feedback를 포함한 키워드 인수를 받습니다. 도우미 todos_remaining() 및 background_tasks_running()은(는) 내장된 할 일 목록 및 백그라운드 작업 조건을 제공합니다. 이를 todos_remaining_message 또는 background_tasks_running_message와 함께 사용해 목표에 맞는 다음 입력을 생성합니다.

AI 판사 사용

AgentLoopMiddleware.with_judge는 심사 기반 루프를 구축합니다. Judge 루프는 기본적으로 5회 반복됩니다.

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

판사의 추론은 더 많은 작업이 필요할 때 에이전트에게 다시 공급됩니다. 원래 요청 및 생성된 응답을 신뢰하는 판사 엔드포인트만 사용합니다.

컨텍스트, 진행률 및 출력 제어

고급 루프의 경우 AgentLoopMiddleware를 직접 구성하세요.

• record_feedback 는 각 작업 반복 후에 간결한 진행률 항목을 만듭니다.
• progress 는 누적된 항목을 콜백에 노출합니다.
• inject_progress=True 는 다음 반복의 입력에 진행률을 추가합니다.
• fresh_context=True 는 원래 작업 및 진행률 로그에서 다시 시작하고 연결된 세션을 해당 사전 루프 스냅샷으로 복원합니다.
• return_final_only=True 는 비 스트리밍 실행에 대한 마지막 응답만 반환합니다.

max_iterations=None는 완료 조건자가 반드시 종료된다고 보장되는 경우에만 전달하세요.

이 페이지에 설명된 패키지된 완료 조건 및 판사 통합은 현재 Go에서 사용할 수 없습니다.

하네스 에이전트와 함께 루핑 사용

미리 구성된 기록, 계획, 메모리, 승인 및 관찰성 파이프라인도 원할 때 Harness 에이전트 설정을 사용합니다.

HarnessAgentOptions.LoopEvaluators을 설정합니다. 이 하네스는 가장 바깥쪽 에이전트 데코레이터로서 LoopAgent을(를) 적용함:

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

비었거나 nullLoopEvaluators 컬렉션은 하네스를 일회성으로 남겨둡니다.

승인 및 세션 동작

LoopAgent 반복 작업에서 보류 중인 도구 승인 요청이 반환되면 완료 조건을 평가하기 전에 중지됩니다. 다른 자율 반복 뒤에 숨기는 대신 호출자에게 요청을 반환합니다. 호출자가 일반적인 tool approval 흐름을 통해 승인 응답을 제공하면 에이전트는 계속 진행할 수 있습니다.

LoopAgent 에서는 승인 처리 자체를 추가하지 않습니다. Harness Agent는 ToolApprovalAgent 바깥쪽에 루프를 적용하여 승인 대기 중인 요청이 루프에서 빠져나갈 수 있도록 합니다.

통화 간에 동일한 AgentSession 것을 다시 사용하여 대화를 계속합니다. 루프 반복은 기본적으로 해당 세션을 공유합니다. FreshContextPerIteration = true 를 사용하면 LoopAgent지원되는 경우 호출자가 제공한 세션 상태를 다시 설정하거나 복원합니다. 직렬화된 세션에 원격 대화 식별자만 포함된 경우 서비스 소유 대화 스토리지는 기록을 유지할 수 있습니다.

loop_should_continue을(를) create_harness_agent에 제공합니다. loop_max_iterations의 기본값은 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 은 다음 입력을 사용자 지정합니다. loop_should_continue가 없으면 팩터리는 루프를 추가하지 않으며 다른 루프 인수는 무시합니다.

승인 및 세션 동작

AgentLoopMiddleware 반복 작업에서 보류 중인 도구 승인 요청이 반환되면 해당 연속 조건자를 평가하기 전에 중지됩니다. 다른 자율 반복 뒤에 숨기는 대신 호출자에게 요청을 반환합니다. 호출자가 일반적인 도구 승인 흐름을 통해 승인 응답을 제공하면, 에이전트는 계속 진행할 수 있습니다.

AgentLoopMiddleware 자체는 ToolApprovalMiddleware를 추가하지 않습니다. Harness 에이전트는 루프를 승인 미들웨어 외부에 배치하여 대기 중인 승인 요청이 루프에서 벗어날 수 있도록 합니다. 도구 자동 승인이 활성화된 상태에서 Harness Agent를 실행할 때마다 AgentSession를 생성하고 전달합니다.

통화 간에 동일한 AgentSession 것을 다시 사용하여 대화를 계속합니다. 루프 반복은 기본적으로 해당 세션을 공유합니다. fresh_context=True를 사용하면 미들웨어는 반복할 때마다 연결된 세션을 루프 시작 전 스냅샷 상태로 복원합니다. 직렬화된 세션에 원격 대화 식별자만 포함된 경우 서비스 소유 대화 스토리지는 기록을 유지할 수 있습니다.

비고

현재 Go에서는 Harness 에이전트 루핑을 사용할 수 없으므로 승인 및 세션 동작이 적용되지 않습니다.

다음 단계

백그라운드 에이전트에 작업 위임

자세히 알아보기

• 계획 및 할 일
• 도구 승인
• 에이전트 하네스