오케스트레이터 실행 흐름

오케스트레이터를 읽을 때는 업무 경로를 고르는 TurnWorkflow, 제한 안에서 반복하는 AgenticExecutor, **매 단계의 다음 행동 하나를 고르는 Controller**를 분리하면 쉽습니다. Controller가 오케스트레이터 전체도 아니고, 루프 자체도 아닙니다.

전체 흐름

그림은 왼쪽의 요청에서 오른쪽의 최종 응답으로 읽습니다. OKF rule 매칭 뒤 특정 rule은 rule 지정 child로, 그 외 요청은 기본 Agentic rule을 통해 Controller로 갈라지고, 각 실행의 완료 결과가 같은 Completed 후보에 합류합니다. 화살표가 겹치지 않도록 compose와 observation의 Controller 복귀선은 그림에서 생략하고 아래 시나리오에서 설명합니다.

작은 화면에서는 좌우로 스크롤하세요. 세부 설명과 SVG·PNG 내보내기는 전체 화면에서 사용할 수 있습니다.전체 화면에서 보기 ↗

그림은 기본 RuleSource.request() 성공 경로입니다. OKF rule 매칭은 routing_rule 문서와 요청의 schema·facts를 모델 호출 없이 대조합니다. 특정 rule이 선택되면 then.call에 적힌 child를 그대로 실행합니다. 그 외 요청은 낮은 우선순위의 조건 없는 기본 rule(기술적으로 catch-all)이 지정한 AgenticProgram의 Controller로 갑니다. 즉 이 노드는 LLM이 Wiki를 검색해 경로를 고르는 단계가 아닙니다.

그림의 rule 지정 child는 특정 종류의 Agent 이름이 아닙니다. then.call = "fixed_handler"처럼 rule에 선언한 alias를 Controller에게 다시 고르게 하지 않고 실행한다는 뜻입니다. 여기서 “고정 호출”은 바로 이 선택 과정이 고정됐다는 의미입니다. Completed 후보 → FinalResponse 직행은 Verification이 미적용된 경우이며, 검증을 활성화하면 두 노드 사이에 아래 시나리오 4의 VerificationLoop가 들어갑니다.

주체	한 번의 실행에서 맡는 일	맡지 않는 일
`TurnWorkflow`	`select → execute → verify? → finalize → emit`, checkpoint phase와 최종화 관리	도구를 매 step 선택하는 일
`AgenticExecutor`	Controller state, observation, step·tool-call 예산, 대기 checkpoint 관리	규칙 문서를 다시 평가하거나 응답을 외부에 전송하는 일
`Controller`	한 step마다 `call_tool`, `final`, `request_input`, `request_review` 중 하나 결정	`while` 루프와 checkpoint 수명 자체를 소유하는 일
child Agent·도구	전달받은 제한된 입력으로 검색·조회·검증·계산	임의의 다음 도구를 호출하는 일
`VerificationLoop`	완성 후보를 opt-in evaluator로 판정하고 제한적으로 수정	최초 라우팅이나 일반 도구 탐색

Controller는 무엇인가?

Controller는 별도 workflow나 A2A child가 아니라 AgenticProgram 안의 다음 행동 판단기입니다. 애플리케이션 부팅 때 [agentic.main]의 Registry model과 prompt를 해석하고, orchestrator-supervisor 같은 도메인 프롬프트 뒤에 SDK 소유 제어 규약을 붙여 AgenticController 하나로 조립합니다. 모델 temperature는 0.0으로 고정됩니다.

같은 supervisor 프롬프트와 제어 규약을 사용하되, 매 step에는 현재 요청·최근 대화·WorkMemory·누적 observation·현재 호출 가능한 도구가 새로 들어갑니다. Controller는 이를 보고 call_tool | final | request_input | request_review 중 다음 행동 하나를 반환하고, AgenticExecutor가 실제 반복과 checkpoint를 관리합니다.

한 사용자 Turn 안
Controller #1 → call_tool(knowledge_search) → 검색 결과를 observation에 누적
              → Controller #2 → final 또는 다음 허용 도구

