resin-notes
Agent

前端转Agent记录

主要通过问答形式去了解agent开发

你了解哪些主流的 Agent 架构

一句话结论:主流可归为 5 类——ReAct 单 Agent、Plan-and-Execute、多 Agent(主从 / 对等)、Workflow 编排、以及 Graph 状态机式(LangGraph)。

架构核心机制适用场景缺点
ReAct思考(Thought)→行动(Action)→观察(Observation) 循环工具少、任务短、需探索步数一多易发散、成本高
Plan-and-Execute先规划完整步骤,再逐步执行步骤可预先拆解的任务计划赶不上变化,需重规划
多 Agent(主从)主 Agent 拆解分派,子 Agent 并行执行复杂、可并行、需专业分工通信开销大、状态一致性难
Workflow 编排预定义 DAG/流程,LLM 只填节点流程稳定、可预测灵活性差,泛化弱
Graph 状态机(LangGraph)节点+边+共享 State,显式控制流长流程、需断点续跑/人审学习成本高

工程视角:选型本质是在 「灵活性」与「可控性」之间取平衡。ReAct 最灵活最难控,Workflow 最可控最死板。真实业务往往是「**Workflow 兜住主流程 + ReAct 处理局部不确定**」的混合体。

实际工程中,这些架构都是混合使用的

例如,“生成一份竞品分析报告”,就可以这样组合:

这里每种模式分别用在:

  • Plan-and-Execute:主 Agent 先规划调研内容,再安排执行。
  • 多 Agent:把两家产品的调研分配给不同 Agent。
  • ReAct:每个调研 Agent 内部反复“搜索 → 阅读结果 → 判断是否继续搜索”。
  • Workflow:规定“调研 → 汇总 → 审核 → 输出”的整体流程。
  • Graph / LangGraph:把上面的步骤、并行分支和执行状态组织起来。LangGraph 官方文档明确支持在同一个图里混合固定步骤与模型自主决策的步骤。

为什么选择主从多 Agent 架构?主 Agent 和从 Agent 各承担什么职责?

一句话结论:主从架构解决的是「单一上下文窗口 + 单一职责 Prompt」无法同时胜任复杂任务的问题——主 Agent 负责规划与协调,子 Agent 负责各自领域的深执行。 职责划分:

  1. 主 Agent(Orchestrator):意图理解、任务拆解、子任务路由、结果校验与汇总、全局状态维护。它是"项目经理",不干重活。
  2. 从 Agent(Worker):每个只挂载最小必要工具集与专属系统提示词,专注单一子任务,做完即返回。它是"领域专家"。

为什么不是单 Agent:

  • 上下文污染:单 Agent 把检索结果、代码、评审意见全塞进一个窗口,导致 Prompt 过长、注意力稀释。
  • 职责冲突:生成者与评审者合一会"自我背书",多 Agent 可做到生成/评审分离。
  • 可并行:独立子任务并行执行,端到端延迟显著下降。
  • 幻觉收敛:子 Agent 上下文窄、目标明确,单点幻觉概率更低。

代价:通信与协调开销、Token 成本上升、状态一致性(并发写冲突)需专门设计。

从 Agent 的数量是怎么确定的?

一句话结论:数量由「任务可分解度 × 依赖关系 × 成本预算」共同决定,而非拍脑袋;实践中遵循「能少不多、按需拆分、动态伸缩」三条原则。

  1. 按职责边界拆:一个子 Agent 对应一个清晰且互斥的职责(检索、编码、评审、格式化),而不是按"数量目标"拆。
  2. 按依赖关系定串并联:有前后依赖的必须串行(如先检索后总结);无依赖的可并行(如多路检索),并行的上限受并发预算约束。
  3. 受成本与延迟约束:每多一个 Agent 就多一轮 LLM 调用;常用 3~5 个为甜点区,超过后边际收益递减。
  4. 动态伸缩:简单任务主 Agent 直接回答(0 个子 Agent);中等任务 1 ~ 2 个;复杂任务才展开到 4 ~ 6 个。可让主 Agent 先输出「任务复杂度评估」再决定分派几个。
  5. 可观测性兜底:通过评测(准确率、Token/任务、端到端延迟)反推最优数量,而不是凭感觉。

