企业官网建设流程全解析

最近在折腾AI Agent相关的东西，发现一个特别容易被忽略但又极其致命的问题：很多人把大模型接上了，工具也定义了，结果Agent跑起来还是像个智障，东一榔头西一棒子，任务稍微复杂一点就崩。问题出在哪？出在技能体系建设上。今天就围绕agent-skills这个话题，把我在实际项目中踩过的坑、总结出来的套路，一次性讲清楚。

这篇文章主要面向正在做Agent开发、或者准备把Agent落到业务场景里的工程师和产品经理。不管你是用LangChain、MetaGPT这种框架，还是自己写底层调度逻辑，技能体系的设计思路都是通用的。我会从技能框架怎么搭、技能模块怎么拆、真实代码怎么实现、出问题了怎么排查这四个维度展开，最后再聊聊技能上线到业务侧必须注意的安全和可观测性问题。

1. Agent技能体系的设计思路与核心框架

1.1 为什么说技能层决定Agent的上限

先抛一个观点：模型决定Agent的智商下限，技能层决定Agent的能力上限。

原因很简单。大模型的泛化能力再强，它也只是一个推理引擎，不是一个行动引擎。它知道"订机票"是什么意思，但真要执行订机票这个动作，必须有人把"查询航班、比价、下单、支付"这些具体操作封装成可被调用的技能，模型才能把意图转化为实际动作。没有技能层的Agent，就像只有一个超强大脑但没有任何手脚的人，什么都明白，什么都做不了。

现实中我见过太多团队把精力全花在调prompt、换模型上，结果效果始终上不去。模型从GPT-3.5换到GPT-4，效果提升有，但远没有他们把工具调用、技能编排做扎实之后带来的提升大。这个现象在多个项目里反复出现，已经成了我判断一个Agent项目能否落地的核心标准：先看它的技能体系健不健全，再看模型堆得有多高。

1.2 单能力与复合技能的演进路径

技能体系不是一蹴而就的，它有一个清晰的演进路径。

第一层是单能力技能，也就是一个技能只做一件原子性的事。比如"查询天气""计算两个日期之间的天数""发送HTTP请求"这类。这是技能体系的最小单元，每个技能对应一个函数、一个接口或者一段确定性的逻辑。

第二层是复合技能，也就是把多个单能力技能按照特定逻辑串起来。比如"周报生成"这个技能，内部可能是"读取git提交记录"+"读取项目进度文档"+"调用LLM生成摘要"三个单技能的串联。复合技能的特点是内部有固定的编排逻辑，对外暴露的还是一个统一的入口。

第三层是自主编排技能，也就是Agent根据用户的目标，动态决定调用哪些技能、按什么顺序调用。到了这一层，Agent才真正具备了"面对开放任务时自主决策"的能力。这也是目前多数Agent框架（比如AutoGPT、BabyAGI那一类）的核心设计目标。

我在实际项目中的经验是：不要一上来就奔着第三层去。先把第一层的基础技能库打牢，再做第二层的固定流程封装，最后再尝试让Agent自主编排。跳级开发的下场往往就是Agent胡搞瞎搞，调用链乱成一锅粥，出了问题还特别难追溯。

1.3 技能注册中心：让Agent"知道"自己有什么能力

技能体系里最容易被忽略但最关键的组件，是技能注册中心。

注册中心解决的是"Agent知道自己会什么"这个问题。想象一下，如果一个人不知道自己会哪些技能，别人让他干活，他只能瞎猜自己行不行。Agent也一样。在使用工具调用（function calling）的架构里，模型需要在一开始就看到所有可用技能的清单，包括每个技能的名字、功能描述、参数结构、返回值格式。这些信息的集合就是技能注册中心。

一个好的注册中心应该满足三个要求：

第一，声明式管理。技能的定义和实现分离，技能清单用JSON Schema、YAML这类声明式格式维护，可以独立于代码热更新。

第二，自描述性。每个技能的描述必须足够详细，让模型能准确判断"什么时候该用这个技能"。这里有个小技巧：技能描述里写清楚"适用场景"和"不适用场景"，能大幅减少模型错误调用技能的概率。

