agent-compose.yml 配置手册

本文档说明当前代码实际接受的 agent-compose.yml / agent-compose.yaml 字段、默认值、约束和使用方式。解析器采用严格字段校验：未知字段、重复字段以及类型不符都会报错，因此字段名必须与本文一致。

重要：项目级工作区只支持顶层复数键 workspaces。顶层 workspace 已不受支持，会被当作未知字段拒绝。Agent 选择某个工作区时仍使用单数键 agents.<agent>.workspace。

可以在应用配置前进行本地校验：

agent-compose config --quiet
agent-compose -f ./path/to/agent-compose.yml config

第一条命令只校验；第二条还会输出归一化后的配置，并对标记为 secret 的值进行脱敏。默认查找当前目录下的 agent-compose.yml，其次查找 agent-compose.yaml；两者同时存在时应使用 -f/--file 明确选择。

完整结构速览

下面的配置用于展示字段所在位置。它刻意包含了较多能力，实际项目只需保留需要的部分。

name: review-pipeline

env_file:
  - .env
  - .env.local

variables:
  DISPLAY_NAME: review-pipeline
  CONTROL_TOKEN:
    value: ${CONTROL_TOKEN}
    secret: true

workspaces:
  source:
    provider: local
    path: .
  upstream:
    provider: git
    url: https://github.com/example/project.git
    branch: main
    path: .

mcp_servers:
  local-tools:
    type: local
    command: npx
    args: ["-y", "@example/mcp-server"]
    env:
      API_TOKEN:
        value: ${MCP_API_TOKEN}
        secret: true
  issue-tracker:
    type: remote
    transport: http
    url: ${ISSUE_TRACKER_MCP_URL}
    headers:
      Authorization:
        value: Bearer ${ISSUE_TRACKER_TOKEN}
        secret: true

volumes:
  cache:
    name: review-cache
    driver: local
    labels:
      purpose: agent-cache
    options: {}

agents:
  reviewer:
    status: enabled
    provider: codex
    model: ${REVIEW_MODEL}
    system_prompt: |
      Review changes carefully and report concrete evidence.
    image: ghcr.io/chaitin/agent-compose-guest:latest
    build:
      context: .
      dockerfile: guest-images/Dockerfile.agent-compose-guest
      target: runtime
      args:
        CHANNEL: stable
      platforms: [linux/amd64]
      tags: [review-agent:latest]
      no_cache: false
      pull: true
    driver:
      docker: {}
    env:
      LOG_LEVEL: info
      SERVICE_TOKEN:
        value: ${SERVICE_TOKEN}
        secret: true
    mcp_servers:
      - local-tools
      - name: audit-api
        type: remote
        transport: sse
        url: https://mcp.example.com/sse
        headers:
          Authorization:
            value: Bearer ${AUDIT_TOKEN}
            secret: true
    capset_ids:
      - engineering
    skills:
      - ./skills/review
      - name: release-check
        source: git
        url: https://github.com/example/agent-skills.git
        path: skills/release-check
        ref: main
    volumes:
      - cache:/cache
      - type: bind
        source: ./reports
        target: /workspace/reports
        read_only: false
    workspace:
      name: source
    scheduler:
      enabled: true
      sandbox_policy: sticky
      triggers:
        - name: hourly-review
          cron: "0 * * * *"
          prompt: Review the current workspace.
          sandbox_policy: new
    jupyter:
      enabled: false
      guest_port: 8888

network:
  mode: default

通用规则

严格解析

• 顶层和各对象中的未知字段会报 unknown field，不会被静默忽略。
• 同一映射中的重复字段会报 duplicate field。
• 布尔字段必须是布尔值，列表字段必须是 YAML sequence，映射字段必须是 YAML mapping。
• 项目名、Agent 名、顶层 Workspace 键、MCP 名、Volume 键和最终 Skill 名使用稳定标识符格式：^[a-z][a-z0-9_-]*$。
• 路径和 URL 的相对基准因字段而异，具体见对应章节。

环境变量来源和优先级

env_file 决定 ${NAME} 插值时可读取哪些 dotenv 文件。加载顺序如下：

1. 按 env_file 列表顺序加载，后面的文件覆盖前面的同名值。
2. 运行 agent-compose CLI 的进程环境最后覆盖 dotenv 文件。