实操验证

  1. 先把 Agent 数量变成参数。
function 查询价格(产品列表, 子Agent数量):

    if 子Agent数量 == 0:
        return 一个Agent处理全部产品(产品列表)

    分组 = 把产品列表分成若干组(子Agent数量)

    各组结果 = 并行执行:
        每组交给一个独立Agent处理

    return 合并(各组结果)

同一项任务会有不同的执行方式:

配置分配方式
0 个子 Agent一个 Agent 处理 A、B、C、D
2 个子 AgentAgent ①处理 A、B;Agent ②处理 C、D
4 个子 Agent每个 Agent 处理一家

实际改动就是调整参数和任务分组。 每个 Agent 的业务逻辑可以保持一致。为了公平,单 Agent 也应该允许并行查资料。 接下来,用同一批题目测试这些配置。

//先用最简单的规则评分
function 评分(结果, 标准答案):
    产品有没有遗漏?
    每个价格是否正确?
    有没有多报、重复报?

    全部满足 → 通过
    否则 → 失败
//main
for 子Agent数量 in [0, 2, 4]:
    记录列表 = []
    for 任务 in 同一批20条测试任务:
        重复运行5次:
            开始时间 = 单调时钟()
            结果 = 查询价格(任务.输入, 子Agent数量)
            耗时 = 单调时钟() - 开始时间
            记录列表.append({
                是否通过: 评分(结果, 任务.标准答案),
                耗时: 耗时,
                总Token: 所有Agent的Token之和
            })
    输出:
        通过率
        平均Token
        P95耗时

P95,就是把耗时从小到大排列后,位于约 95% 位置的值

第 1 次:  0.8 秒
……
第 50 次: 2.1 秒   ← P50
……
第 95 次: 8.0 秒   ← P95
……
第100次: 30.0 秒
//这里 P95=8 秒,表示这批样本中至少 95% 的请求耗时不超过 8 秒;仍有少数请求可能很慢。

测耗时,要从收到任务开始,到最终结果生成结束。

开始计时
    分派任务
    等待模型和工具
    等待子Agent
    重试
    合并结果
结束计时

MCP 和 Tool Calling 的区别是什么?

一句话结论:Tool Calling 是「模型能力」(模型输出结构化函数调用意图),MCP 是「协议标准」(把工具/资源以统一方式对接给任意 LLM 应用),二者是能力与标准的关系,不是替代关系。

维度Tool CallingMCP
本质模型输出调用意图的能力客户端-服务端的开放协议
关注点"模型怎么表达要调哪个函数""工具怎么标准化接入任意宿主"
复用性工具与应用耦合,换应用要重写一次编写,任意支持 MCP 的宿主可用
通信应用内进程调用JSON-RPC 2.0,跨进程/跨网络
能力面仅函数调用Tool + Resource + Prompt 三类
类比一个动词一套插座标准(USB-C)

工程要点:

  1. MCP 底层仍依赖 Tool Calling——模型依旧是输出结构化意图,MCP 解决的是工具描述与传输的标准化。
  2. MCP 的价值在生态:把 N 个应用 × M 个工具的 N×M 集成问题,降为 N+M。
  3. 代价:多一层进程通信,调试链路变长;工具描述注入 Prompt 会占用上下文。

Skill 和固定的 Workflow 有什么区别?

一句话结论:Workflow 是「硬编码的确定性流程」,Skill 是「按需加载的知识+工具封装包」;前者控制流写死,后者由模型决定何时调用、如何组合。