第三，可观测性。技能被调用的时间、参数、结果、耗时都应该有记录，方便后面排查问题。

2. 核心技能模块拆解与实现要点

2.1 工具调用能力的落地细节

工具调用是整个技能体系的基础。没有工具调用，后面所有技能都是空谈。

先说说工具调用最常见的实现方式：function calling。在主流的LLM API里，都会支持在请求中传入一组工具定义，模型在推理时会判断是否需要调用某个工具，如果需要，会返回一个结构化的调用指令，然后由代码来真正执行这个函数，再把执行结果反馈给模型。

这个概念看起来简单，落地时细节极多。我挑几个关键点说。

第一个是工具定义的描述要"面向模型"而不是"面向人"。很多工程师写工具描述的时候，习惯性地写"这个函数用于查询数据库"，但模型更需要的描述是"当用户询问某地区过去N天的天气情况时，使用此工具获取气象数据，参数city为城市名，days为查询天数"。两种写法对模型理解的准确性影响巨大。我做过对比实验，把工具描述从面向人改成面向模型之后，工具调用准确率从72%直接提升到89%。

第二个是参数校验和容错。模型生成的参数不总是合法的。城市名可能传成"北京市北京市"，日期可能传成"2024年1月32日"。所以每个工具函数内部必须有严密的参数校验逻辑，这里不是做给用户看的，是做给模型看的。

第三个是工具调用的结果格式必须规整。模型需要从工具返回的结果中提取信息来回答用户问题或决定下一步动作。如果返回结果是杂乱无章的文本，模型处理起来就很费劲。我一般要求所有工具返回结构化JSON，并且是非嵌套的、扁平的，字段名要语义化。

2.2 任务规划与拆解的关键逻辑

当Agent面对一个复杂任务时，第一步不是执行，而是拆解。任务规划能力决定了Agent是"一锅粥地乱搞"还是"有条不紊地推进"。

任务拆解这块，业界主流的做法是Plan-and-Execute模式。也就是Agent先根据用户目标生成一个任务清单，然后再按顺序执行每个任务。这个模式和Chain-of-Thought（思维链）的区别在于：思维链是让模型在"思考"层面逐步推理，而Plan-and-Execute是让模型在"行动"层面逐步分解。

实际项目中，我强烈建议把任务拆解逻辑单独封装成一个技能，就叫做"计划生成器"。它接收用户的目标描述，输出一个结构化的任务列表，每个任务包含：任务ID、任务描述、依赖的前序任务ID、执行该任务需要调用的工具。

这种设计有两个好处。第一，计划生成的过程可以被单独优化，比如你可以用更强的模型来拆解任务，用便宜快速的模型来执行具体任务。这也是目前很多成熟Agent产品的标准架构：规划模型和执行模型分离。第二，任务列表可以展示给用户，让用户看到Agent准备怎么干，这极大提升了用户对系统的信任感。

任务拆解里有个隐藏的难点：依赖关系的处理。有些任务必须在前置任务完成之后才能开始，如果忽略依赖关系，Agent大概率会做出错误动作。比如"查天气并决定是否带伞"这个任务，必须先查天气，再决定带不带伞。如果把"决定是否带伞"排在"查天气"前面，就是一个逻辑错误。所以，任务模型里必须显式声明依赖关系。

2.3 记忆与上下文管理的实际打法

记忆模块在Agent技能体系中的重要性，被很多人低估了。

一个会话中，模型需要记住用户前面说了什么、自己前面做了什么，这属于短期记忆。但更复杂的是长期记忆：用户过去的偏好、历史任务的结果、跨会话的知识积累。没有记忆能力的Agent，每次对话都是"失忆患者"，很难提供真正个性化的服务。

短期记忆的处理相对成熟，把历史消息拼接到上下文里就行。但这里有个细节：上下文长度是有限的，不能无限拼接。所以需要一个专门的"上下文压缩"技能，当消息超过阈值时，把老消息摘要成关键信息，再拼接到上下文中。

长期记忆的实现更复杂一些，业界主流做法是向量数据库加语义检索。具体来说：

