add-your-agent

将你的 Agent 添加到 Veris Bench

将此仓库中的 Agent 部署为 Veris Bench 上已注册的 Your image 候选项，并通过冒烟试运行证明它可以正常工作。

Agent 保持不变。 在 Agent 旁添加一个服务文件、一个 Dockerfile 和一个候选项文件。只有在别无他法时才修改 Agent 自身的代码，并在报告中说明。

冒烟试运行显示为 completed 并不能证明集成正常。数据库调用全部失败的 Agent，或模型调用未被评分器捕获的 Agent，仍然可以完成运行。第 9 步说明了要检查什么。

第 1 步之前阅读 reference/api.md，第 2 步之前阅读 reference/image.md。

输入

更改任何内容之前，请收集以下信息。缺少时请向用户询问。

输入	来源
VERIS_API_KEY	环境变量，以 vbk_ 开头。只有用户本人可以签发：前往控制台中的 Overview、API keys、Issue。切勿打印该密钥或将其写入文件。
BENCH_API	默认值为 https://bench.api.veris.ai/v1。只有用户提供了其他值时才使用该值。
BENCH_ID	如果用户提供了该技能的参数，则使用该参数。否则请询问用户，或列出其基准测试并让用户选择。
Registry	Docker 可以推送到的仓库前缀，例如 ghcr.io/<org>。
Model keys	Agent 读取的密钥，例如 OPENAI_API_KEY。这些密钥应配置在基准测试中，绝不能放入镜像或仓库。如果环境中没有所需密钥，请让用户在控制台中添加。

步骤

1. 检查访问权限。 读取基准测试。access 必须为 write。如果为 read，请停止并告诉用户原因（reference/api.md 中的“Access”）。
2. 读取 Agent，不做编辑。 记录：语言和入口点；运行单轮对话的函数以及它如何保留历史记录；模型 SDK 及其已安装版本；它调用的每项外部服务，以及每个地址或 DSN 的来源（变量、配置文件或字面值）；它读取的每个密钥；以及它通过相对路径打开的文件。现在根据 reference/image.md 中的“Telemetry”检查 SDK：不受支持的版本不会记录任何模型调用，也不会给出任何提示。
3. 了解基准测试的运行环境。 列出其中的服务（reference/api.md 中的“World”）。将 Agent 调用的每项服务与一个孪生服务配对。如果 Agent 调用的服务没有孪生服务，请告知用户：除非 Veris 为该基准测试启用了网关，否则这些调用会访问真实供应商。
4. 添加服务文件 bench_server.py 或 bench_server.mjs，参照 reference/image.md 中的模式。它应包装 Agent 的单轮对话函数，为每个会话 ID 保存一个会话，提供 /health 服务，并监听 0.0.0.0:8008。使用 http。只有在 Agent 已经支持 WebSocket 时才使用 ws。
5. 在服务文件中，将 Agent 指向孪生服务。 在加载 Agent 的模块之前，将 VERIS_DS_SERVICE_URLS 中的每个孪生服务地址复制到 Agent 已读取的设置中。应用 reference/image.md 中“Twins”所述的客户端修复。
6. 根据 reference/image.md 编写 Dockerfile 和 .dockerignore。 如果仓库中已有 Dockerfile，且它可以运行该服务，则重复使用。
7. 在本地检查。 为 linux/amd64 构建并运行镜像，发送 /health 请求和一轮对话请求（reference/image.md 中的“Local check”）。推送前修复所有失败项。
8. 推送并注册。 推送镜像，固定其摘要，运行 check-image，必要时保存仓库登录信息，确保每个密钥都在基准测试的 candidate-env 中，编写 bench/candidate.json，并注册候选项（reference/api.md）。
9. 运行冒烟试运行并验证。 使用两个需要 Agent 工具的任务，不指定角色设定，重复一次。没有待处理项后，根据下表检查每次尝试。每个失败的行都表示集成存在问题：从运行产物中找出原因，修复问题，推送新摘要，更新候选项，在同一次试运行中等待没有待处理项后重新运行，并再次检查。
10. 报告（格式如下）。

完成意味着每次冒烟测试都符合以下条件

检查项	查看位置（reference/api.md，“Verify”）	失败时的处理方法
已运行	status 为 completed	查看 error 的末尾，其中包含容器的最后几行日志。
Agent 已作答	turns 为 2 或更多，且对话记录中有 Agent 回复	路径或字段映射错误，或者服务在某轮中崩溃。查看 candidate.log 和 transcript.jsonl。
评分器能看到模型调用	agent_trace_reason 为 null，且 agent_trace.json 中的 llm_calls 大于 0	参见 reference/image.md 中的“Telemetry”。仅凭 agent_trace_reason 不够：当跟踪记录中没有模型调用时，它也会是 null。judge_disabled_trace 表示基准测试的评分器不会读取跟踪记录，这不是错误，可跳过此项检查。
Agent 使用了自己的工具	如果 Agent 配有工具，则 tool_calls 大于 0，且 agent_trace.json 中的工具结果不是错误	如果工具错误提到了连接或证书，则属于第 5 步；参见 reference/image.md 中的“Twins”。
Agent 已连接到模拟服务	Agent 使用的每个模拟服务都至少收到过它的一个请求（Verify 命令中的 reached）	Agent 仍指向自己的默认地址。重做第 5 步。不要用 ledger_summary 的计数来判断，因为其中包含平台发出的请求。

passed 不在此列表中。Agent 是否通过任务衡量的是 Agent，而不是集成效果。两次尝试说明不了多少质量问题；完整试运行才能说明。

看起来像成功的陷阱

症状	原因	修复方法
Node Agent：所有数据库工具都失败，且日志中有 pg SSL 警告	node-postgres 将模拟服务 DSN 中的 sslmode=require 视为 verify-full，而模拟服务的证书是自签名的	在服务文件中的 DSN 后追加 uselibpqcompat=true
Node Agent：agent_trace_reason 为 no_spans_received	跟踪钩子将内容写入工作目录，但运行用户没有写入权限	将应用目录的所有者设为运行用户（chown）
Node Agent：llm_calls 为 0，且 candidate.log 中没有 veris-otel-node: instrumented OpenAI 行	openai 包的版本低于 5	将 openai 升级到 5 或更高版本，并更新锁文件，确保构建镜像时安装该版本
尝试在一分钟内失败，出现 exec format error 或拉取错误	在 Apple Silicon 上构建了 arm64 镜像，或基准测试无法拉取镜像	使用 --platform linux/amd64；运行 check-image
Agent 回复为空	image.path 或响应字段与服务不匹配	让 bench/candidate.json 与服务保持一致
工具只在基准测试中失败	地址写死了，或使用了基准测试未设置的变量	第 5 步

向用户报告

• 添加或更改的文件，每个文件占一行。
• 镜像引用、候选项 ID 和试运行 ID，以及控制台链接 https://benchmark.veris.ai/benchmarks/<bench id>?trial=<trial id>。
• 对于每次冒烟测试：报告五项检查结果及 passed。
• Agent 自身代码或依赖的任何更改，以及原因。
• 首次冒烟测试后所做的每项修复，以及原因。
• 下一步：按照 https://docs.veris.ai/run-a-trial 进行完整试运行；对于新版本，在同一次试运行中创建新的候选项。