AI Agent 工程师的核心能力：从模型调用到可靠系统

这两年「AI Agent 工程师」这个头衔冒得很快。招聘 JD 和学习路线里常见一长串名词：Python、LangChain、Prompt、RAG、MCP、多 Agent。照着学完，Demo 通常能跑；接到业务以后，却经常不知道从哪刀下去。

我自己也走过弯路。最早会把精力放在框架和 Prompt 技巧上，后来做 Orca、处理长任务、看 session 日志、修控制面事故，才慢慢意识到：名词清单不是主线。你真正要能回答的，大概是这件事——

定义一个目标，让 Agent 调用真实工具往前推；中途出错时系统别散架；最后用外部证据证明活干完了，而不是模型自己说「完成了」。

下面这张能力地图，是我现在会拿来对照自己的版本。它故意不完整，也故意带一点我自己的偏见。

岗位到底在解决什么

最小 Agent 其实很短：

用户输入
  -> 调用模型
  -> 模型选择工具
  -> 执行工具
  -> 把结果交还模型
  -> 循环直到输出答案

写到这里不难。难的是后面这些具体问题：该调工具时为什么没调？参数错了该重试还是退出？写操作跑两次会不会双发？RAG 搜到的是不是可用证据？上下文膨胀后压什么、留什么？跑了两小时中断了能不能续？模型报完成，谁验收？高风险动作要不要人点头？换模型为什么整系统退化？成功率涨 5%、成本涨三倍，值不值？

这些已经超出「Prompt 写得好不好」。它们落在软件工程、数据、产品、安全和评估上。所以我更愿意把这个岗位想成：懂模型会出错的软件系统工程师。

1. 软件工程基础

最容易被跳过，最后又最常救命。

你不需要一上来就会所有云厂商，但最好有一门主力语言（Python / TypeScript 都行）、会异步和流式、会碰数据库/缓存/队列、会 Git 和测试部署、会设计 API 和错误处理、知道密钥不能乱打日志。更重要的是，能读陌生代码、能从线上痕迹反推发生了什么。

Agent 一做事就会碰到真实系统：读库、调接口、改文件、跑命令、等异步任务、撞限流。模型可以帮你写胶水代码，设计责任它替不了。

举个小例子。sendEmail 看起来就是调一次 API。上线后你得想：重试会不会发两封？超时后到底发没发？用户有没有权给这个地址发？日志会不会漏出正文？Agent 生成的是草稿还是直接发出？失败后怎么补偿？这些全是传统工程题，只是调用方变成了模型。

如果你本来就是后端、全栈或平台方向，别把自己清零。大部分能力能直接搬过来。

2. 懂模型边界，别迷信模型

不一定要会训模型，但要知道它在系统里扮演什么。

token 和 context window 是什么；system / user / tool 消息怎么拼进上下文；temperature、structured output 大致影响什么；tool calling 本质上是模型生成结构化决策，不是它亲手执行了函数；embedding 擅长什么、不擅长什么；prompt cache 为什么命中或失效；不同模型在工具调用、长上下文、成本和速度上差在哪；幻觉没法「修没」，只能被系统设计管住。

有用的不是背参数表，而是出问题时能分层定位。Agent 漏了一次工具调用，可能是描述烂、工具太多、上下文缺触发信息、模型本身弱、system 和用户指令打架，或者上游状态早就错了。如果一律归结成「Prompt 写差了」，后面优化会很快变成玄学。

3. Context 和 RAG

Agent 这一轮能干什么，很大程度取决于它这一轮看见了什么。

我现在会硬拆四种信息，尽量别全塞进聊天历史：

Context：这一轮决策必须看到的
State：任务做到哪、发生过什么
Memory：跨会话还值得留的经验和偏好
Knowledge：靠检索临时捞进来的外部知识

RAG 也别停在「切块丢向量库」。稍微靠谱一点的系统至少会碰到：文档解析（PDF/表格/代码不能当纯文本）、按语义边界 chunk、metadata 过滤、关键词+向量混合检索、rerank、组装上下文时控制长度和冲突、引用回原文、评估「没搜到 / 搜错了 / 模型没用证据」。

练习方式我更推荐给自己挖坑，而不是做一个「上传 PDF 聊天」页面：跨文档引用、表格问答、时间冲突、权限过滤、本来就没有答案。每次错了记在哪一层，进步会快很多。

4. 工具治理

工具是 Agent 从「说」变成「做」的开关，也是翻车高发区。

名字、描述、JSON Schema 只是入门。还得想清楚输入输出契约、副作用、错误类型、超时重试、幂等或补偿、权限审批、输出截断和脱敏、能不能进 trace。我习惯先按风险分层：

类型	例子	默认策略
只读	搜索、查询、读取文件	自动执行
可逆写入	创建草稿、写临时文件	自动执行并记录
高风险写入	发邮件、提交代码、修改订单	执行前确认
不可逆操作	删除数据、扣款、生产部署	强审批或禁止

可以简单记一句：工具清单 = 你交给模型的权力边界。会注册工具，通常只够 Demo；会给工具分层、限权、留痕，才开始像生产系统。

5. Loop、State、Memory

多轮任务里，聊天记录不能当状态机。

我会把 Loop 粗拆成：Goal、Planner、Actor、Observer、Verifier、State、Policy、Exit。两个常见坑：把计划当成一次性十步清单，死守不改；把 transcript 当成 State。State 至少要回答——目标是什么、完成了什么、验证过什么、失败过什么、为什么走下一步、哪些动作不能再做、中断后从哪续。

