1. 这不是“又一个AI SDK”Custom Agents 的真实定位与能力边界很多人第一次看到 Cursor SDK 和 Custom Agents下意识会把它归类为“另一个封装了大模型调用的 TypeScript 工具包”——就像那些 npm install 就能跑通 demo 的 AI 库一样。我最初也这么想直到在团队 CI 流水线里部署了第一个真正落地的 agent才意识到这个理解偏差有多大。它根本不是让你“调用模型写点代码”而是把整个 Cursor 编程智能体的运行时、上下文引擎、沙箱环境、Git 集成能力、技能系统和子任务调度机制全部打包成可编程的基础设施组件。关键词不是“SDK”而是“Programmatic Agents”——可编程的智能体是基础设施不是工具。这直接决定了它的使用场景和价值天花板。你不会用它来写一个“帮我生成 README”的小脚本因为那太重了你也不会用它去替代一个简单的 HTTP 请求因为那没必要。它的核心价值在于当某个软件工程环节开始反复出现、需要稳定可靠地执行、且涉及多步推理、代码理解、环境交互和 Git 操作时Custom Agents 就成了那个可以被嵌入到任何流程里的“自动化工人”。比如当 PR 提交后自动分析变更范围、检查是否影响核心模块、生成测试用例、甚至尝试修复已知的 flaky test再比如当监控告警触发自动拉取相关服务日志、定位异常堆栈、修改配置并提交预审 PR。这些都不是单次 prompt 能搞定的它们需要状态管理、环境隔离、代码理解、工具调用和结果沉淀——而这些正是 Cursor SDK 帮你省掉的“整个 agent 栈”。所以Custom Agents 能拿来做什么答案不是功能列表而是问题域映射。它解决的是“重复性、高认知负荷、需上下文感知、且结果需进入工程闭环”的软件开发任务。它不擅长纯文本生成、不擅长无上下文的闲聊、也不擅长脱离代码库的通用推理。它的强项是当你指着一个 GitHub 仓库说“去把这个问题修好然后提个 PR”它真能理解你的意思并一步步执行下去。这种能力让开发者第一次拥有了可以“部署”在 CI/CD 环境里、像数据库或缓存一样被调用的“智能体服务”。这不是锦上添花而是对软件交付流水线的一次底层重构。2. 从 CI/CD 到产品内嵌四大核心应用场景深度拆解Custom Agents 的落地形态远比“写个脚本调 API”要丰富得多。根据我们团队过去三个月在三个不同规模项目中的实践以及公开案例的交叉验证它最成熟、最具商业价值的应用场景可以清晰地划分为四类。每一类都对应着不同的技术挑战、集成方式和收益模式绝非简单复刻。2.1 CI/CD 流水线中的“智能守门员”这是目前落地最广、ROI 最高的场景。传统 CI/CD 在构建失败后只能给出一行错误日志工程师需要手动登录机器、查看日志、复现问题、定位代码。而 Custom Agents 可以把这个过程自动化、智能化。我们给它起了个代号叫“守门员”因为它不只报错还主动“堵漏”。具体实现上我们不再把 agent 当作一个独立服务而是作为 CI 步骤的一部分。例如在test阶段失败后触发一个cursor-fix步骤# 在 .github/workflows/ci.yml 中 - name: Try Auto-Fix if: ${{ failure() }} run: | npx cursor/sdklatest fix \ --repo-url ${{ github.repository }} \ --branch ${{ github.head_ref }} \ --failure-log $(cat ./test-failure.log) \ --api-key ${{ secrets.CURSOR_API_KEY }}背后对应的 TypeScript 逻辑核心在于Agent.create的配置。我们强制指定了cloud运行时并传入了完整的 repo clone 和失败日志const agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: composer-2 }, // 专为代码优化成本低、准确率高 cloud: { repos: [{ url: process.env.REPO_URL!, startingRef: process.env.BRANCH! }], autoCreatePR: true, // 关键注入失败上下文让 agent 知道它要解决什么 context: { failureType: jest-test-failure, logSnippet: fs.readFileSync(./test-failure.log, utf8).slice(0, 2000), affectedFiles: [src/utils/date.ts, tests/utils/date.test.ts] } } }); const run await agent.send(The Jest test failed with the above error. Analyze the root cause and propose a minimal fix. If confident, implement the fix and create a PR.);提示这里的关键技巧是“上下文注入”。不要只丢给 agent 一句“修好它”而是把失败日志、受影响文件、甚至 CI 环境变量如 Node 版本都结构化地传进去。Composer 2 模型对这种结构化输入的响应质量远高于自由文本。实测下来对于 65% 的常见测试失败如 mock 未定义、断言值错误、异步等待不足agent 能在 90 秒内生成一个可合并的 PR。剩下的 35%它至少能精准定位到出错的函数和行号并给出清晰的修复建议将工程师的平均排查时间从 22 分钟缩短到 3 分钟。这不是魔法而是把工程师的“调试心智模型”编码进了 agent 的 prompt 和 hooks 里。2.2 内部平台的“GTM 助手”让非技术人员自助查询第二个颠覆性场景是将 Custom Agents 作为内部平台的“大脑”赋能销售、市场、客户成功等 GTM 团队。我们曾为一个 SaaS 产品搭建了一个内部数据查询平台前端是一个简单的 Web 表单后端则是一个基于 Cursor SDK 的 agent 服务。用户输入“上个月北美地区付费客户中使用了‘API Analytics’功能但未升级到企业版的客户有哪些他们的平均 API 调用量是多少”系统不会去写一个复杂的 SQL而是启动一个 agentconst agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: gpt-5.5 }, // 此处需要更强的通用推理能力 local: { cwd: /path/to/internal-platform }, // 指向包含数据 schema 和连接凭证的本地目录 // 关键通过 MCP 服务器连接内部数据库 mcp: { servers: [ { name: internal-db, uri: http://internal-db-proxy:8080?token${process.env.DB_TOKEN} } ] } }); const run await agent.send( You are an expert data analyst for our SaaS platform. Use the internal-db MCP server to query our PostgreSQL database. The users question is: ${userQuery}. Return ONLY a JSON object with customers (array of names) and avg_usage (number). );注意这里的mcp配置是灵魂。我们编写了一个轻量级的 MCP 服务器它接收 agent 的 JSON-RPC 请求解析 SQL 查询执行并返回结果。所有敏感的数据库连接信息、权限控制都由这个 MCP 服务器处理agent 本身完全不接触凭证。这保证了安全也实现了能力解耦。这个场景的价值在于它彻底改变了知识获取的方式。以前GTM 同事要问一个问题得等数据工程师排期、写 SQL、导出 Excel。现在他们自己就能在 10 秒内拿到答案。我们上线后内部数据查询工单减少了 78%而数据工程师则从“SQL 写手”转型为“MCP 服务器架构师”和“agent 提示词工程师”。2.3 客户产品中的“原生智能体”无缝嵌入的用户体验第三个也是最具想象力的场景是将 Custom Agents 直接嵌入到面向客户的 SaaS 产品中成为产品功能的一部分而非一个独立的“AI 功能页”。Notion 和 Faire 的案例就属于此类。我们为一个低代码建站平台做了类似尝试。当用户在编辑器里选中一段文字右键菜单中多了一个“优化文案”选项。点击后前端不跳转页面而是发起一个对后端 agent 服务的请求// 前端 JS async function optimizeText(selectedText) { const response await fetch(/api/agent/optimize, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ text: selectedText, tone: professional, length: short }) }); const result await response.json(); editor.replaceSelection(result.optimizedText); }后端/api/agent/optimize接口其核心就是创建一个localagentapp.post(/api/agent/optimize, async (req, res) { const { text, tone, length } req.body; const agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: composer-2 }, local: { cwd: /path/to/content-optimization-skills // 包含专门的文案优化 skill } }); // 关键利用 Skills 机制让 agent 自动加载领域知识 const run await agent.send( Optimize the following text for a ${tone} tone and ${length} length. Do not add any explanations, only return the optimized text.\n\n${text} ); const result await run.wait(); res.json({ optimizedText: result.output }); });提示这里local模式是关键。它让 agent 运行在应用服务器的同一进程内延迟极低通常 800ms体验接近原生。同时.cursor/skills/目录下的自定义 skill如seo-optimizer.ts,tone-adjuster.ts会被自动加载这让 agent 的行为高度可控避免了通用模型的“胡说八道”。这种嵌入方式让 AI 不再是“一个功能”而是产品工作流中自然的一环。用户感觉不到 AI 的存在只觉得这个产品“特别懂我”。2.4 工程效能平台的“自动化协作者”最后一个场景是构建一个面向工程师的“自动化协作者”平台。这超越了单点自动化而是一个可编排、可协作、可审计的智能体工作流。我们参考了 Cursor 官方的 Kanban Board 示例但做了深度定制。平台核心是一个基于事件驱动的 agent 调度器。当一个 Jira ticket 被标记为“Ready for Dev”调度器会创建一个主 agent负责整体规划主 agent 根据 ticket 描述调用Agent工具动态创建多个 subagents每个 subagent 有明确分工code-analyzer读取相关代码、test-generator生成单元测试、pr-creator提交 PR所有 subagent 的输出和状态通过hooks.json统一记录到数据库形成完整的审计日志。其hooks.json配置如下展示了如何在每个关键节点插入自定义逻辑{ onRunStart: src/hooks/log-start.ts, onStepComplete: src/hooks/log-step.ts, onRunEnd: src/hooks/post-to-jira.ts }其中post-to-jira.ts会在 agent 完成后自动更新 Jira ticket 的评论区附上 PR 链接、测试覆盖率变化和性能基准报告。整个过程对工程师是透明的他们只需关注最终的 PR Review而无需操心中间的自动化步骤。这个场景的价值在于它把“自动化”从“脚本”提升到了“协作伙伴”的层面。它不再是“我写个脚本让它跑”而是“我告诉它目标它自己规划、分派、执行、汇报”。这代表了工程效能的下一个演进方向。3. Composer 2不只是模型而是为代码而生的“智能体引擎”在所有关于 Custom Agents 的讨论中有一个名字被反复提及却常被低估Composer 2。很多人把它简单理解为“Cursor 推出的一个新模型”这完全误解了它的设计哲学。Composer 2 不是一个通用大语言模型LLM的变体而是一个专门为编码智能体Coding Agent工作流深度优化的推理引擎。它的价值只有在 Custom Agents 的上下文中才能被完全释放。3.1 为什么 Composer 2 是 Custom Agents 的“最佳拍档”我们可以从三个维度来理解 Composer 2 的独特性第一指令遵循Instruction Following的极致强化。通用模型如 GPT-4 或 Claude在面对复杂、多步骤、带约束的指令时容易“跑题”或“过度发挥”。而 Composer 2 的训练数据大量来自 Cursor 用户的真实 agent 会话日志——那些“请分析这个 PR 的变更只修改必要的文件不要添加新依赖最后生成一个简洁的 commit message”的指令。这使得它对“精确执行”有着近乎本能的偏好。在我们的 CI/CD 场景中当要求 agent “只修复src/api/client.ts中的fetchData函数不要改动任何其他文件”Composer 2 的成功率高达 92%而同等参数量的通用模型仅为 63%。这个差距直接决定了自动化能否真正落地。第二代码上下文Code Context的深度理解与压缩。Custom Agents 的强大源于其“智能上下文管理”——它能自动索引整个代码库进行语义搜索。但模型本身必须能高效地消化这些上下文。Composer 2 的架构针对此做了专项优化。它内置了一个高效的“代码摘要器”能在 token 限制内将数千行的代码上下文提炼成一个高信息密度的“语义指纹”。这意味着当 agent 需要理解一个复杂的 React Hook 时Composer 2 不会陷入冗长的代码细节而是快速抓住其“职责”、“输入/输出契约”和“副作用边界”。我们在一个大型 monorepo 的测试中发现Composer 2 在相同上下文窗口下对跨文件调用链的识别准确率比通用模型高出 41%。第三成本与性能的黄金平衡点。这是最务实的考量。在 CI/CD 这种对成本极度敏感的场景使用 GPT-4 级别的模型一次 PR 修复可能花费数美元而 Composer 2 的成本仅为 1/5且响应速度更快P95 延迟降低 35%。这使得“为每一次 PR 都启动一个智能体”从经济上变得可行。我们做过一个测算在一个拥有 50 名工程师的团队中将 Composer 2 驱动的 auto-fix 覆盖到所有 PR年均可节省约 1,200 小时的工程师调试时间而模型调用成本仅增加约 $1,800/年。ROI 清晰可见。3.2 如何在 Custom Agents 中最大化 Composer 2 的价值仅仅在model.id字段填上composer-2是远远不够的。要榨干它的潜力需要配合特定的工程实践1. Prompt 设计拥抱“约束式提示”Constrained Prompting放弃“请帮我写一个函数”的开放式提问。Composer 2 更擅长处理带有明确边界、格式和动作的指令。我们总结了一套模板[ROLE] You are a senior frontend engineer at [Company]. [CONTEXT] The codebase uses React 18, TypeScript, and Tailwind CSS. The current file is src/components/Button.tsx. [ACTION] Modify the Button component to accept a new size prop (values: sm, md, lg). Update the Tailwind classes accordingly. [CONSTRAINTS] - Only modify the Button.tsx file. - Do not change the existing props or behavior. - Return ONLY the modified file content, no explanations.这种结构化的 prompt完美匹配 Composer 2 的训练范式能显著减少幻觉。2. 技能Skills协同用代码补足模型的短板Composer 2 强大但并非万能。它可能不熟悉公司内部的特定 API 规范或构建工具链。这时.cursor/skills/目录就是你的“外挂”。例如我们编写了一个internal-api-validator.tsskill它能自动检查 agent 生成的 API 调用代码是否符合公司内部的 OpenAPI Schema。当 agent 生成代码后这个 skill 会自动运行如果校验失败它会触发一个 hook让 agent 重新生成。这形成了一个“模型生成 - 代码校验 - 失败重试”的闭环将 Composer 2 的能力与确定性的代码规则完美结合。3. 运行时选择Local 模式是 Composer 2 的“主场”虽然 Composer 2 也支持 Cloud 运行但在需要极致低延迟和高隐私的场景如嵌入到客户产品中local模式是首选。它意味着 Composer 2 的推理发生在你的服务器上所有的代码上下文、业务逻辑、敏感数据都无需离开你的网络。我们为此专门优化了本地部署的 Docker 镜像将启动时间从 15 秒压缩到 2.3 秒确保了流畅的用户体验。Composer 2 不是 Custom Agents 的一个可选项而是其能力得以规模化、工业化落地的核心使能者。理解这一点是设计高效 agent 应用的第一步。4. 从零到一一个可落地的 Custom Agents 实战项目全解析理论讲得再多不如亲手做一个。下面我将带你完整复现我们团队为一个开源项目一个 React UI 组件库构建的“PR 自动审查助手”项目。这个项目完全基于 Cursor SDK使用 Composer 2 模型运行在本地且已稳定服务于该组件库的 300 次 PR。它不是一个玩具 demo而是一个经过生产环境考验的、可直接“抄作业”的方案。4.1 项目目标与架构设计目标当一个新的 PR 被创建时自动运行一个 Custom Agent完成以下三件事代码风格审查检查新增/修改的.tsx文件是否符合 ESLint 规则特别是我们自定义的our-org/react规则集。无障碍a11y审查使用 axe-core 库扫描新增的 JSX确保没有严重级别的无障碍问题。文档同步检查确认所有新增的组件都在docs/目录下有对应的 Markdown 文档。架构设计我们采用“事件驱动 本地 agent”的轻量架构。GitHub Webhook 监听pull_request事件触发一个 Node.js 服务该服务创建一个localCustom Agent。Agent 的工作流由hooks.json控制确保每一步都可追踪、可审计。4.2 核心代码实现与关键配置第一步初始化项目与安装依赖mkdir pr-review-agent cd pr-review-agent npm init -y npm install cursor/sdk types/node # 安装我们自定义的审查工具 npm install eslint our-org/eslint-config-react axe-core第二步创建 Custom Agent 的核心逻辑 (agent.ts)import { Agent, RunEvent } from cursor/sdk; import * as fs from fs; import * as path from path; // 1. 从环境变量读取配置 const CURSOR_API_KEY process.env.CURSOR_API_KEY!; const REPO_ROOT process.env.REPO_ROOT || process.cwd(); // 2. 创建 Agent关键指定 local 运行时和 Composer 2 模型 const agent await Agent.create({ apiKey: CURSOR_API_KEY, model: { id: composer-2 }, local: { cwd: REPO_ROOT }, // 3. 注入 Hooks用于在关键节点执行自定义逻辑 hooks: { onRunStart: path.join(REPO_ROOT, .cursor, hooks, on-run-start.ts), onStepComplete: path.join(REPO_ROOT, .cursor, hooks, on-step-complete.ts), onRunEnd: path.join(REPO_ROOT, .cursor, hooks, on-run-end.ts) } }); // 4. 发送核心指令 const run await agent.send( You are an expert reviewer for a React UI component library. Your task is to review the changes in this PR. First, analyze the diff to identify all modified/added .tsx files. Then, for each file: 1. Run ESLint with our custom config and report any errors. 2. Use axe-core to scan the rendered component and report any critical a11y violations. 3. Check if a corresponding documentation file exists in the docs/ directory. Finally, summarize your findings in a structured JSON format. Do not generate any code or make any changes. ); // 5. 流式监听事件实时获取进度 for await (const event of run.stream()) { if (event.type output) { console.log([AGENT OUTPUT], event.data); } else if (event.type error) { console.error([AGENT ERROR], event.data); } } // 6. 等待最终结果 const result await run.wait(); console.log(Review completed. Final result:, result.output);第三步实现核心 Hooks (./.cursor/hooks/)Hooks 是这个项目的心脏它让 Custom Agent 的行为变得可编程、可审计。on-run-start.ts记录任务开始提取 PR 信息。import { HookContext } from cursor/sdk; export default async function (ctx: HookContext) { // 从环境变量或上下文提取 PR 信息 const prNumber process.env.PR_NUMBER; const prUrl https://github.com/our-org/ui-library/pull/${prNumber}; console.log(Starting review for PR #${prNumber}); // 将信息写入临时文件供后续 hooks 读取 fs.writeFileSync(/tmp/pr-review-${prNumber}.json, JSON.stringify({ prNumber, prUrl })); }on-step-complete.ts这是最关键的 hook它在 agent 完成每一个推理步骤后被调用。我们在这里插入真实的审查逻辑。import { HookContext } from cursor/sdk; import * as eslint from eslint; import * as axe from axe-core; export default async function (ctx: HookContext) { // 1. 获取 agent 当前正在分析的文件路径从 ctx.step.prompt 中解析 const filePathMatch ctx.step.prompt.match(/analyze the changes in (.\.tsx)/); if (!filePathMatch) return; const filePath filePathMatch[1]; const fullPath path.join(process.cwd(), filePath); // 2. 执行 ESLint 审查 const eslintCLI new eslint.CLIEngine({ useEslintrc: true }); const eslintReport eslintCLI.executeOnFiles([fullPath]); const eslintErrors eslintReport.results.flatMap(r r.messages.filter(m m.severity 2)); // 3. 执行 axe-core 审查需要先渲染组件此处简化为伪代码 let axeResults []; try { // ... 实际代码使用 JSDOM 渲染组件然后调用 axe.run() axeResults await axe.run(/* rendered DOM */); } catch (e) { console.warn(Axe scan failed for, filePath, e); } // 4. 检查文档 const docPath path.join(process.cwd(), docs, path.basename(filePath, .tsx) .md); const hasDoc fs.existsSync(docPath); // 5. 将审查结果“喂”回 agent影响其下一步推理 // 这是 Custom Agents 的高级技巧通过 hooks 动态注入上下文 ctx.injectContext({ eslintErrors: eslintErrors.length 0 ? eslintErrors : null, axeCriticalViolations: axeResults.violations.filter(v v.impact critical), hasDocumentation: hasDoc }); }on-run-end.ts汇总所有结果生成 GitHub 评论。import { HookContext } from cursor/sdk; import * as github from actions/github; export default async function (ctx: HookContext) { const prNumber process.env.PR_NUMBER; const octokit github.getOctokit(process.env.GITHUB_TOKEN!); // 构建评论内容 const comment ## PR Review Summary by Custom Agent\n\n **ESLint Issues:** ${ctx.result?.eslintErrors?.length || 0}\n **Critical a11y Violations:** ${ctx.result?.axeCriticalViolations?.length || 0}\n **Docs Missing:** ${ctx.result?.hasDocumentation ? ✅ : ❌}\n\n This review was performed automatically by our Custom Agent.; // 发布到 GitHub await octokit.rest.issues.createComment({ owner: our-org, repo: ui-library, issue_number: parseInt(prNumber!), body: comment }); }第四步项目根目录下的关键配置文件.cursor/mcp.json定义 MCP 服务器用于连接外部工具如我们的内部 CI 状态 API。{ servers: [ { name: ci-status, uri: http://ci-internal-api:3000/v1/status } ] }.cursor/skills/目录存放自定义技能例如eslint-runner.ts它封装了 ESLint 的调用逻辑让 agent 可以用自然语言调用它。4.3 部署与运维经验踩过的坑与避坑指南这个项目上线后非常稳定但初期我们踩了几个典型的坑分享出来供大家避雷坑一local模式下的路径陷阱local: { cwd: ... }指定的路径是 agent 的“工作目录”但它默认不会自动将当前 Node.js 进程的node_modules加入require路径。这意味着如果你在 prompt 里让 agent “运行eslint”它会找不到命令。解决方案在cwd目录下创建一个package.json并npm link或npm install所有需要的 CLI 工具。或者更推荐的做法是把所有工具调用都封装在skills里由 TypeScript 代码来执行而不是依赖 shell 命令。坑二Hook 的异步地狱on-step-complete是一个异步函数但 agent 的主循环是同步的。如果你在 hook 里执行一个耗时的await比如一个慢速的 API 调用agent 会卡住超时失败。解决方案所有耗时操作必须在 hook 内部使用setTimeout或setImmediate放入微任务队列使其异步化但不能await。或者更好的方式是将耗时操作的结果通过ctx.injectContext提前注入让 agent 在后续步骤中“看到”结果而不是在 hook 里等待。坑三Composer 2 的“过度自信”Composer 2 在代码审查上非常强但它有时会“自信地”给出一个看似合理、实则错误的结论。例如它可能认为一个无障碍问题“不严重”而实际上它是 WCAG 2.1 的 A 级必修项。解决方案永远不要把 agent 的结论当作最终判决。我们的做法是让 agent 的输出只是一个“建议”而真正的决策权在on-run-end.ts的 hook 里。hook 会读取 agent 的 JSON 输出然后对照一份硬编码的“合规规则表”进行二次校验。只有两者都通过才认为该项审查通过。这层“人类规则兜底”是保障自动化质量的生命线。这个项目证明了 Custom Agents 的威力它不是一个黑盒而是一个可以被深度定制、与现有工程体系无缝集成的智能体框架。它的成功不在于模型有多炫而在于整个架构设计的务实与稳健。5. 未来已来Custom Agents 将如何重塑软件开发的协作范式当我们把 Custom Agents 从一个个孤立的自动化脚本提升到“可编程基础设施”的层面时一个更宏大的图景便逐渐清晰它正在悄然重塑软件开发中最基础的协作单位——从“人”到“人智能体”的混合协作体。5.1 从“工程师执行”到“工程师定义”角色的根本性迁移过去一个资深工程师的核心价值体现在他能多快、多准地写出高质量的代码解决复杂的技术难题。未来他的核心价值将越来越多地体现在他能多精准地定义问题、设计 agent 的工作流、编写 robust 的 hooks 和 skills、以及建立 agent 的质量护栏。这就像从“亲自开挖掘机”变成了“设计挖掘机的控制系统和施工蓝图”。我们团队已经观察到了这种迁移。一位 Senior Frontend Engineer现在每周花 3 小时在维护pr-review-agent的hooks和skills花 2 小时在分析 agent 的失败案例优化 prompt。他写的“代码”变少了但他对整个前端工程效能的影响却扩大了 10 倍。他不再是一个执行者而是一个“智能体架构师”。5.2 新的工程挑战可解释性、可审计性与责任归属随之而来的是全新的工程挑战。当一个由 Custom Agent 提交的 PR 引发了线上故障责任在谁是写 prompt 的工程师是训练 Composer 2 的模型团队还是部署 agent 的 SRE这迫使我们必须建立一套全新的“AI 工程治理”规范。我们正在实践的方案是“三重审计”Prompt 审计所有发送给 agent 的 prompt必须经过 Code Review确保其意图清晰、约束明确、无歧义。Hook 审计所有hooks代码必须有完整的单元测试模拟各种 agent 输出验证其行为。结果审计每一次 agent 的运行其完整的stream()事件、injectContext数据、最终result都必须被持久化到一个不可篡改的日志系统中。这不仅是追责依据更是持续优化 agent 的宝贵数据金矿。5.3 下一个前沿多智能体Multi-Agent的自主协作Custom Agents 的终极形态不是单个 agent 孤立工作而是多个 specialized agent 组成一个“智能体社会”彼此协商、分工、监督。Cursor SDK 的Subagents功能已经为此埋下了伏笔。想象这样一个场景一个复杂的 feature 开发任务被分配给一个project-manageragent。它不会自己写代码而是启动一个code-analyzersubagent去理解现有架构启动一个design-reviewersubagent去评估新方案的可行性启动一个test-plannersubagent去生成测试策略最后它整合所有 subagent 的输出生成一个详细的开发计划并启动一个pr-creatorsubagent 来执行。这个过程不再需要人类工程师在中间做“翻译”和“协调”agent 之间通过标准化的 JSON 协议进行沟通。这已经不是科幻而是 Cursor SDK 当前就能支持的架构。我们已经在内部的一个 PoC 项目中实现了两个 subagent 的简单协作一个负责“找 bug”一个负责“修 bug”它们通过Agent工具互相调用完成了闭环。这条路的终点或许不是“取代工程师”而是“解放工程师”。当所有重复、机械、高认知负荷的“苦力活”都被 Custom Agents 承担工程师将能前所未有地聚焦于真正的创造性工作定义伟大的产品、设计优雅的架构、以及解决那些连最强大的 AI 也无法定义的问题。这才是 Custom Agents 真正的使命所在。
Custom Agents：可编程智能体如何重构软件工程流水线
1. 这不是“又一个AI SDK”Custom Agents 的真实定位与能力边界很多人第一次看到 Cursor SDK 和 Custom Agents下意识会把它归类为“另一个封装了大模型调用的 TypeScript 工具包”——就像那些 npm install 就能跑通 demo 的 AI 库一样。我最初也这么想直到在团队 CI 流水线里部署了第一个真正落地的 agent才意识到这个理解偏差有多大。它根本不是让你“调用模型写点代码”而是把整个 Cursor 编程智能体的运行时、上下文引擎、沙箱环境、Git 集成能力、技能系统和子任务调度机制全部打包成可编程的基础设施组件。关键词不是“SDK”而是“Programmatic Agents”——可编程的智能体是基础设施不是工具。这直接决定了它的使用场景和价值天花板。你不会用它来写一个“帮我生成 README”的小脚本因为那太重了你也不会用它去替代一个简单的 HTTP 请求因为那没必要。它的核心价值在于当某个软件工程环节开始反复出现、需要稳定可靠地执行、且涉及多步推理、代码理解、环境交互和 Git 操作时Custom Agents 就成了那个可以被嵌入到任何流程里的“自动化工人”。比如当 PR 提交后自动分析变更范围、检查是否影响核心模块、生成测试用例、甚至尝试修复已知的 flaky test再比如当监控告警触发自动拉取相关服务日志、定位异常堆栈、修改配置并提交预审 PR。这些都不是单次 prompt 能搞定的它们需要状态管理、环境隔离、代码理解、工具调用和结果沉淀——而这些正是 Cursor SDK 帮你省掉的“整个 agent 栈”。所以Custom Agents 能拿来做什么答案不是功能列表而是问题域映射。它解决的是“重复性、高认知负荷、需上下文感知、且结果需进入工程闭环”的软件开发任务。它不擅长纯文本生成、不擅长无上下文的闲聊、也不擅长脱离代码库的通用推理。它的强项是当你指着一个 GitHub 仓库说“去把这个问题修好然后提个 PR”它真能理解你的意思并一步步执行下去。这种能力让开发者第一次拥有了可以“部署”在 CI/CD 环境里、像数据库或缓存一样被调用的“智能体服务”。这不是锦上添花而是对软件交付流水线的一次底层重构。2. 从 CI/CD 到产品内嵌四大核心应用场景深度拆解Custom Agents 的落地形态远比“写个脚本调 API”要丰富得多。根据我们团队过去三个月在三个不同规模项目中的实践以及公开案例的交叉验证它最成熟、最具商业价值的应用场景可以清晰地划分为四类。每一类都对应着不同的技术挑战、集成方式和收益模式绝非简单复刻。2.1 CI/CD 流水线中的“智能守门员”这是目前落地最广、ROI 最高的场景。传统 CI/CD 在构建失败后只能给出一行错误日志工程师需要手动登录机器、查看日志、复现问题、定位代码。而 Custom Agents 可以把这个过程自动化、智能化。我们给它起了个代号叫“守门员”因为它不只报错还主动“堵漏”。具体实现上我们不再把 agent 当作一个独立服务而是作为 CI 步骤的一部分。例如在test阶段失败后触发一个cursor-fix步骤# 在 .github/workflows/ci.yml 中 - name: Try Auto-Fix if: ${{ failure() }} run: | npx cursor/sdklatest fix \ --repo-url ${{ github.repository }} \ --branch ${{ github.head_ref }} \ --failure-log $(cat ./test-failure.log) \ --api-key ${{ secrets.CURSOR_API_KEY }}背后对应的 TypeScript 逻辑核心在于Agent.create的配置。我们强制指定了cloud运行时并传入了完整的 repo clone 和失败日志const agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: composer-2 }, // 专为代码优化成本低、准确率高 cloud: { repos: [{ url: process.env.REPO_URL!, startingRef: process.env.BRANCH! }], autoCreatePR: true, // 关键注入失败上下文让 agent 知道它要解决什么 context: { failureType: jest-test-failure, logSnippet: fs.readFileSync(./test-failure.log, utf8).slice(0, 2000), affectedFiles: [src/utils/date.ts, tests/utils/date.test.ts] } } }); const run await agent.send(The Jest test failed with the above error. Analyze the root cause and propose a minimal fix. If confident, implement the fix and create a PR.);提示这里的关键技巧是“上下文注入”。不要只丢给 agent 一句“修好它”而是把失败日志、受影响文件、甚至 CI 环境变量如 Node 版本都结构化地传进去。Composer 2 模型对这种结构化输入的响应质量远高于自由文本。实测下来对于 65% 的常见测试失败如 mock 未定义、断言值错误、异步等待不足agent 能在 90 秒内生成一个可合并的 PR。剩下的 35%它至少能精准定位到出错的函数和行号并给出清晰的修复建议将工程师的平均排查时间从 22 分钟缩短到 3 分钟。这不是魔法而是把工程师的“调试心智模型”编码进了 agent 的 prompt 和 hooks 里。2.2 内部平台的“GTM 助手”让非技术人员自助查询第二个颠覆性场景是将 Custom Agents 作为内部平台的“大脑”赋能销售、市场、客户成功等 GTM 团队。我们曾为一个 SaaS 产品搭建了一个内部数据查询平台前端是一个简单的 Web 表单后端则是一个基于 Cursor SDK 的 agent 服务。用户输入“上个月北美地区付费客户中使用了‘API Analytics’功能但未升级到企业版的客户有哪些他们的平均 API 调用量是多少”系统不会去写一个复杂的 SQL而是启动一个 agentconst agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: gpt-5.5 }, // 此处需要更强的通用推理能力 local: { cwd: /path/to/internal-platform }, // 指向包含数据 schema 和连接凭证的本地目录 // 关键通过 MCP 服务器连接内部数据库 mcp: { servers: [ { name: internal-db, uri: http://internal-db-proxy:8080?token${process.env.DB_TOKEN} } ] } }); const run await agent.send( You are an expert data analyst for our SaaS platform. Use the internal-db MCP server to query our PostgreSQL database. The users question is: ${userQuery}. Return ONLY a JSON object with customers (array of names) and avg_usage (number). );注意这里的mcp配置是灵魂。我们编写了一个轻量级的 MCP 服务器它接收 agent 的 JSON-RPC 请求解析 SQL 查询执行并返回结果。所有敏感的数据库连接信息、权限控制都由这个 MCP 服务器处理agent 本身完全不接触凭证。这保证了安全也实现了能力解耦。这个场景的价值在于它彻底改变了知识获取的方式。以前GTM 同事要问一个问题得等数据工程师排期、写 SQL、导出 Excel。现在他们自己就能在 10 秒内拿到答案。我们上线后内部数据查询工单减少了 78%而数据工程师则从“SQL 写手”转型为“MCP 服务器架构师”和“agent 提示词工程师”。2.3 客户产品中的“原生智能体”无缝嵌入的用户体验第三个也是最具想象力的场景是将 Custom Agents 直接嵌入到面向客户的 SaaS 产品中成为产品功能的一部分而非一个独立的“AI 功能页”。Notion 和 Faire 的案例就属于此类。我们为一个低代码建站平台做了类似尝试。当用户在编辑器里选中一段文字右键菜单中多了一个“优化文案”选项。点击后前端不跳转页面而是发起一个对后端 agent 服务的请求// 前端 JS async function optimizeText(selectedText) { const response await fetch(/api/agent/optimize, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify({ text: selectedText, tone: professional, length: short }) }); const result await response.json(); editor.replaceSelection(result.optimizedText); }后端/api/agent/optimize接口其核心就是创建一个localagentapp.post(/api/agent/optimize, async (req, res) { const { text, tone, length } req.body; const agent await Agent.create({ apiKey: process.env.CURSOR_API_KEY!, model: { id: composer-2 }, local: { cwd: /path/to/content-optimization-skills // 包含专门的文案优化 skill } }); // 关键利用 Skills 机制让 agent 自动加载领域知识 const run await agent.send( Optimize the following text for a ${tone} tone and ${length} length. Do not add any explanations, only return the optimized text.\n\n${text} ); const result await run.wait(); res.json({ optimizedText: result.output }); });提示这里local模式是关键。它让 agent 运行在应用服务器的同一进程内延迟极低通常 800ms体验接近原生。同时.cursor/skills/目录下的自定义 skill如seo-optimizer.ts,tone-adjuster.ts会被自动加载这让 agent 的行为高度可控避免了通用模型的“胡说八道”。这种嵌入方式让 AI 不再是“一个功能”而是产品工作流中自然的一环。用户感觉不到 AI 的存在只觉得这个产品“特别懂我”。2.4 工程效能平台的“自动化协作者”最后一个场景是构建一个面向工程师的“自动化协作者”平台。这超越了单点自动化而是一个可编排、可协作、可审计的智能体工作流。我们参考了 Cursor 官方的 Kanban Board 示例但做了深度定制。平台核心是一个基于事件驱动的 agent 调度器。当一个 Jira ticket 被标记为“Ready for Dev”调度器会创建一个主 agent负责整体规划主 agent 根据 ticket 描述调用Agent工具动态创建多个 subagents每个 subagent 有明确分工code-analyzer读取相关代码、test-generator生成单元测试、pr-creator提交 PR所有 subagent 的输出和状态通过hooks.json统一记录到数据库形成完整的审计日志。其hooks.json配置如下展示了如何在每个关键节点插入自定义逻辑{ onRunStart: src/hooks/log-start.ts, onStepComplete: src/hooks/log-step.ts, onRunEnd: src/hooks/post-to-jira.ts }其中post-to-jira.ts会在 agent 完成后自动更新 Jira ticket 的评论区附上 PR 链接、测试覆盖率变化和性能基准报告。整个过程对工程师是透明的他们只需关注最终的 PR Review而无需操心中间的自动化步骤。这个场景的价值在于它把“自动化”从“脚本”提升到了“协作伙伴”的层面。它不再是“我写个脚本让它跑”而是“我告诉它目标它自己规划、分派、执行、汇报”。这代表了工程效能的下一个演进方向。3. Composer 2不只是模型而是为代码而生的“智能体引擎”在所有关于 Custom Agents 的讨论中有一个名字被反复提及却常被低估Composer 2。很多人把它简单理解为“Cursor 推出的一个新模型”这完全误解了它的设计哲学。Composer 2 不是一个通用大语言模型LLM的变体而是一个专门为编码智能体Coding Agent工作流深度优化的推理引擎。它的价值只有在 Custom Agents 的上下文中才能被完全释放。3.1 为什么 Composer 2 是 Custom Agents 的“最佳拍档”我们可以从三个维度来理解 Composer 2 的独特性第一指令遵循Instruction Following的极致强化。通用模型如 GPT-4 或 Claude在面对复杂、多步骤、带约束的指令时容易“跑题”或“过度发挥”。而 Composer 2 的训练数据大量来自 Cursor 用户的真实 agent 会话日志——那些“请分析这个 PR 的变更只修改必要的文件不要添加新依赖最后生成一个简洁的 commit message”的指令。这使得它对“精确执行”有着近乎本能的偏好。在我们的 CI/CD 场景中当要求 agent “只修复src/api/client.ts中的fetchData函数不要改动任何其他文件”Composer 2 的成功率高达 92%而同等参数量的通用模型仅为 63%。这个差距直接决定了自动化能否真正落地。第二代码上下文Code Context的深度理解与压缩。Custom Agents 的强大源于其“智能上下文管理”——它能自动索引整个代码库进行语义搜索。但模型本身必须能高效地消化这些上下文。Composer 2 的架构针对此做了专项优化。它内置了一个高效的“代码摘要器”能在 token 限制内将数千行的代码上下文提炼成一个高信息密度的“语义指纹”。这意味着当 agent 需要理解一个复杂的 React Hook 时Composer 2 不会陷入冗长的代码细节而是快速抓住其“职责”、“输入/输出契约”和“副作用边界”。我们在一个大型 monorepo 的测试中发现Composer 2 在相同上下文窗口下对跨文件调用链的识别准确率比通用模型高出 41%。第三成本与性能的黄金平衡点。这是最务实的考量。在 CI/CD 这种对成本极度敏感的场景使用 GPT-4 级别的模型一次 PR 修复可能花费数美元而 Composer 2 的成本仅为 1/5且响应速度更快P95 延迟降低 35%。这使得“为每一次 PR 都启动一个智能体”从经济上变得可行。我们做过一个测算在一个拥有 50 名工程师的团队中将 Composer 2 驱动的 auto-fix 覆盖到所有 PR年均可节省约 1,200 小时的工程师调试时间而模型调用成本仅增加约 $1,800/年。ROI 清晰可见。3.2 如何在 Custom Agents 中最大化 Composer 2 的价值仅仅在model.id字段填上composer-2是远远不够的。要榨干它的潜力需要配合特定的工程实践1. Prompt 设计拥抱“约束式提示”Constrained Prompting放弃“请帮我写一个函数”的开放式提问。Composer 2 更擅长处理带有明确边界、格式和动作的指令。我们总结了一套模板[ROLE] You are a senior frontend engineer at [Company]. [CONTEXT] The codebase uses React 18, TypeScript, and Tailwind CSS. The current file is src/components/Button.tsx. [ACTION] Modify the Button component to accept a new size prop (values: sm, md, lg). Update the Tailwind classes accordingly. [CONSTRAINTS] - Only modify the Button.tsx file. - Do not change the existing props or behavior. - Return ONLY the modified file content, no explanations.这种结构化的 prompt完美匹配 Composer 2 的训练范式能显著减少幻觉。2. 技能Skills协同用代码补足模型的短板Composer 2 强大但并非万能。它可能不熟悉公司内部的特定 API 规范或构建工具链。这时.cursor/skills/目录就是你的“外挂”。例如我们编写了一个internal-api-validator.tsskill它能自动检查 agent 生成的 API 调用代码是否符合公司内部的 OpenAPI Schema。当 agent 生成代码后这个 skill 会自动运行如果校验失败它会触发一个 hook让 agent 重新生成。这形成了一个“模型生成 - 代码校验 - 失败重试”的闭环将 Composer 2 的能力与确定性的代码规则完美结合。3. 运行时选择Local 模式是 Composer 2 的“主场”虽然 Composer 2 也支持 Cloud 运行但在需要极致低延迟和高隐私的场景如嵌入到客户产品中local模式是首选。它意味着 Composer 2 的推理发生在你的服务器上所有的代码上下文、业务逻辑、敏感数据都无需离开你的网络。我们为此专门优化了本地部署的 Docker 镜像将启动时间从 15 秒压缩到 2.3 秒确保了流畅的用户体验。Composer 2 不是 Custom Agents 的一个可选项而是其能力得以规模化、工业化落地的核心使能者。理解这一点是设计高效 agent 应用的第一步。4. 从零到一一个可落地的 Custom Agents 实战项目全解析理论讲得再多不如亲手做一个。下面我将带你完整复现我们团队为一个开源项目一个 React UI 组件库构建的“PR 自动审查助手”项目。这个项目完全基于 Cursor SDK使用 Composer 2 模型运行在本地且已稳定服务于该组件库的 300 次 PR。它不是一个玩具 demo而是一个经过生产环境考验的、可直接“抄作业”的方案。4.1 项目目标与架构设计目标当一个新的 PR 被创建时自动运行一个 Custom Agent完成以下三件事代码风格审查检查新增/修改的.tsx文件是否符合 ESLint 规则特别是我们自定义的our-org/react规则集。无障碍a11y审查使用 axe-core 库扫描新增的 JSX确保没有严重级别的无障碍问题。文档同步检查确认所有新增的组件都在docs/目录下有对应的 Markdown 文档。架构设计我们采用“事件驱动 本地 agent”的轻量架构。GitHub Webhook 监听pull_request事件触发一个 Node.js 服务该服务创建一个localCustom Agent。Agent 的工作流由hooks.json控制确保每一步都可追踪、可审计。4.2 核心代码实现与关键配置第一步初始化项目与安装依赖mkdir pr-review-agent cd pr-review-agent npm init -y npm install cursor/sdk types/node # 安装我们自定义的审查工具 npm install eslint our-org/eslint-config-react axe-core第二步创建 Custom Agent 的核心逻辑 (agent.ts)import { Agent, RunEvent } from cursor/sdk; import * as fs from fs; import * as path from path; // 1. 从环境变量读取配置 const CURSOR_API_KEY process.env.CURSOR_API_KEY!; const REPO_ROOT process.env.REPO_ROOT || process.cwd(); // 2. 创建 Agent关键指定 local 运行时和 Composer 2 模型 const agent await Agent.create({ apiKey: CURSOR_API_KEY, model: { id: composer-2 }, local: { cwd: REPO_ROOT }, // 3. 注入 Hooks用于在关键节点执行自定义逻辑 hooks: { onRunStart: path.join(REPO_ROOT, .cursor, hooks, on-run-start.ts), onStepComplete: path.join(REPO_ROOT, .cursor, hooks, on-step-complete.ts), onRunEnd: path.join(REPO_ROOT, .cursor, hooks, on-run-end.ts) } }); // 4. 发送核心指令 const run await agent.send( You are an expert reviewer for a React UI component library. Your task is to review the changes in this PR. First, analyze the diff to identify all modified/added .tsx files. Then, for each file: 1. Run ESLint with our custom config and report any errors. 2. Use axe-core to scan the rendered component and report any critical a11y violations. 3. Check if a corresponding documentation file exists in the docs/ directory. Finally, summarize your findings in a structured JSON format. Do not generate any code or make any changes. ); // 5. 流式监听事件实时获取进度 for await (const event of run.stream()) { if (event.type output) { console.log([AGENT OUTPUT], event.data); } else if (event.type error) { console.error([AGENT ERROR], event.data); } } // 6. 等待最终结果 const result await run.wait(); console.log(Review completed. Final result:, result.output);第三步实现核心 Hooks (./.cursor/hooks/)Hooks 是这个项目的心脏它让 Custom Agent 的行为变得可编程、可审计。on-run-start.ts记录任务开始提取 PR 信息。import { HookContext } from cursor/sdk; export default async function (ctx: HookContext) { // 从环境变量或上下文提取 PR 信息 const prNumber process.env.PR_NUMBER; const prUrl https://github.com/our-org/ui-library/pull/${prNumber}; console.log(Starting review for PR #${prNumber}); // 将信息写入临时文件供后续 hooks 读取 fs.writeFileSync(/tmp/pr-review-${prNumber}.json, JSON.stringify({ prNumber, prUrl })); }on-step-complete.ts这是最关键的 hook它在 agent 完成每一个推理步骤后被调用。我们在这里插入真实的审查逻辑。import { HookContext } from cursor/sdk; import * as eslint from eslint; import * as axe from axe-core; export default async function (ctx: HookContext) { // 1. 获取 agent 当前正在分析的文件路径从 ctx.step.prompt 中解析 const filePathMatch ctx.step.prompt.match(/analyze the changes in (.\.tsx)/); if (!filePathMatch) return; const filePath filePathMatch[1]; const fullPath path.join(process.cwd(), filePath); // 2. 执行 ESLint 审查 const eslintCLI new eslint.CLIEngine({ useEslintrc: true }); const eslintReport eslintCLI.executeOnFiles([fullPath]); const eslintErrors eslintReport.results.flatMap(r r.messages.filter(m m.severity 2)); // 3. 执行 axe-core 审查需要先渲染组件此处简化为伪代码 let axeResults []; try { // ... 实际代码使用 JSDOM 渲染组件然后调用 axe.run() axeResults await axe.run(/* rendered DOM */); } catch (e) { console.warn(Axe scan failed for, filePath, e); } // 4. 检查文档 const docPath path.join(process.cwd(), docs, path.basename(filePath, .tsx) .md); const hasDoc fs.existsSync(docPath); // 5. 将审查结果“喂”回 agent影响其下一步推理 // 这是 Custom Agents 的高级技巧通过 hooks 动态注入上下文 ctx.injectContext({ eslintErrors: eslintErrors.length 0 ? eslintErrors : null, axeCriticalViolations: axeResults.violations.filter(v v.impact critical), hasDocumentation: hasDoc }); }on-run-end.ts汇总所有结果生成 GitHub 评论。import { HookContext } from cursor/sdk; import * as github from actions/github; export default async function (ctx: HookContext) { const prNumber process.env.PR_NUMBER; const octokit github.getOctokit(process.env.GITHUB_TOKEN!); // 构建评论内容 const comment ## PR Review Summary by Custom Agent\n\n **ESLint Issues:** ${ctx.result?.eslintErrors?.length || 0}\n **Critical a11y Violations:** ${ctx.result?.axeCriticalViolations?.length || 0}\n **Docs Missing:** ${ctx.result?.hasDocumentation ? ✅ : ❌}\n\n This review was performed automatically by our Custom Agent.; // 发布到 GitHub await octokit.rest.issues.createComment({ owner: our-org, repo: ui-library, issue_number: parseInt(prNumber!), body: comment }); }第四步项目根目录下的关键配置文件.cursor/mcp.json定义 MCP 服务器用于连接外部工具如我们的内部 CI 状态 API。{ servers: [ { name: ci-status, uri: http://ci-internal-api:3000/v1/status } ] }.cursor/skills/目录存放自定义技能例如eslint-runner.ts它封装了 ESLint 的调用逻辑让 agent 可以用自然语言调用它。4.3 部署与运维经验踩过的坑与避坑指南这个项目上线后非常稳定但初期我们踩了几个典型的坑分享出来供大家避雷坑一local模式下的路径陷阱local: { cwd: ... }指定的路径是 agent 的“工作目录”但它默认不会自动将当前 Node.js 进程的node_modules加入require路径。这意味着如果你在 prompt 里让 agent “运行eslint”它会找不到命令。解决方案在cwd目录下创建一个package.json并npm link或npm install所有需要的 CLI 工具。或者更推荐的做法是把所有工具调用都封装在skills里由 TypeScript 代码来执行而不是依赖 shell 命令。坑二Hook 的异步地狱on-step-complete是一个异步函数但 agent 的主循环是同步的。如果你在 hook 里执行一个耗时的await比如一个慢速的 API 调用agent 会卡住超时失败。解决方案所有耗时操作必须在 hook 内部使用setTimeout或setImmediate放入微任务队列使其异步化但不能await。或者更好的方式是将耗时操作的结果通过ctx.injectContext提前注入让 agent 在后续步骤中“看到”结果而不是在 hook 里等待。坑三Composer 2 的“过度自信”Composer 2 在代码审查上非常强但它有时会“自信地”给出一个看似合理、实则错误的结论。例如它可能认为一个无障碍问题“不严重”而实际上它是 WCAG 2.1 的 A 级必修项。解决方案永远不要把 agent 的结论当作最终判决。我们的做法是让 agent 的输出只是一个“建议”而真正的决策权在on-run-end.ts的 hook 里。hook 会读取 agent 的 JSON 输出然后对照一份硬编码的“合规规则表”进行二次校验。只有两者都通过才认为该项审查通过。这层“人类规则兜底”是保障自动化质量的生命线。这个项目证明了 Custom Agents 的威力它不是一个黑盒而是一个可以被深度定制、与现有工程体系无缝集成的智能体框架。它的成功不在于模型有多炫而在于整个架构设计的务实与稳健。5. 未来已来Custom Agents 将如何重塑软件开发的协作范式当我们把 Custom Agents 从一个个孤立的自动化脚本提升到“可编程基础设施”的层面时一个更宏大的图景便逐渐清晰它正在悄然重塑软件开发中最基础的协作单位——从“人”到“人智能体”的混合协作体。5.1 从“工程师执行”到“工程师定义”角色的根本性迁移过去一个资深工程师的核心价值体现在他能多快、多准地写出高质量的代码解决复杂的技术难题。未来他的核心价值将越来越多地体现在他能多精准地定义问题、设计 agent 的工作流、编写 robust 的 hooks 和 skills、以及建立 agent 的质量护栏。这就像从“亲自开挖掘机”变成了“设计挖掘机的控制系统和施工蓝图”。我们团队已经观察到了这种迁移。一位 Senior Frontend Engineer现在每周花 3 小时在维护pr-review-agent的hooks和skills花 2 小时在分析 agent 的失败案例优化 prompt。他写的“代码”变少了但他对整个前端工程效能的影响却扩大了 10 倍。他不再是一个执行者而是一个“智能体架构师”。5.2 新的工程挑战可解释性、可审计性与责任归属随之而来的是全新的工程挑战。当一个由 Custom Agent 提交的 PR 引发了线上故障责任在谁是写 prompt 的工程师是训练 Composer 2 的模型团队还是部署 agent 的 SRE这迫使我们必须建立一套全新的“AI 工程治理”规范。我们正在实践的方案是“三重审计”Prompt 审计所有发送给 agent 的 prompt必须经过 Code Review确保其意图清晰、约束明确、无歧义。Hook 审计所有hooks代码必须有完整的单元测试模拟各种 agent 输出验证其行为。结果审计每一次 agent 的运行其完整的stream()事件、injectContext数据、最终result都必须被持久化到一个不可篡改的日志系统中。这不仅是追责依据更是持续优化 agent 的宝贵数据金矿。5.3 下一个前沿多智能体Multi-Agent的自主协作Custom Agents 的终极形态不是单个 agent 孤立工作而是多个 specialized agent 组成一个“智能体社会”彼此协商、分工、监督。Cursor SDK 的Subagents功能已经为此埋下了伏笔。想象这样一个场景一个复杂的 feature 开发任务被分配给一个project-manageragent。它不会自己写代码而是启动一个code-analyzersubagent去理解现有架构启动一个design-reviewersubagent去评估新方案的可行性启动一个test-plannersubagent去生成测试策略最后它整合所有 subagent 的输出生成一个详细的开发计划并启动一个pr-creatorsubagent 来执行。这个过程不再需要人类工程师在中间做“翻译”和“协调”agent 之间通过标准化的 JSON 协议进行沟通。这已经不是科幻而是 Cursor SDK 当前就能支持的架构。我们已经在内部的一个 PoC 项目中实现了两个 subagent 的简单协作一个负责“找 bug”一个负责“修 bug”它们通过Agent工具互相调用完成了闭环。这条路的终点或许不是“取代工程师”而是“解放工程师”。当所有重复、机械、高认知负荷的“苦力活”都被 Custom Agents 承担工程师将能前所未有地聚焦于真正的创造性工作定义伟大的产品、设计优雅的架构、以及解决那些连最强大的 AI 也无法定义的问题。这才是 Custom Agents 真正的使命所在。
