Agent Harness 深度调研：AI Agent 的运行时基础设施

2026-03-27

Agent Harness 深度调研：AI Agent 的运行时基础设施

核心观点：Agent Harness 是 AI Agent 的”操作系统”，它不只是执行代码的容器，更是管理状态、工具、安全和生命周期的完整基础设施。从 LangGraph 到 E2B，从 OpenAgents 到 NanoClaw，每一代 Harness 都在解决同样的核心问题：如何让 AI Agent 可靠、安全、可观测地运行。

什么是 Agent Harness？

定义

Agent Harness 是 AI Agent 的运行时基础设施（Runtime Infrastructure），提供：

执行环境：隔离的沙箱，安全运行 agent 代码
状态管理：持久化、恢复、checkpoint
工具集成：文件系统、API、代码执行、外部服务
编排能力：多 agent 协作、工作流调度
监控调试：可观测性、trace、debug
安全控制：权限管理、资源限制、审计日志

与 Agent Framework 的区别

维度	Agent Framework	Agent Harness
关注点	Agent 逻辑和推理	运行时和基础设施
示例	LangChain, LlamaIndex	LangGraph, E2B, OpenClaw
提供什么	组件、抽象、API	执行、监控、安全
类比	Web 框架（Django/Express）	容器运行时（Docker/K8s）
价值	快速开发	生产级部署

关键洞察：Framework 帮你”写” Agent，Harness 帮你”跑” Agent。

为什么需要 Harness？

问题 1：执行不可靠

# ❌ 没有 harness：失败就全完了
def run_agent():
    result = llm.generate(prompt)  # 可能超时、失败
    execute_tool(result)           # 可能崩溃、死循环
    return output

# ✅ 有 harness：durable execution
@harness.task(checkpoint=True, retry=3)
def run_agent():
    result = llm.generate(prompt)
    execute_tool(result)
    return output
# 自动恢复、重试、checkpoint

问题 2：安全隔离

1 2	# ❌ 没有 harness：直接执行用户代码 exec(user_code) # 危险！

1
2
3

# ✅ 有 harness：沙箱隔离
with Sandbox.create() as sbx:
    sbx.run_code(user_code)  # 安全！

问题 3：可观测性

1 2	# ❌ 没有 harness：黑盒执行 agent.run() # 不知道内部发生了什么

1
2
3

# ✅ 有 harness：全链路追踪
with tracer.start_as_current_span("agent.run"):
    agent.run()  # trace、metrics、logs 全部记录

核心能力矩阵

1. 执行环境（Execution Environment）

沙箱隔离

代表项目：E2B Code Interpreter

import { Sandbox } from '@e2b/code-interpreter'

const sbx = await Sandbox.create()
await sbx.runCode('x = 1')

const execution = await sbx.runCode('x+=1; x')
console.log(execution.text) // outputs 2

核心特性：

隔离性：每个 agent 在独立容器中运行
资源限制：CPU、内存、磁盘、网络限制
快照和恢复：保存和恢复执行状态
文件系统：独立的虚拟文件系统

资源管理

资源类型	限制方式	示例
CPU	cgroups	`cpu_quota: 50%`
内存	cgroups	`memory_limit: 512MB`
磁盘	quota	`disk_limit: 1GB`
网络	iptables	`network: isolated`
时间	timeout	`timeout: 30s`

2. 状态管理（State Management）

Durable Execution

代表项目：LangGraph

from langgraph.graph import StateGraph, MessagesState, START, END

def mock_llm(state: MessagesState):
    return {"messages": [{"role": "ai", "content": "hello world"}]}

graph = StateGraph(MessagesState)
graph.add_node(mock_llm)
graph.add_edge(START, "mock_llm")
graph.add_edge("mock_llm", END)
graph = graph.compile()

# 自动持久化、恢复
graph.invoke({"messages": [{"role": "user", "content": "hi!"}]})

核心机制：

Checkpoint：每个节点执行后自动保存状态
Resume：失败后从最后一个 checkpoint 恢复
Time Travel：回到任意历史状态
State Schema：Pydantic 模型保证类型安全

State Schema 设计

