在海外开发者社区经常能看到类似 “What agent skills are necessary?” 的讨论。提出这个问题的人往往已经跑通了一个能调用大模型的小 Demo但真正开始做 Agent 产品时才发现模型返回文本只是最外层真正决定 Agent 能不能稳定完成任务的是一整套围绕模型能力展开的工程组件也就是通常所说的 Agent Skills。这篇文章会从概念、分类、最小实现、生产部署、问题排查到学习路线把 Agent Skills 这件事讲清楚。核心结论先放在前面一个能回答问题的聊天机器人和一个能在真实环境里持续执行任务的 Agent差距不在模型本身而在模型之外的技能编排、工具调用、记忆管理、安全确认、错误恢复和评估反馈。下面逐步展开。1. 先建立统一认知Agent、Skill、Tool、Harness 到底怎么区分很多项目讨论到一半就陷入争论根源是名词没有对齐。这里先统一概念后续所有实现都基于这套划分。1.1 从一次工具调用看 Agent 的基本工作链路一个最简单的 Agent 循环可以拆成四步模型接收用户任务。模型决定调用某个 Skill。Skill 执行并返回结构化结果。模型观察结果后决定继续调用、调整方案或直接给出最终答案。用一个极简伪代码描述这个循环def agent_loop(user_task: str, model, available_skills: dict, max_iterations: int 10): messages [{role: user, content: user_task}] for i in range(max_iterations): resp model.get_response(messages, skillsavailable_skills) if resp.finish_reason stop: return resp.content if resp.finish_reason tool_call: for call in resp.tool_calls: if call.name not in available_skills: raise UnknownSkillError(call.name) skill available_skills[call.name] result skill.run(**call.args) messages.append({ role: tool, tool_call_id: call.id, content: result.model_dump_json(), }) else: raise AgentLoopError( f第 {i 1} 轮出现无法处理的结束原因: {resp.finish_reason} ) raise AgentLoopError( f超过最大迭代次数 {max_iterations}Agent 未能在任务上收敛 )这段代码里available_skills是 Agent 能使用的技能集合model.get_response负责决定调用哪个技能skill.run是技能的真实执行。如果模型连续调用多个技能循环会继续下去如果模型认为任务完成就返回stop。这个循环是所有 Agent 项目的骨架。1.2 用一张表区分几个高频概念热搜词里反复出现 “harness 和 agent 区别”“skill 和 agent 的区别”“agent框架与编排”说明很多人在概念层卡住了。下面是常用区分方式概念通俗理解在 Agent 系统中的职责常见误区Agent一个能自主完成任务的执行单元调度模型、技能、记忆和外部环境把“调用大模型的脚本”直接叫 AgentSkillAgent 具备的一项能力描述“能做什么”及其输入输出约定把 Skill 等同于一段 Prompt 或一个函数ToolSkill 的具体实现载体执行真实操作比如搜索、写文件、查数据库只实现 Tool却没有定义模型怎么理解它Harness承载 Agent 运行的框架与循环管理模型调用、技能调度、上下文、日志和终止条件以为装了 Harness 就等于有完整 AgentFramework一站式开发框架把上述组件组合成可运行应用过度依赖框架失去对关键链路控制从工程角度看Agent 是一个运行时概念Skill 是能力抽象Tool 是能力实现Harness 是执行环境。四者必须协作才能构成一个可靠系统。这里给出一个判断标准如果项目中只有“客户端 一段提示词”没有技能注册表、没有工具调用协议、没有循环终止条件那它还不是 Agent只是一个“增强对话脚本”。2. 从工程角度看哪些 Agent Skills 是必要的可以把 Agent Skills 理解为“模型之外必须补齐的能力模块”。按照必要程度可以分成两级最低可用使能级和可用生产级。2.1 最低可用 Agent 需要的一组 Skill一个 Demo 级的 Agent 至少需要四种能力指令遵循模型能理解用户任务知道什么时候该结束。工具调用模型能按约定调用外部函数并把工具结果填回上下文。基础结果校验工具返回后模型需要判断结果是成功还是失败不能把错误信息当作可用结果。简单会话记忆多轮对话中能记住用户刚提过的要求而不是每次丢失上下文。这四样跑通一个 Agent 才真正“能干活”。如果只有模型 Prompt没有任何工具调用协议那本质上仍是聊天接口。2.2 生产级 Agent 还需要补齐的能力进入生产环境后以下能力往往不是“加分项”而是“缺一个就出大问题”的必需项技能域解决什么问题典型实现方向是否必需工具接入与 Function Calling让模型稳定调用外部函数统一的参数 Schema、错误返回格式、工具注册表必需记忆管理跨会话或在长任务中保留状态短期上下文管理、长期存储、向量检索必需规划与任务分解面对复杂任务时能拆解步骤Planner、子任务队列、阶段性检查点高反思与自我修正发现错误或结果不可信时主动调整Reflector、Critic 组件、重试策略高安全与权限控制防止破坏性操作、越权访问和数据泄露白名单、敏感操作确认、审计日志必需人机协同在关键节点找用户确认Human-in-the-loop、确认回调高评估与回归验证输出质量避免改一个功能坏一片断言测试、评估 Prompt、对比集必需日志与可观测性知道每一轮 Agent 做了什么结构化日志、追踪 ID、耗时统计必需长上下文管理处理超长对话和大量工具结果摘要、裁剪、滑动窗口视场景而定多 Agent 协作多个 Agent 分担角色并交换信息消息协议、任务仲裁、共享内存视场景而定这张表可以直接用来做 Agent 项目的能力盘点。实际开发时可以先根据业务场景调整优先级但工具接入、记忆、安全、评估、日志这五项在大多数生产场景里都建议提前考虑。2.3 为什么“思考能力”也要被当成 Skill 来设计规划、反思、质疑、总结这些能力表面上是模型 Prompt 的事但在工程里最好也抽象成 Skill。一个常见做法是在技能注册表里增加plan、reflect、critic这类“元技能”。它们不是外部工具而是模型内部的一轮思维过程。例如class PlanParams(BaseModel): goal: str Field(description任务目标) constraints: list[str] Field(default[], description执行约束) class PlanSkill(Skill): name task_plan description 将复杂任务拆解为可执行的子任务列表 parameters_model PlanParams def execute(self, params): # 调用模型生成计划并把计划写入上下文 plan_prompt f请为任务拆解步骤{params.goal}\n约束{params.constraints} result llm_call(plan_prompt) return SkillResult(message计划已生成, data{plan: result})把思考过程显式建模有两个好处第一可以单独测试和评估某类能力第二可以在循环里加入条件判断比如“反思结果标记任务不可行时提前终止”。3. 动手实现一套必要的 Agent Skills下面用一个简化示例展示如何把上面的概念落地。示例代码用于说明思路实际项目请根据自己的包名、路径和模型协议调整。3.1 先定义 Skill 的统一抽象输入、输出、错误协议如果每个 Skill 的返回格式都不一样模型就会很难判断“这次调用到底成没成功”。因此第一步是统一协议。from pydantic import BaseModel, Field class SkillResult(BaseModel): ok: bool True message: str data: dict | None None error: str | None None class Skill: name: str description: str parameters_model: type[BaseModel] requires_confirmation: bool False def schema(self) - dict: return { name: self.name, description: self.description, parameters: self.parameters_model.model_json_schema(), } def run(self, **kwargs) - SkillResult: params self.parameters_model(**kwargs) return self.execute(params) def execute(self, params): raise NotImplementedError这里的关键点是所有 Skill 返回SkillResult模型只需要解析ok、message、data、error四个字段。参数模型用 Pydantic 定义框架可以把它转成 JSON Schema 给模型做 Function Calling 时模型依赖这份 Schema 来生成参数。requires_confirmation标记该 Skill 是否需要在执行前让用户确认。3.2 写几个典型 Skill搜索、写文件、记忆读写搜索是典型的外部工具。示例实现里省略了真实搜索引擎 API重点展示参数约束和结果包装class WebSearchParams(BaseModel): query: str Field(description搜索关键词) max_results: int Field(default5, ge1, le10, description返回结果数量) class WebSearchSkill(Skill): name web_search description 搜索公开网页信息适用于获取最新资料 parameters_model WebSearchParams def execute(self, params): if params.max_results 10: return SkillResult(okFalse, errormax_results 不能超过 10) # 实际项目在这里接入搜索服务的 SDK return SkillResult( messagef搜索完成: {params.query}, data{items: [示例结果一, 示例结果二]} )写文件属于高风险操作需要单独控制覆盖行为import os class FileWriteParams(BaseModel): path: str Field(description目标文件路径) content: str Field(description写入内容) overwrite: bool Field(defaultFalse, description是否覆盖已有文件) class FileWriteSkill(Skill): name file_write description 将内容写入本地文件默认不允许覆盖已有文件 parameters_model FileWriteParams requires_confirmation True def execute(self, params): if os.path.exists(params.path) and not params.overwrite: return SkillResult( okFalse, error目标文件已存在请确认是否覆盖, ) with open(params.path, w, encodingutf-8) as f: f.write(params.content) return SkillResult(messagef文件已写入: {params.path})记忆读写可以先用一个简单的内存存储后续再替换为数据库或向量库class EpisodicMemory: def __init__(self, max_items: int 20): self.events [] self.max_items max_items def add(self, event: str): self.events.append(event) if len(self.events) self.max_items: self.events.pop(0) def recent_facts(self, k: int 5) - str: return \n.join(self.events[-k:])记忆最容易被忽略的地方是“写入策略”。不是所有工具结果都值得记只有对后续任务有影响的事实才需要写入。否则记忆会变成上下文噪音甚至污染模型判断。3.3 在 Agent Loop 中把 Skill 串起来注册所有 Skill 后把它传给模型调用层SKILL_REGISTRY { web_search: WebSearchSkill(), file_write: FileWriteSkill(), } def call_model(messages, tools): # 这里对接具体模型服务OpenAI 兼容接口通常传入 tools 参数 # 实际项目需要根据模型厂商的协议调整字段名 return model_client.chat.completions.create( modelyour-model, messagesmessages, tools[tool.schema() for tool in tools.values()], )在循环里模型返回工具调用后统一从注册表执行for call in resp.tool_calls: skill SKILL_REGISTRY[call.name] result skill.run(**call.args) messages.append({ role: tool, tool_call_id: call.id, content: result.model_dump_json(), })这里有几个容易出错的细节工具调用 ID 必须原样回传否则模型服务无法关联工具结果。content必须是可解析的 JSON 字符串不能是 Python 对象。模型一次可能请求调用多个工具需要逐个执行并逐一回填结果。3.4 给 Skill 增加安全确认Human-in-the-loop不是所有操作都应该由模型自主完成。写文件、发邮件、删数据、转账这类操作建议执行前暂停一次。def confirm(message: str) - bool: # 实际项目中可以弹出 UI、发送审批消息或读取一个确认文件 user_input input(f{message} [y/N]: ) return user_input.strip().lower() in (y, yes) def run_skill_with_guardrail(skill_name: str, kwargs: dict): if skill_name not in SKILL_REGISTRY: raise UnknownSkillError(skill_name) skill SKILL_REGISTRY[skill_name] if getattr(skill, requires_confirmation, False): if not confirm(f即将执行 {skill_name}({kwargs})是否继续): return SkillResult(okFalse, error用户取消执行) return skill.run(**kwargs)这个实现非常简单但思路值得沿用把“能否执行”和“如何执行”分开判断。即使模型决定调用高风险 Skill执行前仍然有人工确认环节。3.5 给 Agent 增加评估反馈机制没有评估Agent 就只能靠肉眼观察结果。一个最基础的评估组件可以这样设计def evaluate_output(question: str, output: str, expected_keywords: list[str] | None None): if expected_keywords: missing [kw for kw in expected_keywords if kw not in output] if missing: return { pass: False, reason: f输出缺少关键内容{missing}, question: question, output: output, } return { pass: True, reason: 断言通过, question: question, output: output, }更完整的做法是准备一组回归用例每个用例包含“问题、期望结果断言、不允许出现的内容、运行环境”。每次修改 Prompt、Skill 或模型版本后都把这组用例跑一遍。注意不要只验证程序能启动还要验证输入、输出、异常分支和日志是否符合预期。Agent 程序能运行但结果错误比直接崩溃更难排查。4. 参数配置与生产部署学习环境和生产环境的差距很多 Agent 在本地跑得通上线就崩问题往往出在参数配置和生产环境差异上。4.1 一个 Skill 需要配置哪些运行参数下面是常规应配置的参数实际项目可根据含义增加或删减参数含义典型值调大的影响调小的影响timeoutSkill 单次执行超时5-30 秒等待更久降低超时失败率更快失败但可能误杀慢任务max_retries失败重试次数0-3提高成功率但增加耗时快速失败对偶发错误不友好max_results查询类结果数量上限5-10信息更多但占用上下文更省 token但可能丢关键信息cache_ttl结果缓存时间0-300 秒减少重复调用但可能返回旧数据实时性更强但成本上升concurrency_limit同一 Skill 并发上限1-10吞吐更高但可能打爆下游更稳但任务排队时间长requires_confirmation是否需要人工确认高风险操作设为 True更安全但增加等待更自动化但风险升高log_level日志详细程度INFO / DEBUG排查方便但日志量大日志少节省存储调参时一定要结合业务。比如写文件的接口服务超时设 5 秒大概率不够因为磁盘繁忙时写大文件可能超过 10 秒而搜索接口如果 10 秒还没返回更可能是网络问题重试 2 次意义有限。4.2 Agent Loop 本身的运行参数Agent 循环的参数也很关键尤其是迭代上限和终止条件agent_loop( user_task分析用户反馈并生成改进报告, modelmodel, available_skillsSKILL_REGISTRY, max_iterations15, )这里max_iterations是防止 Agent 进入死循环的最重要防线。设置过小复杂任务完不成设置过大一个问题可能跑几分钟甚至一直循环。生产环境建议分场景配置例如简单问答 5 次复杂任务 20 次超限后返回“任务未完成”并附上已执行步骤。其他相关配置temperature一般 0 到 0.3 比较适合工具调用类任务过高会产生随机参数或不稳定决策。top_p和 temperature 类似通常保持默认或配合调整不要两个同时大幅度调高。stop 条件可以增加关键词停止比如出现“任务完成”或“无法继续”时提前结束。工具数量一次传给模型的工具不要过多建议按场景分组加载避免模型在几十个工具间犹豫。4.3 生产环境比 Demo 多考虑哪些事情Demo 里可以只用print输出结果但生产环境至少还要补齐这些追踪与审计记录每一轮用户输入、模型响应、工具调用、工具结果和最终输出。幂等设计同一个工具调用如果重试不能产生重复副作用。比如写文件可以用“覆盖前校验版本号”发通知可以用“任务 ID 去重”。限流与配额防止单个用户的任务占用全部模型并发。回滚策略Prompt 或 Skill 代码变更后保留上一版本方便快速回退。权限隔离Agent 运行环境只给最小权限不要让它拥有整个服务器权限。数据安全工具结果中如果包含敏感信息要在发给模型前脱敏或过滤。监控告警对循环超限、工具失败率高、模型返回异常等情况设置告警。学习环境和生产环境最大的差异是“失败成本”。Demo 中失败无非重新运行生产环境中一次错误调用可能造成数据覆盖、资损或安全事故。这也是为什么权限和安全确认必须提前设计。5. 高频踩坑与排查思路实际开发中Agent 项目的问题通常集中在工具调用、上下文、记忆和终止条件几个方向。下面列出高频问题。5.1 模型始终不调用工具或调用格式错误现象模型只返回文本完全不调用 Skill或者调用时参数缺字段、参数类型不对。常见原因模型本身不支持 Function Calling或当前模型版本要求不同的调用协议。工具描述不清晰模型不知道这个工具适合什么问题。JSON Schema 里有冲突定义比如要求required但缺少对应properties。一次传了太多工具模型选择困难。模型没有在 Prompt 中被明确要求“当需要最新信息时调用搜索”。检查方式打印传给模型的tools列表确认 Schema 完整。用一个小测试请求只传一个 Skill看模型是否能调用。查看模型服务返回的原始响应确认finish_reason是不是tool_call。处理建议每个工具的描述写清楚“在什么场景使用”和“不要误用”。参数尽量少字段名要与常见语义一致。如果模型对 JSON Schema 支持不好可以降级为“由模型输出 JSON再由程序解析”的模式。5.2 工具调用成功了但 Agent 不会利用工具结果现象模型发出tool_call工具正常返回结果但下一轮模型没有基于工具结果继续而是开始空泛总结。常见原因工具结果格式过碎或过长模型提取不到关键信息。工具返回的data字段没有做摘要直接把原始大对象塞进上下文。工具结果缺少ok/error语义模型无法判断这次调用是否成功。处理建议工具结果统一做摘要尽量控制在几百字以内。把返回结果里的关键条目重新组织成自然语言而不是返回裸 JSON。在 Prompt 中明确“优先使用最新的工具结果回答不要凭记忆猜测。”def format_search_result(result: SkillResult) - str: if not result.ok: return f搜索失败{result.error} items result.data.get(items, []) lines [f{i 1}. {item} for i, item in enumerate(items[:5])] return 搜索结果摘要\n \n.join(lines)这样模型看到的是可读文本而不是难以解析的嵌套结构。5.3 长任务出现 “Agent execution terminated due to error” 或直接中断现象任务执行到一半日志里出现类似Agent execution terminated due to error.的异常或者循环直接退出。常见原因超过max_iterations上限。工具执行抛出未捕获异常导致循环中断。上下文长度超限模型接口直接报错。模型 API 限流或网络超时。工具参数包含不可序列化对象回填到 messages 时失败。检查方式先看异常栈定位是模型调用层还是 Skill 执行层。查看任务是第几轮中断的统计每轮 token 消耗。检查最大迭代次数和实际调用次数。检查工具返回结果是否经过model_dump_json()或json.dumps()序列化。处理建议在 Agent 循环的最外层包一个try/except把异常转成可阅读的错误结果而不是让任务直接崩溃。对每个 Skill 的执行加入独立异常捕获保证一个 Skill 失败不影响整个循环。在每次迭代前检查上下文长度提前做摘要裁剪。为外部 API 调用加入超时和指数退避重试。def safe_run_skill(skill, kwargs): try: return skill.run(**kwargs) except Exception as e: return SkillResult( okFalse, errorfSkill {skill.name} 执行异常: {type(e).__name__}: {e}, )# 排查时可以先从日志里筛选异常片段 grep -n Agent execution terminated\|ToolFailed\|RateLimit agent.log5.4 记忆污染导致前后矛盾现象Agent 在长会话后半段开始混淆信息把上一轮确认过的结论又说错。常见原因把所有历史消息都堆进上下文不区分重要程度。记忆写入过早把中间过程当成了最终事实。检索到的记忆与当前问题无关却被强制拼进上下文。多个会话共用一份记忆没有按用户或任务隔离。处理建议记忆写入前设置审核条件比如“只有工具执行成功且结果与任务目标相关时才写入”。记忆数据带上来源、时间和置信度模型检索时能看到元信息。按会话 ID 或用户 ID 隔离记忆空间。现象常见原因检查方式处理建议同一事实前后回答不一致记忆写入无审核或没有读取记忆打印每次读到的记忆片段加上写入审核记忆与当前任务做相关性过滤Agent 记不住关键要求短期记忆容量太小被工具结果挤占查看上下文裁剪策略为“用户关键要求”单独设置持久槽位答非所问内容来自旧任务跨会话记忆未隔离检查记忆表是否带 session_id按会话、用户、项目维度隔离5.5 权限过于宽泛破坏性操作没有确认现象Agent 可以直接覆盖生产文件、批量发消息或删除数据一旦模型判断失误后果严重。常见原因所有 Skill 都没有requires_confirmation。模型 Prompt 中缺少“哪些操作不能直接执行”的约束。Agent 运行环境使用了过大的文件或网络权限。处理建议默认所有写操作都标记为高风险。在运行环境里用独立账号只授予任务所需的最小权限。对敏感操作保留审计日志包括用户、时间、参数、结果。5.6 没有回归评估改了 Prompt 后老场景退步现象新功能上线后原有场景突然表现变差但没有人知道是哪次改动导致的。常见原因Prompt 修改没有版本记录。Skill 行为变化没有配套回归用例。只测了“正常路径”没有测“工具失败路径”和“拒绝路径”。处理建议建立一份回归用例集至少覆盖正常调用、工具失败、参数错误、用户取消、超长上下文、模型拒绝。每次变更后跑一遍用例集并记录通过率。把用例集纳入 CI和普通代码测试一起执行。6. 从“必要技能”倒推一条 Agent 开发学习路线这部分回应很多人都关心的“Agent 开发学习路线”和“Agent 面试题”话题。学习路线不需要贪多关键是先补齐必要技能。6.1 按工程难度排序的学习路径阶段学习内容完成标准基础大模型 API、Prompt 设计、上下文长度能写出稳定输出格式的对话程序工具能力Function Calling、JSON Schema、工具错误返回能让模型稳定调用一个自定义函数循环Agent Loop、迭代上限、结果回填实现一个“调用工具-观察-继续”的最小 Agent记忆短期记忆、长期存储、向量检索实现跨会话记住关键事实的 Agent规划任务拆解、反思、计划修正实现复杂任务的自动拆步与阶段性校验评估回归用例、评估 Prompt、错误分类建立一套可重复跑的 Agent 测试集安全权限控制、人工确认、审计日志给高风险操作加护栏工程化日志追踪、限流、监控告警、回滚把 Agent 部署成可运维的服务每个阶段都尽量写一个可运行的小项目而不是只看概念。比如学 Function Calling就写一个“天气查询”工具学记忆就写一个“会议记录助手”。6.2 面试和团队评审中会被反复追问的问题这些问题本质上都在考察 Agent Skills 的工程完备度你的 Agent 如果陷入死循环怎么办工具调用失败后Agent 如何恢复你怎么保证 Agent 不会执行破坏性操作长上下文到了上限任务还没完成怎么办多个工具结果之间存在冲突模型应该听谁的修改 Skill 后如何证明旧场景没有被破坏记忆数据如果被写错了怎么纠正如果这些问题只能回答“提示词里写了”说明 Agent 还停留在实验阶段如果能给出明确的检查点、默认值、失败策略和日志才是生产级答案。6.3 可复用的检查清单新 Skill 上线前检查[ ] 是否有明确的名称和描述[ ] 参数是否有范围约束和默认值[ ] 返回格式是否遵循SkillResult统一协议[ ] 失败和超时是否有明确返回[ ] 是否在安全评估中确认该操作的风险等级[ ] 高风险操作是否设置了requires_confirmation True[ ] 是否记录了日志包含调用方、参数、耗时、结果[ ] 是否加入回归用例集Agent 进入生产前检查[ ] 最大迭代次数是否设置是否分场景配置[ ] 上下文超限是否有自动裁剪策略[ ] 工具异常是否会被捕获并返回给模型[ ] 权限是否按最小权限原则配置[ ] 是否有完整追踪日志能复现一次任务[ ] 是否有限流、缓存和超时控制[ ] 是否有回滚方案[ ] 是否跑过至少一轮完整回归排查 Agent 问题时按这个顺序查输入是否正确用户指令、历史消息、附加文件。模型层是否支持工具调用返回的finish_reason是什么是否有异常。工具层Skill 是否注册参数是否解析成功工具执行是否抛错。上下文层消息是否超长工具结果是否被正确回填是否有内容被意外截断。权限层是否因为缺少权限或人审导致执行被拒绝。配置层超时、重试、迭代上限、并发是否设置过小或过大。评估层是否能用一条简单命令复现问题并有无对照用例。7. 写在最后先补齐必要项再追求花哨回到 “What agent skills are necessary?” 这个问题真正有价值的答案不是列一个无限多的能力清单而是找到“最低完备集”。在这个集合里工具调用协议、记忆管理、安全确认、错误恢复、评估反馈和可观测性每一项都比单纯的“模型换得更大”更关键。对一个刚开始做 Agent 的团队建议先把一个最小闭环跑通一个能调工具的循环一个能返回结构化结果的 Skill一个能在失败时恢复的异常处理一个能证明结果没跑偏的评估用例。这四件事做完Agent 才具备交给真实用户使用的底线。下一步可以从三个方向扩展一是给 Agent 增加可信任的长期记忆二是加入更完善的人工审批流三是让多个 Agent 以清晰的消息协议协作。每一层扩展都会引入新的 Skill 需求但底层的工程纪律不会变所有能力都要有可解释的输入输出所有失败都要有可追踪的日志所有变化都要有可回归的测试。把这条主线守住Agent 开发基本不会走上“什么都试一下但什么都不稳定”的老路。