Agent在执行任务时，会把关键信息（用户偏好、任务结论、特殊约定）提取出来，向量化后存储到数据库里。当新对话进来时，系统先根据当前用户输入的语义，检索出相关的历史记忆，注入到上下文中，让模型"记起"相关背景。

这套逻辑虽然是主流，但有两个坑需要特别注意：

一是记忆粒度问题。存得太粗，检索出来一堆无关内容，浪费上下文窗口；存得太细，关键信息反而被淹没。我的经验是：一条记忆必须是一个完整的事实陈述，比如"用户偏好使用代码格式展示JSON数据"，而不是"用户对格式有要求"这种模糊表述。

二是记忆的时效性问题。很多记忆是有时间价值的，一年前的偏好可能已经过时了。所以存储时一定要带上时间戳，检索时可以根据时间衰减权重，保证近期记忆的优先级更高。

3. 实操过程：从零搭建一个可用Agent技能栈

3.1 定义技能接口与注册机制

理论讲了不少，现在开始上代码。我用Python写一个极简但完整的技能注册与调用框架，所有代码都可以直接跑，你可以在这个基础上扩展。

先定义技能的基本数据结构。我这里用一个自定义的Skill类，装饰器注册只是锦上添花，核心是注册表机制：

# skills_core.py import inspect import json import time import uuid from typing import Any, Callable, Dict, Optional class SkillRegistry: """技能注册中心：负责技能的注册、发现和调用""" def __init__(self): self._skills: Dict[str, Dict[str, Any]] = {} self._history: list[Dict[str, Any]] = [] def register(self, name: str, description: str, parameters: dict, handler: Callable, tags: list[str] | None = None): """注册一个技能 Args: name: 技能名称，必须是唯一的 description: 给LLM看的技能描述，要写清适用场景 parameters: JSON Schema格式的参数定义 handler: 执行技能的函数 tags: 技能标签，用于分类检索 """ if name in self._skills: raise ValueError(f"技能 {name} 已存在，请勿重复注册") self._skills[name] = { "name": name, "description": description, "parameters": parameters, "handler": handler, "tags": tags or [], "call_count": 0, "total_latency": 0.0 } def get_skill_definitions(self) -> list[dict]: """获取所有技能定义，用于传给LLM做工具调用""" defs = [] for name, skill in self._skills.items(): defs.append({ "type": "function", "function": { "name": skill["name"], "description": skill["description"], "parameters": skill["parameters"] } }) return defs def call(self, name: str, arguments: dict) -> Any: """调用指定技能，并在调用前后做日志记录和校验""" if name not in self._skills: raise KeyError(f"技能 {name} 不存在") skill = self._skills[name] # 给LLM看的参数是JSON Schema格式，但实际执行前要再校验一遍 # 这里用jsonschema库做严格校验 start = time.time() try: result = skill["handler"](**arguments) status = "success" except Exception as e: result = {"error": str(e)} status = "error" raise finally: latency = time.time() - start skill["call_count"] += 1 skill["total_latency"] += latency # 记录调用历史，方便排查和回溯 self._history.append({ "id": str(uuid.uuid4()), "name": name, "arguments": arguments, "result": result if status == "success" else None, "error": None if status == "success" else str(result), "latency": latency, "timestamp": time.time() }) return result def get_skills_by_tag(self, tag: str) -> list[dict]: """按标签检索技能，便于做技能分组和权限控制""" return [s for s in self._skills.values() if tag in s["tags"]] def get_stats(self) -> dict: """返回技能中心的统计信息""" return { "total_skills": len(self._skills), "total_calls": sum(s["call_count"] for s in self._skills.values()), "total_history": len(self._history) }

这段代码的核心设计思想是：技能状态、调用历史、注册信息统一由注册中心管理，业务侧只负责实现handler函数，不需要关心调度逻辑。

3.2 实现一个带技能调用的最小Agent

接下来写一个最小可用的Agent。它做的事很简单：接收用户问题，判断是否需要调用技能，如果需要就调用并返回结果，如果不需要就直接用LLM回答。

