100monkeys.ai

블로그 · 가이드 · 2026년 10월 29일

AEGIS 워크플로의 상태와 전이, 단계별로

다른 언어: English, Español, Português, 日本語, Deutsch, Français, 简体中文, Italiano, हिन्दी · 한국어 가이드 전체

공개: AEGIS는 100monkeys.ai가 만들고 있으므로 이 가이드는 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 공개 AEGIS 문서(영어), 주로 Workflow Manifest Reference와 CLI Reference를 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 아래의 YAML 줄과 명령은 모두 그 페이지들에서 복사했고, 이 가이드를 위해 실행한 것은 없습니다. 인용은 영어 그대로 두고 옆에 번역을 붙였습니다. 문서가 답하지 않는 질문은 마지막 절에서 밝힙니다.

AEGIS by 100monkeys.ai, in beta는 워크플로를 YAML 파일 하나로 쓴 유한 상태 기계로 실행합니다. 레퍼런스는 이를 에이전트, 컨테이너, 시스템 명령, 사람의 승인 게이트를 조율하는 "a durable, restartable sequence"(지속되고 다시 시작할 수 있는 순서)라고 부릅니다. 이 가이드는 상태를 하나씩 작성하며 엔진이 다음 상태를 어떻게 고르는지 보여 줍니다.

1단계. 헤더 작성하기

apiVersion: 100monkeys.ai/v1
kind: Workflow

metadata:
  name: dev-pipeline
  version: "1.0.0"

apiVersion은 정확히 100monkeys.ai/v1, kind는 정확히 Workflow여야 합니다. name은 ^[a-z0-9][a-z0-9-]{0,62}$를 따르고, 이름과 버전의 쌍은 유일해야 합니다. 기존 버전을 덮어쓰려면 force 매개변수가 필요합니다. metadata.input_schema는 선택 사항이며, 있으면 호출자의 입력을 실행 전에 검증하고, 맞지 않는 페이로드는 "rejected with HTTP 422; no workflow execution is created."(HTTP 422로 거부되며 워크플로 실행은 만들어지지 않습니다.)

2단계. 첫 상태와 한도 정하기

spec 아래에서 initial_state는 필수이며 spec.states에 있어야 합니다. 끝나지 않는 루프를 막는 한도가 두 가지 있습니다. spec.max_total_transitions는 기본 50, 최대 100이며, 그 뒤에는 "the workflow terminates"(워크플로가 종료됩니다). 상태마다의 max_state_visits는 기본 5, 최대 20입니다. 각 상태에는 timeout도 있고 기본값은 300s입니다. spec.context에는 반복 한도나 임계값처럼 모든 상태가 {{workflow.context.KEY}}로 읽는 상수를 둡니다.

3단계. 상태마다 종류 고르기

모든 상태는 kind를 지정합니다. 레퍼런스에는 여덟 가지가 있습니다.

4단계. 시도할 순서대로 전이 작성하기

전이는 "evaluated top-to-bottom. The first matching transition is taken."(위에서 아래로 평가됩니다. 처음 맞는 전이가 선택됩니다.) 각 전이는 target 상태와, 선택적으로 condition을 지정합니다. 레퍼런스의 예시에 있는 이 System 상태는 종료 코드로 분기합니다.

    EXECUTE:
      kind: System
      command: python main.py
      env:
        CODE: "{{GENERATE.output}}"
        PYTHONPATH: /workspace
      transitions:
        - condition: exit_code_zero
          target: VALIDATE
        - condition: exit_code_non_zero
          target: REFINE
          feedback: "Execution failed: {{EXECUTE.output.stderr}}"

종류별로 쓸 수 있는 조건은 다음과 같습니다. 대부분의 종류에 on_success와 on_failure, System과 ContainerRun에 exit_code_zero, exit_code_non_zero, value를 붙인 exit_code, Human에 input_equals, input_equals_yes, input_equals_no, ParallelAgents에 consensus, all_approved, any_rejected, 모든 종류에 Handlebars expression을 쓰는 custom, 그리고 무조건 대체 경로로 always 또는 조건 없음. 레퍼런스의 조언은 이렇습니다. "Always include an unconditional fallback as the last transition."(마지막 전이로 항상 무조건 대체 경로를 두세요.)

