ブログ · ガイド · 2026年10月29日

AEGIS ワークフローの状態と遷移を一歩ずつ

他の言語: English, Español, Português, Deutsch, Français, 한국어, 简体中文, Italiano, हिन्दी · 日本語のガイド一覧

開示: AEGIS は 100monkeys.ai が開発しているため、このガイドは作り手による説明として読んでください。公開されている AEGIS ドキュメント、主に Workflow Manifest Reference と CLI Reference をもとに当社の AI エージェントが下書きし、当社が確認しました。この日本語版は英語の原文ガイドの翻訳です。以下の YAML の各行とコマンドはそれらのページからそのまま写したもので、このガイドのためにはどれも実行していません。引用は英語のまま載せ、訳を添えています。ドキュメントが答えていない点は、最後の節に書いています。

AEGIS by 100monkeys.ai, in beta は、ワークフローを 1 つの YAML ファイルに書かれた有限状態機械として実行します。リファレンスはこれを "a durable, restartable sequence"(永続的で再開可能な一連の処理)と呼び、エージェント、コンテナ、システムコマンド、人による承認ゲートをまとめて動かします。このガイドでは状態を 1 つずつ書き、エンジンが次の状態をどう選ぶかを示します。

ステップ 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 に存在しなければなりません。終わらないループを止める上限が 2 つあります。spec.max_total_transitions の既定値は 50、上限は 100 で、それを超えると "the workflow terminates"(ワークフローは終了する)。各状態の max_state_visits の既定値は 5、上限は 20 です。各状態には timeout もあり、既定は 300s です。spec.context には、反復回数の上限やしきい値のように、どの状態も {{workflow.context.KEY}} として読める定数を置きます。

ステップ 3. 各状態の種類を選ぶ

どの状態も kind を名乗ります。リファレンスが挙げるのは 8 種類です。

• Agent はデプロイ済みのエージェントを実行し、その status、output、score、iterations を状態名の下に書き込みます。
• System はシェルの command を実行し、stdout、stderr、exit_code を記録します。
• Action は update_blackboard や repository_commit のようなワークフロー自身の操作を 1 つ実行します。"no agent chooses or calls it, and no shell runs."(どのエージェントもそれを選ばず呼ばず、シェルも動かない)。
• Human は人が答えるまで実行を止めます。
• ParallelAgents は複数の審査役を実行し、合意の戦略でスコアをまとめます。
• ContainerRun と ParallelContainerRun は CI や CD の作業向けにコンテナのステップを実行します。
• Subworkflow は別のワークフローを、待つ形でも待たない形でも起動し、深さは最大 10 です。

ステップ 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}}"

2 つの比較はどちらも厳密なので、ちょうど 0.95 のスコアは上のどちらの遷移も選びません。スコアは状態の score、なければ final_score、なければ consensus.score から読まれます。スコアを持たない状態はどちらにも一致せず、ほかに一致するものがなければ実行は State "<name>" carries no score for its score transitions で失敗します。score_between は Agent 状態に対して両端を含む min と max を取ります。

ステップ 6. 起きたことを次の状態へ渡す

遷移の feedback 文字列は、遷移先の状態で {{state.feedback}} になります。失敗のメッセージはこうして再試行するエージェントに届きます。終わった状態はそれぞれ名前の下で Blackboard に書かれるので、後の状態は {{EXECUTE.output.stdout}} や {{VALIDATE.score}} を読めます。2 つの名前空間は分けておきます。{{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"(状態への出入りだけ)を表示するので、各状態がどの分岐を取ったかを最も早く確かめられます。

ドキュメントが答えていないこと

• ゲートの言葉。 Workflow Manifest Reference では input_equals_yes が "yes"、"approve"、"approved"、"true" を受け付けるとし、Human Approvals のページは yes、y、1 としています。どちらかの一覧に頼る前に、自分のゲートを試してください。
• 2 つ目の書き方。 同じページの Blackboard の例は kind: agent、input_template、そして遷移を on: success と next: で書いていますが、リファレンスのほかの部分は kind: Agent、input、condition、target です。エンジンが両方を受け付けるかどうかは書かれていません。
• テンプレート内の算術。 例では {{blackboard.iteration_number + 1}} を設定していますが、式の演算子として挙げられているのは比較と論理だけで、+ はありません。
• 一致しないとき。 スコアの場合を除き、状態が終わってどの遷移にも一致しないとき何が起きるかは書かれていません。
• 種類はいくつか。 ドキュメントの索引は "all seven state kinds"(7 種類すべての状態)と書いていますが、リファレンスの表は 8 種類を挙げています。

次に読むもの

Human 状態を、レビュー担当に見えるものや沈黙の意味まで詳しく知るには、オーケストレーターに承認ステップを持たせる方法を読んでください。AEGIS は 100monkeys.ai に載っているコマンドでインストールできます。

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

AEGIS をインストール