1 前言：Agent 技术全景图
核心知识点
- Agent 定义：以大模型为"大脑"，具备工具调用（Tool Use）、规划（Planning）、记忆（Memory）三大核心能力的自主执行系统。
- 2026 Agent 技术栈分层 ：
- 模型层：GPT-4o、Claude 3.5/4、Gemini 2.0 等基础推理能力
- 接口层：ToolCall / FunctionCall / MCP（Model Context Protocol）
- 编排层：LangChain、LangGraph、Swarm、AutoGen
- 工程层：Harness（Agent 运行时框架）、Claw（代码级 Agent 工具）
- 学习路径：ToolCall → Agent Loop → State Management → Harness → Production
2 LangChain & LangGraph 简介
核心知识点
-
LangChain 定位：LLM 应用开发框架，提供标准化组件（Models、Prompts、Indexes、Chains、Agents）。
-
Chain vs Agent ：
- Chain：预设执行路径，适合固定流程
- Agent：动态决策下一步动作，适合开放域任务
-
LangGraph 核心 ：
- 用图结构（StateGraph）替代线性 Chain，支持循环、条件分支、并行
- 关键概念：
State（共享状态）、Node（函数节点）、Edge（转移边） - 支持持久化 （Persistence）和人机协同（Human-in-the-loop）
-
代码要点 ：
pythonfrom langgraph.graph import StateGraph, END # 定义状态类型、节点、边，编译后执行
3 ToolCall：从理论到代码实现
核心知识点
-
ToolCall 本质 ：模型输出结构化 JSON（
name+arguments），由外部系统执行后返回结果。 -
OpenAI 格式标准 ：
json{ "role": "assistant", "tool_calls": [{ "id": "call_xxx", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"北京\"}"} }] } -
实现步骤 ：
- 工具描述（Schema）：名称、描述、参数定义（JSON Schema）
- 绑定到模型：
tools=[{"type": "function", "function": {...}}] - 解析模型响应，提取
tool_calls - 本地执行对应函数，获取
tool_result - 将结果以
role="tool"回传模型，进入下一轮推理
-
关键细节 ：
- 参数精度：模型常犯的错（幻觉参数、类型错误）
- 多步调用：一个对话轮次可能触发多个 ToolCall
- 错误恢复：Tool 执行失败时，需将错误信息回传模型，让其自行修正
4 ToolCall 进阶：多工具编排与错误处理
核心知识点
- 工具选择策略（Tool Selection） ：
- 少而精 > 多而杂：工具描述质量直接决定调用准确率
- 命名规范：动词+名词，如
search_web、write_file
- 并行执行 vs 顺序执行 ：
- 只读工具（如查询）可并行批处理
- 写操作（如文件写入、数据库更新）必须顺序执行，避免竞态
- 错误处理机制 ：
- 参数校验失败 → 返回
is_error=True，让模型重试 - 工具执行超时 → 设置 hard timeout（建议 30s 默认）
- 工具不存在 → 返回 Unknown tool，触发模型重新规划
- 参数校验失败 → 返回
- MCP（Model Context Protocol） ：
- Anthropic 提出的开放标准，统一工具描述和调用方式
- 解决跨框架工具互操作问题（LangChain、OpenAI、Claude 共用一套工具定义）
5 Agent Loop：构建 Agent 的核心循环
核心知识点
-
Agent Loop 伪代码结构 ：
typescriptwhile (turnCount < maxTurns) { // 1. 调用模型，传入历史消息 + 可用工具 const response = await callModel(messages, tools); // 2. 若无 tool_calls，任务完成，返回结果 if (!hasToolCalls(response)) break; // 3. 执行工具调用，收集结果 const toolResults = await executeTools(response.tool_calls); // 4. 将 assistant 消息 + tool_results 加入历史 messages.push(assistantMessage, ...toolResults); turnCount++; } -
关键状态管理 ：
messages：完整对话历史（需控制长度，防止超出上下文窗口）turnCount：防止无限循环（建议 max 10-25 轮）abortController：支持用户中断执行
-
流式输出 ：使用
AsyncGenerator逐块返回，提升用户体验
6 Harness 概念与架构：Agent 的工程化骨架
核心知识点
- Harness 定义 ：Agent 的运行时 harness（ harness = 马具/ harness），即让 Agent 从"能跑"到"跑稳"的工程框架。
- 三层架构 ：
- 执行层（Execution）：Agent Loop、Tool Orchestration、并行/串行调度
- 状态层（State）：对话持久化、Session 管理、上下文压缩、记忆维护
- 治理层（Governance）：权限控制、Hook 系统、断路器、审计日志
- 核心组件实现路线图 ：
- 对话循环（Agent Loop）
- 工具系统（Tool System + MCP 适配）
- 权限系统（Permission Layer）
- 钩子系统（Hook System）
- 状态持久化（JSONL / SQLite / 远程存储）
- 上下文管理（Context Compression / Summarization）
7 Harness 核心机制：权限、钩子与断路器
核心知识点
- 渐进式权限（4 阶段/5 层） ：
validateInput：输入合法性校验（参数类型、范围）checkPermissions：用户角色与工具权限匹配PreToolUse Hook：前置拦截（如敏感操作二次确认）canUseTool：用户显式确认（尤其针对写操作）- Hard blocks ：
rm -rf /、curl | sh等危险命令直接拒绝（不可覆盖）
- 钩子系统（Hook System） ：
- 事件类型：
pre_tool_use、post_tool_use、session_start、session_end - 执行方式：独立 Shell 命令，通过环境变量
HOOK_INPUT传入上下文 - 阻塞型钩子：返回
outcome: "blocking"可中断工具执行
- 事件类型：
- 断路器模式（Circuit Breaker） ：
- 失败阈值：连续 3 次失败触发（快速失败，避免资源浪费）
- 恢复策略：成功一次即重置计数器
- 降级方案：切换到 fallback 模型或简化流程
- 反模式：阈值设为 100 次等于没有断路器
8 Claw 与代码级 Agent：从 Harness 到落地
核心知识点
- Claw 定位：面向代码仓库的 Agent 工具（类似 Claude Code 的底层能力），实现"AI 编程助手"的工程化。
- 核心能力 ：
- 代码图谱构建（CodeGraph）：让 Agent 少读文件、快速定位相关代码
- 文件操作：Read、Edit、Write、Glob（批量匹配）
- 命令执行：Bash 命令运行 + 输出捕获
- 渐进式加载：按需加载代码上下文，节省 Token
- Claude Code 架构启示 ：
- 零上下文管理：不依赖系统提示词堆砌规则，而是通过 Harness 代码约束行为
- 更多 Context，更少 Control：给模型足够上下文，减少硬编码控制逻辑
- 长程任务接力：大任务拆分为子任务，通过 Session 持久化实现断点续传
- "做梦"式记忆维护：自动总结 Session 历史，生成长期记忆，让 Agent"越用越聪明"
- 工程化实践 ：
- Skill 设计：将"从文章到视频"等复杂任务切分为阶段，中间卡人工检查点
- 状态持久化格式：JSONL（每行一个事件，便于追加和回放）
- 会话恢复：启动时扫描 JSONL，处理 dangling toolCall（无对应 toolResult 时注入合成错误，避免死锁）