【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载Harbor 是一套面向终端任务的 agent 评测框架而benchmarks/harbor目录中的适配器evaluation adapter把本仓库的unreal-agent-runner包装为 Harbor 的unreal-agent已安装型 agentinstalled agent使其能够直接参与 Harbor 0.22.0 的基准评测。本文以 benchmarks/harbor/README.md 为主体结合仓库源码与测试完整讲解如何同步依赖、构建可复现的 runner 发布包bundle、用harbor run发起本地 Docker 或 Modal 云端评测、理解支持的工具与 ViewImage 图像限制以及如何解读输出的 ATIF 轨迹与 token 指标并最终通过单元测试与 smoke 测试验证整个链路。读完本文你将掌握在 Harbor 生态中完整落地 unreal-agent 评测的全部可复现操作步骤与底层原理。适配器定位与前置依赖Harbor evaluation adapter 的核心目标是把unreal-agent-runner评测为 Harbor 中的unreal-agent。它不是一个新的 agent 实现而是一个薄薄的桥接层UnrealAgent类继承 Harbor 的BaseInstalledAgent在安装阶段把构建好的 runner 二进制上传进评测容器在运行阶段把任务指令以 JSON 请求的形式喂给 runner并在结束后把 runner 输出的 JSONL 会话日志转换为 Harbor 的 ATIF 轨迹。运行与构建该适配器需要以下前置条件均已在 pyproject.toml 与 README 中声明Go版本由仓库根目录 go.mod 指定用于交叉编译 runner 二进制Python 3.12适配器本身是 Python 包uv依赖管理与虚拟环境工具Docker 或 Modal评测任务的目标执行环境Harbor 0.22.0固定版本依赖harbor0.22.0Modal 执行则安装harbor[modal]0.22.0。初始化与构建生成可校验的 runner 发布包同步依赖从仓库根目录执行make -C benchmarks/harbor sync该命令实际执行uv sync --locked --all-extras见 Makefile以锁定的方式安装全部依赖与可选用依赖含 modal extra。构建 runner bundlemake -C benchmarks/harbor build REVISIONHEADMakefile 中的 build 目标会调用 build.pypython3 build.py --revision $(REVISION) --runner $(RUNNER) --arch $(ARCH) --output $(BUNDLE)构建过程的关键设计如下从 git 归档出干净的源码树build.py先以git rev-parse --verify revision^{commit}把REVISION解析为完整 commit再用git archive commit导出该 commit 的源码快照而非工作区内容确保构建输入完全可复现。交叉编译 runner在归档源码树中对./cmd/unreal-agent-runner执行go build -trimpath -buildvcsfalse并强制GOOSlinux、GOARCHarch默认amd64可选arm64、CGO_ENABLED0产出静态二进制。写入 manifest 清单manifest.json记录revision完整 40 位 commit、runner默认为unreal-agent-runner、sha256二进制校验和、goos/goarch、go_version。输出到固定目录产物落在bin/harbor/short-commit/包含unreal-agent-runner可执行文件与manifest.json。两个值得注意的行为已有 bundle 不会被覆盖若BUNDLE目录已存在build.py会直接抛出FileExistsError(Refusing to replace runner bundle: ...)。因此当需要为同一 commit 重新构建时应显式指定一个新的输出目录make -C benchmarks/harbor build REVISIONHEAD BUNDLE../../bin/harbor/short-commit-v2。默认目标平台是 Linux amd64对应 Harbor 评测容器的常见架构如需 arm64用ARCHarm64覆盖。manifest 同时记录了所选 runner 与 revision保证了哪个版本的 runner 参与了哪次评测是可追溯的。为什么安装阶段要校验 bundle适配器在UnrealAgent.__init__中会通过 bundle.py 的Bundle.load()加载并严格校验 bundlerevision必须恰好是 40 位十六进制、sha256必须是 64 位十六进制goos必须是linuxgoarch只能是amd64或arm64每次read_binary()都会用 manifest 中的 sha256 校验二进制内容校验和不一致直接抛ValueError。对应的 test_bundle.py 用test_changed_binary_is_rejected_after_construction验证了构建后再替换二进制文件会被拒绝这一安全属性。这样评测中任何对本地文件的篡改都不可能混入与 manifest 不符的二进制。发起一次 Harbor 评测本地 Docker 评测构建完成后使用绝对路径的 bundle 路径发起评测export OPENAI_API_KEY... uv run --project benchmarks/harbor --locked harbor run \ -p /absolute/path/to/task \ -a harness_harbor.agent:UnrealAgent \ -m openai/gpt-5.4 \ --ak bundle$PWD/bin/harbor/short-commit \ --ak thinking_levelhigh参数逐项说明参数含义-p任务目录的绝对路径Harbor 任务包含 instruction、task.toml、verifier 等-a已安装型 agent 的入口固定为harness_harbor.agent:UnrealAgent-m模型名格式为provider/model如openai/gpt-5.4--akagent kwargsagent keyword argumentsbundle指向本地 bundle 目录thinking_level设定推理强度--ae环境变量覆盖environment overrides例如注入 API keythinking_level 的取值范围thinking_level是适配器暴露的核心控制参数合法取值与默认值如下low | medium | high (默认) | xhigh | max该参数在 agent.py 的UnrealAgent.__init__中做了白名单校验——传入不支持的取值会直接抛出ValueError(Unsupported thinking_level)并且在安装前就失败见 test_bundle.py 的test_invalid_model_and_reasoning_fail_before_installation。它随后被写入传给 runner 的request.json的thinking_level字段由 runner 透传给 LLM 服务端。模型名与前缀约束-m参数只能使用三个前缀之一openai/、openrouter/、fireworks_ai/。UnrealAgent构造时会用self.model_name.partition(/)拆分 provider 与模型名并对以下情形直接拒绝同样在安装前失败无/分隔符或模型名为空如test、openai/provider 不属于三个允许值如anthropic/test。同时支持嵌套的模型路径例如openai/organization/model测试test_provider_keys_and_nested_model_paths覆盖了这一点。各家 provider 的密钥配置前缀所需环境变量/密钥来源openai/modelOPENAI_API_KEYopenrouter/modelOPENROUTER_API_KEYfireworks_ai/modelFIREWORKS_AI_API_KEY运行时若对应 provider 的 key 缺失UnrealAgent.run会抛出ValueError(fNo API key configured for {self._provider})。在 Harbor 的命令行里可以用--ae传递环境覆盖例如 smoke 测试里就是这样注入OPENAI_API_KEY与OPENAI_BASE_URL的也可以像上面那样先export到 shell 环境。适配器内部是如何驱动 runner 的理解了命令行之后看 agent.py 中run()的实现能更清楚整条调用链组装 JSON 请求写入环境的agent/request.json{ prompt: 任务指令, model: 模型名, thinking_level: low|medium|high|xhigh|max, session_id: 每次评测随机生成的 UUID, disallowed_tools: [SkillUse] }设置 runner 所需环境变量UNREAL_HARNESS_LLM_PROVIDERfireworks_ai会映射为fireworks其余原样传递UNREAL_HARNESS_LLM_API_KEY来自 Harbor 的 model connectionUNREAL_HARNESS_LLM_BASE_URL仅在配置了自定义 base URL 时注入。在评测容器内以 agent 身份执行export SHELL$(command -v bash) runner -workspace . \ -session-directory logs/sessions \ -log-directory logs/logs \ logs/request.json \ logs/runner.jsonl \ 2 logs/runner.stderr也就是说任务指令经 stdin 送入 runnerrunner 在容器工作目录内自主执行所有会话事件以 JSONL 写到runner.jsonl。session_id贯穿整个过程用于把多次评测/多轮推理关联到同一会话。安装阶段的可靠性处理install()阶段不只上传二进制适配器还会上传 CA 证书certifi.where()到容器内的ca.pem供缺少系统证书链的基础镜像使用以根用户chmod 755runner 并执行runner -h冒烟验证二进制可用使用 NamedTemporaryFile 先把 bundle 二进制整体读入内存再上传杜绝上传过程中本地文件被替换导致二进制混装。此外由于 Terminal-Bench 的 verifier 需要curl来启动测试运行器而 Harbor 对每个 installed agent 都会先安装 curl适配器在ensure_curl()中做了两层兜底见 test_install.py常规安装失败后会执行APT_ARCHIVE_FALLBACK把已失效的deb.debian.org与 security 源改写为archive.debian.org并apt-get update再重试安装避免因为 apt 镜像迁移导致整个 trial 直接得零分。OpenRouter 的自动提示缓存策略使用openrouter/model时适配器有两条值得注意的工程决策主动开启 OpenRouter 的自动 prompt caching请求以一小时 TTL 的缓存窗口运行携带 session id整个会话保持在同一上游、同一会话标识上。这样做的效果是对 Anthropic 等使用显式断点explicit breakpoint的上游服务随着对话增长可以持续命中缓存并且在长时间工具调用和推理轮次之间保持缓存不失效显著降低重复上下文的 token 消耗。这一策略写在 README 中也与run()中session_id与thinking_level一并写入请求的设计相互印证。在 Modal 上运行 Terminal-Bench 4.0对于 Terminal-Bench 4.0 这类云端任务README 提供了完整的 Modal 运行示例。先配置 Modal 凭证然后执行uv run --project benchmarks/harbor --locked --extra modal harbor run \ -d terminal-bench/terminal-bench4.0.0 \ -e modal -a harness_harbor.agent:UnrealAgent \ -m openai/gpt-6-astra \ --ak bundle$PWD/bin/harbor/short-commit --ak thinking_levelmax \ -k 5 -n 40 --job-name tb4-unreal-agent参数差异点参数含义--extra modal安装harbor[modal]可选依赖-d数据集标识这里是terminal-bench/terminal-bench4.0.0-e modal执行环境切换为 Modal 而非 Docker-k 5每个 trial 的最大轮数/重试限制Harbor 的并发或约束参数按 Harbor 文档语义使用-n 40任务并发数40 个 trial 并行--job-name tb4-unreal-agent本次评测任务的命名结果检查统一使用 Harbor 的查看命令harbor view jobs/tb4-unreal-agent输出工具、图像限制与 ATIF 轨迹暴露的工具集评测会话中runner 默认只暴露两个工具对应 run.go 中的names : []string{tool.BashName, tool.ViewImageName}Bash在容器工作目录执行 shell 命令ViewImage查看工作目录中的图片文件。注意disallowed_tools: [SkillUse]会禁用技能工具因此任务即使声明了 MCP server 或 skills 目录适配器也不会去启用它们而是把它们记录进轨迹元数据task_mcp_servers、task_skills_dir避免 trial 直接失败——这正是 agent.py 中_not_offered字典的用途test_bundle.py 的TaskCapabilityTests验证了这一行为。ViewImage 的硬性限制ViewImage 返回图片前会做缩放与编码约束默认限制定义在 viewimage.goDefaultMaxSize 5_000_000 - 1_000 // 4,999,000 字节不含 data URL 前缀 DefaultMaxWidth 2000 DefaultMaxHeight 2000即返回的图片不超过 2000×2000 像素base64 内容不超过 5 MB 减去 1 KB4,999,000 字节。底层实现位于 image.go解码支持 PNG/JPEG/GIF/BMP/TIFF/WebP 等常见格式通过image/gif、image/jpeg、image/png与golang.org/x/image/bmp、tiff、webp注册解码器按MaxWidth/MaxHeight计算ScaleRatio min(1, MaxWidth/w, MaxHeight/h)等比缩放后再按 JPEG 或 PNG 编码MaxSourcePixels默认 32,000,000限制解码工作量防止超大图片导致的内存/CPU 问题若缩放后仍超出MaxSize会明确报告exceeded by N bytes (P%)。轨迹输出与 ATIF 观测评测结束后日志与会话文件统一存放在agent/目录下agent/ ├── request.json # 写入的请求体 ├── runner.jsonl # runner 的 JSONL 会话记录 ├── runner.stderr # runner 的标准错误 ├── trajectory.json # 转换后的 ATIF 轨迹核心产出 ├── images/ # ViewImage 返回的图像按内容 sha256 命名 └── sessions/ # runner 持久化的会话文件*.session.jsonl其中agent/trajectory.json由 trajectory.py 的convert()从runner.jsonl转换而来schema 版本为ATIF-v1.7。转换规则值得关注runner 记录必须携带严格递增的Sequence序号乱序会被拒绝model_response记录解析Outputmessage / reasoning / tool_call 三种类型、UsageInputTokens、OutputTokens、CachedInputTokens、ReasoningTokens、CacheWriteInputTokens并累加进最终指标tool_call_status记录按CallID归并到发起该调用的 agent step形成按工具调用分组Observations 挂到发起调用的 step 下的结构工具仍在运行时观察内容为固定文本 Tool call is still running...即源码中的RUNNING常量直到后续记录送达最终结果。异步时序保留是轨迹设计上的亮点每条 observation 的extra同时包含sequence、timestamp与available_before_turn字段——available_before_turn记录该结果在哪个 turn 之前对模型可见从而忠实还原长时运行的 Bash/ViewImage 在 agent 继续干别的事情之后才返回的并发时序。轨迹的 notes 中对此有明确说明test_trajectory.py 的test_internal_control_and_delayed_observations与 test_view_image.py 的test_multimodal_observations_preserve_async_availability分别验证了 Bash 与图像观察的异步可用性。trajectory.json还汇总了 token 总量total_prompt_tokens、total_completion_tokens、total_cached_tokens以及额外的reasoning_tokens与cache_write_tokens。final_metrics会被回填到 Harbor 的context.n_input_tokens/n_cache_tokens/n_output_tokens由于 runner 记录的是 token 而非账单金额cost_usd一律为None。若会话日志在下载前丢失如沙箱连接中断适配器不会让整个 job 中止而是在context.metadata中标记agent_logs_missing: True见 test_bundle.py 的test_missing_runner_log_is_recorded_not_raised。图像观察的坐标还原元数据ViewImage 结果写入轨迹时图片文件以内容 sha256 命名images/sha256.jpg|.png落盘轨迹中以相对路径引用当原始格式与编码格式不同如 BMP/TIFF 转成 PNG/JPEG或发生了缩放ScaleRatio 1时附加文本说明例如original MIME type: image/bmp; original dimensions: 4000x2; multiply coordinates by 2.00 to approximate original这为 Agent 后续引用图像坐标如点击、框选提供了从缩放后坐标反推原始坐标的换算提示逻辑在 viewimage.go 的imageMetadata()与轨迹转换的view_image_result()中保持一致并由 test_view_image.py 的多种比例用例覆盖。验证lint、单元测试与 smoke 测试静态检查与单元测试make -C benchmarks/harbor test checkcheck用ruff check .与ruff format --check .做 lint 与格式校验test以python -m unittest discover -s tests -v跑全部单元测试覆盖 bundle 校验、安装流程、轨迹转换含各种 Bash 状态与图像结果、ViewImage 元数据等。Docker smoke 测试make -C benchmarks/harbor smoke BUNDLE../../bin/harbor/short-commitsmoke.pybenchmarks/harbor/tests/smoke.py在临时目录中启动一次真实的 Harbor Docker trial任务为 tests/task指令只有一句Write done to /app/answer, inspect the command output, and view /app/image.bmp见 instruction.mdtask 定义见 task.toml模型使用openai/smoke并通过--ae注入测试 key 与本地模拟服务OPENAI_BASE_URLhttp://127.0.0.1:8765/v1运行环境是 Docker-n 1 -k 1只跑单 trial。smoke 测试的断言非常严格它一次性验证了整条链路这也解释了为什么 smoke 依赖 Docker 和本地测试模型verifier 回报reward 1任务真实完成所有对模型的请求都是流式stream: true工具集恰好是{Bash, ViewImage}模型实际收到的工具结果与轨迹导出的观测完全一致文本与图像逐一比对含图像 data URL 的 base64 内容轨迹中只有一条 user 消息token 指标与模拟模型的固定用量10/4/3精确吻合cost_usd为 Nonetrajectory.json中 agent 的binary_sha256与 manifest 的sha256一致证明轨迹记录的正是被评测的二进制收集到的*.session.jsonl会话文件中不包含 API key防止密钥泄漏进持久化会话。若 trial 抛异常smoke 会读取agent/runner.stderr输出详细失败原因。通过后打印Harbor Docker smoke passed: reward, text/image observations, usage and provenance.常见排查路径小结bundle 目录已存在build.py拒绝覆盖换一个BUNDLE输出目录或先删除旧目录thinking_level 或模型前缀报错检查取值是否在low/medium/high/xhigh/max、模型是否为openai/、openrouter/、fireworks_ai/前缀这些校验在安装前即失败容器里没有 curl / apt 源失效ensure_curl会自动回退到archive.debian.org重试轨迹缺失检查agent/trajectory.json是否存在若只有agent_logs_missing: True说明日志在沙箱断连前未下载可用harbor view结合runner.jsonl/runner.stderr人工复原图像观察异常确认图片未超过 2000×2000 与 4,999,000 字节 base64 上限超限时 ViewImage 会返回包含超限字节数与百分比的具体错误文本。总体而言这套适配器把构建可复现 runner → 安装进评测容器 → 驱动模型完成任务 → 导出带异步时序的 ATIF 轨迹串成了一条完整、可审计的评测流水线bundle 的 sha256 校验保证被测对象不变session_id 贯通保证会话可追踪available_before_turn与 token 明细保证轨迹可复现、可分析。无论你是要复现一次 Harbor 评测、跑 Terminal-Bench 云端任务还是要基于轨迹数据做后续分析都可以从本文的构建与运行命令直接入手。赞分享【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载相关推荐Harbor ATIF轨迹格式深度解析统一Agent行为日志助力SFT与RL训练Harbor ATIF轨迹格式深度解析统一Agent行为日志助力SFT与RL训练 Harbor ATIF轨迹格式Agent Trajectory IntePhoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪Phoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪 Harbor 负责在沙箱环境中运行 A可观测性AI 评测LLMOpsAI 应用人工智能ADK 评估数据集实战指南为 rag-agent-search 构建与运行 Agent 评测ADK 评估数据集实战指南为 rag agent search 构建与运行 Agent 评测 导读 本指南以 adk samples 仓库中 core/rag示例工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 unreal-agent 的 Harbor 0.22.0 评测适配器：构建、运行与 ATIF 轨迹输出实战指南
【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载Harbor 是一套面向终端任务的 agent 评测框架而benchmarks/harbor目录中的适配器evaluation adapter把本仓库的unreal-agent-runner包装为 Harbor 的unreal-agent已安装型 agentinstalled agent使其能够直接参与 Harbor 0.22.0 的基准评测。本文以 benchmarks/harbor/README.md 为主体结合仓库源码与测试完整讲解如何同步依赖、构建可复现的 runner 发布包bundle、用harbor run发起本地 Docker 或 Modal 云端评测、理解支持的工具与 ViewImage 图像限制以及如何解读输出的 ATIF 轨迹与 token 指标并最终通过单元测试与 smoke 测试验证整个链路。读完本文你将掌握在 Harbor 生态中完整落地 unreal-agent 评测的全部可复现操作步骤与底层原理。适配器定位与前置依赖Harbor evaluation adapter 的核心目标是把unreal-agent-runner评测为 Harbor 中的unreal-agent。它不是一个新的 agent 实现而是一个薄薄的桥接层UnrealAgent类继承 Harbor 的BaseInstalledAgent在安装阶段把构建好的 runner 二进制上传进评测容器在运行阶段把任务指令以 JSON 请求的形式喂给 runner并在结束后把 runner 输出的 JSONL 会话日志转换为 Harbor 的 ATIF 轨迹。运行与构建该适配器需要以下前置条件均已在 pyproject.toml 与 README 中声明Go版本由仓库根目录 go.mod 指定用于交叉编译 runner 二进制Python 3.12适配器本身是 Python 包uv依赖管理与虚拟环境工具Docker 或 Modal评测任务的目标执行环境Harbor 0.22.0固定版本依赖harbor0.22.0Modal 执行则安装harbor[modal]0.22.0。初始化与构建生成可校验的 runner 发布包同步依赖从仓库根目录执行make -C benchmarks/harbor sync该命令实际执行uv sync --locked --all-extras见 Makefile以锁定的方式安装全部依赖与可选用依赖含 modal extra。构建 runner bundlemake -C benchmarks/harbor build REVISIONHEADMakefile 中的 build 目标会调用 build.pypython3 build.py --revision $(REVISION) --runner $(RUNNER) --arch $(ARCH) --output $(BUNDLE)构建过程的关键设计如下从 git 归档出干净的源码树build.py先以git rev-parse --verify revision^{commit}把REVISION解析为完整 commit再用git archive commit导出该 commit 的源码快照而非工作区内容确保构建输入完全可复现。交叉编译 runner在归档源码树中对./cmd/unreal-agent-runner执行go build -trimpath -buildvcsfalse并强制GOOSlinux、GOARCHarch默认amd64可选arm64、CGO_ENABLED0产出静态二进制。写入 manifest 清单manifest.json记录revision完整 40 位 commit、runner默认为unreal-agent-runner、sha256二进制校验和、goos/goarch、go_version。输出到固定目录产物落在bin/harbor/short-commit/包含unreal-agent-runner可执行文件与manifest.json。两个值得注意的行为已有 bundle 不会被覆盖若BUNDLE目录已存在build.py会直接抛出FileExistsError(Refusing to replace runner bundle: ...)。因此当需要为同一 commit 重新构建时应显式指定一个新的输出目录make -C benchmarks/harbor build REVISIONHEAD BUNDLE../../bin/harbor/short-commit-v2。默认目标平台是 Linux amd64对应 Harbor 评测容器的常见架构如需 arm64用ARCHarm64覆盖。manifest 同时记录了所选 runner 与 revision保证了哪个版本的 runner 参与了哪次评测是可追溯的。为什么安装阶段要校验 bundle适配器在UnrealAgent.__init__中会通过 bundle.py 的Bundle.load()加载并严格校验 bundlerevision必须恰好是 40 位十六进制、sha256必须是 64 位十六进制goos必须是linuxgoarch只能是amd64或arm64每次read_binary()都会用 manifest 中的 sha256 校验二进制内容校验和不一致直接抛ValueError。对应的 test_bundle.py 用test_changed_binary_is_rejected_after_construction验证了构建后再替换二进制文件会被拒绝这一安全属性。这样评测中任何对本地文件的篡改都不可能混入与 manifest 不符的二进制。发起一次 Harbor 评测本地 Docker 评测构建完成后使用绝对路径的 bundle 路径发起评测export OPENAI_API_KEY... uv run --project benchmarks/harbor --locked harbor run \ -p /absolute/path/to/task \ -a harness_harbor.agent:UnrealAgent \ -m openai/gpt-5.4 \ --ak bundle$PWD/bin/harbor/short-commit \ --ak thinking_levelhigh参数逐项说明参数含义-p任务目录的绝对路径Harbor 任务包含 instruction、task.toml、verifier 等-a已安装型 agent 的入口固定为harness_harbor.agent:UnrealAgent-m模型名格式为provider/model如openai/gpt-5.4--akagent kwargsagent keyword argumentsbundle指向本地 bundle 目录thinking_level设定推理强度--ae环境变量覆盖environment overrides例如注入 API keythinking_level 的取值范围thinking_level是适配器暴露的核心控制参数合法取值与默认值如下low | medium | high (默认) | xhigh | max该参数在 agent.py 的UnrealAgent.__init__中做了白名单校验——传入不支持的取值会直接抛出ValueError(Unsupported thinking_level)并且在安装前就失败见 test_bundle.py 的test_invalid_model_and_reasoning_fail_before_installation。它随后被写入传给 runner 的request.json的thinking_level字段由 runner 透传给 LLM 服务端。模型名与前缀约束-m参数只能使用三个前缀之一openai/、openrouter/、fireworks_ai/。UnrealAgent构造时会用self.model_name.partition(/)拆分 provider 与模型名并对以下情形直接拒绝同样在安装前失败无/分隔符或模型名为空如test、openai/provider 不属于三个允许值如anthropic/test。同时支持嵌套的模型路径例如openai/organization/model测试test_provider_keys_and_nested_model_paths覆盖了这一点。各家 provider 的密钥配置前缀所需环境变量/密钥来源openai/modelOPENAI_API_KEYopenrouter/modelOPENROUTER_API_KEYfireworks_ai/modelFIREWORKS_AI_API_KEY运行时若对应 provider 的 key 缺失UnrealAgent.run会抛出ValueError(fNo API key configured for {self._provider})。在 Harbor 的命令行里可以用--ae传递环境覆盖例如 smoke 测试里就是这样注入OPENAI_API_KEY与OPENAI_BASE_URL的也可以像上面那样先export到 shell 环境。适配器内部是如何驱动 runner 的理解了命令行之后看 agent.py 中run()的实现能更清楚整条调用链组装 JSON 请求写入环境的agent/request.json{ prompt: 任务指令, model: 模型名, thinking_level: low|medium|high|xhigh|max, session_id: 每次评测随机生成的 UUID, disallowed_tools: [SkillUse] }设置 runner 所需环境变量UNREAL_HARNESS_LLM_PROVIDERfireworks_ai会映射为fireworks其余原样传递UNREAL_HARNESS_LLM_API_KEY来自 Harbor 的 model connectionUNREAL_HARNESS_LLM_BASE_URL仅在配置了自定义 base URL 时注入。在评测容器内以 agent 身份执行export SHELL$(command -v bash) runner -workspace . \ -session-directory logs/sessions \ -log-directory logs/logs \ logs/request.json \ logs/runner.jsonl \ 2 logs/runner.stderr也就是说任务指令经 stdin 送入 runnerrunner 在容器工作目录内自主执行所有会话事件以 JSONL 写到runner.jsonl。session_id贯穿整个过程用于把多次评测/多轮推理关联到同一会话。安装阶段的可靠性处理install()阶段不只上传二进制适配器还会上传 CA 证书certifi.where()到容器内的ca.pem供缺少系统证书链的基础镜像使用以根用户chmod 755runner 并执行runner -h冒烟验证二进制可用使用 NamedTemporaryFile 先把 bundle 二进制整体读入内存再上传杜绝上传过程中本地文件被替换导致二进制混装。此外由于 Terminal-Bench 的 verifier 需要curl来启动测试运行器而 Harbor 对每个 installed agent 都会先安装 curl适配器在ensure_curl()中做了两层兜底见 test_install.py常规安装失败后会执行APT_ARCHIVE_FALLBACK把已失效的deb.debian.org与 security 源改写为archive.debian.org并apt-get update再重试安装避免因为 apt 镜像迁移导致整个 trial 直接得零分。OpenRouter 的自动提示缓存策略使用openrouter/model时适配器有两条值得注意的工程决策主动开启 OpenRouter 的自动 prompt caching请求以一小时 TTL 的缓存窗口运行携带 session id整个会话保持在同一上游、同一会话标识上。这样做的效果是对 Anthropic 等使用显式断点explicit breakpoint的上游服务随着对话增长可以持续命中缓存并且在长时间工具调用和推理轮次之间保持缓存不失效显著降低重复上下文的 token 消耗。这一策略写在 README 中也与run()中session_id与thinking_level一并写入请求的设计相互印证。在 Modal 上运行 Terminal-Bench 4.0对于 Terminal-Bench 4.0 这类云端任务README 提供了完整的 Modal 运行示例。先配置 Modal 凭证然后执行uv run --project benchmarks/harbor --locked --extra modal harbor run \ -d terminal-bench/terminal-bench4.0.0 \ -e modal -a harness_harbor.agent:UnrealAgent \ -m openai/gpt-6-astra \ --ak bundle$PWD/bin/harbor/short-commit --ak thinking_levelmax \ -k 5 -n 40 --job-name tb4-unreal-agent参数差异点参数含义--extra modal安装harbor[modal]可选依赖-d数据集标识这里是terminal-bench/terminal-bench4.0.0-e modal执行环境切换为 Modal 而非 Docker-k 5每个 trial 的最大轮数/重试限制Harbor 的并发或约束参数按 Harbor 文档语义使用-n 40任务并发数40 个 trial 并行--job-name tb4-unreal-agent本次评测任务的命名结果检查统一使用 Harbor 的查看命令harbor view jobs/tb4-unreal-agent输出工具、图像限制与 ATIF 轨迹暴露的工具集评测会话中runner 默认只暴露两个工具对应 run.go 中的names : []string{tool.BashName, tool.ViewImageName}Bash在容器工作目录执行 shell 命令ViewImage查看工作目录中的图片文件。注意disallowed_tools: [SkillUse]会禁用技能工具因此任务即使声明了 MCP server 或 skills 目录适配器也不会去启用它们而是把它们记录进轨迹元数据task_mcp_servers、task_skills_dir避免 trial 直接失败——这正是 agent.py 中_not_offered字典的用途test_bundle.py 的TaskCapabilityTests验证了这一行为。ViewImage 的硬性限制ViewImage 返回图片前会做缩放与编码约束默认限制定义在 viewimage.goDefaultMaxSize 5_000_000 - 1_000 // 4,999,000 字节不含 data URL 前缀 DefaultMaxWidth 2000 DefaultMaxHeight 2000即返回的图片不超过 2000×2000 像素base64 内容不超过 5 MB 减去 1 KB4,999,000 字节。底层实现位于 image.go解码支持 PNG/JPEG/GIF/BMP/TIFF/WebP 等常见格式通过image/gif、image/jpeg、image/png与golang.org/x/image/bmp、tiff、webp注册解码器按MaxWidth/MaxHeight计算ScaleRatio min(1, MaxWidth/w, MaxHeight/h)等比缩放后再按 JPEG 或 PNG 编码MaxSourcePixels默认 32,000,000限制解码工作量防止超大图片导致的内存/CPU 问题若缩放后仍超出MaxSize会明确报告exceeded by N bytes (P%)。轨迹输出与 ATIF 观测评测结束后日志与会话文件统一存放在agent/目录下agent/ ├── request.json # 写入的请求体 ├── runner.jsonl # runner 的 JSONL 会话记录 ├── runner.stderr # runner 的标准错误 ├── trajectory.json # 转换后的 ATIF 轨迹核心产出 ├── images/ # ViewImage 返回的图像按内容 sha256 命名 └── sessions/ # runner 持久化的会话文件*.session.jsonl其中agent/trajectory.json由 trajectory.py 的convert()从runner.jsonl转换而来schema 版本为ATIF-v1.7。转换规则值得关注runner 记录必须携带严格递增的Sequence序号乱序会被拒绝model_response记录解析Outputmessage / reasoning / tool_call 三种类型、UsageInputTokens、OutputTokens、CachedInputTokens、ReasoningTokens、CacheWriteInputTokens并累加进最终指标tool_call_status记录按CallID归并到发起该调用的 agent step形成按工具调用分组Observations 挂到发起调用的 step 下的结构工具仍在运行时观察内容为固定文本 Tool call is still running...即源码中的RUNNING常量直到后续记录送达最终结果。异步时序保留是轨迹设计上的亮点每条 observation 的extra同时包含sequence、timestamp与available_before_turn字段——available_before_turn记录该结果在哪个 turn 之前对模型可见从而忠实还原长时运行的 Bash/ViewImage 在 agent 继续干别的事情之后才返回的并发时序。轨迹的 notes 中对此有明确说明test_trajectory.py 的test_internal_control_and_delayed_observations与 test_view_image.py 的test_multimodal_observations_preserve_async_availability分别验证了 Bash 与图像观察的异步可用性。trajectory.json还汇总了 token 总量total_prompt_tokens、total_completion_tokens、total_cached_tokens以及额外的reasoning_tokens与cache_write_tokens。final_metrics会被回填到 Harbor 的context.n_input_tokens/n_cache_tokens/n_output_tokens由于 runner 记录的是 token 而非账单金额cost_usd一律为None。若会话日志在下载前丢失如沙箱连接中断适配器不会让整个 job 中止而是在context.metadata中标记agent_logs_missing: True见 test_bundle.py 的test_missing_runner_log_is_recorded_not_raised。图像观察的坐标还原元数据ViewImage 结果写入轨迹时图片文件以内容 sha256 命名images/sha256.jpg|.png落盘轨迹中以相对路径引用当原始格式与编码格式不同如 BMP/TIFF 转成 PNG/JPEG或发生了缩放ScaleRatio 1时附加文本说明例如original MIME type: image/bmp; original dimensions: 4000x2; multiply coordinates by 2.00 to approximate original这为 Agent 后续引用图像坐标如点击、框选提供了从缩放后坐标反推原始坐标的换算提示逻辑在 viewimage.go 的imageMetadata()与轨迹转换的view_image_result()中保持一致并由 test_view_image.py 的多种比例用例覆盖。验证lint、单元测试与 smoke 测试静态检查与单元测试make -C benchmarks/harbor test checkcheck用ruff check .与ruff format --check .做 lint 与格式校验test以python -m unittest discover -s tests -v跑全部单元测试覆盖 bundle 校验、安装流程、轨迹转换含各种 Bash 状态与图像结果、ViewImage 元数据等。Docker smoke 测试make -C benchmarks/harbor smoke BUNDLE../../bin/harbor/short-commitsmoke.pybenchmarks/harbor/tests/smoke.py在临时目录中启动一次真实的 Harbor Docker trial任务为 tests/task指令只有一句Write done to /app/answer, inspect the command output, and view /app/image.bmp见 instruction.mdtask 定义见 task.toml模型使用openai/smoke并通过--ae注入测试 key 与本地模拟服务OPENAI_BASE_URLhttp://127.0.0.1:8765/v1运行环境是 Docker-n 1 -k 1只跑单 trial。smoke 测试的断言非常严格它一次性验证了整条链路这也解释了为什么 smoke 依赖 Docker 和本地测试模型verifier 回报reward 1任务真实完成所有对模型的请求都是流式stream: true工具集恰好是{Bash, ViewImage}模型实际收到的工具结果与轨迹导出的观测完全一致文本与图像逐一比对含图像 data URL 的 base64 内容轨迹中只有一条 user 消息token 指标与模拟模型的固定用量10/4/3精确吻合cost_usd为 Nonetrajectory.json中 agent 的binary_sha256与 manifest 的sha256一致证明轨迹记录的正是被评测的二进制收集到的*.session.jsonl会话文件中不包含 API key防止密钥泄漏进持久化会话。若 trial 抛异常smoke 会读取agent/runner.stderr输出详细失败原因。通过后打印Harbor Docker smoke passed: reward, text/image observations, usage and provenance.常见排查路径小结bundle 目录已存在build.py拒绝覆盖换一个BUNDLE输出目录或先删除旧目录thinking_level 或模型前缀报错检查取值是否在low/medium/high/xhigh/max、模型是否为openai/、openrouter/、fireworks_ai/前缀这些校验在安装前即失败容器里没有 curl / apt 源失效ensure_curl会自动回退到archive.debian.org重试轨迹缺失检查agent/trajectory.json是否存在若只有agent_logs_missing: True说明日志在沙箱断连前未下载可用harbor view结合runner.jsonl/runner.stderr人工复原图像观察异常确认图片未超过 2000×2000 与 4,999,000 字节 base64 上限超限时 ViewImage 会返回包含超限字节数与百分比的具体错误文本。总体而言这套适配器把构建可复现 runner → 安装进评测容器 → 驱动模型完成任务 → 导出带异步时序的 ATIF 轨迹串成了一条完整、可审计的评测流水线bundle 的 sha256 校验保证被测对象不变session_id 贯通保证会话可追踪available_before_turn与 token 明细保证轨迹可复现、可分析。无论你是要复现一次 Harbor 评测、跑 Terminal-Bench 云端任务还是要基于轨迹数据做后续分析都可以从本文的构建与运行命令直接入手。赞分享【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载相关推荐Harbor ATIF轨迹格式深度解析统一Agent行为日志助力SFT与RL训练Harbor ATIF轨迹格式深度解析统一Agent行为日志助力SFT与RL训练 Harbor ATIF轨迹格式Agent Trajectory IntePhoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪Phoenix Harbor 插件实战指南将 Harbor Agent 评估沉淀为版本化数据集、实验与 ATIF 追踪 Harbor 负责在沙箱环境中运行 A可观测性AI 评测LLMOpsAI 应用人工智能ADK 评估数据集实战指南为 rag-agent-search 构建与运行 Agent 评测ADK 评估数据集实战指南为 rag agent search 构建与运行 Agent 评测 导读 本指南以 adk samples 仓库中 core/rag示例工程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考