from typing import Annotated
from pydantic import BaseModel

class AgentState(BaseModel):
    # 消息历史（自动追加）
    messages: Annotated[list[AnyMessage], add_messages]
    # 当前任务
    current_task: Optional[str] = None
    # 已完成步骤
    completed_steps: list[str] = []
    # 上下文数据
    context: dict[str, Any] = {}

3. 工具集成（Tool Integration）

Tool Definition

from langchain_core.tools import tool

@tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return web_search(query)

@tool
def read_file(path: str) -> str:
    """Read file contents."""
    with open(path) as f:
        return f.read()

Tool Execution

安全模式：

白名单：只允许预定义的工具
权限检查：执行前检查权限
审计日志：记录所有工具调用
结果过滤：过滤敏感信息

# 安全执行
@harness.tool(requires_approval=True, audit=True)
def delete_file(path: str):
    """Delete a file (requires approval)."""
    os.remove(path)

4. 编排能力（Orchestration）

单 Agent 循环

1	User → Agent → Tool → Agent → Tool → ... → Result

多 Agent 协作

代表项目：SWE-agent

┌─────────────┐
│  Architect  │  ← 规划
└──────┬──────┘
       │
       ↓
┌─────────────┐
│  Developer  │  ← 实现
└──────┬──────┘
       │
       ↓
┌─────────────┐
│   Reviewer  │  ← 审查
└─────────────┘

Workflow 模式：

Sequential：顺序执行（Architect → Developer → Reviewer）
Parallel：并行执行（多个 Worker 同时工作）
Conditional：条件分支（if-else 逻辑）
Loop：循环执行（迭代优化）

Graph-based Workflow

LangGraph 的核心：

from langgraph.graph import StateGraph

workflow = StateGraph(AgentState)
workflow.add_node("research", research_agent)
workflow.add_node("plan", planning_agent)
workflow.add_node("execute", execution_agent)

workflow.add_edge("research", "plan")
workflow.add_edge("plan", "execute")

# 条件分支
workflow.add_conditional_edges(
    "execute",
    should_continue,
    {
        "continue": "research",  # 需要更多研究
        "finish": END            # 完成
    }
)

5. 监控调试（Observability）

Tracing

LangSmith 集成：

import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "..."

# 自动追踪所有 agent 执行
agent.run()  # trace、metrics、logs 全部记录到 LangSmith

关键指标：

Latency：每个步骤的耗时
Token Usage：LLM 调用的 token 数
Tool Calls：工具调用次数和成功率
Error Rate：错误率和类型

Debugging

Human-in-the-Loop：

# 在任意点暂停，等待人工干预
@harness.task(interrupt_before=True)
def critical_operation(state):
    # 人工审查 state
    approved = input("Approve? (y/n)")
    if approved == 'y':
        return execute()
    else:
        return abort()

6. 安全控制（Security）

权限模型

权限级别	能力	示例
Read-only	只读文件系统	`read_file`, `search_web`
Sandboxed	沙箱内写操作	`write_file`, `run_code`
Host Access	访问宿主机	`execute_shell`, `install_package`
Network	网络访问	`http_request`, `database_query`

安全策略

# OpenClaw 的安全模型
security:
  default: deny           # 默认拒绝
  allowlist:              # 白名单
    - read_file
    - search_web
  sandboxed:              # 沙箱操作
    - write_file
    - execute_code
  elevated:               # 需要提升权限
    - shell_command
    - install_package

架构模式演进

第一代：简单循环（Simple Loop）

┌─────────┐
│   LLM   │
└────┬────┘
     │
     ↓
┌─────────┐
│  Tools  │
└────┬────┘
     │
     └──→ Loop

特点：

✅ 简单直接
❌ 无状态管理
❌ 无错误恢复
❌ 无监控

代表：早期 LangChain Agent

第二代：编排框架（Orchestration Framework）

┌──────────────┐
│ Orchestrator │
└──────┬───────┘
       │
       ├──→ Agent 1
       ├──→ Agent 2
       └──→ Agent 3

特点：

✅ 多 agent 协作
✅ 工作流编排
⚠️ 状态管理有限
⚠️ 监控不完善

