data-harness：无框架依赖的 Python ReAct 代理，数据工作流的受控执行方案

data-harness 是一个轻量级的 Python ReAct 代理 SDK，通过受控的 Python 解释器、句柄状态管理和显式连接器披露，为数据密集型工作流提供可审计、可重现的 AI 执行环境。

问题背景：为什么传统代理框架不适合数据工作流\n\n当前大多数 AI 代理框架的设计理念是"给模型一个 shell，让它自由发挥"。这种模式在探索性任务中表现不错，但在数据密集型工作流中却存在严重问题：\n\n- 不可预测的副作用：模型可以随意执行任意命令，修改系统状态\n- 安全暴露风险：bash 访问意味着潜在的数据泄露和系统破坏\n- 难以重现：同样的输入可能产生不同的执行路径和结果\n- 上下文爆炸：大型数据对象（如 DataFrame）直接塞进对话历史，导致 token 消耗激增\n\ndata-harness 采取了一种截然不同的方法：模型在一个受约束的 Python 解释器中操作，数据存储在会话缓存中并以命名句柄暴露。没有 bash，状态显式管理，日志可以完整重现执行过程。\n\n## 核心理念：受控执行与显式状态\n\ndata-harness 的设计哲学可以概括为：约束带来清晰。通过限制模型的执行环境，强制开发者设计更干净的工具，从而获得更可预测、更安全的 AI 工作流。\n\n### 句柄/快照模式（Handle/Snapshot Pattern）\n\n大型对象（DataFrame、数组、查询结果）存储在 SessionCache 中，而不是消息历史中。模型只能看到一个紧凑的快照——形状、列名、少量样本行。它通过句柄名称编写 Python 代码来访问实际数据。\n\n这种设计的好处：\n\n- 上下文精简：模型不会被海量数据淹没\n- 数据可见：模型仍然知道数据的存在和结构\n- 性能优化：避免在每次对话中重复传输大型对象\n\n### 前缀稳定的系统提示词\n\nsystem prompt 在对话过程中永远不会改变。提醒、状态和提示信息都追加到对话后缀。这是 KV 缓存优化：稳定的前缀意味着提供商可以缓存它，从而减少长对话的延迟和成本。\n\n### 渐进式连接器披露\n\n数据连接器（数据库、API、数据仓库）已注册，但在显式加载前对工具列表隐藏。较短的工具列表意味着模型做出更好的路由决策。只有在相关时，连接器才可见。\n\n### 子代理隔离\n\n派生的子代理获得全新的适配器和缓存。状态通过 input_handles 显式传递。没有隐式共享状态。这使得子代理行为可重现、可调试。\n\n## 架构设计：模块化的组件系统\n\ndata-harness 的架构由多个松耦合的组件组成，每个组件都有明确的职责：\n\n### Provider Adapter（提供商适配器）\n\n适配器是提供商 SDK 和 harness 之间的边界：它将 Anthropic/OpenAI 的响应转换为 data-harness 标准化的 Message、ToolUseBlock 和 token-count 类型。这种显式设计使得 harness 不绑定于特定模型提供商，测试时可以用 FakeAdapter 替换而无需修改业务代码。\n\n### Harness（核心引擎）\n\nHarness 拥有 ReAct 循环、消息管理、工具调度、提醒机制和 JSONL 日志记录。它是整个系统的协调中心，但不关心具体的模型提供商或数据存储细节。\n\n### SessionCache（会话缓存）\n\n大型值以句柄加紧凑快照的形式存储。这种设计让模型能够引用复杂数据结构，而无需在每次交互中重复传输。\n\n### AgentSession（代理会话）\n\n对于聊天机器人或工作台应用，AgentSession 保持 harness 和缓存跨多个后续问题 alive。这是实现持续对话状态的关键组件。\n\n### Python Interpreter（Python 解释器）\n\n受控的执行表面，没有 bash 工具。这是 data-harness 与传统代理框架的根本区别。\n\n## 使用示例：从简单到复杂\n\n### 基础用法\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.anthropic import AnthropicAdapter\n\nadapter = AnthropicAdapter(model=\"claude-sonnet-4-6\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nresult = agent.run(\"Compute the mean of [1, 2, 3, 4, 5] and print it.\")\nprint(result)\n\n\n### 会话模式\n\n对于需要上传文件和持续对话的应用：\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.openai import OpenAIAdapter\n\nadapter = OpenAIAdapter(model=\"gpt-4o-mini\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nsession = agent.session()\nsession.put(\"uploaded_data\", df)\n\nprint(session.ask(\"What columns are in the uploaded data?\"))\nprint(session.ask(\"Which numeric column has the highest average?\"))\n\n\n### 连接器模式\n\n连接器工具在加载前对模型隐藏，保持工具列表简洁：\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.anthropic import AnthropicAdapter\n\nadapter = AnthropicAdapter(model=\"claude-sonnet-4-6\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nmarket_data = agent.connector(\n \"market_data\",\n description=\"Market data tools.\",\n)\n\ndef fetch_ohlcv(symbol: str) -> list[dict]:\n return [{\"symbol\": symbol, \"close\": 101.2}]\n\nmarket_data.tool(\n fetch_ohlcv,\n description=\"Fetch OHLCV data for a ticker.\",\n)\n\nresult = agent.run(\"Load market_data and inspect AAPL.\")\nprint(result)\n\n\n## 工程不变式：设计背后的思考\n\ndata-harness 的每个设计决策都是有意为之的。理解这些不变式是使用该框架的关键：\n\n### 无 Bash 原则\n\n给予代理 shell 访问是最省力的路径，但在生产中会产生真正的问题。data-harness 故意将模型限制在 Python 中——对于大多数数据工作负载来说这已经足够，并且强制更干净的工具设计。\n\n### KV 缓存优化\n\n前缀稳定的系统提示词允许提供商缓存 KV，减少长对话的延迟和成本。提醒和状态更新只追加到后缀，从不插入前缀。\n\n### 可重现性优先\n\n每个回合都从一开始就记录到 .jsonl 文件。不是事后追加，而是原生支持。每行是一个完整的回合记录，包括延迟、token 计数、缓存命中/未命中。可重现性是一等公民。\n\n### 显式优于隐式\n\n状态转移、工具可用性、数据访问——一切都通过显式 API 调用完成。没有魔法，没有隐式共享，没有全局状态。\n\n## 适用场景：什么时候选择 data-harness\n\ndata-harness 特别适合以下场景：\n\n### 数据管道和 ETL 工作流\n当需要在 AI 辅助下处理结构化数据、执行数据转换、生成报告时，data-harness 的受控环境和句柄模式让数据操作既强大又安全。\n\n### 金融和监管行业\n这些行业对可审计性和可重现性有严格要求。data-harness 的 JSONL 日志、显式状态管理和无 bash 设计天然满足合规需求。\n\n### 多步骤分析任务\n对于需要多轮推理、中间结果保存、工具链调用的复杂分析任务，data-harness 的会话管理和子代理隔离提供了清晰的执行模型。\n\n### 生产环境部署\n相比实验性的代理框架，data-harness 的设计更关注生产环境的稳定性、安全性和可维护性。\n\n## 与相关项目的对比\n\n| 特性 | data-harness | 传统代理框架 |\n|------|--------------|--------------|\n| 执行环境 | 受控 Python | 完整 shell |\n| 状态管理 | 显式句柄 | 隐式/全局 |\n| 可重现性 | JSONL 日志原生支持 | 通常事后追加 |\n| 上下文优化 | 句柄/快照模式 | 直接嵌入 |\n| 工具发现 | 渐进式披露 | 全部暴露 |\n| 子代理 | 完全隔离 | 通常共享状态 |\n\n## 快速开始\n\n安装要求 Python 3.10+ 和 uv：\n\nbash\n# 克隆仓库\ngit clone https://github.com/maxkskhor/data-harness.git\ncd data-harness\n\n# 安装依赖\nuv sync\n\n# 运行快速开始示例\nuv run python examples/quickstart.py\n\n# 运行高级示例（需要 ANTHROPIC_API_KEY）\nuv run python examples/advanced_wiring.py\n\n# 运行测试\nuv run pytest tests/ -v\n\n\n## 学习资源\n\n作者撰写了一系列深入的设计文章：\n\n1. Designing a ReAct Harness for Data Workflows Without Bash - 框架设计初衷\n2. How a Bash-Free Data Agent Remembers Its Work - 状态管理机制\n3. The Bugs Hidden Inside a Data Agent Harness - 工程实践中的陷阱\n\n未来还将推出 learn-data-harness 仓库，提供更简化的教学指南，剥离异步、生产沙箱和 SDK 复杂特性，专注于核心概念。\n\n## 结语：重新思考 AI 代理的设计\n\ndata-harness 代表了一种对 AI 代理框架的重新思考。它不是追求让 AI "无所不能"，而是在明确的约束下提供"足够好用"且"可控可审计"的能力。\n\n对于数据密集型工作流，这种设计理念尤为重要。数据的价值在于其准确性和可解释性，而失控的 AI 代理可能引入不可预测的错误和偏见。data-harness 通过受控执行、显式状态、完整日志，为数据工作流提供了一个更可靠的基础。\n\n如果你正在构建需要处理敏感数据、需要满足合规要求、或者需要可重现结果的生产级 AI 应用，data-harness 值得认真考虑。