5단계. 점수로 분기하기

    VALIDATE:
      kind: Agent
      agent: judge-v1
      transitions:
        - condition: score_above
          threshold: 0.95
          target: COMPLETE
        - condition: score_below
          threshold: 0.95
          target: REFINE
          feedback: "{{VALIDATE.output.reasoning}}"

두 비교는 모두 엄격하므로, 점수가 정확히 0.95이면 위의 어느 전이도 선택되지 않습니다. 점수는 상태의 score에서, 없으면 final_score에서, 그것도 없으면 consensus.score에서 읽습니다. 점수가 없는 상태는 어느 쪽에도 맞지 않으며, 다른 것도 맞지 않으면 실행은 State "<name>" carries no score for its score transitions로 실패합니다. Agent 상태에서 score_between은 경계를 포함하는 min과 max를 받습니다.

6단계. 일어난 일을 다음 상태로 넘기기

전이의 feedback 문자열은 이어지는 상태에서 {{state.feedback}}가 됩니다. 실패 메시지가 다시 시도하는 에이전트에게 닿는 방법이 이것입니다. 끝난 상태는 각각 이름 아래 Blackboard에 기록되므로, 뒤의 상태는 {{EXECUTE.output.stdout}}이나 {{VALIDATE.score}}를 읽습니다. 두 네임스페이스를 구분하세요. {{input.KEY}}는 호출자가 넘긴 값이며 "is immutable"(변경할 수 없습니다). 반면 {{blackboard.KEY}}는 실행이 진행되면서 늘어납니다. 아직 어떤 상태도 쓰지 않은 키를 가리키는 템플릿은 빈 문자열 대신 상태 이름과 함께 ERROR: missing key라는 보이는 자리 표시를 렌더링합니다.

7단계. 가드를 두고 루프하고, 실행 끝내기

    REFINE:
      kind: System
      command: update_context
      env:
        ITERATION: "{{blackboard.iteration_number + 1}}"
        ERRORS: "{{state.feedback}}"
      transitions:
        - condition: custom
          expression: "{{blackboard.iteration_number < workflow.context.max_iterations}}"
          target: GENERATE
        - condition: custom
          expression: "{{blackboard.iteration_number >= workflow.context.max_iterations}}"
          target: FAILED

    COMPLETE:
      kind: System
      command: finalize
      transitions: []

transitions: []인 상태는 종료 상태입니다. "When reached, the workflow execution completes with status completed."(이 상태에 도달하면 워크플로 실행은 completed 상태로 끝납니다.) max_state_visits에만 기대지 말고, 위처럼 Blackboard에 루프 자체의 가드를 두세요.

8단계. 검증, 배포, 실행, 그리고 전이 지켜보기

aegis workflow validate ./pipeline.yaml
aegis workflow deploy ./pipeline.yaml
aegis workflow run dev-pipeline --input '{"task": "..."}'
aegis workflow logs <execution_id> --transitions

validate는 매니페스트를 로컬에서 검사합니다. deploy는 그것을 등록하며, 같은 이름과 버전이 이미 있으면 --force를 붙이지 않는 한 실패합니다. logs --transitions는 "state entries/exits only"(상태의 진입과 이탈만)를 보여 주며, 각 상태가 어느 분기를 탔는지 가장 빨리 확인하는 방법입니다.

문서가 답하지 않는 것

다음

검토자가 무엇을 보고 침묵이 무엇을 뜻하는지까지 포함해 Human 상태를 자세히 보려면 오케스트레이터에 승인 단계를 주는 방법: AEGIS를 실제 예시로 한 패턴을 읽으세요. AEGIS는 100monkeys.ai에 적힌 명령으로 설치합니다.

curl -fsSL https://get.100monkeys.ai | bash

100monkeys.ai에서 AEGIS 설치하기