长任务稳不稳，常常不取决于 context window 开多大，而取决于这些状态有没有被系统接住。我在 Orca 的 Goal Mode 上栽过：模型看得见控制工具，执行线程却拿不到 owner，463 次 update_goal 全失败，任务还一直显示 active。细节在《一个 Goal 为什么跑了 5 小时》里。那种故障，单靠「把 Prompt 写严谨一点」解决不了。

6. Harness Engineering

如果把模型当发动机，Harness 就是油路、刹车、仪表和护栏：Prompt 装配、工具权限、Loop 与状态、沙箱、Hooks/Skills/MCP、trace、压缩与恢复、Verifier、人工接管。

我自己印象最深的一次，用户只回了三个字：

卡死了。

session 里 input tokens 冲到快 88 万。不是某个请求单纯超时，而是一堆小事叠起来：文件读太长、搜索没分页、旧 reasoning 反复带回、压缩太晚、工具输出膨胀，压缩时 UI 还没告诉用户发生了什么。最后改的是工具输出、上下文重放、soft compaction、TUI 状态和回归测试。模型没换，换的是它工作的环境。

完整排查见《用户说 Orca 卡死了，我最后修的是 Agent 的上下文债》。

我会把 Harness 想成：模型表现好时系统能跑；模型犯错、工具失败、上下文膨胀、任务中断时，系统还知道自己在哪、下一步谁说了算。

7. 评估和可观测性

这是我认为最稀缺、也最该先练的能力。

改 Prompt 感觉更好、换模型感觉更聪明、加工具感觉更强——都可能只是换了一种错法。评估至少要同时看任务是否完成、证据是否站得住、过程是否离谱、成本是否可接受、失败是否可控。能确定性验收的优先用确定性：跑测试、对查询结果、查引用、看下游状态、核对审批记录。LLM-as-Judge 可以辅助，别当唯一裁判。

再加 trace。没有 trace，你看到的只有最后一段漂亮话，优化无从下手。

8. 安全、成本和上线

Demo 问「能不能」。上线还要问「出事怎么办」。

Prompt injection、最小权限、沙箱、密钥与日志脱敏、超时限流熔断、模型路由和预算、checkpoint/回滚/人工接管、灰度监控复盘——这些不该等发布前一周才补。Agent 的特别风险在于：它答错之后往往还有执行权。权限边界最好在定义工具时就定，而不是事后补丁。

成本也是产品问题。「再让模型想一轮」几乎零心理成本；「这一轮值不值得」才是工程决策。默认所有步骤都走最贵模型，通常撑不久。

9. 产品和领域判断

不是所有流程都该做 Agent。

更适合的场景通常带一点不确定性、需要动态选工具、能从环境反馈里推进、有可检查的成功标准，失败后能恢复或交回给人。规则固定的流程，普通工作流往往更便宜也更稳。「帮公司做正确战略」这类不可验收目标，堆多少 Agent 也解决不了定义问题。

开工前我会逼自己问几句：为什么不是普通自动化？用户愿意交出多大权力？过程要不要可见？哪些错一次都不能发生？人卡在哪一步？模型账和工程账加起来，业务吃不吃得消？

四个项目，比刷框架有用

如果重来一次，我不会先把框架生态扫一遍，而会用四个项目硬练。

项目一：有证据的 RAG

选你真熟悉的领域做知识助手。要求能处理多种文档、metadata + hybrid search、回答带原文引用、找不到就拒答、至少 30 条评估样本，并记录召回/答案/延迟/成本。做完以后，解析、检索、上下文和评估会从名词变成手感。

项目二：会做事的单 Agent

给 3–5 个真实工具（搜、读、写草稿、提审批之类）。Schema 清楚、错误有语义、写操作尽量幂等、高风险要确认、结果过 Verifier、全程能在 trace 里重放。先别碰多 Agent——单 Agent 的工具、状态、权限都没顺，多智能体只会放大混乱。

项目三：可中断可恢复的长任务

让它跑几十分钟、跨多步：分析仓库、修问题、跑测试、出报告。Goal 和验收标准要写清，State 别靠聊天历史，支持 checkpoint/resume，有 token 和工具预算，能察觉无进展，中断后知道从哪续，搞不定就交回人。这一步会把 Loop、State、Memory、Harness 揉在一起。

项目四：给真实用户用

人不必多，十个认真用的人就够打穿 Demo。你会撞上模糊输入、权限差、失败恢复、吐槽、成本和延迟、版本退化、监控和事故。Agent 能力不是看教程长出来的，多半是某次失败之后，你把它沉淀成了机制。

怎么判断自己入没入门

框架数不是指标。我会问自己：

不用框架，能不能手写一个最小 Agent Loop？
能不能说清 Context / State / Memory 的差别？
会不会给工具做权限和副作用分级？
出了错，能分清是 RAG 召回问题还是生成问题吗？
能不能写 20–30 条固定 eval，而不是靠「感觉」？
有 trace 时，能不能指出任务从哪步开始跑偏？
长任务中断后，是接着干还是从头来？
改动后能不能证明成功率真的涨了？
能不能讲清楚什么时候不该上 Agent？

多数答得上来，并且有项目能当证据，就已经不只是「会调模型 API」。

现在还没想清楚的地方

写到这里，有几块我自己也还在摇摆。比如评估集怎么跟产品迭代同步而不沦为过时清单；多 Agent 什么时候收益大于协调成本；成本预算该挂在任务层还是工具层。这些暂时没有漂亮结论，就先不硬编。

我目前比较确信的只有两点：模型带来了过去软件没有的泛化能力；这种能力默认不稳定，不能直接当交付。中间那截桥——目标、上下文、工具、状态、Loop、验收、风险——就是 Agent 工程要天天补的地方。

模型大概决定上限；工程决定下限会不会塌。日常工作大多是在把下限往上托一点。