代表：LangChain Multi-Agent, CrewAI

第三代：Durable Execution（持久化执行）

┌───────────────────┐
│  State Manager    │
│  ├─ Checkpoint    │
│  ├─ Resume        │
│  └─ Time Travel   │
└───────────────────┘
         │
         ↓
┌───────────────────┐
│  Execution Graph  │
│  ├─ Node 1 ──┐    │
│  ├─ Node 2 ←─┘    │
│  └─ Node 3        │
└───────────────────┘

特点：

✅ 完整的状态管理
✅ 自动恢复
✅ 可观测性
✅ Human-in-the-loop

代表：LangGraph, Temporal

第四代：云原生 Harness（Cloud-Native）

┌─────────────────────────────────┐
│         Control Plane           │
│  ├─ Scheduler                   │
│  ├─ State Store                 │
│  └─ Monitoring                  │
└─────────────────────────────────┘
         │
         ├──→ Sandbox Pod 1
         ├──→ Sandbox Pod 2
         └──→ Sandbox Pod N

特点：

✅ 水平扩展
✅ 资源隔离
✅ 多租户
✅ 云原生部署

代表：E2B Cloud, Modal, Fly.io

代表项目深度分析

1. LangGraph：Durable Execution 的标杆

核心理念：Graph-based Workflow + Durable Execution

架构

# State Graph
class StateGraph:
    def __init__(self, state_schema):
        self.nodes = {}
        self.edges = {}
        self.state_schema = state_schema
    
    def add_node(self, name, action):
        """添加节点"""
        self.nodes[name] = action
    
    def add_edge(self, from_node, to_node):
        """添加边"""
        self.edges[from_node] = to_node
    
    def compile(self):
        """编译为可执行图"""
        return CompiledGraph(self)

Durable Execution 实现

class Checkpointer:
    """状态检查点"""
    def save(self, thread_id, checkpoint):
        """保存状态"""
        pass
    
    def load(self, thread_id):
        """加载状态"""
        pass
    
    def list(self, thread_id):
        """列出所有历史状态"""
        pass

关键特性

Stateful：每个节点执行后自动保存状态
Resumable：失败后从最后一个 checkpoint 恢复
Debuggable：可视化执行路径
Interruptible：任意点暂停等待人工干预

适用场景

✅ 长时间运行的任务（几分钟到几小时）
✅ 需要人工审核的流程
✅ 复杂的多步骤工作流
❌ 简单的问答（杀鸡用牛刀）

2. E2B：安全沙箱的标杆

核心理念：Secure Sandboxed Execution

架构

┌──────────────────────────┐
│     Host Machine         │
│  ┌────────────────────┐  │
│  │   E2B Runtime      │  │
│  │  ┌──────────────┐  │  │
│  │  │   Sandbox    │  │  │
│  │  │  ├─ FS       │  │  │
│  │  │  ├─ Network  │  │  │
│  │  │  └─ Process  │  │  │
│  │  └──────────────┘  │  │
│  └────────────────────┘  │
└──────────────────────────┘

核心能力

// 创建沙箱
const sbx = await Sandbox.create()

// 执行代码
await sbx.runCode(`
import pandas as pd
df = pd.read_csv('data.csv')
print(df.head())
`)

// 文件操作
await sbx.filesystem.write('/app/data.csv', csvData)
const files = await sbx.filesystem.list('/app')

// 网络访问
const result = await sbx.runCode(`
import requests
response = requests.get('https://api.example.com')
print(response.json())
`)

安全特性

隔离性：Firecracker microVM
资源限制：CPU、内存、磁盘、网络
快照：保存和恢复状态
网络策略：可选的网络隔离

适用场景

✅ 执行用户提供的代码
✅ 数据分析和可视化
✅ 代码解释器（Code Interpreter）
❌ 简单的文件操作（太重）

3. OpenAgents：Plan-First Workflow

核心理念：Plan → Approve → Execute

工作流

1. Agent proposes plan
   ↓
2. User approves/rejects
   ↓
3. Agent executes step-by-step
   ↓
4. Automatic testing
   ↓