따라서 “다음 Agent 호출 분기마다 판단한다”는 설명은 Controller가 선택하는 Agentic 도구 경로에는 맞지만, 모든 child 호출에 적용되지는 않습니다. OKF rule의 then.call로 확정된 child는 Controller를 거치지 않고, result_gate: complete나 transition complete도 다음 Controller 판단을 건너뛰고 후보로 갑니다. 판단은 멀티턴의 매 Turn 끝에 한 번 일어나는 것이 아니며, request_input처럼 명시적으로 멈출 때만 같은 실행이 다음 Turn으로 이어집니다.

structured_output_retries는 잘못된 Controller JSON을 같은 step 안에서 복구하는 횟수입니다. 이 내부 복구는 별도의 Controller step이나 tool call로 세지 않습니다.

Agent Loop 횟수는 두 예산으로 제한

[agentic.main]
model = "controller-model"
prompt = "orchestrator-supervisor"

# Controller가 다음 행동을 판단할 수 있는 execution 전체 횟수입니다.
max_controller_steps = 4

# Controller가 child 도구를 호출할 수 있는 execution 전체 횟수입니다.
max_tool_calls = 3

max_controller_steps는 1..4, max_tool_calls는 1..3이며 둘 다 위 값이 기본값입니다. 도구를 한 번 호출하면 보통 다음 Controller 판단이 이어지므로 “4회 반복”과 “도구 3회 호출”은 같은 뜻이 아닙니다. Controller가 final이나 request_input을 고른 step도 Controller 예산을 사용합니다.

도구 결과가 충분하면 Controller를 한 번 더 호출하지 않고 끝낼 수도 있습니다.

[agentic.main.tools.knowledge_search]
safety = "read_only"
response_data_schema = "example.search.result.v1"

# 답변이 준비된 구조화 결과는 Controller를 다시 부르지 않고 후보로 완료합니다.
[[agentic.main.tools.knowledge_search.result_transitions]]
id = "answer_ready"
when = [
  { path = "status", op = "eq", value = "success" },
  { path = "answer", op = "non_empty" },
]
when_mode = "all"
action = "complete"

# 추가 판단이 필요한 결과는 observation으로 같은 Agent Loop에 돌려보냅니다.
[[agentic.main.tools.knowledge_search.result_transitions]]
id = "needs_reasoning"
when = [{ path = "status", op = "eq", value = "partial" }]
action = "continue"

선언한 전이와 일치하지 않은 결과도 기존처럼 observation에 추가되고 Controller가 다음 행동을 판단합니다. result_transitions는 구조화 응답을 가진 read_only 도구에만 허용됩니다.

시나리오 1: 정형 요청은 rule이 실행 대상을 확정

schema·facts가 명확한 정형 요청
→ 입력 Guardrail
→ OKF routing_rule 일치
→ rule의 then.call에 선언된 child 실행
→ result_gate: complete
→ provisional Completed 후보
→ FinalResponse → 출력 Guardrail → emit

이 경로에서는 “어느 child를 쓸지”를 Controller에게 묻지 않습니다. rule 지정 child의 result_gate가 compose를 반환할 때만 child 결과를 observation으로 넘겨 Controller가 합성합니다. 규칙 경로도 checkpoint, WorkMemory, 최종화와 안전 경계를 우회하지 않습니다.

시나리오 2: 일반 요청은 Controller와 허용 도구가 반복

특정 rule만으로 실행 대상을 확정할 수 없는 일반 요청
→ OKF의 조건 없는 기본 rule이 AgenticProgram 선택
→ Controller step 1: call_tool(knowledge_search)
→ 검색 도구 결과
   ├─ transition complete → Completed 후보
   └─ continue 또는 불일치 → observation 저장
                              → Controller step 2: final 또는 다른 허용 도구

observation으로 돌아갈 때 요청을 처음부터 다시 처리하지 않습니다. 같은 AgenticExecutor state에 결과를 누적하고, 남은 Controller·도구 예산 안에서 다음 step을 실행합니다. 이미 완료한 도구는 같은 입력 구간의 allowlist에서 빠져 중복 호출을 막습니다.

시나리오 3: `request_input` 뒤 다음 Turn에서 재개