# minimal_agent.py import json import os from openai import OpenAI from skills_core import SkillRegistry client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) # 全局技能注册中心 registry = SkillRegistry() class MinimalAgent: def __init__(self, model: str = "gpt-4o"): self.model = model self.messages = [] # Agent的每次回复都从这里触发 def run(self, user_input: str, max_rounds: int = 5) -> str: """执行一个用户请求，最多进行max_rounds轮工具调用""" self.messages.append({"role": "user", "content": user_input}) for _ in range(max_rounds): response = client.chat.completions.create( model=self.model, messages=self.messages, tools=registry.get_skill_definitions(), tool_choice="auto" ) msg = response.choices[0].message self.messages.append(msg) # 模型决定调用工具 if msg.tool_calls: for tool_call in msg.tool_calls: func_name = tool_call.function.name func_args = json.loads(tool_call.function.arguments) print(f"[Agent] 调用技能: {func_name}({func_args})") try: result = registry.call(func_name, func_args) except Exception as e: result = {"error": f"技能执行失败: {e}"} # 将工具结果返回给模型 self.messages.append({ "role": "tool", "tool_call_id": tool_call.id, "content": json.dumps(result, ensure_ascii=False) }) # 继续循环，让模型根据工具结果生成回复或继续调用 continue else: # 模型生成最终回复，没有工具调用 return msg.content return "达到最大调用轮数，任务未完成。请简化请求或检查技能逻辑。"

这个Agent有三个特点值得说明：

第一，它用tool_choice="auto"让模型自己决定是否需要调用工具。如果你希望某些任务必须先用某个工具，可以改为tool_choice={"type": "function", "function": {"name": "query_weather"}}强制调用。

第二，每次工具调用结果都以role: "tool"回传给模型，这也是OpenAI Function Calling的标准要求。很多刚上手的朋友容易漏掉这一步，导致模型"失忆"，上下文断裂。

第三，设置了max_rounds上限，防止Agent无限循环调用下去。这在生产环境尤其重要，否则一个失控的循环可能会把你的API账单烧穿。

3.3 让Agent学会复杂技能的连续调用

上面的MinimalAgent已经能跑，但它只会"一次调一个工具，然后结束"。真实场景里，我们经常需要Agent连续调用多个技能才能完成任务。比如用户说"帮我把这个需求文档翻译成英文，然后总结出三个技术要点"，这就涉及翻译和总结两个技能。

让Agent实现连续调用的核心在于：模型接收到第一个工具的返回结果后，如果任务还没完成，它会继续发起工具调用。我的MinimalAgent里的for循环已经天然支持了这个流程。问题在于如何保证连续调用的质量。

我的做法是在技能注册时给每个技能标注"输出协议"：

def skill_requires_translation(): """实现翻译+总结的连续调用场景""" def _translate_text(text: str, target_lang: str) -> str: # 真实项目里会调用翻译API return f"[{target_lang}] {text}" def _summarize_points(text: str, num: int) -> list[str]: # 简化实现：实际会调用LLM做摘要 return ["要点1", "要点2", "要点3", "要点4"][:num] registry.register( name="translate_text", description="当用户要求将文本翻译成指定语言时使用。适用于文档翻译、消息翻译、标题翻译等场景。", parameters={ "type": "object", "properties": { "text": {"type": "string", "description": "需要翻译的原始文本"}, "target_lang": {"type": "string", "description": "目标语言，如'中文'、'英文'、'日文'"} }, "required": ["text", "target_lang"] }, handler=_translate_text ) registry.register( name="summarize_points", description="当用户要求从一段文本中提取要点、总结关键信息时使用。适用于会议纪要、文档摘要、需求分析等场景。", parameters={ "type": "object", "properties": { "text": {"type": "string", "description": "需要总结的文本内容"}, "num": {"type": "integer", "description": "需要提取的要点数量，默认3个"} }, "required": ["text"] }, handler=_summarize_points )

这里有个经验：技能描述里要刻意避免"翻译完后继续总结"这类跨技能协作的描述。为什么？因为模型看到这种描述反而会困惑：到底这个技能能不能调用另一个技能？正确的做法是：每个技能只描述自己的能力范围，跨技能的编排由Agent的规划层来决策，而不是在技能描述里写死。

如果你希望某个场景下技能调用顺序是固定的，不要依赖模型自主决策，直接写一个编排函数把他焊死：