维度固定 WorkflowSkill
控制流开发者写死的 DAG / if-else模型自主决定是否/何时使用
形态流程定义一段可复用的指令+工具+资源包(常有 SKILL.md 目录结构)
灵活性低,流程变化要改代码高,模型按上下文组合
可预测性高,结果稳定中,依赖模型判断
上下文占用无(不在 Prompt 里)元数据常驻,正文按需加载(渐进式披露)
适用步骤固定、合规性强的场景能力复用、跨任务沉淀

类比:Workflow 是流水线,Skill 是工具柜——流水线固定动作,工具柜让模型自己挑工具。

工程要点:Skill 的关键设计是渐进式披露(Progressive Disclosure)——只在 Prompt 里放 skill 的 name + description,模型判断需要时才加载完整内容,从而避免上下文爆炸。这是 Claude Code 等产品的核心做法。

Memory 复用机制 / Context 与长期 Memory 的区别

一句话结论:Context 是「当前对话窗口内的临时状态」,长期 Memory 是「跨会话持久化并可检索的知识」;前者昂贵易失,后者廉价持久,二者需配合使用。

维度Context(短期)长期 Memory
存储位置模型输入窗口外部存储(向量库/DB/文件)
生命周期单次会话跨会话持久
容量受窗口限制(如 128K)近乎无限
读取方式直接进 Prompt检索后按需注入
成本高(Token 计费)低(只注入命中片段)

Memory 复用机制的典型实现(四层):

  1. 写入:会话结束后,抽取关键事实/偏好,写成结构化条目(含时间、来源、置信度)。
  2. 存储:向量库(语义检索)+ 结构化 DB(精确查询)双写。
  3. 检索:新会话开始时,按用户 query 做相似度召回,Top-K 注入 Context 头部。
  4. 管理:去重、冲突消解(新覆盖旧)、过期淘汰(TTL / 遗忘曲线)。

工程避坑:① 无脑全量注入会让上下文爆炸;② 不做冲突消解会导致模型收到矛盾记忆;③ 缺少来源标注会污染后续推理。

AI Coding 工作流 / 如何让 AI 更符合期望地工作?

完整工作流(可直接背):

  1. 拆需求:把大需求拆成可独立验证的小任务(一个任务一次对话)。
  2. 给上下文:明确技术栈、目录结构、命名规范、已有代码片段;用规则文件(如 CLAUDE.md / .cursorrules)固化偏好。
  3. 定验收:先写测试或明确输入输出,让 AI 有"对错标准"。
  4. 小步验证:每轮只让它改一小块,跑通再继续。
  5. 强制自检:让它"先复述理解,再给方案,最后改代码";改完要求它列出改动点与潜在风险。
  6. 人工兜底:边界情况、安全、性能必须人工把关。

常见坑:需求太泛导致跑偏;上下文不足导致幻觉 API;不做验证导致"看起来对但跑不通"。

Agent Harness 是什么?包含哪些组件?

一句话结论:Harness 是"包围模型的运行时控制层"——模型负责在当前上下文里产出判断/动作,Harness 负责提供上下文、工具、状态、权限、循环控制、预算、错误处理、验证与观测。Agent 的可靠性是"模型 + Harness + 外部环境"的系统属性,而非模型单方面决定。

六大组件:

  1. Context 管理:组装系统指令、用户请求、任务状态、历史摘要、检索证据、工具观察,并控制 Token 预算。
  2. Tool Runtime:暴露版本化工具 Schema,完成参数校验、鉴权、超时、重试、幂等与副作用隔离。
  3. Orchestrator:驱动 ReAct / Plan-and-Execute / 状态机,限制步数、并发、成本与截止时间。
  4. Memory / RAG:管理短期状态、长期记忆、文档检索与权限。
  5. Verifier 与 Guardrail:用测试、DB 状态、规则、人工审批判断"动作能否执行、结果是否达标"。
  6. Observability:Trace、Prompt/工具版本、Token、延迟、错误、回放与指标。

优秀 Harness 的判断标准:面对工具失败、上下文超限、用户取消、权限变化、模型输出不规范时,系统是否仍能安全、可解释、可恢复地运行。

