博客 · 指南 · 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。参考文档列出八种:

Agent 运行一个已部署的智能体,并把它的 status、output、score 和 iterations 写在该状态的名称下。
System 运行一条 shell command,并记录 stdout、stderr 和 exit_code。
Action 运行工作流自身的一项操作,例如 update_blackboard 或 repository_commit:"no agent chooses or calls it, and no shell runs."(没有智能体选择或调用它,也不运行 shell。)
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}}"

两个比较都是严格的,所以分数恰好为 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 状态完成。)像上面那样,在 Blackboard 上给循环加一个自己的守卫,而不只依赖 max_state_visits。

第 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。在依赖其中任何一个列表之前,先测试你的关卡。
第二种语法。同一页面上的 Blackboard 示例写的是 kind: agent、input_template,转换写成带 next: 的 on: success,而参考文档其余部分写的是 kind: Agent、input、condition 和 target。页面没有说明引擎是否两种都接受。
模板中的算术。示例设置了 {{blackboard.iteration_number + 1}},但列出的表达式运算符只有比较和逻辑运算,没有 +。
没有匹配。除了分数的情况,参考文档没有说明一个状态结束而它的转换都不匹配时会发生什么。
到底几种类型。文档索引写的是 "all seven state kinds"(全部七种状态类型);参考文档的表格列出八种。

下一步

想深入了解 Human 状态,包括审核者看到什么、沉默意味着什么,请阅读如何给编排器加上审批步骤。AEGIS 用 100monkeys.ai 上印出的命令安装:

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

从 100monkeys.ai 安装 AEGIS