data-gen-ebd/agent.md
amos b773033658 Record model requests and payloads as prefix deltas in the native trace
Each model_request/model_payload repeated the full context, so the trace
grew with the square of the request count: batch 6 Qwen runs hit 64 MiB
at ~75 requests and 14 attempts (13 graded PASS) were discarded.
Requests now record only items after the common prefix with the previous
one (schema embedded-rollout.pi/2), and pi_run.expand rebuilds full
payloads before the unchanged broker/feedback checks. Needs a new image
(trace6) and recalibration before use.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-18 10:50:56 +08:00

67 lines
9.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Agent 接入合同
本文件约束已有 Agent 如何进入任务环境。项目负责工作区、生命周期、验收和证据,当前只采集真实 rollout,不实现模型训练或另一套通用 Agent。
## 启动与输入
启动命令以 argv 传给 `run`,由执行器在 Docker 工作容器内运行,不拼接 shell。镜像必须包含所需 Agent、编译器及运行依赖;先解析并冻结实际 image ID,再用相同身份执行和评分。
Agent 从缺陷模板复制出的候选工作区开始,可以读取、修改、构建、运行并进行公开自测。题面通过 stdin 传入,同时只读挂载到 `/task/prompt.md`;工作目录为 `/workspace`,不额外增加路径环境变量。
正式 verifier、gold/noop/cheat、控制端目录及 Docker socket 不提供给 Agent;Agent 镜像本身也不能包含正式 grader 或参考样例。任务目录的完整内部内容不能整体挂入工作容器。
`--agent-id` 是调用方填写的版本标签,不能单凭它证明实际 CLI 或模型身份。当前接入 Pi 0.73.1 与 GLM-5.3 Chat Completions,真实身份另从原生事件和调用证据核对。不得把上游密钥放入 argv、题面、候选、镜像或轨迹。评分容器始终无网络。
`run` 必须提供 `--calibration` 的 attempt 目录。只有同 task/verifier/image 的 Docker 校准回执包含每类样例五次(默认 20 次)全部符合预期的试验、整体 PASS 才允许启动;可信 host 回执不能代替。
正式 Pi 通过 `python3 -m rollout.pi_run TASK --image IMAGE --credential-file PRIVATE_FILE --output runs` 启动。PRIVATE_FILE 是私有、不纳入 Git、无符号链接的 JSON 常规文件,权限 0600,含 `model_api_key`;只把路径交给可信控制端。`--calibration` 可选,省略时自动校准;controller 自动建立专用 bridge/代理并在结束后核对清理。低层 `run` 的手工 proxy/network 配置保留给执行器验证,正常 Pi 采集不要求手工管理。
真实 Pi 工作容器固定 2 GiB、1 CPU,独立 `--agent-timeout` 默认 900 秒用于防止挂死;评分容器仍为 512 MiB、1 CPU,按任务的 60 秒期限验收。费用与模型轮数不设置上限。工作区与 `/trace` 合计写入不超过 2 GiB,输出盘剩余不足 30 GiB 时不启动或停止 Agent,细节见 architecture.md。阶段内先测量,不将此配置作为后续任务的通用容量。
本步 Pi 通过可信 host 模型代理访问 GLM-5.3。上游密钥只在 host 私有文件与代理内,Agent 仅收到非敏感 base URL;代理绑定本次专用 Docker bridge 并只接受该网络来源,不开放公网。`--model-base-url` 传不含凭证、query 或 fragment 的地址;当前 Pi adapter 仅接受 IP 形式的 HTTP 私有代理 URL。`--agent-network` 指定已创建的专用 internal 网络,执行器拒绝非 internal 网络,未指定时 Agent 使用 `--network none`;Agent 只能访问本网络内的代理,不能直连外网。控制端负责 proxy 与网络最终回收;grade 始终无网。
容器内 Pi 入口为 `node /opt/embedded-rollout/agent/pi.mjs --trace /trace/native.jsonl --model MODEL --max-tokens N`,三个参数都由 controller 按 `MODELS` 表给出,镜像内不保留默认值;调整模型输出上限不需要换镜像或重新校准。实际请求、context、模型/工具事件与结束事实写入该文件,目录与候选分离。adapter 禁用自动压缩、重试和外部扩展,固定工具为 read/edit/write/bash;每轮模型输入、wire payload、响应状态与 session 结束事实按实际记录。摘要只证明文件身份,因果闭合与来源完整性单独验收,不因文件存在而宣称全部通过。
## 提交、终止和评分
工作区是 template 的完整副本;Agent 结束后只冻结 task.json 的 `candidate_files`,其他文件和新建文件不进入正式候选。冻结时逐个拒绝缺失、符号链接、越界或超过 1 MiB 的候选文件。退出码 0 只是 Agent 执行结束,不能代表任务完成。
执行器冻结候选摘要,启动新的评分容器。grader 使用受保护的 root 文件与隔离 Python;C 编译器和候选降为 UID/GID 65534,清除补充组。主动检查该身份读取正式 grader 是否得到 PermissionError;无法确认则 UNVERIFIED。候选只读,构建临时产物写入独立临时位置。详情见 [architecture.md](docs/architecture.md),实际 Docker 验收结论见 [acceptance.md](docs/acceptance.md),不以 daemon 可用代替隔离通过。
超时、异常退出或中断均保存已有日志与终止原因,执行清理并留下回执;清理无法确认时不得继续把资源算作可用。
Docker CLI 超时、中断或被信号终止后,daemon 请求可能仍在途;即使精确 rm 后当时 inspect 显示不存在,也不能据此把容器清理记为 confirmed。该生命周期记录 unknown,并使父 controller 传播自动校准的清理不确定性;专属 network 创建的 CLI 未正常结束也按相同规则处理。只有后续按名称/ID 的现场复核与清理才能另记 confirmed,不能覆盖原始事件。
## 记录要求
M0 的监督事件记录启动 argv、镜像身份、阶段、时间、退出码、超时、候选摘要、评分结果及清理。它证明执行器做了什么,不能证明模型看到了哪些反馈。
当前 Pi 原生 adapter 需要保留并验收:
- 真实模型身份与请求/返回、system context、工具 schema。
- 工具调用 ID、参数、结果及它们进入后续模型输入的顺序。
- 会话结束、上下文压缩或截断、用量与费用的真实事实;没有费用字段时记未知。
- 原始文件摘要、最终候选、正式评分及身份关联。
缺少上述原生记录时,`run` 产物只能作为执行证据,不计为完整真实轨迹。脚本或 mock Agent 不得标为真实模型执行;缺当前模型连通性时不得用历史结果补齐。当前回执保留 `NOT_TRAIN_READY` 兼容字段,本项目不提供训练转换或训练准入流程。
## 接入验收
先用可信脚本验证目录与超时等执行机制,再接已有真实 Agent。真实接入至少证明一次工具操作产生真实反馈、进入下一轮模型输入,并与最终提交和独立评分关联。gold/负例校准、会话完整性、任务成功和清理分别记录,失败尝试也可形成有效 rollout。
2026-10-12 已完成新 runtime 校准、36 Docker 的真实 Pi/GLM-5.3 闭环和 Salty 归档复核;模型/工具因果证据 VERIFIED,独立评分 PASS,Agent 正常结束且清理 confirmed。实际请求、反馈、检查数量和摘要以 [现场回执](docs/rollout-receipt.json) 为准,验收与限制见 [acceptance.md](docs/acceptance.md) 和 [runtime-review.md](docs/runtime-review.md)。首次异常轨迹不计为合格样本。Salty 正式模型通道与 Agent 后端仍需验证,不把 host bridge 代理直接暴露公网,隐藏测试不放入 Agent 可读个人盘。镜像身份与清理例外详见 [onboarding.md](docs/onboarding.md)。
只运行本项目授权试跑,不动已有作业;代码只推送到项目 `origin` 的 main。Salty 持久内容集中于唯一个人目录,本次临时文件、容器、proxy、网络和作业核对证据后清理。
## 流式编码和限额
Pi 的 `message_update` 仅省略重复累计的 `message` 与 `assistantMessageEvent.partial`,header 的 `message_update_omits` 明确标记;增量字段、完整 `message_end`、model request/payload 和 session entries 保留。header `schema=embedded-rollout.pi/2` 起,`model_request` 与 `model_payload` 按前缀增量记录:每条带 `delta: {field, from}`,`field` 为 context 的 `messages` 或 payload 的 `input`(Responses)/`messages`(GLM),该列表等于上一条同类事件重建后的前 `from` 项加本条所列项,其他字段完整记录,首条 `from=0`。原先每次重复全量 context 和 payload,轨迹随请求数平方增长(20261017-C-embedded-6-hard 的 Qwen 75 次请求即达 64 MiB,两类事件占 78%,14 次尝试因此作废);增量后同样的轨迹约 16 MB 且线性增长。host 先重建全量再核对 broker 摘要与工具反馈,无 `delta` 的 pi/1 事件按全量处理。原生文件与 host stdout 同步写入,按 UTF-8 字节在写前限制 64 MiB(host 读取同一上限)。超限主动 abort,不继续工具或模型调用,留下唯一 `TRACE_LIMIT_EXCEEDED` 不完整终态;该尝试不能归档为完整轨迹。
stdout 可能是非阻塞管道:每行循环写到全部字节写入,管道满时短暂等待重试,不能因部分写入丢失 host 侧证据。每次回复的输出上限由 `MODELS` 给出(GLM `max_tokens=131072`、Qwen `max_output_tokens=65536`,均经上游实测接受),controller 回执记录 `model_max_tokens` 与 `model_sampling=service-default`;证据核对要求每个线上 payload 的该字段等于回执值,否则 UNVERIFIED。Pi SDK 未指定时默认截到 32000,长推理会在调用工具前耗尽并以 `length` 终止,属于配置故障而非能力结果。
## Qwen Responses 试跑
2026-10-12 用户指定 `qwen3.8-27b-nvfp4` 与 `http://114.111.18.115:18080/v1/responses`。本次新增 `--model qwen3.8-27b-nvfp4`,保留默认 GLM 接入;只允许这两个固定模型与各自上游路径,不接受 Agent 自选上游。上游 HTTP 是用户指定的连接方式,密钥仍仅留在受保护的 host 文件及代理内。
Qwen 使用 Pi 已有 `openai-responses` adapter,保留原生模型与工具记录,不加入 GLM 专有请求字段。首次接入不发送可选 reasoning 参数;服务实际返回的思考内容仍按原样记录。Responses 必须由 host broker 确认收到 `response.completed` 才算正常模型调用;提前断流或 `response.incomplete/failed` 不计为完整轨迹。新 adapter 镜像需重新完成同任务 20 次 Docker 校准,再运行真实 Agent 并独立评分。算术接口测试不代表任务成功。