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）
• 代码要点：

  from langgraph.graph import StateGraph, END
  # 定义状态类型、节点、边，编译后执行
  

3 ToolCall：从理论到代码实现

核心知识点

• ToolCall 本质：模型输出结构化 JSON（name + arguments），由外部系统执行后返回结果。
• OpenAI 格式标准：

  {
    "role": "assistant",
    "tool_calls": [{
      "id": "call_xxx",
      "type": "function",
      "function": {"name": "get_weather", "arguments": "{\"city\":\"北京\"}"}
    }]
  }
  

• 实现步骤：
  1. 工具描述（Schema）：名称、描述、参数定义（JSON Schema）
  2. 绑定到模型：tools=[{"type": "function", "function": {...}}]
  3. 解析模型响应，提取 tool_calls
  4. 本地执行对应函数，获取 tool_result
  5. 将结果以 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 伪代码结构：

  while (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 从"能跑"到"跑稳"的工程框架。
• 三层架构：
  1. 执行层（Execution）：Agent Loop、Tool Orchestration、并行/串行调度
  2. 状态层（State）：对话持久化、Session 管理、上下文压缩、记忆维护
  3. 治理层（Governance）：权限控制、Hook 系统、断路器、审计日志
• 核心组件实现路线图：
  • 对话循环（Agent Loop）
  • 工具系统（Tool System + MCP 适配）
  • 权限系统（Permission Layer）
  • 钩子系统（Hook System）
  • 状态持久化（JSONL / SQLite / 远程存储）
  • 上下文管理（Context Compression / Summarization）

7 Harness 核心机制：权限、钩子与断路器

核心知识点

• 渐进式权限（4 阶段/5 层）：
  1. validateInput：输入合法性校验（参数类型、范围）
  2. checkPermissions：用户角色与工具权限匹配
  3. PreToolUse Hook：前置拦截（如敏感操作二次确认）
  4. canUseTool：用户显式确认（尤其针对写操作）
  5. 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 时注入合成错误，避免死锁）