Recipes

Recipe 会根据 Benchmark 提供的任务信息和所选 Environment，自动补全镜像、工作目录和资源等运行设置。AgentCompass 默认会自动匹配并应用内置 Recipe；常规评测不需要传入 Recipe 参数，也不需要修改 Recipe 实现。

只有在 Benchmark 页面明确要求选择替代 Recipe、排查问题时需要限制匹配范围，或团队需要加载自定义适配逻辑时，才需要手动设置 Recipe。除此之外，保持默认自动匹配即可。

​

Recipe 如何工作

同一个 Benchmark 任务在 Docker、Daytona 或 Modal 中运行时，可能需要不同的镜像和工作目录设置。每次任务开始执行前，AgentCompass 都会使用与当前 Benchmark 和 Environment 匹配的 Recipe 准备这些设置，例如：

• 根据任务 ID 或任务中记录的镜像地址选择运行镜像；
• 将工作目录设为 Benchmark 需要的 /testbed、/workspace 或 /root；
• 将 CPU、内存、磁盘或 GPU 要求转换为所选 Environment 的参数；
• 在评分需要单独启动 sandbox 时，补充它的镜像和网络设置。

Recipe 不会替你选择 Harness 或 model，也不会执行任务或评分。为了让已选组合正常运行，它可能调整 Harness 的安装或执行设置。

​

什么时候需要手动设置 Recipe

场景	设置方式
使用默认的内置 Recipe	不传 Recipe 参数
使用 Benchmark 页面注明的替代 Recipe	传入 --recipe <recipe-id>
复现或排查时只允许特定 Recipe	传入 --recipe <recipe-id>；可重复指定
加载团队自定义 Recipe	传入 --recipe-dir <package-dir>

--recipe 不会强制执行指定 Recipe，而是只允许列出的 ID 参与匹配。Recipe 仍需与当前 Benchmark、Environment 和任务信息相符；未传入该选项时，AgentCompass 会从所有可用 Recipe 中自动匹配。

如果多个 Recipe 同时匹配，它们都会应用。需要确认实际应用项时，可在 DEBUG 运行日志 中查找 Recipe matched。

​

示例

下面使用 sample_ids 运行一个 SWE-bench Verified 实例。命令没有传入 --recipe；AgentCompass 会根据 swebench_verified 和 modal 自动匹配内置 Recipe。

export MODEL_NAME="<model-id>"
export MODEL_BASE_URL="<base-url>"
export MODEL_API_KEY="<api-key>"
export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  "$MODEL_NAME" \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"

该 Recipe 会根据实例信息选择镜像，并将工作目录设为 /testbed。其他内置适配示例：

组合	Recipe 自动补全的内容
Terminal-Bench 2 + daytona	读取任务声明的 Docker 镜像，并将默认工作目录设为 /root
ResearchClawBench + docker、daytona、modal	选择该 Benchmark 所需的运行镜像；Daytona 和 Modal 默认使用 /workspace

​

覆盖 Recipe 提供的值

需要使用自定义镜像或快照时，通过 --env-params 传入所选 Environment 支持的字段：

Environment	常用覆盖字段
Docker	image
Daytona	image 或 snapshot
Modal	image 或 named_image

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env docker \
  --env-params '{"image":"<custom-image>"}'

所选 Environment 支持该字段时，显式值优先于 Recipe 推导的默认值，但不会关闭 Recipe。Recipe 仍可能补充未指定的工作目录、资源或网络设置。阶段网络配置见网络策略。

​

可信外部 Recipe

这是面向团队自定义适配逻辑的高级用法。--recipe-dir 可为本次运行加载外部 Recipe：

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env <environment> \
  --recipe-dir ./company_recipes \
  --recipe company_swe_recipe

外部 Recipe 作为 Python 代码在 AgentCompass 进程中执行，不受任务 sandbox 隔离。只应加载经过审查的可信软件包。

外部软件包要求

• 目录必须是包含 __init__.py 的 Python 软件包。
• 根模块必须导出非空的 RECIPE_CLASSES 列表或元组。
• 每一项都必须是继承 AgentCompass BaseRecipe 基类的具体类，定义唯一 id，并支持无参数构造。
• 相对路径从当前工作目录解析。

“Recipe 目录”决定加载哪些外部实现，“Recipe ID”决定允许哪些已加载 Recipe 参与匹配：

使用方式	Recipe 目录	Recipe ID
agentcompass run	可重复指定 --recipe-dir	可重复指定 --recipe
单评测 Python SDK	recipe_dirs=[...]	enabled_recipes=[...]
单评测配置文件	runtime.recipe_dirs	execution.enabled_recipes
launch 编排文件	顶层 runtime.recipe_dirs	defaults.execution.enabled_recipes 或 requests[].execution.enabled_recipes

agentcompass launch 没有 --recipe 或 --recipe-dir 选项，需要将对应字段写入编排文件。显式 CLI 或 SDK 列表会替换配置文件中的对应列表，而不是追加。

Recipe ID 重复会导致加载失败。如果多个 Recipe 修改同一镜像、工作目录或网络设置，AgentCompass 不会自动解决冲突，因此不应同时加载职责重叠的实现。

​

相关页面

• Benchmark
• Environment
• agentcompass run
• 网络策略
• Environment 集成