DeepAgents Mini Harness

一个基于 DeepAgents 的最小版 Agent Harness 实现。

概述

Agent 评测不能只看最终答案，还要看执行过程。Harness 将评测流程标准化为 5 个模块：

Task → Environment → Tools → Trace → Grader

本项目将这 5 个模块落地为可运行的 Python 代码，接入了 DeepSeek 真实模型，输出标准化的 Eval Report。

快速开始

1. 安装

uv sync

2. 配置模型

创建 .env 文件（项目已自带 .gitignore 排除）：

DEEPAGENTS_MODEL=deepseek-v4-flash
DEEPSEEK_API_KEY=sk-你的密钥
DEEPSEEK_API_BASE=https://api.deepseek.com/v1

支持任何 OpenAI 兼容的 API（修改 DEEPAGENTS_MODEL + DEEPSEEK_API_BASE 即可切换）。

3. 运行

uv run python main.py

有 API 密钥 → 自动进入 live 模式，调用真实模型执行任务。 无 API 密钥 → 自动降级 demo 模式，用模拟数据展示全流程。

架构

模块	文件位置	说明
Task	main.py:36-43	SYSTEM_PROMPT 定义任务目标与约束
Environment	main.py:16-19	INITIAL_FILES 注入固定文件环境
Tools	main.py:23-33	显式定义 list_files + read_file，精确控制 Agent 行为
Trace	main.py:108-121	按 tool_call_id 匹配 AIMessage ↔ ToolMessage，提取执行轨迹
Grader	main.py:46-67	同时检查过程（是否读了 README）和结果（答案是否合规）

输出格式

{
  "case_id": "case_001",
  "trace": [
    {
      "tool": "read_file",
      "arguments": { "path": "/README.md" },
      "result": "本项目支持本地启动、基础登录和配置管理。"
    }
  ],
  "answer": "根据文件内容，未能确认插件系统支持。",
  "grade": {
    "success": true,
    "reason": "读取了README.md，且回答包含'不能确认'。"
  }
}

运行示例

[Harness] Mode: live

Agent 调用轨迹：

#	工具	参数
1	list_files	"."
2	read_file	"./README.md"
3	read_file	"./config.md"

最终评分 success: true 时，说明 Agent 正确读取了目标文件且回答符合预期。

依赖

• deepagents — Agent 编排框架
• langchain-openai — OpenAI 兼容 API 客户端
• python-dotenv — 环境变量加载
• langchain-deepseek — DeepSeek 模型支持（可选，按需安装）

参考

• 陈思州，《关于Agent Harness，我整理了一个最小版！》，Datawhale
• DeepAgents 文档