若未配置 env_file，CLI 先查配置文件所在目录的 .env，不存在时再查当前工作目录的 .env。显式写 env_file: [] 表示不自动加载任何 dotenv 文件。显式文件不存在、不可读或列表中有空路径都会失败。

${NAME} 只支持简单形式，不支持 shell 的 ${NAME:-default}、命令替换或递归展开。引用的变量不存在时配置校验失败。

当前支持插值的位置包括：

• variables.*.value
• agents.*.model
• agents.*.env.*.value
• 项目级和 Agent 内联 MCP 的 url、env.*.value、headers.*.value
• Skill 的 name、source、url、path、ref、username

其他字符串字段不会自动插值，例如 name、provider、image、system_prompt、Workspace 字段、Build 字段和 Scheduler 字段。

环境值的两种写法

variables、agents.*.env、MCP env 和 MCP headers 都使用同一个值结构：

PLAIN_VALUE: hello
SECRET_VALUE:
  value: ${SECRET_VALUE}
  secret: true

secret 是脱敏元数据，不会自行从环境读取值；仍需在 value 中写 ${NAME}。

顶层字段

name

name: code-review

允许小写字母开头，后续可包含小写字母、数字、_ 和 -。例如 review-v2 合法，Review、2-review 和包含空格的名称不合法。项目身份同时受规范化的配置文件路径影响，因此同名但来自不同路径的项目可被区分。

env_file

单文件可以写标量：

env_file: .env.production

多文件写列表：

env_file:
  - .env
  - .env.production

variables

variables:
  REGION: cn-hangzhou
  RELEASE_TOKEN:
    value: ${RELEASE_TOKEN}
    secret: true

variables 当前用于保存项目级配置值和脱敏语义。若某个值要传入 sandbox，仍需在对应 Agent 的 env 中声明。

workspaces：项目级工作区

顶层必须使用 workspaces：

workspaces:
  source:
    provider: local
    path: .

以下旧写法无效：

# 错误：顶层 workspace 会被严格解析器拒绝
workspace:
  provider: local
  path: .

每个 workspaces.<key> 支持：

本地 Workspace 在每次项目 run 创建时被复制为隔离快照，Agent 对快照的修改不会写回源目录。

workspaces:
  source:
    provider: local
    path: ./src
  release-branch:
    provider: git
    url: https://github.com/example/service.git
    branch: release
    path: .

Workspace 选择规则：

• 顶层 workspaces 只是命名定义，不会自动分配给任何 Agent。
• Agent 省略 workspace 时，无论顶层定义了多少个 Workspace，该次 run 都不配置 Workspace。
• Agent 需要使用顶层 Workspace 时，必须通过 workspace.name 显式引用，或定义内联 Workspace。
• 显式的空对象 workspace: {} 非法；不使用 Workspace 时应省略该 key。

mcp_servers：项目级 MCP

项目级 MCP 是命名映射，名称须符合稳定标识符格式。支持 local 和 remote 两类。

Local MCP

mcp_servers:
  filesystem:
    type: local
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    env:
      NODE_ENV: production

Remote MCP

mcp_servers:
  docs:
    type: remote
    transport: sse
    url: https://mcp.example.com/sse
    headers:
      Authorization:
        value: Bearer ${MCP_TOKEN}
        secret: true

项目级 MCP 不会自动注入所有 Agent。Agent 必须在自己的 mcp_servers 中引用或定义需要的 Server。

volumes：项目级 Volume

volumes:
  cache: {}
  shared-data:
    name: existing-data
    driver: local
    external: true
    labels:
      owner: platform
    options:
      tier: fast

Volume map key 必须符合稳定标识符格式。Agent 通过 agents.<name>.volumes 挂载项目 Volume。

agents.<name>

agents 是以 Agent 名为 key 的映射：

agents:
  reviewer:
    provider: codex
    image: ghcr.io/chaitin/agent-compose-guest:latest

支持的字段如下：

status、provider、model 和 system_prompt

agents:
  reviewer:
    status: enabled
    provider: claude
    model: ${CLAUDE_MODEL}
    system_prompt: |
      Focus on correctness, security, and regression risk.

Provider 支持 codex、claude、gemini 和 opencode。当前兼容归一化还接受 claude-code / claude_code、gemini-cli / gemini_cli、open-code / open_code，新配置建议使用规范名称。