问题背景：为什么传统代理框架不适合数据工作流\n\n当前大多数 AI 代理框架的设计理念是"给模型一个 shell，让它自由发挥"。这种模式在探索性任务中表现不错，但在数据密集型工作流中却存在严重问题：\n\n- 不可预测的副作用：模型可以随意执行任意命令，修改系统状态\n- 安全暴露风险：bash 访问意味着潜在的数据泄露和系统破坏\n- 难以重现：同样的输入可能产生不同的执行路径和结果\n- 上下文爆炸：大型数据对象（如 DataFrame）直接塞进对话历史，导致 token 消耗激增\n\ndata-harness 采取了一种截然不同的方法：模型在一个受约束的 Python 解释器中操作，数据存储在会话缓存中并以命名句柄暴露。没有 bash，状态显式管理，日志可以完整重现执行过程。\n\n核心理念：受控执行与显式状态\n\ndata-harness 的设计哲学可以概括为：约束带来清晰。通过限制模型的执行环境，强制开发者设计更干净的工具，从而获得更可预测、更安全的 AI 工作流。\n\n句柄/快照模式（Handle/Snapshot Pattern）\n\n大型对象（DataFrame、数组、查询结果）存储在 SessionCache 中，而不是消息历史中。模型只能看到一个紧凑的快照——形状、列名、少量样本行。它通过句柄名称编写 Python 代码来访问实际数据。\n\n这种设计的好处：\n\n- 上下文精简：模型不会被海量数据淹没\n- 数据可见：模型仍然知道数据的存在和结构\n- 性能优化：避免在每次对话中重复传输大型对象\n\n前缀稳定的系统提示词\n\nsystem prompt 在对话过程中永远不会改变。提醒、状态和提示信息都追加到对话后缀。这是 KV 缓存优化：稳定的前缀意味着提供商可以缓存它，从而减少长对话的延迟和成本。\n\n渐进式连接器披露\n\n数据连接器（数据库、API、数据仓库）已注册，但在显式加载前对工具列表隐藏。较短的工具列表意味着模型做出更好的路由决策。只有在相关时，连接器才可见。\n\n子代理隔离\n\n派生的子代理获得全新的适配器和缓存。状态通过 input_handles 显式传递。没有隐式共享状态。这使得子代理行为可重现、可调试。\n\n架构设计：模块化的组件系统\n\ndata-harness 的架构由多个松耦合的组件组成，每个组件都有明确的职责：\n\nProvider Adapter（提供商适配器）\n\n适配器是提供商 SDK 和 harness 之间的边界：它将 Anthropic/OpenAI 的响应转换为 data-harness 标准化的 Message、ToolUseBlock 和 token-count 类型。这种显式设计使得 harness 不绑定于特定模型提供商，测试时可以用 FakeAdapter 替换而无需修改业务代码。\n\nHarness（核心引擎）\n\nHarness 拥有 ReAct 循环、消息管理、工具调度、提醒机制和 JSONL 日志记录。它是整个系统的协调中心，但不关心具体的模型提供商或数据存储细节。\n\nSessionCache（会话缓存）\n\n大型值以句柄加紧凑快照的形式存储。这种设计让模型能够引用复杂数据结构，而无需在每次交互中重复传输。\n\nAgentSession（代理会话）\n\n对于聊天机器人或工作台应用，AgentSession 保持 harness 和缓存跨多个后续问题 alive。这是实现持续对话状态的关键组件。\n\nPython Interpreter（Python 解释器）\n\n受控的执行表面，没有 bash 工具。这是 data-harness 与传统代理框架的根本区别。\n\n使用示例：从简单到复杂\n\n基础用法\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.anthropic import AnthropicAdapter\n\nadapter = AnthropicAdapter(model=\"claude-sonnet-4-6\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nresult = agent.run(\"Compute the mean of [1, 2, 3, 4, 5] and print it.\")\nprint(result)\n\n\n会话模式\n\n对于需要上传文件和持续对话的应用：\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.openai import OpenAIAdapter\n\nadapter = OpenAIAdapter(model=\"gpt-4o-mini\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nsession = agent.session()\nsession.put(\"uploaded_data\", df)\n\nprint(session.ask(\"What columns are in the uploaded data?\"))\nprint(session.ask(\"Which numeric column has the highest average?\"))\n\n\n连接器模式\n\n连接器工具在加载前对模型隐藏，保持工具列表简洁：\n\npython\nfrom data_harness import Agent\nfrom data_harness.providers.anthropic import AnthropicAdapter\n\nadapter = AnthropicAdapter(model=\"claude-sonnet-4-6\")\nagent = Agent(adapter=adapter, system=\"You are a data analyst.\")\n\nmarket_data = agent.connector(\n \"market_data\",\n description=\"Market data tools.\",\n)\n\ndef fetch_ohlcv(symbol: str) -> list[dict]:\n return [{\"symbol\": symbol, \"close\": 101.2}]\n\nmarket_data.tool(\n fetch_ohlcv,\n description=\"Fetch OHLCV data for a ticker.\",\n)\n\nresult = agent.run(\"Load market_data and inspect AAPL.\")\nprint(result)\n\n\n工程不变式：设计背后的思考\n\ndata-harness 的每个设计决策都是有意为之的。理解这些不变式是使用该框架的关键：\n\n无 Bash 原则\n\n给予代理 shell 访问是最省力的路径，但在生产中会产生真正的问题。data-harness 故意将模型限制在 Python 中——对于大多数数据工作负载来说这已经足够，并且强制更干净的工具设计。\n\nKV 缓存优化\n\n前缀稳定的系统提示词允许提供商缓存 KV，减少长对话的延迟和成本。提醒和状态更新只追加到后缀，从不插入前缀。\n\n可重现性优先\n\n每个回合都从一开始就记录到 .jsonl 文件。不是事后追加，而是原生支持。每行是一个完整的回合记录，包括延迟、token 计数、缓存命中/未命中。可重现性是一等公民。\n\n显式优于隐式\n\n状态转移、工具可用性、数据访问——一切都通过显式 API 调用完成。没有魔法，没有隐式共享，没有全局状态。\n\n适用场景：什么时候选择 data-harness\n\ndata-harness 特别适合以下场景：\n\n数据管道和 ETL 工作流\n当需要在 AI 辅助下处理结构化数据、执行数据转换、生成报告时，data-harness 的受控环境和句柄模式让数据操作既强大又安全。\n\n金融和监管行业\n这些行业对可审计性和可重现性有严格要求。data-harness 的 JSONL 日志、显式状态管理和无 bash 设计天然满足合规需求。\n\n多步骤分析任务\n对于需要多轮推理、中间结果保存、工具链调用的复杂分析任务，data-harness 的会话管理和子代理隔离提供了清晰的执行模型。\n\n生产环境部署\n相比实验性的代理框架，data-harness 的设计更关注生产环境的稳定性、安全性和可维护性。\n\n与相关项目的对比\n\n| 特性 | data-harness | 传统代理框架 |\n|------|--------------|--------------|\n| 执行环境 | 受控 Python | 完整 shell |\n| 状态管理 | 显式句柄 | 隐式/全局 |\n| 可重现性 | JSONL 日志原生支持 | 通常事后追加 |\n| 上下文优化 | 句柄/快照模式 | 直接嵌入 |\n| 工具发现 | 渐进式披露 | 全部暴露 |\n| 子代理 | 完全隔离 | 通常共享状态 |\n\n快速开始\n\n安装要求 Python 3.10+ 和 uv：\n\nbash\n克隆仓库\ngit clone https://github.com/maxkskhor/data-harness.git\ncd data-harness\n\n安装依赖\nuv sync\n\n运行快速开始示例\nuv run python examples/quickstart.py\n\n运行高级示例（需要 ANTHROPIC_API_KEY）\nuv run python examples/advanced_wiring.py\n\n运行测试\nuv run pytest tests/ -v\n\n\n学习资源\n\n作者撰写了一系列深入的设计文章：\n\n1. Designing a ReAct Harness for Data Workflows Without Bash - 框架设计初衷\n2. How a Bash-Free Data Agent Remembers Its Work - 状态管理机制\n3. The Bugs Hidden Inside a Data Agent Harness - 工程实践中的陷阱\n\n未来还将推出 learn-data-harness 仓库，提供更简化的教学指南，剥离异步、生产沙箱和 SDK 复杂特性，专注于核心概念。\n\n结语：重新思考 AI 代理的设计\n\ndata-harness 代表了一种对 AI 代理框架的重新思考。它不是追求让 AI "无所不能"，而是在明确的约束下提供"足够好用"且"可控可审计"的能力。\n\n对于数据密集型工作流，这种设计理念尤为重要。数据的价值在于其准确性和可解释性，而失控的 AI 代理可能引入不可预测的错误和偏见。data-harness 通过受控执行、显式状态、完整日志，为数据工作流提供了一个更可靠的基础。\n\n如果你正在构建需要处理敏感数据、需要满足合规要求、或者需要可重现结果的生产级 AI 应用，data-harness 值得认真考虑。