def translate_and_summarize(text: str, target_lang: str, summary_num: int = 3): """固定的连续调用编排：先翻译，再总结""" translated = registry.call("translate_text", { "text": text, "target_lang": target_lang }) # 注意这里把翻译结果传给总结技能 summary = registry.call("summarize_points", { "text": str(translated), "num": summary_num }) return {"translated": translated, "summary": summary}

对于确定性的多步骤流程，编排函数永远比模型自主调度更可靠、更省钱、更快。

4. 常见问题与排查技巧实录

4.1 工具调用失败的五大坑

工具调用是Agent技能体系里最脆弱的一环，我在实际项目中总结了五个高频坑，每个都是"踩到才知道痛"级别的。

第一个坑：模型返回的JSON参数有语法错误。这是最最常见的。模型生成的{"city": "北京", "days": 7}本身可能没问题，但在复杂参数结构下，模型偶尔会少个括号、多个逗号。我的处理方案是：在传给handler执行前，先用json.loads解析，如果解析失败，不要把错误直接抛回给模型，而是构造一个友好的错误信息返回给模型，让模型自己修正参数重新调用。很多框架默认会直接return error，效果远不如"把这个JSON错误信息明确告诉模型，让它重新生成参数"。

第二个坑：参数类型不匹配。比如定义days为integer，模型传了"7"字符串。轻量解决方案是在handler入口做一次类型转换。但更本质的解决方案是让工具定义里的description写得更细，比如"days为整数，单位为天，取值范围1-10"。模型对描述的理解远比类型声明本身准确。

第三个坑：工具结果过大导致上下文爆炸。有些技能返回的数据量特别大，比如查询数据库返回几百行记录，Agent需要把整个结果塞进上下文再进行下一步推理，浪费掉大量上下文空间。我的做法是：在技能handler里就做好结果裁剪，只返回与任务相关的摘要信息。例如数据库查询技能，默认只返回前20行，并在结果末尾注明"共查询到N条记录，以上为前20条，如需更多请使用limit参数指定"。

第四个坑：技能并发调用时的状态混乱。比如Agent同时调用"发送邮件"和"记录日志"两个技能，如果它们共享某个全局状态，就会出现竞态问题。处理方案是：技能handler尽量做成无状态的（本身不保存状态），所有必要状态都通过参数传入。

第五个坑：技能执行耗时太长，导致Agent整体响应超时。特别是一些调用外部API的技能，一个请求可能就要几秒。我的经验是给每个技能设定超时时间，超时后立即返回一个"技能执行超时"的结果给模型，让模型决定是重试还是换方案。

4.2 技能冲突与命名空间问题

我见过一个团队，两个工程师各自开发技能模块，一个管"用户服务"，一个管"订单服务"，结果两个人都注册了一个叫check_status的技能。上线后模型随机调用，一会儿查用户状态，一会儿查订单状态，数据彻底乱了。

技能命名冲突是多人协作开发Agent技能库时一定会遇到的问题。解决方案有三种：

第一，强制命名空间前缀。比如用户相关技能统一以user_开头，订单相关技能统一以order_开头，这样能从命名层面规避冲突。

第二，用子注册中心隔离。每个业务域有自己独立的一个SkillRegistry实例，主注册中心按域代理分发。这个方案更适合大规模团队。

第三，技能注册时做冲突检测。我在前面的SkillRegistry代码里已经加了重复注册抛异常的机制，但生产环境建议再加一道CI检查：每次提交代码时自动检查全量技能定义的名称唯一性。

命名空间问题不只是代码层面的，也是模型理解层面的。模型看到check_status和user_check_status两个技能，前者名称太泛，很容易导致误用。所以技能命名最好像API设计一样有语义：模块名_动词_对象。比如order_create,order_cancel,user_get_profile。这个名字本身就包含模块、动作、对象三层信息，模型不容易搞混。

4.3 排查工具调用异常的速查表

做Agent开发，几乎天天都要排查工具调用问题。我整理了一个速查表，遇到问题可以直接按这个顺序检查：

这个速查表是我实际运维Agent服务时最常用的东西，基本覆盖了80%的日常问题。

