Agent Harness 深度教学指南：每个 AI Agent 都需要的基础设施
·
Agent Harness 深度教学指南：每个 AI Agent 都需要的基础设施
作者：技术探索者 | 日期：2026年5月16日 | 标签：AI Agent, Agent Harness, LLM, Strands Agents, AWS AgentCore, MCP
目录
- 引言：为什么只有模型是不够的？
- 什么是 Agent Harness？
- Agent Harness 的核心组件
- 为什么构建 Harness 这么困难？
- 托管式 Harness：Agent 工厂模式
- Strands Agents SDK 实战
- 用 AgentCore 5 分钟搭建一个 AI Agent
- Agent Skills：教会你的 Agent 领域知识
- Harness vs. Framework 的区别
- 学习资源与下一步
引言：为什么只有模型是不够的？
想象一下这个场景：你拥有 Claude 或 GPT-4 的 API 权限。你发送一个 Prompt，它返回一段文字。这对聊天机器人或一次性问答来说足够了——但如果你想让模型：
- 浏览网页并拉取实时数据？
- 执行 Python 代码来分析数据？
- 记住你上周告诉它的内容？
- 跨多个步骤协调执行——每一步都依赖上一步的结果？
- 调用你的内部 API 或工具？
一个原始的模型，独立来看，做不到这些。 它可以谈论做这些事情，但没有能力真正执行。
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 这就像雇了一位天才分析师，但是： │
│ │
│ ❌ 没有笔记本电脑 │
│ ❌ 没有互联网 │
│ ❌ 只能通过传纸条来沟通 │
│ │
│ 智力在那里 —— 但基础设施不在。 │
│ │
│ 这个缺失的基础设施，就是 Agent Harness。 │
│ │
└─────────────────────────────────────────────────────────────────┘
什么是 Agent Harness？
Agent Harness 是你围绕模型构建的一切东西，用来将它从一个"文本生成器"转变为一个能在真实世界中行动的 Agent。
最简洁的公式：
╔══════════════════════════════════════════════════╗
║ ║
║ Agent = Model + Harness ║
║ ║
║ 你的 Agent 中，不是模型本身的部分 ║
║ ——全部属于 Harness ║
║ ║
╚══════════════════════════════════════════════════╝
关键理解：你今天使用的任何 AI 产品——Claude Code、GitHub Copilot、Cursor、Perplexity——背后都有一个 Harness 在默默工作。模型只是庞大系统中的一个组件。
Agent Harness 的核心组件
Agent Harness 通常包含以下 8 大核心组件：
┌─────────────────────────────────────────────────────────────┐
│ Agent Harness 架构全景 │
│ │
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ 1. 编排循环 │ │ 2. 工具连接 │ │
│ │ Orchestration │ │ Tool Connections │ │
│ │ Loop │ │ │ │
│ │ │ │ 浏览器 / 代码执行 / API调用 │ │
│ │ 用户消息 → 模型 │ │ 数据库查询 / 文件操作 │ │
│ │ → 执行动作 │ │ │ │
│ │ → 回传结果 │ └──────────────────────────────┘ │
│ │ → 重复直到完成 │ │
│ └──────────────────┘ ┌──────────────────────────────┐ │
│ │ 3. 记忆系统 (Memory) │ │
│ ┌──────────────────┐ │ │ │
│ │ 4. 上下文管理 │ │ 短期: 会话内上下文 │ │
│ │ Context Mgmt │ │ 长期: 跨会话持久记忆 │ │
│ │ │ └──────────────────────────────┘ │
│ │ 决定每一步什么 │ │
│ │ 信息进入Prompt │ ┌──────────────────────────────┐ │
│ │ (Token有限！) │ │ 5. 计算与沙箱 │ │
│ └──────────────────┘ │ Compute & Sandboxing │ │
│ │ │ │
│ ┌──────────────────┐ │ 安全隔离的代码执行环境 │ │
│ │ 6. 身份认证 │ └──────────────────────────────┘ │
│ │ Authentication │ │
│ │ │ ┌──────────────────────────────┐ │
│ │ 安全调用外部API │ │ 7. 可观测性 (Observability) │ │
│ │ 不泄露凭证 │ │ │ │
│ └──────────────────┘ │ 日志、追踪、调试工具 │ │
│ │ 出问题时知道发生了什么 │ │
│ ┌──────────────────┐ └──────────────────────────────┘ │
│ │ 8. 会话管理 │ │
│ │ Session Mgmt │ │
│ │ │ │
│ │ 暂停/恢复 │ │
│ │ 断点续传 │ │
│ └──────────────────┘ │
└─────────────────────────────────────────────────────────────┘
下面逐一详解每个组件：
1. 编排循环（Orchestration Loop）
这是 Harness 的"心脏"——负责驱动 Agent 的整个思考-行动循环。
┌─────────┐
│ 用户输入 │
└────┬────┘
▼
┌─────────────────────────────┐
│ 将用户消息 + 上下文发给模型 │ ◄──────────────────────┐
└────────────┬────────────────┘ │
▼ │
┌──────────────────────┐ │
│ 模型决定下一步行动 │ │
│ (思考 → 选择工具) │ │
└────────────┬─────────┘ │
▼ │
┌───────────────┐ │
│ 需要调用工具？ │── 否 ──► 返回最终结果给用户 │
└───────┬───────┘ │
│ 是 │
▼ │
┌──────────────────────┐ │
│ 执行工具调用 │ │
│ (浏览器/代码/API等) │ │
└────────────┬─────────┘ │
▼ │
┌──────────────────────┐ │
│ 将工具结果回传给模型 │───────────────────────────────┘
└──────────────────────┘
(循环继续，直到任务完成)
2. 工具连接（Tool Connections）
让模型能够与外部世界交互的"管道"。
┌─────────────────────────────────────────────────┐
│ Agent 可以连接的工具类型 │
├─────────────────────────────────────────────────┤
│ │
│ 🌐 浏览器 可以导航真实网页、阅读内容 │
│ 🐍 代码解释器 Python 沙箱，执行计算和分析 │
│ 🔌 外部 API RESTful API、GraphQL 等 │
│ 🗄️ 数据库 SQL/NoSQL 查询 │
│ 📁 文件系统 读写本地或云端文件 │
│ 🔧 MCP 服务器 连接 Slack/GitHub/Notion 等 │
│ 🛠️ 自定义函数 你自己编写的任意工具 │
│ │
└─────────────────────────────────────────────────┘
3. 记忆系统（Memory）
┌───────────────────────────────────────────────────────┐
│ Agent 记忆架构 │
│ │
│ ┌───────────────────────┐ ┌───────────────────────┐ │
│ │ 短期记忆 │ │ 长期记忆 │ │
│ │ (Short-term Memory) │ │ (Long-term Memory) │ │
│ │ │ │ │ │
│ │ • 当前会话的对话历史 │ │ • 跨会话持久化 │ │
│ │ • 工具调用的结果 │ │ • 用户偏好 │ │
│ │ • 中间推理步骤 │ │ • 历史经验总结 │ │
│ │ │ │ • 知识库索引 │ │
│ │ 会话结束 → 清除 │ │ 永久保存 → 数据库 │ │
│ └───────────────────────┘ └───────────────────────┘ │
└───────────────────────────────────────────────────────┘
4. 上下文管理（Context Management）
Token 限制的挑战：
对话进行了 50 轮后...
┌──────────────────────────────────────┐
│ "你不能无限追加内容——模型有 Token 限制" │
└──────────────────────────────────────┘
解决策略：
策略1: 滑动窗口 策略2: 摘要压缩 策略3: 智能检索
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 只保留最近 │ │ 把旧对话 │ │ 用向量搜索│
│ N 轮对话 │ │ 压缩为摘要│ │ 找相关的 │
│ │ │ │ │ 历史片段 │
└──────────┘ └──────────┘ └──────────┘
简单但可能丢失 保留关键信息 最精准但
重要上下文 节省Token 实现最复杂
为什么构建 Harness 这么困难？
从零构建一个 Harness 的真实流程：
第1天: "这应该很简单"
└─ 选框架 (LangGraph/LlamaIndex/CrewAI) → 写工具连接 → 管理 Prompt 结构
第3天: "等等，还需要这些？"
└─ 工具调用失败的错误处理 → 重试逻辑 → 流式输出处理 → 日志系统
第5天: "好的，还需要..."
└─ 容器化 → 计算资源配置 → 部署
第7天: "糟糕..."
└─ 需要会话持久化 → 加数据库
└─ 需要 API 认证 → 加凭证管理
└─ 需要理解 Agent 的推理过程 → 加追踪系统
第14天: "这已经是一个完整的工程项目了" 😰
核心洞察：构建 AI Agent 的真正障碍，不是模型——而是 Harness。模型的智能已经足够了，缺的是让它行动起来的基础设施。
托管式 Harness：Agent 工厂模式
好消息是，工具终于跟上了这个问题。托管式 Harness 的理念很简单：
传统方式（手动构建）： 托管方式（声明式配置）：
自己搭服务器 声明你需要什么
自己写编排逻辑 平台帮你构建 Harness
自己管理计算资源 VS 自动处理底层基础设施
自己配置认证和安全 一行命令部署
自己搭建监控追踪 开箱即用的可观测性
≈ 几周开发时间 ≈ 5 分钟
Amazon Bedrock AgentCore
AgentCore 是 AWS 推出的托管式 Harness 服务。它使用 Strands Agents（AWS 开源 Agent SDK）来组装编排循环、工具执行、记忆管理、上下文处理和流式输出，然后在隔离的 microVM 中运行——独立的 CPU、内存和文件系统——无需你配置任何服务器。
┌────────────────────────────────────────────────────────────┐
│ AgentCore Harness 内置能力 │
├────────────────────────────┬───────────────────────────────┤
│ 隔离 microVM (每会话独立) │ Shell 访问 (直接执行命令) │
│ 持久化文件系统 (断点续传) │ 模型无关路由 (多模型切换) │
│ 内置浏览器工具 │ 内置代码解释器 (Python沙箱) │
│ MCP 服务器支持 │ AgentCore 网关 (API管理) │
│ 自定义工具定义 │ Skills 领域知识包 │
│ 全链路可观测性 │ 自动追踪每个操作 │
└────────────────────────────┴───────────────────────────────┘
Strands Agents SDK 实战
Strands Agents 是 AWS 开源的 Agent Harness SDK，支持 Python 和 TypeScript。
最小示例：3 行代码创建一个 Agent
# Python 版本
from strands import Agent
agent = Agent()
agent("帮我分析一下最近 AI Agent 框架的发展趋势")
添加自定义工具
// TypeScript 版本
import { Agent, tool } from '@strands-agents/sdk'
import z from 'zod'
// 定义一个搜索日志的工具
const searchLogs = tool({
name: 'search_logs', // 工具名称
description: 'Search logs by keyword.', // 描述（模型据此决定何时调用）
inputSchema: z.object({ // 输入参数的 Schema
query: z.string(), // 搜索关键词
hours: z.number().default(24), // 时间范围（默认24小时）
}),
callback: ({ query, hours }) => // 实际执行逻辑
logApi.search(query, hours),
})
// 创建 Agent 并绑定工具
const agent = new Agent({ tools: [searchLogs] })
// 调用 Agent
await agent.invoke(
'Find all timeout errors from the last 6 hours'
)
添加记忆管理
import {
Agent,
SummarizingConversationManager // 摘要式记忆管理器
} from '@strands-agents/sdk'
const agent = new Agent({
tools: [searchLogs],
conversationManager: new SummarizingConversationManager(),
// 当对话变长时，自动将旧消息压缩为摘要
// 既节省 Token，又保留关键上下文
})
添加安全守护（Hooks）
import {
Agent, BeforeToolCallEvent
} from '@strands-agents/sdk'
const agent = new Agent({
tools: [searchLogs, queryDatabase],
traceAttributes: { // 追踪属性
service: 'ops-agent',
env: 'production',
},
})
// 在工具调用前拦截，实现安全控制
agent.addHook(BeforeToolCallEvent, (event) => {
console.log(`Tool: ${event.toolUse.name}`) // 记录调用了哪个工具
console.log(`Input: ${event.toolUse.input}`) // 记录输入参数
// 示例：阻止危险的数据库写操作
if (event.toolUse.name === 'query_database') {
const sql = String(event.toolUse.input.query).toUpperCase()
if (sql.includes('DROP') || sql.includes('DELETE')) {
event.cancel = 'Read-only access. Write operations are blocked.'
}
}
})
用 AgentCore 5 分钟搭建一个 AI Agent
以下是一个完整的实战案例：构建一个AI 趋势分析师，它能自动浏览 HackerNews 和 dev.to，抓取当日热门 AI 帖子，按主题聚类，生成排名摘要和图表。
步骤 1：安装 CLI
npm install -g @aws/agentcore@preview
步骤 2：创建 Agent 配置
agentcore create
# 交互式引导：选择模型、工具、认证方式等
生成的配置文件如下：
{
"name": "TrendsAgentHarness",
"model": {
"provider": "bedrock",
"modelId": "global.anthropic.claude-sonnet-4-6"
},
"tools": [
{
"type": "agentcore_browser",
"name": "browser"
},
{
"type": "agentcore_code_interpreter",
"name": "code-interpreter"
}
],
"skills": [],
"authorizerType": "AWS_IAM"
}
步骤 3：编写系统提示词
创建 system-prompt.md：
Your job is to keep a pulse on what the AI and dev community
is buzzing about right now. Every session, head over to
HackerNews and dev.to, scrape today's hottest posts, then
use the code interpreter to make sense of it all — cluster
the topics, rank them by how often they show up, and summarize
the top 5 in plain language. Throw in a bar chart. No fluff.
步骤 4：一键部署
agentcore deploy
步骤 5：调用执行
agentcore invoke --harness TrendsAgentHarness \
--session-id "$(uuidgen)" \
"What's trending in IT today?"
执行流程可视化：
用户: "What's trending in IT today?"
│
▼
Agent 思考 → 决定先浏览 HackerNews
│
├──► 🌐 [Browser] 导航到 HackerNews
│ └── 阅读热门帖子标题和描述
│
├──► 🌐 [Browser] 导航到 dev.to
│ └── 阅读 AI/DevTools 分类热门帖子
│
├──► 🐍 [Code Interpreter] 执行 Python
│ ├── 按主题聚类所有帖子
│ ├── 计算每个主题的出现频率
│ └── 生成柱状图
│
└──► 📝 流式输出格式化摘要到终端
✅ 全部在隔离的 microVM 中运行
✅ 会话结束后自动清理，无数据泄露
Agent Skills：教会你的 Agent 领域知识
Agent Skill 是一种将领域专业知识打包给 Agent 的机制——由 Markdown 指令和（可选）脚本组成。
┌─────────────────────────────────────────────────┐
│ Agent Skill 的本质 │
│ │
│ 不是微调模型 ❌ │
│ 不是训练新模型 ❌ │
│ 而是结构化知识 ✅ Agent 在需要时自动参考 │
│ │
│ 类比：给新员工一本操作手册 │
│ 而不是重新训练他的大脑 │
│ │
├─────────────────────────────────────────────────┤
│ │
│ 实际用途： │
│ 📋 内部数据格式处理规范 │
│ 📋 公司 API 使用惯例 │
│ 📋 Excel 报表处理的特定流程 │
│ 📋 代码审查标准 │
│ 📋 故障排查知识库 │
│ │
└─────────────────────────────────────────────────┘
Harness vs. Framework 的区别
这是一个常见的混淆点，必须澄清：
┌──────────────────────────────────────────────────────────────┐
│ │
│ Framework（框架） Harness（完整运行系统） │
│ ═══════════════ ═══════════════════════ │
│ │
│ 提供构建积木： 完全组装好的系统： │
│ • 工具接口 • 框架代码 │
│ • 循环模式 • 计算资源 │
│ • 模型连接器 • 沙箱隔离 │
│ • 记忆存储 │
│ • 身份认证 │
│ • 可观测性 │
│ │
│ 类比：一箱零件 类比：一辆能开的车 │
│ (需要你自己组装) (上车就能跑) │
│ │
│ 例如： 例如： │
│ Strands SDK AgentCore Harness │
│ LangGraph Claude Code 的后端 │
│ CrewAI GitHub Copilot 的后端 │
│ LlamaIndex Cursor 的后端 │
│ │
│ 你用 Framework 来构建 Harness │
│ 或者用托管服务让平台帮你构建 │
│ │
└──────────────────────────────────────────────────────────────┘
逃生舱：当配置不够用时
当你的用例变得足够复杂——比如需要多 Agent 协作、自定义路由逻辑、自己的向量数据库——AgentCore 允许你导出为代码：
配置模式 (快速路径) 代码模式 (完全控制)
│ ▲
│ agentcore export │
└───────────────────────────┘
从配置毕业到代码，同一个平台，更多控制权
学习资源与下一步
核心学习资源
| 资源 | 说明 | 链接 |
|---|---|---|
| Agent Harness 概念文章 | 理解什么是 Agent Harness 的最佳入门 | https://dev.to/aws-builders/what-is-an-agent-harness-and-why-every-ai-agent-needs-one-382l |
| Strands Agents SDK | 开源 Agent Harness SDK (Python/TS) | https://strandsagents.com/ |
| Strands 快速入门 | 5分钟上手教程 | https://strandsagents.com/docs/user-guide/quickstart/overview/ |
| Strands 示例代码 | 丰富的实战示例 | https://strandsagents.com/docs/examples/ |
| AgentCore 文档 | AWS 托管 Harness 服务文档 | https://docs.aws.amazon.com/bedrock/latest/userguide/agentcore.html |
| Strands GitHub | 源码和社区讨论 | https://github.com/strands-agents/sdk-python |
推荐学习路径
Level 1: 理解概念 ⭐
├── 阅读 "What Is an Agent Harness" 原文
├── 理解 Agent = Model + Harness 公式
└── 了解 Harness 的 8 大组件
Level 2: 动手实践 ⭐⭐
├── 安装 Strands Agents SDK
├── 用 3 行代码创建第一个 Agent
└── 添加自定义工具（Tool）
Level 3: 深入掌握 ⭐⭐⭐
├── 实现记忆管理（Memory）
├── 添加安全守护（Hooks/Guards）
└── 集成 MCP 工具服务器
Level 4: 生产部署 ⭐⭐⭐⭐
├── 使用 AgentCore 部署到云端
├── 配置可观测性和追踪
└── 实现 Agent Skills
Level 5: 高级架构 ⭐⭐⭐⭐⭐
├── 多 Agent 协作 (Agent-as-Tool, Swarm)
├── 自定义编排逻辑
├── 导出为代码进行深度定制
└── 构建企业级 Agent 系统
相关生态
| 框架/工具 | 定位 | 特点 |
|---|---|---|
| Strands Agents | Agent Harness SDK | AWS 出品，开源，渐进式复杂度 |
| LangGraph | Agent Framework | LangChain 生态，图编排 |
| CrewAI | Multi-Agent Framework | 多 Agent 角色扮演协作 |
| LlamaIndex | RAG + Agent Framework | 擅长数据检索和知识库 |
| AutoGen | Multi-Agent Framework | 微软出品，对话式协作 |
| AgentCore | Managed Harness | AWS 托管，配置即部署 |
总结
╔══════════════════════════════════════════════════════════════╗
║ ║
║ Agent Harness 核心要点回顾 ║
║ ║
║ 1. Agent = Model + Harness ║
║ 模型是大脑，Harness 是让它行动的一切 ║
║ ║
║ 2. Harness 的 8 大组件： ║
║ 编排循环 | 工具连接 | 记忆 | 上下文管理 ║
║ 计算沙箱 | 认证 | 可观测性 | 会话管理 ║
║ ║
║ 3. 构建 Harness 的障碍 >> 选择模型的障碍 ║
║ 这才是 AI Agent 开发的真正瓶颈 ║
║ ║
║ 4. 托管式 Harness（如 AgentCore）将开发时间 ║
║ 从"数周"压缩到"5分钟" ║
║ ║
║ 5. Strands Agents SDK 是开源的 Agent Harness SDK ║
║ 渐进式复杂度 + 零锁定 ║
║ ║
║ 6. 有趣的工作不再是"管道胶水代码" ║
║ 而是：Agent 该做什么？需要什么知识？如何推理和沟通？ ║
║ ║
╚══════════════════════════════════════════════════════════════╝
理解了 Agent Harness，你就理解了 AI Agent 架构的核心。从今天开始，把精力从"基础设施管道"转移到"你的 Agent 应该为世界做些什么"上吧！
参考文献：
- Suryansh Gupta, “What Is an Agent Harness? And Why Every AI Agent Needs One”, dev.to, 2026
- AWS Strands Agents SDK 官方文档, strandsagents.com
- Amazon Bedrock AgentCore 官方文档, docs.aws.amazon.com
欢迎交流：如有任何问题或建议，欢迎在评论区留言讨论！
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
11
0- 0
已为社区贡献2条内容
所有评论(0)