image

agents:
  reviewer:
    image: ghcr.io/chaitin/agent-compose-guest:latest

运行时会确保所选 driver 能使用该镜像。若同时配置 build，image 也会加入构建 tag；若两者均未提供 tag，执行 agent-compose build 会失败。

GitHub CI 当前只向 GHCR 发布以下两个多平台镜像：

Agent 的 image 应使用 ghcr.io/chaitin/agent-compose-guest:<tag>。daemon 镜像用于部署控制面，不能作为 guest 镜像使用。CI 不发布 BoxLite-only、Microsandbox-only 或其他 driver 专用 guest 镜像。

build

短写法只指定 context：

build: ./guest

完整写法：

build:
  context: ./guest
  dockerfile: Dockerfile
  target: runtime
  args:
    VERSION: "1.2.3"
  platforms:
    - linux/amd64
  tags:
    - example/guest:latest
  no_cache: false
  pull: true

当前 agent-compose build 使用 Docker daemon image store。CLI 同名选项可以覆盖或追加 YAML 配置。

driver

省略 driver 时默认为：

driver:
  docker: {}

必须且只能选择一个 runtime：

driver:
  docker:
    host: ""

或：

driver:
  boxlite:
    kernel: ""
    rootfs: ""

或：

driver:
  microsandbox:
    profile: secure

为完整说明 schema，下面的结构可以被解析器识别，但当前会在规范化阶段失败：

# 当前实现中无效。
driver:
  firecracker:
    kernel: /path/to/kernel
    rootfs: /path/to/rootfs

即使 schema 支持某个 driver，当前二进制也必须编译了该 driver。可通过 agent-compose --json version 的 compiled_drivers 查看；这不代表 KVM、Docker daemon 或运行时制品健康。

env

env:
  LOG_LEVEL: debug
  API_TOKEN:
    value: ${API_TOKEN}
    secret: true

这些值进入 Agent sandbox。相同名称的空项会在后续边界归一化；secret: true 控制展示脱敏。

mcp_servers

引用一个项目级 MCP：

mcp_servers: filesystem

引用多个：

mcp_servers:
  - filesystem
  - issue-tracker

定义 Agent 专属 MCP：

mcp_servers:
  - name: private-tools
    type: local
    command: private-mcp
    args: ["serve"]

内联对象支持 name、type、transport、command、args、env、url 和 headers，其 local/remote 约束与项目级 MCP 相同。内联 MCP 必须提供 name；同一 Agent 内不能重复声明同名内联 MCP。重复引用同一个项目级 MCP 会去重。

capset_ids

capset_ids:
  - engineering
  - ticketing

列表会去除空值和重复值。配置了 capability gateway 时，这些 ID 用于将 sandbox 限制到对应 OctoBus capability set，并注入访问所需的环境和能力说明；gateway 未配置或能力说明获取失败时采用 best-effort 行为并产生 warning。

skills

Skill 目录必须包含有效的 SKILL.md。支持 file、git 和 zip 来源；同一 Agent 的最终 Skill 名不可重复。

本地目录短写：

skills:
  - ./skills/review

等价完整写法：

skills:
  - name: review
    source: file
    path: ./skills/review

Git 来源：

skills:
  - name: review
    source: git
    url: https://github.com/example/skills.git
    path: review
    ref: v1.0.0
    username: ${GIT_USERNAME}
    token: ${GIT_TOKEN}

GitHub shorthand：

skills:
  - source: git
    url: github:example/skills//review@v1.0.0

ZIP 来源：

skills:
  - name: review
    source: zip
    url: https://downloads.example.com/review.zip
    path: review

password 和 token 不允许明文。它们在 Skill 解析阶段通过 daemon 环境解析，避免把凭证展开后写入项目规范。远程 ZIP 下载限制为 HTTP(S)，并执行大小、压缩包和网络地址安全检查。

volumes

短写格式是 source:target[:ro|rw]：

volumes:
  - cache:/cache
  - ./reports:/workspace/reports:ro

长写格式：

volumes:
  - type: volume
    source: cache
    target: /cache
    read_only: false
  - type: bind
    source: ./reports
    target: /workspace/reports
    read_only: true

