1. 别急着写Agent先想明白它要过几道关现在的AI大模型圈子最不缺的就是Agent项目。每家都有Demo你问它帮我写个登录接口它唰唰输出一串代码看起来无所不能。可一旦你真把它放进研发交付流程——让它去改Issue、提PR、跑测试、审代码——大多数项目当场翻车要么工具调不通要么模型在循环里出不来要么回答得一本正经但全是幻觉要么改一个Prompt导致另一个场景全线崩坏。我见过太多团队把调通一个API当成做完了Agent结果上线两周就灰溜溜撤回去。这中间的差距恰恰就是大厂级Agent项目和玩具Demo的分水岭。一个能进入真实研发交付流程的Agent不是模型提示词这么简单它背后至少需要四样东西运行底座模型跑在哪、工具怎么接、权限怎么控也就是标题里说的底座。Harness控制Agent不只有大脑还要有骨架。Harness负责把模型推理和工具调用编排成一个可控的循环。Loop与度量Agent跑起来之后你得知道它每次循环在干什么、干得好不好、花了多少钱。知识工程模型不知道你公司的私有代码和文档RAG知识库是让它先查资料再开口的关键。这篇文章我会按这四个模块逐个拆最后把它们串进一条真实的研发交付流水线里。无论你是想在公司做智能编码助手还是准备把Agent接入研发管理平台这套拆法都适用。先说第一个问题为什么有些Agent跑不起来。2. 运行底座MCP如何让Agent真正摸到研发工具2.1 MCP到底解决了什么问题很多人第一次听到MCPModel Context Protocol模型上下文协议第一反应是又一个新协议。但你把目光拉回实际开发场景就明白了Agent要干活必然要调用外部工具——拉取Git仓库代码、查Jira工单、读日志、跑测试、搜知识库。在没有统一标准之前每对接一个系统你都得为Agent写一套专用的工具适配代码。今天接GitLab写一个明天接飞书写一个后天接内部运维平台再写一个全部是重复劳动。MCP的作用就是把这些工具接入统一成一套标准协议。打个比方以前是每个设备配一个专用充电头现在变成了USB-C谁支持这个口就能插上去用。MCP Server暴露工具、资源和提示词MCP Host负责管理和调度MCP Client建立连接并转发请求。对做Agent的人来说这意味着你不需要关心对面系统的私有API细节只要对方提供一个MCP Server你的Agent就能直接调用它的能力。大厂为什么热衷这套因为研发交付流程里的系统太多了代码仓库、CI流水线、缺陷管理、文档平台、监控系统如果每个Agent项目各接一遍工程成本会高到无法接受。标准化之后一套工具可以被多个Agent复用也能让不同团队沉淀的能力互相流通。2.2 一个最小MCP Server长什么样MCP Server没有想象中那么复杂它的最小实现就是一个暴露若干工具的服务。以Python为例用FastMCP库几十行就能写出来from mcp.server.fastmcp import FastMCP mcp FastMCP(dev-tools) mcp.tool() def search_issue(keyword: str, project: str) - list[dict]: 在指定项目的缺陷管理系统中搜索Issue # 这里调用你的内部系统API issues call_issue_api(project, keyword) return [ {id: item[id], title: item[title], status: item[status]} for item in issues ] if __name__ __main__: mcp.run()从这个例子你可以看到模型对工具一无所知它只知道我有个search_issue工具传入关键字和项目名能拿到Issue列表。而MCP做的事情就是把这个能力以标准方式暴露给模型包括工具名字、参数结构、返回结果。模型在推理时看到这个工具描述就会决定要不要调用它。实际生产环境中工具描述本身需要下功夫。模型是靠工具名和描述来判断什么时候用、怎么用的。描述写得太笼统模型就会在无关场景误调用参数定义得不清晰模型就会传错值。这块需要你像写API文档一样认真打磨。2.3 底座层的三个坑MCP只是底座的一部分。把底座真正铺稳我实际踩过几个坑值得提前说第一个坑是工具调用的超时管理。模型发起工具调用后如果MCP Server卡住不返回Agent的循环会一直等在那里。默认超时时间一定要设而且要区分工具类型查询类工具可以给短超时耗时的构建类工具可以给长超时。否则一个Agent实例可能因为一个慢工具而挂掉半天。第二个坑是幂等性。Agent在循环中可能因为网络重试而重复调用同一个工具。如果一个工具是创建PR或打标签这类有副作用的操作重复调用会造成灾难。设计工具时要注意幂等比如创建PR前先检查是否已存在相同分支和标题的PR。第三个坑是权限。这是最容易被忽略的。很多团队图省事给Agent一个管理员Token这等于让一个可能失控的自动程序拿到全仓库权限。正确做法是给Agent单独申请最小权限凭证只开它完成特定任务所需的范围。后面讲研发交付集成时我还会详细说这一点。3. Harness控制层Agent有想法但不能让它乱跑3.1 Harness和Agent的分工很多人分不清Harness和Agent的区别觉得它们是同一个东西。我用一个老土的类比说明Agent是大脑负责做决策Harness是骨架加神经负责把决策变成可控的动作同时确保大脑不会乱来。具体到代码层面Harness要做的事情包括接收任务、组织上下文、调用模型推理、解析模型输出判断它到底是想要调用工具还是输出最终答案、执行工具调用、把结果反馈给模型、处理错误、管理循环终止条件。简单说Agent负责想Harness负责做和管理做的过程。为什么不能把这个循环直接写在业务代码里因为真实的研发流程天然是一个状态机有串行步骤有并行分支有条件跳转还有需要人工审批的暂停点。如果你用裸的while循环去写很快会发现代码里全是if-else和全局状态改一个分支就会引入新问题。最典型的是模型在多轮工具调用后需要回退一步重新规划手写循环处理这种场景极其痛苦。3.2 用LangGraph搭一个研发Agent的HarnessLangGraph是LangChain生态里专门做Agent编排的框架它的核心概念是状态图和节点。每一个节点是一段逻辑调用模型、执行工具、判断条件节点之间用有向边连接整个图驱动着状态流转。这个思路和研发流程的匹配度非常高。举个实际的例子做一个从Issue到PR的研发Agent它的Harness至少需要这几个节点from typing import TypedDict from langgraph.graph import StateGraph class AgentState(TypedDict): issue_id: str repo: str plan: list[str] current_step: int code_diff: str test_results: str pr_url: str def planner(state: AgentState) - dict: # 调用模型把Issue拆解成实现计划 plan llm.invoke(f为Issue {state[issue_id]} 生成实现计划) return {plan: plan} def executor(state: AgentState) - dict: # 按计划执行代码修改 diff implement_plan(state[repo], state[plan], state[current_step]) return {code_diff: diff} def verifier(state: AgentState) - dict: # 运行测试验证修改是否正确 results run_tests(state[repo], state[code_diff]) return {test_results: results} graph StateGraph(AgentState) # 定义流转 graph.add_node(planner, planner) graph.add_node(executor, executor) graph.add_node(verifier, verifier) graph.add_edge(planner, executor) graph.add_edge(executor, verifier) # 如果测试没通过回到executor重新修最多循环3次 graph.add_conditional_edges( verifier, decide_next_step, # 返回 pass 或 fix {pass: finish, fix: executor} )这个例子展示了Harness的典型形态。你看见的关键点是模型不在自由奔跑它每一步都被限定在图里该规划就规划该执行就执行该验证就验证出问题只能走预设的回退路径。3.3 硬性边界设计再聪明的模型也需要硬性控制。我强烈建议每个Harness都内置这几条规则不要等出了问题再补第一最大迭代次数。模型在复杂任务中容易陷入修不好就继续修的死循环。在Harness里设置一个最大步数上限比如15步超过就自动终止并输出当前进展交给人工判断。这比让模型无限循环省钱得多。第二人工审批节点。凡是涉及写操作、合并代码、修改配置的动作都应在Harness里设置人工确认节点。Harness执行到这一步时暂停等人在界面或IM里点了允许再继续。本质上这就是Human-in-the-loop它不会拖慢所有任务但能在关键节点拦住错误。第三工具白名单。Harness层面限定每个Agent实例能调用的工具集合。研发Agent可以调代码搜索、可以跑测试但没有权限调生产环境运维工具。这个白名单是底层能力边界和模型是否想调用无关。Harness设计的核心思路用一句话总结让模型有足够的自由度去处理复杂情况但所有自由度都必须在预设的轨道范围内。4. Loop与度量让Agent的每一次循环都可观测、可评估4.1 看清Agent循环的四个阶段Agent的运行本质是一个循环。拆开看每个循环包含四个阶段观察Observe读取当前任务和运行环境的状态比如拿到的Issue内容、当前的代码分支、上次工具调用的返回结果。推理Reason模型根据上下文决定下一步行动是继续调用工具还是产生最终输出。行动Act实际调用某个工具、执行代码修改、或者写一段文字。反思Reflect查看行动结果判断是否达成目标决定继续、回退还是终止。这个循环每走一遍就是一次Loop。Harness的职责之一是记录每个Loop的信息。很多Agent项目出问题不是模型不够聪明而是团队根本不知道模型在循环里做了什么。等到线上出Bug连基本的排查线索都没有。4.2 建立度量体系没有度量就没有改进。Agent的度量不像传统软件那样只看接口成功率要多维度一起看度量维度具体指标观测方式结果质量任务完成率、代码通过率、人工采纳率人工验收自动校验过程效率平均步数、单任务耗时、工具调用成功率Trace日志统计成本模型调用费用、Token消耗、GPU资源用量账单稳定性死循环率、超时率、异常中断率运行监控我个人的经验是链路指标比单点指标更重要。你单独测模型推理准确率可能很高但放进Agent循环里一次小错误会被后续步骤放大。真正要盯的是端到端任务完成率而不只是模型回答正确率。4.3 建立回归评估集和追踪系统想让Agent持续迭代两个基础设施必须有评估集和追踪系统。评估集我建议直接从真实任务里录。从历史Issue中挑20到50个有代表性的任务人工准备好期望最终产物比如一个修复后的PR、一段补全的测试代码、一份正确的变更说明。每次改动Prompt、换模型、调Harness结构都拿这批任务跑一遍回归看完成率是否下降。没有这个回归机制你很可能今天优化了A场景明天弄坏了B场景还不自知。追踪系统可以用LangSmith这类现成平台也可以自建。关键要求是每个Loop有唯一ID记录每次模型输入输出、每次工具调用的参数和返回结果、耗时和成本。这样一旦有问题你就能顺着Trace还原模型当时的决策过程而不是对着日志猜。这里有个容易犯的操作错误一开始就追求评估集规模大。实际上20条精心标注的任务比200条随便收集的任务有用得多。先把小评估集的通过率做上去再逐步扩充覆盖更多场景。5. 知识工程与RAG先给Agent配上企业知识库再谈干活5.1 为什么纯靠模型参数不够很多做Agent的人容易幻想大模型训练时见过天量代码应该什么都知道。现实是模型对它训练截止之后的代码一无所知更不熟悉你们公司内部的编码规范、架构设计文档和私有SDK用法。如果让Agent凭记忆回答这些私有知识问题它大概率会一本正经地编出一个看似合理的错误答案这就是幻觉。解决幻觉的主流方案是RAGRetrieval-Augmented Generation检索增强生成。核心逻辑很简单让模型在生成回答之前先从企业知识库中检索相关内容把检索结果作为上下文喂给模型模型再基于这些材料生成答案。模型不再背答案而是翻书找答案。这不仅能减少幻觉还能让回答带上可追溯的来源方便人工审计。5.2 Agentic RAG的实现路径RAG在Agent场景里有一个重要升级叫Agentic RAG。传统RAG是查一次、生成一次检索结果不好就直接拉胯。Agentic RAG则把检索本身变成了Agent可调用的工具Agent先判断这个问题是否需要查知识库查了之后发现结果不够它可以改写查询词重试或者换一个向量库再查。热词里那个fastapilangchainlanggraphragpgvector的AI Agentic RAG就是很典型的落地技术栈。整体链路我拆开说第一步是文档解析和清洗。把PDF、Word、Markdown等各种格式的文档转成纯文本去掉页眉页脚和无关噪音同时保留文档标题、作者、更新时间这些元数据后面检索和权限控制都要用。第二步是分块。文档不能整篇塞给模型上下文装不下相关性也会被稀释。通常按固定长度或语义结构切块一般几百个Token一块。块太大会混入无关内容块太小会丢失上下文。这里需要根据文档类型多试几次。第三步是向量化。把每个文本块通过Embedding模型转成向量。中文场景要注意选对模型比如bge系列、m3e系列在这块的表现都不错。向量化质量直接决定检索效果这也是很多人忽略的地方。第四步是存储。向量数据库可以选pgvector直接复用PostgreSQL小团队够用或Milvus数据量大、高并发时更合适。热词里的pgvector路线好处是少维护一个组件业务数据和向量在一起。第五步是检索和重排。通常用向量检索加关键词检索的混合模式再把两者结果合并交给重排模型排序取最相关的几段作为上下文。重排这一步很关键很多人光做向量检索就草草上线效果差再想加就麻烦了。from langchain_community.vectorstores import PGVector from langchain_community.embeddings import HuggingFaceEmbeddings embeddings HuggingFaceEmbeddings(model_nameBAAI/bge-large-zh-v1.5) vector_store PGVector( connection_stringpostgresql://user:passlocalhost:5432/ragdb, embedding_functionembeddings, collection_namecompany_docs ) # 检索时配合BM25关键词检索做混合召回 results vector_store.similarity_search_with_score(如何部署内部服务, k10)知识工程落到研发交付场景时最常用的一个结合点是Agent在修改代码前先检索项目的README、架构文档、历史Issue和提交记录理解代码仓库的设计意图和约定再动代码。很多Agent改出来的代码能跑但不符合项目风格根本原因就是跳过了这一步。5.3 知识库维护与权限知识库不是一次性建好就完事的。文档是持续更新的知识库也要有同步机制文档变更后触发重新分块和向量化并保留版本记录。否则Agent会拿三个月前的过期文档给用户当依据。权限隔离同样要提前设计。不同项目、不同团队的文档放进独立的Collection或带上项目标签检索时按当前任务的项目ID做过滤。Agent只能检索到它被允许访问的知识这是底线要求。不然一个Agent同时接两个客户项目很可能把A的隐私文档检索出来带到B的回答里。关于RAG的效果我的切身体会是项目落地过程中80%的精力会花在数据治理上而不是模型调优上。文档解析乱、分块不合理、embedding选错这些问题都会让检索效果很差。遇到检索不准先别急着换大模型把前面这几步重新梳理一遍往往收益更大。6. 把Agent嵌入真实研发交付流PR、Issue、CI6.1 事件驱动的接入方式前面讲的底座、Harness、度量、知识库都是单机能力。Agent要进入真实研发交付流程必须有合适的接入方式。最常用的是事件驱动研发平台产生事件比如有人提了PR、有人评论了Issue、代码推到了主干分支Webhook把事件推给Agent服务Agent服务唤醒Harness开始执行。举一个完整的PR助手场景开发者在GitHub或GitLab上创建了一个PR。Webhook收到pull_request事件Agent服务被触发。Harness启动先拉取PR的diff内容。Agent用RAG检索项目相关文档、历史Issue、团队代码规范。模型基于diff和检索结果进行分析检查潜在Bug、性能问题、代码风格、缺失的测试用例。Agent在PR上提交评论逐条指出问题并给出修改建议。如果配置了自动修复权限Agent还可以创建一个修改分支但必须先经过人工审批才能合并。这个过程里Human-in-the-loop体现在评论和审批环节Agent给意见人做最终决定。这个设计不是保守而是必要。代码合并是研发流程里风险最高的操作之一Agent现阶段适合当高水平的评审助手不适合当无人监管的提交者。6.2 接入研发流程的落地步骤如果要从零开始做我建议按这个节奏推进第一步影子模式运行。Agent先只生产分析结果不执行任何写操作。比如它分析PR后产出如果是我会这样改的建议但不真的改代码。这个阶段用来验证准确率同时让团队建立对Agent的信任。第二步低风险动作自动化。等建议准确率足够高、误报率降下来了让它做一些低风险操作比如自动生成PR描述、自动补充单元测试、自动给Issue打标签分优先级。这些动作即使出错成本也可控。第三步逐步开放高权限动作。比如自动修Bug并提交修复PR但必须保留分支保护和人工审批。观察一段时间的线上表现再考虑能不能放开更多。注意Agent token的权限配置。这个我前面提过一次这里再强调给Agent的凭证一定是独立申请的最小权限。比如PR助手只需要读写某个仓库的权限就不要给它整个组织的权限。很多安全问题不是模型出问题而是权限配置太宽了。6.3 上线后的度量与迭代接入真实流程后需要用数据回答这几个问题PR评审时间有没有缩短Bug逃逸率有没有下降Agent建议的人工采纳率是多少误报率呢这些指标直接决定团队信不信这套系统、愿不愿意继续用。我见过一个团队把Agent接进PR流程后只看推荐了多少条建议这个数字一度觉得效果很好直到研发反馈建议质量不行基本看都不看。后来把指标改成建议采纳率才发现实际不到两成。所以度量指标的选择一定要贴近真实业务价值而不是只盯着Agent活跃度这种虚荣指标。在并行项目多、仓库多的团队里还可以给Agent加一个仓库优先级的配置让它优先处理核心项目的PR避免所有仓库一拥而上把算力耗光。最后把这篇文章的核心串起来运行底座负责让Agent接得上工具Harness负责让Agent跑得稳Loop与度量负责让Agent成效看得见知识工程负责让Agent回答有依据事件驱动把这一切接入真实的研发交付流程。这套体系不是一次搭完就结束的它是一个持续迭代的工程。我个人的建议是从最简单的PR助手或文档助手起步先跑通一条链路再逐步扩展场景。每一步都要让工程师看到实实在在的效率提升他们才会愿意配合Agent一起工作。一个真正落地的Agent项目团队里多了一个不知疲倦的初级工程师而不是多了一个大家都要盯着它别闯祸的实习生。