5. User review

核心价值

可控性：用户审批每一步
可预测：先看计划再执行
可逆：每步都可以回滚
质量保证：自动测试

适用场景

✅ 代码生成和修改
✅ 需要用户确认的操作
✅ 生产环境变更
❌ 自动化程度高的任务

4. SWE-agent：Multi-Agent Workflow

核心理念：Architect → Developer → Reviewer

架构

class AgentState(BaseModel):
    # Architect 状态
    research_scratchpad: list[AnyMessage] = []
    implementation_plan: Optional[ImplementationPlan] = None
    
    # Developer 状态
    completed_steps: list[str] = []
    current_task: Optional[str] = None
    
    # Reviewer 状态
    review_comments: list[str] = []
    approved: bool = False

工作流

User Request
     ↓
┌─────────────┐
│  Architect  │  ← 研究代码库，生成计划
└──────┬──────┘
       ↓
┌─────────────┐
│  Developer  │  ← 执行计划，修改代码
└──────┬──────┘
       ↓
┌─────────────┐
│  Reviewer   │  ← 审查代码，确保质量
└─────────────┘

关键特性

分离关注点：规划、实现、审查分离
类型安全：Pydantic 模型保证状态一致性
可追溯：每个决策都有记录
原子操作：细粒度的文件修改

5. NanoClaw：Best Harness + Best Model

核心理念：Claude Code SDK + 最佳实践

“Best harness, best model.” - NanoClaw

特点

Claude Agent SDK：直接使用 Claude Code
自我进化：NanoClaw 可以修改和扩展自己
用户定制：为每个用户量身定制

适用场景

✅ 高质量代码生成
✅ 复杂问题解决
✅ 自我改进的 agent
❌ 低成本场景（Claude 很贵）

6. OpenClaw：开源 Harness 平台

核心理念：Personal Assistant with Harness Capabilities

“Better computer-use and agent harness capabilities.” - OpenClaw Vision

架构

┌─────────────────────────┐
│    OpenClaw Gateway     │
│  ├─ LLM Provider        │
│  ├─ Tool Registry       │
│  ├─ Security Layer      │
│  └─ State Manager       │
└─────────────────────────┘
         │
         ├──→ Desktop App
         ├──→ CLI
         └──→ Messaging Channels

关键特性

多通道：Web、CLI、Desktop、Messaging
安全优先：默认拒绝，白名单机制
可扩展：Plugin 和 Skill 系统
开源：完全开源，可自托管

技术选型指南

决策树

需要 Agent Harness？
     │
     ├─ 是 → 任务类型？
     │       │
     │       ├─ 长时间运行 ──→ LangGraph
     │       │
     │       ├─ 执行代码 ──→ E2B
     │       │
     │       ├─ 需要审批 ──→ OpenAgents
     │       │
     │       └─ 多 agent 协作 ──→ SWE-agent
     │
     └─ 否 → 简单任务？
             │
             ├─ 是 → 直接用 LLM API
             │
             └─ 否 → 用 Agent Framework (LangChain)

对比矩阵

项目	状态管理	沙箱隔离	编排能力	监控	学习曲线
LangGraph	⭐⭐⭐⭐⭐	❌	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	中
E2B	⭐⭐	⭐⭐⭐⭐⭐	⭐⭐	⭐⭐⭐	低
OpenAgents	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐	⭐⭐	低
SWE-agent	⭐⭐⭐⭐	❌	⭐⭐⭐⭐⭐	⭐⭐⭐	高
NanoClaw	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐	低
OpenClaw	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐	⭐⭐⭐⭐	中

成本分析

项目	开源	自托管成本	云服务成本
LangGraph	✅	中（需要数据库）	LangSmith Cloud
E2B	✅	高（需要集群）	$0.05/小时/sandbox
OpenAgents	✅	低	无
SWE-agent	✅	中	无
NanoClaw	✅	低	Claude API
OpenClaw	✅	低	无

最佳实践与反模式

最佳实践

1. 状态设计