5. 把Agent技能推向真实业务前的最后检查

5.1 安全边界怎么设

技能体系在Demo阶段跑通是一回事，推到生产环境是另一回事。安全边界是上生产前最优先要解决的事情。

第一层安全是权限隔离。Agent的技能本质上是"让AI替你操作某些系统"。如果操作的是只读接口，风险不大；但如果涉及数据库写入、邮件发送、订单取消、用户信息变更这类高危操作，就必须做权限管控。我的做法是：给每个技能配置一个安全等级，低危技能（查询类）可以直接调用，高危技能（写入、删除、外发）必须经过二次确认才能执行。二次确认可以是代码里预设的审批逻辑，也可以是人工审批。

第二层安全是参数白名单。高危技能的参数需要做白名单校验。比如"发送邮件"技能，收件人地址必须限制在特定域名或特定名单内；"删除数据"技能，传入的主键必须存在于预先授权列表中。不能完全信任模型生成的参数。

第三层安全是操作审计。每个技能调用都应该记录操作人、调用参数、执行结果、时间戳，并且这个审计日志不能被Agent自己删除或篡改。这一步看似成本高，但一旦出现事故，审计日志是唯一的回溯依据。

5.2 可观测性和日志追踪

Agent具备技能调用能力之后，很多用户会反馈"结果不对"。但Agent是个黑盒，你怎么知道它内部做了什么？没有可观测性，排查Agent问题就像闭着眼睛找东西。

我可以负责任地说，日志追踪是Agent系统上线前最值得投入的环节。

具体要做三件事。第一件事是技能调用链路的完整记录。从用户输入开始，Agent每一步思考、每一步工具调用、每个工具的请求和响应，都要有结构化的log。我通常用一个agent_session_id来串联一次完整请求的所有日志，这样排查问题时可以通过session_id一把梭。

第二件事是延迟埋点。每个技能的耗时、每次LLM请求的token消耗、整个Agent的端到端耗时，都要有指标监控。这些指标能帮你定位性能瓶颈：究竟是模型响应慢，还是工具执行慢，还是整个编排流程太啰嗦。

第三件事是失败重放。当用户反馈一个问题时，你要能重放当时的调用序列，看看模型在哪个环节做出了错误决策。我的SkillRegistry代码里保留了_history，就是为了支持这种回放。生产环境可以用专门的trace库（比如LangSmith、Langfuse、Phoenix这类工具）来做，效果更强大。

5.3 技能迭代的三个节奏

最后聊聊技能库本身的迭代。技能不是写一次就完事了，它是需要持续维护升级的。

我的经验是技能库应该按三个节奏迭代。第一个节奏是敏捷迭代，每周处理一批高频问题。从线上日志里找"模型频繁调用但效果不好"的技能，针对性地优化描述、调整参数、改进handler逻辑。

第二个节奏是版本化迭代。技能定义带有版本号，每次改动记录变更日志，方便回滚。特别是多个Agent共享同一个技能库时，技能升级可能导致某个Agent行为变化，版本化让你能精确定位是哪次变更引起的。

第三个节奏是季度级重构。每季度审视一遍整个技能库，删除没用的技能，合并重复度高的技能，补充新发现的场景能力。技能库和代码库一样，指望它"写完就永远不再动"是不可能的。

最后想说的话

我在实际项目里的体会是，Agent开发最迷人的地方就是它的"失控感"——同一个技能库，模型每次调用路径可能完全不同，甚至会走出你完全没想到的更优解。但反过来，这种失控感也是风险所在。技能体系的价值就在于：把模型的能力圈在一个可控的框架里，让它的自由度体现在"怎么做"上，而不是"能做什么"上。

最后再分享一个小技巧。如果你刚开始搭技能体系，不要一开始就追求技能数量多。先把三五个核心技能打磨到极致，让Agent在这几个技能上表现稳定，再逐步扩充。技能库的丰富度永远不是第一目标，第一目标是"模型每次都能在正确的时候选择正确的技能，而且执行结果稳定可靠"。这一点做到了，你的Agent项目就已经超过了市面上大部分同类的Demo了。