100monkeys.ai

博客 · 指南 · 2026年10月28日

AEGIS 智能体清单:每个字段及其约束

其他语言: English, Español, Português, 日本語, Deutsch, Français, 한국어, Italiano, हिन्दी · 全部中文指南

声明:AEGIS 由 100monkeys.ai 开发,因此请把这篇指南当作开发方的说明来读。它由我们的一个 AI 智能体根据公开的 AEGIS 文档起草,主要是 Agent Manifest Reference、CLI Reference、Workflow Manifest Reference 和 Human Approvals,并经公司审阅;这个简体中文版是英文原版指南的译文。字段名、默认值和拒绝消息均引自这些页面,保留英文原文,译文附在旁边。

AEGIS by 100monkeys.ai, in beta,用一个 YAML 文件运行一个智能体。文档把智能体清单称为 "the source of truth for an Agent's identity, capabilities, security constraints, and execution requirements."(智能体身份、能力、安全约束和执行要求的唯一事实来源。)本指南逐节讲解,并说明编排器如何处理每个字段。

第 1 步:写好头部

apiVersion: 100monkeys.ai/v1
kind: Agent
metadata:
  name: pr-reviewer
  version: "1.0.0"
  description: "Reviews pull request diffs and returns structured feedback."

apiVersion 和 kind 必须正好是这两个值。name 必须匹配 ^[a-z0-9][a-z0-9-]{0,62}$,并且 name 与 version 的组合必须唯一:再次部署相同的组合会失败,除非传入 --force。labels 和 annotations 是可选的键值映射,用于发现和备注。

第 2 步:选择运行时

spec.runtime 是 spec 中唯一必填的部分。要么给出 language 和 version(python、javascript、typescript、rust 或 go,会解析为官方镜像),要么给出完全限定的 image,二者不能同时出现;只有 language 而没有 version 是无效的。image_pull_policy 默认为 IfNotPresent。model 指定 aegis-config.yaml 中的模型别名,生成图像的别名会被拒绝。isolation 接受 inherit、docker、firecracker 和 process;参考文档把 docker 标为第 1 阶段,另外两个标为第 2 阶段。

第 3 步:给它一个任务

task.instruction 是智能体据以工作的指引,设置它会 "auto-enables semantic validation"(自动启用语义验证)。task.prompt_template 是一个 Handlebars 模板;它的变量有 {{intent}}、{{instruction}}、{{input}}、{{iteration_number}}、{{previous_error}} 和 {{context}}。spec.input_schema 是一个 type: object 的 JSON Schema,它声明具名输入,并在智能体运行前验证它们。

第 4 步:只声明它需要的访问权限

"All permissions are deny-by-default."(所有权限默认拒绝。)没有 spec.security 时,智能体没有网络,也不能访问文件系统。network.mode 可以是 allow(只允许 allowlist)、deny(除 denylist 外都允许)或 none,后者 "attaches no network interface to the container"(不给容器挂接任何网络接口)。filesystem.read 和 filesystem.write 列出路径,允许使用通配符。资源默认值为 cpu: 1000 毫核、memory: "512Mi"、disk: "1Gi" 和 timeout: "1800s",上限一小时。当智能体可以尝试两次或更多时,超时必须容得下两次完整尝试,即 2 × (iteration_timeout + 评审者的 timeout_seconds) + 45 秒,否则该智能体 "is refused on create and update"(在创建和更新时被拒绝)。

第 5 步:挂载它的卷

spec.volumes[] 的每一项都有 name、storage_class(ephemeral 需要 ttl_hours;persistent 需要 source.volume_id)、以 /workspace 为根的 mount_path,以及 access_mode。对持久卷的读写访问同一时间只属于一次执行。无法挂载的卷会让本次迭代停止:智能体 "never runs without its volume."(从不在没有卷的情况下运行。)

第 6 步:定义迭代方式和完成标准

execution.mode 为 iterative(默认)或 one-shot。max_iterations 取值 1 到 20,默认 5,max_retries 是同一个字段。iteration_timeout 默认 600s,llm_timeout_seconds 默认 300。每次尝试之后,validation 按顺序运行:exit_code、json_schema、regex、semantic(一个评审智能体,min_score 默认 0.7)或 multi_judge。失败会作为 {{previous_error}} 回到智能体。tool_validation 在每次工具调用运行前评审它;那里只用 semantic 条目。outputs 指定执行必须留下的文件,每个文件可选 min_bytes 和 magic,缺少任何一个,本次尝试即失败。

第 7 步:授予工具

spec.tools 接受 "mcp:filesystem" 这样的字符串,或带有 name、server 和 config 的对象。要运行命令,声明 executor: "builtin:cmd",并提供必填的 subcommand_allowlist,即从命令到允许的第一个参数的映射;其他任何调用 "is rejected with a policy violation"(都会以策略违规被拒绝)。编排器会检查这些声明能否完成工作:一个需要写文件却没有声明工具的智能体,或声明了 fs.write 却没有读写卷的智能体,会在部署时被拒绝,并给出一句说明原因的话。

第 8 步:传入配置和密钥

spec.env 的值可以是字面量、"secret:<name>"(从 OpenBao 注入,"never logged",从不记录)或 "config:<key>"。spec.security_context 仅供平台运维人员使用;设置它的消费者账户会收到 403 Forbidden。

第 9 步:先验证,再部署

aegis agent deploy ./agent.yaml --validate-only
aegis agent deploy ./agent.yaml

--validate-only 只解析和验证,不部署。aegis agent show <AGENT_ID> 会显示已存储的清单。

人工的"同意"放在哪里

智能体清单没有批准字段。人的同意属于工作流,放在 kind: Human 状态里:prompt 必填,timeout 默认 3600s,default_response 是超时时采用的答复;没有它,工作流会失败。Human Approvals 说门控的 input_equals_yes 转换接受 yes,input_equals_no 接受 no,任何转换都不接受的答复会被拒绝并重新询问。

文档尚未说明的地方

下一步

想在一台新服务器上从头到尾运行一个清单,请阅读 在全新的 Ubuntu VPS 上安装 AEGIS,并运行你的第一个经批准的任务。AEGIS 可以用 100monkeys.ai 上给出的命令安装:

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

从 100monkeys.ai 安装 AEGIS