长程任务耗时从 5 分钟劣化到 20 分钟,如何归因?

一句话结论:先不要归因于"模型变慢",而是用同一个 trace_id 把任务拆成阶段与子调用,对比正常样本与异常样本的分布差异,再逐层收敛。

排查路径(五步):

  1. 确认范围:全部请求慢,还是特定用户/任务类型/模型路由/地域/时间段?
  2. 分解关键路径:拆解为模型生成、工具 I/O、队列等待、锁等待、DB/向量库、网络重试、人工审批、上下文压缩各阶段耗时。
  3. 对比版本与分布:检查最近的模型、Prompt、工具 Schema、索引、依赖库、配置、容器发布、流量变化;对比输入 Token、工具调用次数、轨迹长度。
  4. 识别长尾:看 P50/P95/P99 而非均值;查连接池耗尽、线程池排队、限流、GC、CPU、GPU 显存/KV Cache、丢包与外部服务限额。
  5. 回放与最小复现:在脱敏沙箱固定输入/版本/工具返回,分别关闭 RAG、工具、压缩、重试,找出时间增长的变量。

Agent 特有的四类诱因:

  • 模型陷入重复工具调用或反复重规划(Loop 不收敛);
  • 上下文增长导致 Prefill 与压缩变慢;
  • 工具超时后指数重试放大耗时;
  • 多任务争抢同一锁/连接池,或某外部接口尾延迟升高、并发触发限流。

修复四层:① 设总 Deadline + 阶段预算(超时即降级/转人工);② 控制 Agent 行为(超时、取消、最大重试,瞬时错误指数退避+抖动,参数/权限错误不重试,副作用工具用幂等键,重规划限次);③ 降关键路径(并行无依赖子任务、流式+缓存、工具返回分页/摘要、缩小召回与 Rerank 范围);④ 基础设施治理(连接池/线程池上限与背压、熔断、舱壁隔离、备用路由)。

收尾金句(可直接背):长程 Agent 的性能优化,本质是把一个不可控的开放循环,拆成有预算、有状态、有验证的有限执行图。

工具调用如何保障可靠性?

  1. Schema 约束:用 JSON Schema / 函数调用定义类型、枚举、范围、必填项、字段关系;拒绝无法解析或多余字段,杜绝把自然语言直接拼成 SQL / Shell / URL。
  2. 上下文与身份校验:运行时补充不可由模型决定的 user_id、租户、权限、服务端时间;模型只能提供业务参数。
  3. 执行前检查:校验权限、资源存在性、前置状态、金额/范围、幂等键与风险等级;高风险动作用"预览 → 用户确认 → 提交",必要时人工审批。
  4. 失败分类:区分参数错误、权限拒绝、资源不存在、业务冲突、瞬时网络错误、服务端故障——只有可恢复错误才重试,且限制次数与总时长。
  5. 执行隔离:文件/代码/网络工具放沙箱容器,限制域名、syscall、资源与路径;工具结果视为不可信数据,防 Prompt Injection 反向改写系统指令。
  6. 结果验证:工具返回 ≠ 业务成功。用 DB 状态、测试、签名回执或确定性规则验证;返回结构关联 tool_call_id、状态、错误码、版本、延迟。
  7. 可观测与评测:统计工具选择准确率、参数准确率、执行成功率、重试率、重复副作用率、恢复率、P95 延迟;用故障注入验证超时/断网/空结果/恶意返回。

核心:把"模型的概率性动作"包在"确定性接口、权限与验证"之内。工具描述要短、清晰、互不重叠;能由规则确定的路由,不要把选择权交给模型。

上下文窗口越来越大怎么处理?压缩必然丢信息,如何最小化损失?

一句话结论:上下文治理的目标不是扩大窗口,而是在有限预算内保留"当前任务真正依赖的信息";压缩的关键是区分「可丢失的表达」与「不可丢失的状态」。