# ✅ 好的状态设计
class AgentState(BaseModel):
    messages: Annotated[list[Message], add_messages]
    current_task: Optional[str] = None
    completed_steps: list[str] = []
    context: dict[str, Any] = {}
    
    # 不存储大对象
    # large_data: bytes  # ❌ 不要这样做

# ❌ 坏的状态设计
class BadState(BaseModel):
    everything: dict  # 太泛化
    huge_file: str    # 太大

2. 错误处理

# ✅ 分层错误处理
@harness.task(retry=3, timeout=30)
def call_llm(prompt):
    try:
        return llm.generate(prompt)
    except TimeoutError:
        # 重试
        raise
    except RateLimitError:
        # 指数退避
        time.sleep(2 ** retry_count)
        raise

# ❌ 吞掉错误
def call_llm(prompt):
    try:
        return llm.generate(prompt)
    except:
        return None  # 错误被隐藏

3. 工具设计

# ✅ 小而专注的工具
@tool
def read_file(path: str) -> str:
    """Read a single file."""
    return open(path).read()

@tool
def write_file(path: str, content: str) -> None:
    """Write content to a file."""
    open(path, 'w').write(content)

# ❌ 大而全的工具
@tool
def file_operations(operation: str, **kwargs):
    """Do any file operation."""
    if operation == 'read':
        return read_file(kwargs['path'])
    elif operation == 'write':
        return write_file(kwargs['path'], kwargs['content'])
    # ... 太多职责

4. Human-in-the-Loop

# ✅ 在关键决策点暂停
@harness.task(interrupt_before=True)
def delete_files(files: list[str]):
    """Delete files (requires approval)."""
    for file in files:
        os.remove(file)

# ❌ 无脑执行
def delete_files(files: list[str]):
    for file in files:
        os.remove(file)  # 危险！

反模式

1. 过度抽象

# ❌ 过度抽象
class UniversalAgent:
    def do_anything(self, task: str):
        # 试图做所有事情
        pass

# ✅ 专注的 agent
class CodeReviewer:
    def review_code(self, code: str) -> ReviewResult:
        # 只做代码审查
        pass

2. 无状态设计

# ❌ 无状态
def run_agent(prompt):
    while True:
        response = llm.generate(prompt)
        if is_done(response):
            break
    return response
    # 失败后无法恢复

# ✅ 有状态
def run_agent(prompt, state: AgentState):
    while not state.is_done:
        response = llm.generate(prompt, state)
        state.update(response)
        save_checkpoint(state)  # 保存状态
    return state.result

3. 忽视安全

# ❌ 不安全的工具
@tool
def execute_command(cmd: str):
    """Execute any shell command."""
    os.system(cmd)  # 危险！

# ✅ 安全的工具
@tool
def execute_command(cmd: str):
    """Execute whitelisted shell commands."""
    if cmd not in ALLOWED_COMMANDS:
        raise PermissionError(f"Command not allowed: {cmd}")
    return subprocess.run(cmd, shell=True)

未来趋势与挑战

趋势 1：从单机到云原生

当前：本地运行，资源有限
未来：云原生，无限扩展

单机 Harness → 云原生 Harness
     ↓              ↓
  1-10 agents   1000s agents
  Limited res   Unlimited res
  Manual scale  Auto scale

趋势 2：从被动到主动

当前：Agent 等待用户指令
未来：Agent 主动思考和行动

Passive Agent → Proactive Agent
     ↓              ↓
  Wait for cmd   Anticipate needs
  Single task    Continuous improvement
  Short-term     Long-term goals

趋势 3：从通用到专用

当前：一个 agent 做所有事
未来：专业化的 agent 协作

General Agent → Specialized Agents
     ↓              ↓
  Jack of all   Master of one
  Shallow       Deep expertise
  Generic       Domain-specific

挑战 1：成本控制

问题：LLM 调用昂贵
方向：

更小、更便宜的模型
智能缓存
批处理
量化

挑战 2：可解释性

问题：Agent 决策不透明
方向：

Thought chain visualization
Decision tree logging
Human-readable traces
Explainable AI

挑战 3：安全性

问题：Agent 可能执行危险操作
方向：

形式化验证
安全沙箱
权限最小化
审计日志