同一 Agent 不能将多个条目挂到相同 target。短写使用 : 分隔，因此不适合包含冒号的 source/target，此时应使用长写。

workspace：Agent 选择或内联工作区

这里是 Agent 内部的单数 workspace，与顶层复数 workspaces 不是同一个层级。

引用顶层条目：

workspace:
  name: source

内联本地 Workspace：

workspace:
  provider: local
  path: ./src

内联 Git Workspace：

workspace:
  provider: git
  url: https://github.com/example/project.git
  branch: main
  path: .

若 name 与 provider/url/branch/path 同时出现，该对象按内联 Workspace 处理，而不是从顶层继承后局部覆盖。需要复用时只写 name。

scheduler

Scheduler 可以使用声明式 triggers，也可以使用 JavaScript script；两者互斥。

new 为每次调用创建新 sandbox；sticky 允许 Scheduler 绑定并复用 sandbox。单个 Trigger 的 sandbox_policy 可覆盖执行 Agent 时的策略。

声明式 Trigger

每个 Trigger 必须且只能写一个 kind 字段：cron、interval、timeout 或 event。

scheduler:
  enabled: true
  sandbox_policy: sticky
  triggers:
    - name: nightly
      cron: "0 2 * * *"
      prompt: Run the nightly review.
    - name: heartbeat
      interval: 30m
      prompt: Check service health.
    - name: startup-once
      timeout: 15s
      prompt: Perform the startup check.
      sandbox_policy: new
    - name: webhook-review
      event:
        topic: webhook.github.push
      prompt: Review the pushed changes.

内联脚本

scheduler:
  enabled: true
  script: |
    scheduler.interval("review", async function () {
      return scheduler.agent("Review the workspace.");
    }, 60000);

脚本由 Scheduler runtime 验证，并从脚本注册结果获取触发器。

外部脚本

scheduler:
  enabled: true
  script:
    url: ./scheduler.js

url 支持：

• 相对或绝对本地路径；相对路径以 compose 文件目录为基准。
• file:///absolute/path/scheduler.js。
• http:// 或 https:// URL。

应用项目时 CLI 会读取脚本并将内容快照保存到项目规范，而不是让 daemon 以后重新读取来源。读取限制包括 10 秒超时、最大 1 MiB、最多 5 次 HTTP redirect、UTF-8 校验；HTTPS 不允许降级 redirect 到 HTTP，URL userinfo 不允许使用。

jupyter

jupyter:
  enabled: true
  guest_port: 8888

设置 guest_port 但保持 enabled: false 会保留端口配置，但默认不启动 Jupyter。CLI run --jupyter 可以为单次运行启用。

network

network:
  mode: default

该字段目前主要表达和持久化项目网络意图，实际 runtime 网络拓扑仍由所选 driver 和 daemon 部署环境负责。

常见错误与迁移提示

顶层误写 workspace

错误：

workspace:
  provider: local
  path: .

正确：

workspaces:
  source:
    provider: local
    path: .

agents:
  reviewer:
    workspace:
      name: source

同时配置 Scheduler script 和 triggers

二者互斥。把所有注册逻辑放入 script，或完全使用声明式 triggers。

以为 variables 会自动进入 sandbox

variables 不会继承到 Agent。需要显式写：

variables:
  API_URL: https://api.example.com

agents:
  reviewer:
    env:
      API_URL: https://api.example.com

如果目标是复用部署环境值，可在两个位置都写 ${API_URL}，并通过 env_file 或 CLI 进程环境提供。

以为项目 Workspace 会被自动选择

顶层 workspaces 不会被自动选择。Agent 省略 workspace 时，即使项目只定义了一个条目，也不会配置 Workspace。需要使用时应设置 workspace.name 或内联 Workspace；不使用时应省略该 key，而不是写 workspace: {}。

选择未编译或运行条件不满足的 driver

配置 schema 通过不代表 runtime 一定可启动。BoxLite/Microsandbox 只在 Linux 完整构建中编译，并依赖 KVM 和对应运行时制品；Docker 需要可达的 Docker daemon。

最小配置示例

name: docker-minimal

agents:
  reviewer:
    provider: codex
    image: ghcr.io/chaitin/agent-compose-guest:latest
    driver:
      docker: {}

验证并应用：

agent-compose config --quiet
agent-compose up
agent-compose run reviewer --prompt "Review this project."