用户让 AI 排查订单导出超时: “10 万条订单导出要 60 多秒,希望降到 10 秒以内。先定位原因,不要修改代码,也不能改数据库结构。”

接下来聊了几十轮,AI 看了代码、执行了查询、读取了大量日志。后来用户补充: “可以修改导出模块并运行测试,但不要提交代码。”

这时上下文快满了。

  1. 直接概括,很容易把真正重要的东西压丢 如果只留下: “用户希望优化订单导出性能,已排查数据库,接下来修改代码。”

看起来保留了大意,却丢了很多决定后续行为的信息:

  • 验收条件是 10 万条、10 秒以内。
  • 不能改数据库结构。
  • 后来授权修改的是导出模块,不是整个系统。
  • 可以运行测试,不能提交代码。
  • “排查过数据库”到底发现了什么,哪些还只是猜测? 因此,压缩首先要保留的不是“聊过哪些话题”,而是下一步行动依赖的状态。
  1. 先抽取状态,再写摘要 可以形成这样的 checkpoint。以下编号均为演示,实际系统应指向可回读的原始记录。

目标,授权与约束,已确认事实,已完成的任务,下一步任务,完成状态 要解决什么、哪些地方不能动、现在查到了什么、哪些还没验证、下一步做什么

{
  "goal": "10 万条订单导出控制在 10 秒以内",
  "constraints": ["不能修改数据库结构", "不能提交代码"],
  "authorization": {
    "allowed": ["修改导出模块", "运行测试"],
    "source": "用户消息 M18"
  },
  "confirmed": [
    {
      "fact": "当前测试耗时 64 秒",
      "evidence": "测试记录 T7"
    }
  ],
  "hypotheses": ["逐条查询客户信息可能导致耗时"],
  "status": "已定位相关代码,尚未修改",
  "next": "验证批量查询方案"
}

这份记录里的内容,对应你熟悉的业务概念:

  • goal:验收标准。
  • constraints:业务规则。
  • authorization:本次允许的操作范围。
  • confirmed:已经有证据支持的事实。
  • hypotheses:待验证的判断。
  • status、next:任务进度。 其中,授权记录帮助模型理解任务边界;真正执行修改、提交等操作时,后端仍然负责检查权限。
  1. 日志可以移出窗口,但关键证据必须能找回来 模型提出调用请求,后端执行,再把结果提供给模型继续分析。 假设 queryLogs这个工具函数 查到几万行日志,后端可以先做投影、过滤和聚合,给模型返回:
{
  "runId": "R7",
  "durationMs": 64000,
  "finding": "订单循环中重复执行客户查询",
  "sample": ["少量有代表性的日志"],
  "rawLogId": "L12"
}
  1. 最近的原文,负责解决“刚才那个” 用户接着说: “就按刚才那个方案做,但客户名称为空时也要正常导出。”

如果只保留阶段摘要,AI 可能不知道“刚才那个方案”是哪一个。 因此,进入下一阶段时,输入可以这样组合:

  1. 每次阶段切换,都更新状态,而不是不断叠加摘要 定位完成后写一次 checkpoint;修改完成后再更新: 已完成:批量查询改造。 正确性检查:通过,证据 T21。 性能测量:尚未执行。 下一步:使用 D1 重新测量,判断是否达到 10 秒要求。 旧摘要可留在外部历史中,当前上下文主要携带最新状态。否则,几十份摘要本身也会造成上下文膨胀。

  2. 校验压缩效果,要看接手后会不会做错 压缩完成后,可以让接手的 AI 回答:

  • 验收的数据规模和耗时要求是什么?
  • 当前允许修改哪里?能不能改表、提交代码?
  • 哪些发现已确认,哪些只是猜测?
  • 哪些测试已经执行?结果在哪里?
  • 下一步应该做什么? 任何一项答错,都说明压缩丢失了关键状态。进一步评估时,可以比较使用完整历史和压缩上下文后的任务完成情况,检查约束遗漏、事实错误、证据恢复能力以及 Token 成本。

On this page