一个在 Hacker News 上反复出现的问题是一个认真想做 AI Agent 的开发者究竟该学哪些技能这个问题表面看起来像学习路线咨询实际上暴露了当前 AI 应用开发的一个普遍困境很多人会写提示词、会调模型 API但一旦把任务从“单轮问答”变成“多轮 Tool Calling”从“demo 能跑”变成“生产可用”整个系统就开始失控。我的判断很明确真正决定 Agent 能不能落地的不是会不会用某个框架而是有没有掌握一套“技能拆解 工具调用 记忆设计 可靠工程”的组合能力。这套能力行业里通常称为 Agent Skill中文常译为“Agent 技能”。它既包括模型本身的推理和指令遵循能力也包括开发者封装给 Agent 的工具能力还包括让 Agent 稳定运行、可测试、可治理的工程手段。这篇文章会从 Hacker News 上的问题出发先厘清 Agent、Skill、Harness 这几个高频词的关系再给出一个 Agent 开发者的七项必备技能清单然后提供一个带 Skill 机制的最小可运行示例最后聊一聊常见坑和生产环境最佳实践。读完你至少能回答三个问题Agent 技能到底指什么上手做 Agent 需要准备哪些东西从 demo 到生产最容易卡在哪些地方1. 这篇文章真正要解决的问题最近两年AI Agent 从一个概念变成了实际工程。GitHub 上有大量 Agent 开源项目很多公司也开始在内部做自动运维、自动测试、智能客服、代码审查助手。这些项目看起来各不相同底层却有一套共同的抽象模型负责推理工具负责执行流程负责兜底。于是“Agent 需要哪些技能”这个问题就成了开发团队绕不开的命题。但很多人的反应是先去学某个框架比如 LangChain、AutoGen、CrewAI或者去看最新的 Agent 协议、Agent 框架源码。这种做法不能说错但如果只停留在“跑通官方示例”的层面很快会遇到几个典型问题模型调用了工具但工具返回的结果格式不对下一轮对话直接崩掉。Agent 在一个循环里反复调用同一个工具拿不到终止条件。上下文窗口越来越长Agent 记不住前面的关键结论。工具权限太大Agent 在一次错误决策里删掉了不该删的数据。本地跑得好好的 Agent部署到线上后无人看管日志缺失出了问题无从排查。这些问题的根源都不是“不会用框架”而是“缺乏对 Agent 工程化技能的拆解能力”。换句话说Agent 技能不是某一个单一技能而是一套从模型层到工程层的技能栈。这篇文章要解决的问题就是把这套技能栈讲清楚。我给出的判断是如果你想在 2025 年之后继续做 Agent 开发最重要的不是追新框架而是掌握六个字——拆能力、建护栏。拆能力是把复杂任务拆成模型可以调用的技能单元建护栏是让每一次工具调用都有边界、有日志、有验证、有回滚路径。哪些读者最应该看这篇文章三类人第一类是刚入门 AI 应用开发准备做第一个 Agent 的开发者第二类是用过 LangChain 但发现出问题时很难调试的工程师第三类是团队里要负责 Agent 落地的技术负责人。后面所有内容都会围绕这三类人的真实场景展开。2. Agent 与 Agent Skill 的核心概念辨析在进入实操之前必须先把几个高频概念理清楚。因为现在社区里的术语使用并不统一同一个人可能今天说 Skill明天说 Tool后天说 MCP很容易把人绕晕。2.1 Agent 是什么Agent 的中文叫智能体但它并不是一个玄学概念。从一个开发者的视角看Agent 是一个能够自主完成以下循环的程序接收用户目标或系统任务。基于大模型进行推理和规划。选择合适的工具或技能去执行。观察执行结果决定下一步动作。直到任务完成或达到终止条件。这个循环的核心是“自主决策”。传统程序是开发者把每一步分支都写死Agent 则是把决策权交给模型由模型根据上下文选择执行哪个函数。这样做的好处是灵活坏处是不可控。所以 Agent 工程里最核心的工作就是在这个“灵活”和“不可控”之间想办法。有一个常见的误解是只要接了大模型的 API写一个 while 循环调 chat.completions就是 Agent。这个说法不够准确。一个最小 Agent 至少应该包含“计划—执行—观察—再计划”的结构并且要有明确的终止条件、工具执行上下文和错误处理机制。否则它充其量是一个“带工具调用的聊天机器人”。2.2 Skill 是什么Skill 直译是“技能”。在 Agent 语境下一个 Skill 通常是一个可复用的能力单元它包含三层内容语义描述告诉模型这个技能是做什么的、什么时候该用、参数是什么。可执行逻辑一段代码、一个函数、一个脚本或者一个 API 调用。输入输出约束JSON Schema、参数校验、返回格式约定。为什么要单独强调 Skill因为 Agent 开发中最大的成本不是模型调用而是“让模型理解你有什么能力并且知道怎么用”。同一个函数如果描述写得好模型会主动调用如果描述写得模糊模型宁可胡说也不调用。Skill 本质上就是给模型写的一份“能力使用说明书”。和 Tool 相比Skill 更强调复用和组合。Tool 通常指单个函数或单个 APISkill 则可以是一个函数、一段提示词模板和一条执行规则的组合。比如“查询订单状态”是一个 Tool但“如果订单异常自动查询物流单号、计算超时天数、判断是否需要升级工单”就可以封装成一个 Skill。2.3 Skill 与 Agent、Harness 的边界三者可以用一个比喻来理解Agent 是厨师Skill 是菜谱和刀具Harness 是厨房的管理制度。Agent 负责根据客人的需求判断今天做什么菜决定用哪个菜谱Skill 提供具体的做菜步骤和工具Harness 则规定每一步操作必须遵守的流程比如开火前检查燃气、出锅前试菜、做完后记录日志。在技术层面Harness 通常指“包裹 Agent 的外层执行框架”。它负责 Agent 主循环、工具调用的调度、消息历史的维护、错误重试、日志追踪、安全策略注入等。你可以把 Harness 理解为 Agent 运行时的“操作系统”。所以回到很多人问的问题Harness 和 Agent 的区别是什么我的理解是Agent 是模型 上下文 工具调用的决策单元Harness 是让这个决策单元跑起来的工程外壳。没有 HarnessAgent 只能在 Jupyter Notebook 里演示有了 HarnessAgent 才能变成线上服务。其实很多东西也可以归入 Harness 的范畴比如 Agent 的循环控制、超时管理、任务队列、并发策略。如果一上来就研究 Harness很容易陷入“什么都要自己造轮子”的误区。更好的路径是先理解 Agent 的决策循环再理解 Skill 的封装方式最后才去选或写 Harness。2.4 Agent 架构下技能为什么是复用单元过去做软件我们习惯以“函数”“类”“微服务”为粒度组织代码。到了 Agent 时代模型不是通过函数名调用能力而是通过语义匹配来决定调用哪个能力。因此能力的描述质量决定了 Agent 的上限。Skill 存在的意义就是把能力描述、执行逻辑、参数约束和验证方式打包在一起。这样同一个 Agent 可以拥有多个 Skill同一个 Skill 也可以被多个 Agent 复用。比如一家公司可以把“查库存”“算运费”“生成退货单”分别封装成三个 Skill售前 Agent、售后 Agent、供应链 Agent 都能调用。从工程角度看把 Skill 单独抽象出来还有一个好处可以单独测试。你不必启动整个 Agent 就能验证“给定这个参数Skill 会不会返回预期结果”。这正是 Agent 应用从 demo 走向生产的关键一步。很多团队问我 Agent 项目怎么测试其实第一步就是把 Skill 当作普通函数来测第二步才是测 Agent 的决策和编排逻辑。3. Agent 开发的七项必备技能清单如果现在让我给一位准备进入 Agent 开发的工程师画一条学习路线我会把它拆成七项技能。它们不是并列关系而是从模型层往工程层递进的关系。3.1 提示词与上下文工程这是最基础但也最容易被低估的一项。Agent 的 prompt 不是写一段“你是助手”就结束了。真正可用的 Agent prompt 通常包含五个部分角色定义、任务目标、可使用的技能列表、工作流程约束、输出格式要求。当 Agent 开始调用工具后上下文里会出现系统消息、用户消息、助手消息、工具调用消息、工具返回消息。如何让模型在多轮上下文中不产生误解是典型的上下文工程问题。一个常见做法是在每一轮工具返回后把返回结果重新整理成“观察结果”而不是直接把原始 JSON 塞给模型。这样能显著降低模型在下一轮决策时的困惑。3.2 函数调用与工具定义Agent 真正能“做事”靠的是函数调用。但函数调用并不是在代码里写一个 if-else 判断而是要让模型理解函数的用途、参数、限制并且在合适的时候返回一个结构化的工具调用请求。这里最容易踩的坑有两个第一工具描述写得太短模型不知道什么时候用第二参数定义不完整模型生成 JSON 时缺少必填项。我的建议是每个工具描述都要包含“功能边界”和“使用场景”。功能边界是在描述里明确写出“这个工具不能做什么”使用场景是告诉模型“当用户提到哪些词的时候应该优先考虑这个工具”。3.3 记忆与状态设计Agent 和普通接口的最大区别是“有状态”。同一个用户在不同轮次提出的要求可能依赖之前的信息。如果把所有历史消息都塞进上下文成本会越来越高模型也会越来越“失焦”。所以在 Agent 架构里记忆通常被拆成短期记忆和长期记忆。短期记忆就是当前任务上下文一般放在 messages 数组里长期记忆可以存在向量数据库、Redis 或普通数据库里用于跨会话复用。设计记忆时一定要明确三个问题写什么、读什么、什么时候遗忘。没有遗忘机制的记忆最终会因为噪声过多而让 Agent 变笨。3.4 检索增强与知识接入大模型的知识有截止日期企业内部知识也无法凭空学会。所以 Agent 通常会接入检索增强生成RAG能力或者通过 MCP 等协议连接外部数据源。对 Agent 来说检索能力本身就是一个 Skill。这一项技能的关键不在向量数据库而在“检索质量”。常见问题是模型拿到的检索片段和问题无关导致最终回答东拉西扯。建议在检索链路里增加重排序环节并且把检索结果按“相关性”“来源”“时效性”整理成结构化上下文。3.5 可观测性与测试Agent 的不确定性强不能像普通接口那样只靠单元测试。你需要能回答四个问题模型选择了哪个工具工具返回了什么Agent 为什么选择这个而不是那个哪一轮开始结果开始偏离预期因此日志和追踪是 Agent 开发的核心设施。每一步都要记录 trace_id、输入、输出、耗时、模型名称、token 消耗。测试方面除了常规单元测试还应该有基于历史真实案例的回放测试以及针对工具调用的断言比如“用户在询问天气时必须调用天气查询工具”。3.6 安全与权限治理这是 Agent 落地中最容易出问题的环节。一个拥有工具调用能力的 Agent本质上获得了执行代码和操作系统的能力。权限越大风险越大。安全设计必须从第一版开始做Skill 默认拒绝危险操作所有非只读操作必须经过人工确认Agent 调用外部 API 时要有独立的密钥和权限范围数据库写操作要在测试环境验证后再放生产环境。不要等到 Agent 在一次错误决策中删了数据才意识到安全护栏的重要性。3.7 部署与优化前面六项技能都做好之后剩下就是工程运维。Agent 服务可能需要支持多用户并发、模型调用超时、限流、失败重试、成本控制。哪些操作可以缓存哪些模型适合快速响应哪些任务需要更强大的推理模型都需要在部署层面做策略。从个人开发者到团队协作还涉及 Agent 配置管理、Skill 版本管理、灰度发布等问题。不要小看这些工程细节它们往往决定了 Agent 能不能从“演示”变成“日活可用”的业务系统。4. 环境准备与最小项目结构下面进入实操。我们这里演示的是一个最小但完整的 Agent 项目它具备 Skill 注册、模型决策、工具调用、结果返回的完整链路。由于不同模型 API 的版本差异较大本文只演示通用的 OpenAI-compatible 接口路径版本细节请以你实际使用的模型服务为准。4.1 运行环境准备一台能运行 Python 的机器推荐 Python 3.10 及以上版本。需要安装两个依赖openai用于调用 OpenAI-compatible 的 chat/completions 接口。python-dotenv用于从本地 .env 文件加载环境变量。编辑requirements.txtopenai1.0.0 python-dotenv1.0.0然后执行pip install -r requirements.txt4.2 项目目录我们用一个非常小的目录结构来演示agent-skills-demo/ ├── .env ├── requirements.txt └── main.py这个结构适合快速跑通也方便你理解 Agent 的核心代码。生产项目可以在这个基础上增加 config 目录、skills 目录、tests 目录但核心逻辑是一样的。4.3 配置方式创建.env文件OPENAI_API_KEYyour-api-key OPENAI_BASE_URLhttps://api.openai.com/v1 MODEL_NAMEgpt-4o-mini如果你使用的是国内模型服务或自建模型服务只要它兼容 OpenAI 的/v1/chat/completions协议就可以通过OPENAI_BASE_URL指向对应的服务地址无需修改代码逻辑。注意API Key 千万不要提交到 Git 仓库建议在.gitignore中忽略.env文件。5. 一个带 Skill 的 Agent 完整示例我们现在开始写代码。这里的 Skill 在代码中体现为两个部分一是模型能读到的技能描述二是能被 Agent 调用的可执行函数。5.1 定义工具Skill 的可执行部分先创建main.py定义两个最简单、最安全的 Skill一个查天气一个列目录文件。为什么选这两个因为它们足够简单不需要真实网络请求和数据库适合演示工具调用的完整链路并且它们的结果可验证方便你在本地确认 Agent 是否真的走了“推理—调用—观察—回复”的完整循环。# main.py import json import os from openai import OpenAI client OpenAI( api_keyos.getenv(OPENAI_API_KEY), base_urlos.getenv(OPENAI_BASE_URL, https://api.openai.com/v1), ) SKILLS [ { name: fetch_weather, description: 根据城市名返回当前天气描述常用于回答“今天适合出门吗”这类问题。, parameters: { type: object, properties: { city: {type: string, description: 城市名例如杭州} }, required: [city] } }, { name: list_files, description: 列出指定目录下的文件列表用于帮助用户了解项目结构。, parameters: { type: object, properties: { directory: {type: string, description: 目录路径} }, required: [directory] } } ] def execute_skill(name: str, arguments: dict) - str: if name fetch_weather: city arguments.get(city, 未知城市) return f{city}晴25 摄氏度宜出行。 if name list_files: directory arguments.get(directory, .) try: files os.listdir(directory) return json.dumps(files[:20], ensure_asciiFalse) except Exception as exc: return fERROR: {exc} return fERROR: unknown skill {name}这段代码里最值得注意的地方是execute_skill。它不直接修改系统状态不删除文件不会向外部发起危险请求只是读取目录和返回模拟天气数据。真实项目里这里可以是任何业务能力但建议参考这个“只读优先”的安全模式。5.2 Agent 主循环接下来写 Agent 的主循环。核心逻辑是把用户输入加入 messages。调用模型时传入所有 Skill 描述。如果模型返回的是文本说明任务完成。如果模型返回的是工具调用请求执行对应 Skill并把结果作为 tool 消息返回给模型。循环直到模型给出最终文本或达到最大轮次。# main.py追加代码 def run_agent(user_input: str, max_turns: int 3): messages [ {role: system, content: 你是一个可以调用技能完成任务的助手。}, {role: user, content: user_input}, ] tools [ {type: function, function: skill} for skill in SKILLS ] for turn in range(max_turns): response client.chat.completions.create( modelos.getenv(MODEL_NAME, gpt-4o-mini), messagesmessages, toolstools, tool_choiceauto, ) message response.choices[0].message messages.append(message) # 如果没有工具调用模型已经给出了最终答案 if not message.tool_calls: return message.content # 否则逐个执行模型请求调用的 Skill for tool_call in message.tool_calls: result execute_skill( tool_call.function.name, json.loads(tool_call.function.arguments), ) messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) return 达到最大交互轮次任务未完成。这个循环很容易理解但它已经是一个完整的 Agent 雏形有决策、有工具调用、有观察、有终止条件。后面你学任何 Agent 框架本质上都是在这个循环外面套更多的工程手段。5.3 运行与调用最后加一个入口方便从命令行测试# main.py追加代码 if __name__ __main__: import sys question sys.argv[1] if len(sys.argv) 1 else 请列出当前目录的文件并告诉我杭州天气如何。 print(run_agent(question))运行python main.py 帮我看看当前目录有哪些文件杭州天气怎么样如果一切正常模型会先调用list_files再调用fetch_weather最后把两个结果整理成一段自然语言回答。这里需要区分一个概念你可能会看到模型中消息里既出现了 Assistant 的 tool_calls又出现了 Tool 的执行结果。也就是说模型并不直接执行execute_skill它只是发出一条“我希望调用 fetch_weather”的指令真正执行的是你的本地函数。这个设计非常关键它让模型永远不直接接触你的系统文件所有执行都发生在你的代码控制范围内。6. 运行结果与效果验证这个示例的验证点有三个模型是否正确选择了 Skill、Skill 是否正确返回结果、Agent 是否能把多轮信息整合成最终答案。如果代码跑通你会看到类似下面的输出不同模型和上下文下内容会有差异这里只作为示意当前目录下有以下文件.env、main.py、requirements.txt。 杭州天气晴25 摄氏度宜出行。如果模型没有调用工具而是直接编造了天气说明你的 Skill 描述质量不够模型没有意识到需要调用工具。这时候可以修改fetch_weather的描述加上一句“只在你需要获取天气数据时调用不要根据常识猜测天气”。这种看起来很小的调整往往就是 Agent 行为改善的关键。如果程序报错先做三件事第一确认.env里的 API Key 和 Base URL 是否正确第二确认网络环境能正常访问你配置的模型服务第三把异常堆栈里最靠上的错误信息发给模型排查通常大部分问题都能通过这步定位。7. Agent 开发常见问题与排查思路问题现象可能原因排查方式解决方案Agent 从来不调用工具工具描述模糊或模型不支持 function calling审查 Skill 描述打印 messages 查看模型决策重写 Skill 描述加入触发场景和边界说明工具被反复调用无法结束缺少终止条件或工具返回结果未满足预期增加日志观察每轮 tool_calls 内容设置 max_turns或增加“结果校验”环节工具参数 JSON 解析失败模型生成的参数缺少必填字段打印 tool_call.function.arguments使用更严格的 JSON Schema并在代码里校验必填字段上下文窗口很快被占满每轮都注入完整历史消息计算 messages 的 token 数引入短期记忆截断或把历史消息摘要化模型调用外部服务时权限过大工具执行代码没有限制危险操作审查 execute_skill 的逻辑增加白名单、人工审核遵循最小权限原则本地运行正常部署后不稳定日志缺失无法定位原因检查部署环境的日志等级和监控引入 trace_id、全链路日志和告警模型不理解复杂任务单轮指令过载拆解任务观察哪一步出错把任务拆成多个 Skill让 Agent 分步完成不同模型的工具调用行为差异大模型能力不同固定模型版本建立回归测试关键 Agent 使用同一模型工具调用失败时降级这几个问题不是凭空列出来的而是 Agent 项目里最高频的故障点。尤其是“工具被反复调用”和“上下文窗口被占满”在原型阶段不常见一旦进入真实业务就会出现。早一点设计好终止条件和记忆策略能省去大量后续返工。8. Agent 开发最佳实践与工程建议8.1 技能命名与注册Skill 的命名会直接影响模型是否主动使用它。建议采用“动词 对象 场景”的命名方式例如query_open_order、calculate_refund_amount、get_user_recent_trade避免使用含义模糊的名字。同时在注册时给每个 Skill 带上版本号。线上 Agent 升级时如果某个 Skill 的行为改变你能够追踪是哪一版本导致的回归。如果你负责的团队有多个 Agent建议把 Skill 清单做成独立的配置文件而不是散落在主代码里。例如一个skills.json可以这样组织{ agent_name: ops-assistant, system_prompt: 你是一个运维助手只在获得明确授权后执行变更操作。, skills: [ { name: fetch_weather, description: 查询指定城市天气, parameters: { type: object, properties: { city: {type: string} }, required: [city] } } ], max_turns: 5, allow_skills: [fetch_weather, list_files] }这样设计的好处是Skill 的增删改都不需要动模型调用代码只需修改配置并重新加载。对于不熟悉代码的运营人员来说这也更友好。8.2 日志、追踪与版本管理在 Agent 的开发过程中日志应该遵循“每次决策都有迹可循”的原则。每一轮循环至少记录以下内容trace_id 或 session_id。模型名称和模型参数。入参 user_input。模型返回的 tool_calls。每个工具的名称、参数、执行耗时、返回结果。当前 messages 的累计 token 数。有了这些记录当你发现 Agent 在线上“发疯”时才能回放当时的完整决策链路。没有 trace 的 Agent 项目本质上是一个黑盒。等到出了问题再希望模型自己解释清楚几乎不可能。版本管理方面不仅代码要进 GitSkill 的定义和 system prompt 也应纳入版本控制。一次线上 Agent 行为变化往往不是代码变化而是提示词或 Skill 描述被悄悄改动了。8.3 安全边界与最小权限Agent 给应用带来便利的同时也放大了安全风险。传统 API 的参数和逻辑基本可预期但 Agent 的每一步都是模型自动决策这意味着错误操作一旦发生可能是连锁反应。安全实践建议遵循五条铁律所有非只读操作默认关闭只有显式配置才允许执行。危险操作必须经过人工确认比如“用户确认删除前Agent 不得发起删除请求”。Skill 执行时使用独立密钥不要使用管理员权限的账号。数据库删除、批量更新、文件覆盖等操作执行前必须在测试环境验证并保留回滚脚本。Agent 的日志里必须对密码、Token、个人隐私信息做脱敏处理。很多团队只在测试环境用假数据所以 Agent 看起来一切正常。等到生产环境接上真实库某个工具误删了一条记录才发现根本没有设计审批流程。这个风险不是模型造成的而是工程护栏缺失造成的。8.4 从原型到生产从 Demo 到生产的路径我建议分成三步走。第一步先把最小决策循环跑通。就像上面示例一样不引入复杂框架只做“模型 工具调用 结果返回”。这一阶段的目的是验证模型是否理解 Skill 描述工具是否能稳定执行。第二步补齐工程设施。加入日志、追踪、超时控制、重试机制、配置管理、安全策略。这里才开始选择是否使用 Agent 框架。框架解决的是工程模板和调度编排问题而不是模型能力问题。如果你的场景逻辑简单自己维护一个封装好的 agent loop 可能比引入重框架更省心。第三步引入记忆和评估。当 Agent 要处理多轮复杂任务时加入短期记忆、长期记忆、RAG 检索能力。同时建立一套评估集把典型的用户问题记录成回归用例每次修改 Skill 或提示词后都跑一遍确保没有破坏已有能力。从原型到生产真正的分水岭不是“能不能用自然语言对话”而是“Agent 的行为是否可以预期、可以回溯、可以控制”。9. 总结与后续学习方向回到开头那个 Hacker News 问题Agent 技能到底哪些是必要的答案不是某个框架也不是某一种模型调用技巧而是一套组合能力懂得如何把任务拆解成模型可调用的 Skill懂得如何设计记忆和上下文懂得如何用日志和评估保证行为可控更懂得如何给 Agent 设安全边界。这套能力本身就是最重要的 Agent Skill。对于刚起步的开发者我的建议很直接先不要急着研究复杂的 Agent 编排框架也不要一开始就追求多 Agent 协作。找一个你自己熟悉的业务场景封装 3 个以内的 Skill跑通一个最小 Agent然后把日志和测试补上。这个过程经历一遍你对 Agent 的理解会超过只看文档的很多倍。如果还想继续深入接下来可以关注四个方向一是模型 Tool Calling 在不同模型上的表现差异二是 RAG 和记忆管理对长任务的影响三是 Agent 测试与评估框架的设计思路四是 MCP 这类开放工具协议。无论技术热点怎么变“如何让模型稳定、安全、可解释地调用能力”这个命题会一直存在。建议先把今天这个最小示例收藏起来改造成自己的第一个 Agent 项目跑起来之后很多概念就自然通了。