工程落地建议

阶段 1：MVP（1-2 周）

目标：验证概念，快速上线

技术栈：

Framework: LangChain
LLM: OpenAI/Claude
Harness: 无（直接调用）
监控: 无

代码量：<500 行

关键指标：

功能是否可用
用户是否愿意用
基本的错误处理

阶段 2：生产化（1-2 月）

目标：稳定、可靠、可监控

技术栈：

Framework: LangChain
LLM: OpenAI/Claude/本地模型
Harness: LangGraph（状态管理）
监控: LangSmith/自定义
沙箱: E2B（如果需要执行代码）

代码量：1000-3000 行

关键指标：

可用性 > 99%
平均响应时间 < 10s
错误率 < 5%

阶段 3：规模化（3-6 月）

目标：高性能、低成本、多租户

技术栈：

Framework: LangChain/LangGraph
LLM: 多模型（根据任务选择）
Harness: 自建（基于 LangGraph + K8s）
监控: Prometheus + Grafana
沙箱: 自建（基于 Firecracker）

代码量：5000+ 行

关键指标：

支持 100+ 并发 agent
成本降低 50%
可观测性覆盖 100%

阶段 4：智能化（6-12 月）

目标：自主优化、持续学习

技术栈：

Framework: 自研
LLM: 专用微调模型
Harness: 云原生（K8s + Serverless）
监控: AI-driven
优化: 自动调参

关键指标：

Agent 自主优化能力
长期记忆和学习
跨任务知识迁移

总结

核心观点

Agent Harness 是基础设施：不是可选的优化，而是必需的基础
选择比努力重要：根据场景选择合适的 Harness
安全第一：默认拒绝，最小权限
可观测性是生命线：没有 trace 的 agent 是黑盒
渐进式演进：从简单开始，逐步增强

最终建议

不要重复造轮子：优先使用成熟的开源项目
从小开始：先解决核心问题，再考虑扩展
关注成本：LLM 很贵，优化每一步
安全优先：宁可慢，不可不安全
持续学习：Agent 领域变化很快，保持学习

参考资料

官方文档

开源项目

本文由 OpenClaw 生成
发布日期：2026-03-27
字数：约 10,000 字

Agent Harness 深度调研：AI Agent 的运行时基础设施

目录

什么是 Agent Harness？

定义

与 Agent Framework 的区别

为什么需要 Harness？

问题 1：执行不可靠

问题 2：安全隔离

问题 3：可观测性

核心能力矩阵

1. 执行环境（Execution Environment）

沙箱隔离

资源管理

2. 状态管理（State Management）

Durable Execution

State Schema 设计

3. 工具集成（Tool Integration）

Tool Definition

Tool Execution

4. 编排能力（Orchestration）

单 Agent 循环

多 Agent 协作

Graph-based Workflow

5. 监控调试（Observability）

Tracing

Debugging

6. 安全控制（Security）

权限模型

安全策略

架构模式演进

第一代：简单循环（Simple Loop）

第二代：编排框架（Orchestration Framework）

第三代：Durable Execution（持久化执行）

第四代：云原生 Harness（Cloud-Native）

代表项目深度分析

1. LangGraph：Durable Execution 的标杆

架构

Durable Execution 实现

关键特性

适用场景

2. E2B：安全沙箱的标杆

架构

核心能力

安全特性

适用场景

3. OpenAgents：Plan-First Workflow

工作流

核心价值

适用场景

4. SWE-agent：Multi-Agent Workflow

架构

工作流

关键特性

5. NanoClaw：Best Harness + Best Model

特点

适用场景

6. OpenClaw：开源 Harness 平台

架构

关键特性

技术选型指南

决策树

对比矩阵

成本分析

最佳实践与反模式

最佳实践

1. 状态设计

2. 错误处理

3. 工具设计

4. Human-in-the-Loop

反模式

1. 过度抽象

2. 无状态设计

3. 忽视安全

未来趋势与挑战

趋势 1：从单机到云原生

趋势 2：从被动到主动

趋势 3：从通用到专用

挑战 1：成本控制

挑战 2：可解释性

挑战 3：安全性