Turn 1: Controller step 1 → request_input("처리할 대상을 알려주세요.")
        → execute checkpoint 저장 → input_required emit

Turn 2: 사용자 보완 입력 → 입력 Guardrail
        → TurnWorkflow가 execute checkpoint 발견
        → AgenticExecutor.resume(...)
        → 같은 Controller state에서 step 2 실행

여기서 OKF rule 선택으로 돌아가지 않습니다. 새 입력은 resume_input으로 같은 실행에 들어가고, 입력 구간별 도구 중복 목록만 다시 열립니다. execution 전체의 controller_steps와 tool_calls는 누적됩니다. 완료되어 checkpoint가 지워진 뒤 사용자가 새 질문을 보내면 그때는 새 workflow 실행이므로 select부터 시작합니다.

시나리오 4: 후보 뒤 Verification Loop

outcome-evaluator는 사용자 답변을 만드는 일반 도구가 아니라 VerificationLoop가 호출하는 판정 전용 child Agent입니다. bounded 요청·후보·근거를 받아 pass | revise | review를 반환하며, 라우팅하거나 업무 도구를 호출하지 않습니다. [agents]에 evaluator alias만 등록해서는 검증이 켜지지 않고, [verification.<workflow>]의 mode = "observe" | "enforce"가 함께 있어야 해당 workflow 후보를 평가합니다.

AgenticExecutor의 provisional 후보
→ VerificationLoop
   ├─ off: evaluator 호출 없이 통과
   ├─ observe: 판정·오류를 기록하고 원 후보 통과
   └─ enforce
      ├─ pass → finalize
      ├─ revise → 같은 Controller state, tools 비활성, 최대 1회 수정 → 재평가
      └─ review·오류·상한 소진 → typed failure
→ FinalResponse → 출력 Guardrail → WorkMemory accept → emit

TOML의 [verification.<workflow>]에서 mode, evaluator와 max_revisions = 0..1을 설정합니다. 이 루프는 Agent Loop를 처음부터 돌리는 두 번째 실행이 아닙니다. enforce의 수정은 기존 observation을 유지한 채 도구 없이 수행됩니다. evaluator timeout·일시 unavailable로 verify checkpoint가 남은 실행은 재개 시 child를 다시 호출하지 않고 저장한 후보부터 평가를 이어 갑니다. 자세한 설정과 실패 계약은 결과 검증 루프를 보세요.

“다시 처음으로 돌아가나?” 정리

발생한 일	다음 시작점	처음부터 다시 실행?
도구 결과가 `continue`이거나 전이 불일치	같은 Agent Loop의 다음 Controller step	아니요. observation과 예산을 유지
Controller·child가 보완 입력 요청	저장한 `execute` checkpoint	아니요. 다음 Turn에서 같은 execution 재개
evaluator의 retryable 장애	저장한 `verify` checkpoint	아니요. 저장 후보부터 평가 재개
`enforce`가 `revise` 판정	같은 Controller state의 도구 없는 수정	아니요. 최대 1회만 수정
완료 후 들어온 별도 사용자 요청	`select`와 rules-first 라우팅	예. 새 workflow execution이며 대화·committed memory는 정책대로 참조

Event/Turn cycle과 Hill Climbing의 경계

A2A Event / Turn cycle은 요청 수신, checkpoint 재개, event emit을 설명하는 개념 경계입니다. SDK에 그 이름의 별도 public event-loop class가 있는 것은 아닙니다.
Agent Loop는 SDK runtime의 AgenticExecutor가 실제로 수행하는 bounded loop입니다.
Verification Loop는 후보 뒤에 붙는 SDK opt-in runtime 기능입니다.
Hill Climbing은 runtime loop가 아니라 저장소의 offline maintainer 도구입니다. trace 분석과 replay 제안까지만 자동화하고 Registry prompt 반영·배포·승격은 사람이 수행합니다.

네 경계를 한 그림으로 비교하려면 결과 검증 루프의 SDK Runtime Loop와 오프라인 개선 경계를 이어서 보세요. 실제 프로젝트를 만들 준비가 됐다면 오케스트레이터 시작하기로 이동하세요.