企业官网建设流程全解析

1. 为什么我把 Agent 的"技能"单独拎出来做

先说个背景。我手上有好几个 Agent 项目，最早做的时候走了不少弯路。起初的想法很简单：把大模型的对话能力接上工具调用，让 Agent 能查天气、能算数学、能调数据库。但真正跑起来才发现，模型输出是概率性的，同一个功能今天能用明天抽风是常态，更别提把工具逻辑、提示词、参数校验、失败重试全堆在一个 Agent 工程里，代码很快就烂成一锅粥。

后来我梳理了一下，问题就出在"技能"和"Agent"没有分层。打个比方，Agent 像一个厨师，技能就是他的刀工、火候、调味手法。你不能让厨师每次做菜的时候再去现学刀工，那样出菜质量极不稳定。正确做法是先把刀工练成肌肉记忆，厨师只管根据菜单调配。这个"肌肉记忆"，落到工程上就是 AI Skills。

腾讯云的 AI Skills 本质上是把 Agent 的一个完整能力闭环——从意图识别、参数抽取、工具执行到结果规整——封装成独立可复用的单元。它不只是简单的函数调用，而是一套带描述、带输入输出协议、带错误处理策略的"能力包"。我最初在本地用 LangChain 搭过类似的东西，但每次都要自己处理服务发现、鉴权、可观测性、版本管理这些问题，累得够呛。迁到腾讯云 AI Skills 之后，这些基础设施层面的活儿基本都能省掉，我可以把精力集中在技能本身的逻辑打磨上。

这篇文章就围绕我在腾讯云上从零构建"全能 Agent"的完整过程展开，目标是让你看完之后能照着搭出一套自己的技能体系。会涉及技能怎么设计、Agent 怎么跟技能配合、服务怎么部署、上线后怎么调优排障，以及我在实测中踩过的那些文档里不会写的坑。

先给一个整体视角：一个完整的 Agent 项目在腾讯云上大概分四层——接入层负责对话与权限，调度层负责意图路由，技能层负责具体能力执行，数据层负责记忆与状态。AI Skills 落在第三层，但它的设计质量直接决定第二层能不能把意图分清楚。所以这篇文章把重点放在技能层和它跟调度层的衔接上。

2. 技能设计：先想清楚三个问题再做

很多人的做法是拿到需求就开始写代码，结果技能做出来要么太宽泛什么都接不住，要么太窄换个场景就废了。我在动手之前会先回答三个问题，这三个问题基本决定了技能的边界和质量。

2.1 这个技能的"最小职责单元"是什么

技能不能贪大。我见过有人把一个"文档处理技能"做成能读取、转换、摘要、翻译、问答、对比的六合一模块，结果每个子功能都是半吊子，意图一多模型就糊涂。我的实践是：一个技能只解决一件事，但这件事要做得深入。

举个例子，如果 Agent 需要处理 Excel 报表，我不会做一个通用的"报表技能"，而是拆成"报表数据校验""报表指标计算""报表格式标准化""报表异常标注"四个技能。每个技能只吃一种输入、产一种输出、只依赖一类工具。这样做的直接好处是：Agent 路由意图时非常清晰，模型只需要根据技能描述和输入参数判断调用哪个，几乎不会歧义。另一个隐藏好处是排障方便——某个技能出问题时，影响面被局限在一个小模块里，不会拖垮整个 Agent。

2.2 技能的输入输出协议怎么定

输入输出协议是技能设计的核心，也是跟大模型交互的契约。腾讯云的 AI Skills 支持自定义参数结构和返回结构，我的建议是：参数尽量扁平，类型尽量明确，描述尽量带示例。因为模型做参数抽取时，依赖的是参数名和描述文字，描述里带示例能大幅提升抽取准确率。

我当时设计一个"图表生成技能"时，最初的参数结构是嵌套的：

{ "data": { "xAxis": ["一月", "二月"], "series": [ {"name": "销量", "values": [100, 150]} ] }, "chartType": "bar", "title": "月度销量" }

实测下来，模型抽取这种嵌套结构时经常漏填或者填错层级，成功率只有七成左右。后来我把参数结构改成扁平化，并给每个字段加了示例值：

{ "series_names": ["销量", "利润"], "x_labels": ["一月", "二月", "三月"], "series_values": [[100, 150, 130], [30, 45, 40]], "chart_type": "bar", "title": "月度经营数据" }

成功率直接干到九成半以上。核心原因在于：文本型大模型对"平铺的、自上而下填充字段"这件事的把握度，远高于"递归地构造嵌套对象"。这个经验我后来在多个技能里反复验证过，结论一致。

2.3 技能要不要带状态

这是个容易被忽略的问题。技能默认应该是无状态的——每次调用都是独立的，输入、执行、返回，完事儿。但有些场景确实需要跨多次调用的状态，比如多轮对话里用户先问"我上个月电费多少"，再问"那这个月呢"，两个问题如果被路由到同一个查询技能，模型需要知道"这个月"指的是哪个月份，这其实是对话上下文的职责，不应该由技能自己记状态。

我的原则是：技能本身不做记忆，只接收上下文参数。如果 Agent 需要连续对话，调度层负责维护会话上下文，并把相关的历史摘要作为参数传给技能。这样技能还是无状态的，但用户体验上是有状态的。这个分工特别重要，否则技能一多，状态管理就会变成一场灾难。

3. 在腾讯云上把技能跑起来：从云端配置到本地联调

腾讯云的 AI Skills 功能在云端控制台里就能完成技能的生命周期管理——创建、配置、发布、监控。但我不建议直接在页面上写完所有东西，更顺滑的方式是：本地开发调试好逻辑，再同步到云端。这样迭代速度快，出问题也容易定位。

3.1 创建技能的第一步：描述文档比代码重要

后端逻辑再完备，如果技能描述文档写得稀烂，Agent 也调不对。我把技能描述当成跟大模型沟通的"说明书"，写清楚这几个要素：

• 这个技能是干什么的（一句话，尽量包含动作和对象）
• 什么情况下应该调用它（正例和反例都写，反例尤其重要）
• 输入参数的定义和示例
• 输出的格式约定
• 出错时可能返回的状态码和含义

腾讯云控制台里有一个"技能描述"编辑区，支持 Markdown 格式。我强烈建议在这里写一份结构化描述，不要随手糊两行。你花在描述上的时间，会在线上意图识别准确率上十倍赚回来。

我当时写在线查询技能的描述，反例部分帮了大忙。我写的是："本技能仅用于查询，不用于计算和汇总。若用户询问总计、平均值、同比增长等计算类需求，请调用【指标计算】技能，不要调用本技能。"就这么一句话，把查询和计算两类技能的误调用率从 25% 压到了不足 5%。

3.2 本地脚手架：用腾讯云 SDK 把技能逻辑跑通

云端的技能函数最终是要被执行引擎调用的，对应到代码层面，就是一个标准的 HTTP 服务，接收技能请求参数，执行逻辑，返回结构化结果。我习惯用 Python FastAPI 写这个服务框架。

from fastapi import FastAPI, Request from pydantic import BaseModel from typing import List, Optional app = FastAPI() class ExcelQueryRequest(BaseModel): sheet_id: str row_range: Optional[str] = None filters: Optional[List[dict]] = None class QueryResult(BaseModel): success: bool rows: Optional[List[dict]] = None message: Optional[str] = None error_code: Optional[str] = None @app.post("/excel/query", response_model=QueryResult) async def query_excel(req: ExcelQueryRequest): try: # 具体查询逻辑，连接腾讯云对象存储、读取 Excel、执行过滤 result = execute_query(req) return QueryResult(success=True, rows=result) except Exception as e: return QueryResult(success=False, message=str(e), error_code="QUERY_FAILED")

这个脚手架有两个好处：一是本地起服务就能用 Postman 直接打接口测试，不需要每次都推上云端；二是后续把服务打包成容器镜像推到腾讯云容器服务，或者在云函数里托管，都是同一套代码，迁移成本极低。

3.3 联调阶段最容易忽略的鉴权问题

腾讯云的 AI Skills 在远程调用技能时默认会做身份校验。联调时最常见的问题是：配置了技能服务地址，但请求一直返回 401 或者 403。原因不外乎两类：

一类是签名问题。云端调用时会在请求头带上签名信息，你的服务端必须用腾讯云提供的 SDK 或密钥对签名做校验。如果你只是想先联调通，建议先在技能配置里选"开发模式"，该模式下云端会附带一个调试用的凭证，服务端拿这个凭证校验即可。

另一类是网络隔离问题。如果你的技能服务部署在私有网络里，云端执行引擎访问不到。解决办法是把服务通过负载均衡暴露到云端可访问的入口，或者打通内网通道。很多人在这一步卡一整天，其实检查一下安全组的入站规则、负载均衡的后端服务健康检查是否通过，就能找到问题。

我当时卡在健康检查上——负载均衡配好了，后端服务也起来了，但技能调用还是报"服务不可达"。查了半天才发现是健康检查路径配错了，我写的是/health，FastAPI 默认没这个路由，负载均衡判定后端不健康，流量自然进不来。

4. Agent 与技能的协同：路由、编排与上下文传递

技能只是零件，Agent 才是整机。技能设计得再完美，如果 Agent 不知道怎么路由、不会编排多技能协作，照样发挥不出战斗力。

4.1 意图路由的两种策略，各有适用场景

训练 Agent 路由意图，业界基本是两条路线：基于模型分类和基于语义检索。

基于模型分类适合意图数量少（10 个以内）、边界清晰的场景。你可以让大模型从技能列表里选一个返回，这种方案实现简单，但意图一多，模型容易混淆相近技能。

基于语义检索适合技能数量多、意图边界模糊的场景。把每个技能的描述向量化存入向量数据库，用户请求先做向量检索，召回 Top3 技能再交给模型做精排。腾讯云的向量数据库和 AI Skills 能直接打通，不用自己维护整套检索服务。

我实际项目里技能超过 15 个之后，纯模型分类的准确率明显下降，尤其是我上面提到的查询和计算这类语义相近的技能。后来切到"向量召回 + 模型精排"的混合方案，整体意图路由准确率提升了将近 20 个百分点，而且新增技能只需更新向量索引，旧技能完全不用动。如果你的技能清单在持续生长，我建议一步到位用混合方案。

4.2 多技能协作：把顺序依赖设计成显式状态机

单技能调用好处理，难的是多个技能协作完成一个复杂任务。比如"分析上季度各区域销售数据并生成可视化看板"，拆开就是：查询技能取数 → 计算技能汇总 → 图表技能画图 → 报告技能排版。

我早期实现多技能协作是纯提示词驱动，让大模型自己决定先调哪些技能。结果就是经常漏调步骤，或者数据还没算完就开始画图，最终输出牛头不对马嘴。

后来我改成显式状态机的方案：Agent 维护一个任务状态，每完成一个技能就更新状态，下一个技能依赖前一个技能的产出。调度层根据状态决定"现在该调用哪个技能"，而不是让模型自由发挥。这个改动直接把我这边的复杂任务成功率从四成拉到了八成以上。

class ReportPipelineState: def __init__(self): self.current_step = "query" self.steps = { "query": "excel_query_skill", "aggregate": "metric_calc_skill", "chart": "chart_generate_skill", "report": "report_layout_skill", } def next_step(self): order = list(self.steps.keys()) idx = order.index(self.current_step) if idx < len(order) - 1: self.current_step = order[idx + 1] return self.steps[self.current_step] return None

这个设计模式说白了就是流水线：每个技能是工位，状态机是传送带，产品经过一个工位处理完就流动到下一个。缺点是需要预先定义好流水线的节拍和顺序，但好处是每一步都可观测、可回滚、可重试，对于生产环境来说这些特性比灵活性重要得多。

4.3 上下文传递：不要一股脑全塞给技能

多技能协作必然涉及上下文传递。最常见的错误是：把所有历史对话、中间数据全部拼到技能请求里，导致请求体越来越大，模型处理速度越来越慢，费用也越来越高。

我的经验是，在传给技能之前，调度层先做上下文裁剪：只保留当前步骤必需的参数和上一步的可验证输出摘要，其余全部丢弃。比如图表生成技能，我就传给它维度列表、指标数值和图表类型，不传对话历史和用户原话。这样技能自己处理得干净，Agent 路由得也快。

上下文传递有个要注意的细节：技能 A 的输出作为技能 B 的输入时，字段名必须对得上。腾讯云的技能描述里对输入输出字段做了很严格的类型约定，如果技能 A 返回的是字符串型数字"123"，技能 B 声明接收整数型 123，调度层需要做一次显式类型转换。我在调度层加了个字段映射的配置项，避免每次更换技能都要改代码。

5. 上线后的问题排查与进阶调优

技能上线只是开始，真正花时间的是上线后根据监控反馈持续调优。这里分享几个我踩过的坑和反复验证有效的优化手段。

5.1 一次完整的排查链路：从日志到根因

有一次我发现某个技能的生产成功率从 95% 掉到了 80%，界面上的错误提示只有两个字："超时"。直接看日志，发现日志里技能执行耗时在 15 秒到 30 秒不等，而我配置的技能超时时间是 10 秒。

第一反应是后端服务变慢了。但看服务本身的监控，CPU、内存都正常，慢查询也没有。后来把日志粒度打到调用链级别才发现，慢的不是我自己的逻辑，而是技能里调用的下游 API 响应变慢了——某个第三方接口从原来的平均 200ms 涨到了 8 秒。

排查链路走到这里，根因就清楚了：第三方接口因为上游链路拥堵，响应时间出现长尾。解决办法是在技能代码里给下游调用加超时熔断：

from tenacity import retry, stop_after_attempt, wait_exponential @retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10)) def call_downstream_api(data): response = requests.post(DOWNSTREAM_URL, json=data, timeout=3) response.raise_for_status() return response.json()

加上超时重试之后，单个下游调用最多等 3 秒就失败，重试三次，累计最长等待约 15 秒。虽然没有完全消除超时，但至少不会再无限期等下去，而且重试大概率能等到下游恢复。这个调整让成功率回到了 93% 左右。剩余 2% 的失败率，主要是因为某些第三方接口持续 10 秒以上不恢复，这属于上游的稳定性问题，不是我能完全解决的。

这个案例给我的启示是：技能排查要有从请求入口到下游依赖的全链路追踪能力，否则你根本不知道时间花在哪个环节。腾讯云的自定义监控和日志服务配合调用链追踪，基本能把每个技能的耗时打点做出来，强烈建议早点把这块配好，别等出事再搭。

5.2 Token 消耗优化的三招实操

Agent 跑起来之后，成本大头基本是模型调用。尤其是多技能协作场景，每个步骤都要跟模型交互，Token 消耗像流水一样。我实测下来，以下三个招数对降本立竿见影。

第一招：技能描述做精简。技能描述太长会占用大量 Token，而且模型处理冗长描述时反而抓不住重点。我之前有个技能描述写了 1200 字，精简到 400 字之后，每次调用的 Token 消耗直接少了三分之一，意图识别准确率反而还升了。精简的原则是：保留调用场景、参数示例、反例，砍掉各种跟调用决策无关的背景介绍。

第二招：模型分级调用。不是所有技能调用都需要最强的模型。我配了模型路由：简单技能（如格式转换、字段抽取）用更快更便宜的模型，复杂技能（如多条件检索、报告生成）用强模型。粗算一下，这招能省下 20% 到 30% 的调用成本。

第三招：结果缓存。对确定性输出的技能，比如查询历史统计数据、获取静态配置，加上一层 Redis 缓存，相同参数的请求直接命中缓存。我这边几个高频查询技能加了缓存之后，调用量减少了将近一半，后端压力也小了，两全其美。

5.3 技能安全：输入校验和敏感信息治理

Agent 的每个技能入口，本质上就是一个可被外部请求触发的 API。安全这块我在上线前重新过了一遍，重点是两点。

第一点是输入校验。腾讯云不太希望你技能里出现任意代码执行或者超长文本注入，所以我自己额外加了输入白名单和长度限制。所有技能入口都做两轮校验：第一轮是结构校验，字段类型、枚举值、长度必须符合协议；第二轮是语义校验，比如日期必须晚于 2020 年、金额不能为负数。这样就算大模型被用户提示词带偏了，技能层面也能兜底。

第二点是敏感信息治理。Agent 在调用技能时可能会在日志中记录业务数据，这些数据里可能混有用户隐私或内部业务信息。我做的配置是：日志脱敏，匹配手机号、身份证号、银行账号、密钥的字段在落盘前打星号。这个配置在腾讯云的日志服务里可以直接设置，不用自己改代码。

6. 我养成的"全能 Agent"最终长什么样

说了这么多方法论，最后用一个实际的工程快照收尾。我的这个 Agent 上线跑了快三个月，目前接了 23 个技能，覆盖数据查询、统计分析、图表生成、报告撰写、信息检索、任务提醒六大类。

架构上是典型的"接入层 + 调度层 + 技能层 + 数据层"四层结构。接入层是微信公众号和网页端两个入口，共用一套鉴权和会话管理。调度层用的就是前面说的"向量召回 + 模型精排"混合路由，配合显式状态机做多技能编排。技能层跑在腾讯云容器服务上，每个技能独立部署、独立伸缩，技能之间互不影响。数据层用的腾讯云数据库存会话记忆和技能执行记录，Redis 做结果缓存。

上线以来我监控了几个核心指标：意图路由准确率做到了 92%，技能执行成功率做到了 94%，端到端平均响应时长控制在 3 秒以内。这个结果肯定不算完美，但已经能稳定支撑日常业务使用。

回头看整个搭建过程，我最深的体会是：Agent 的能力边界不是模型决定的，是技能体系的完善度决定的。模型再聪明，没有扎实的技能支撑，就像一个智商很高但没有任何生活经验的人，聊什么都头头是道，真让他干点实事就露馅了。

技术选型上，如果你已经决定用腾讯云生态，那 AI Skills 几乎是必选项——它跟账号体系、日志、监控、容器服务之间的打通，能省下大量自研中间件的时间。如果你还在观望，我的建议是：先拿一两个业务场景做试点，把"技能设计"和"意图路由"这两块的感觉找到，再逐步扩大技能清单。这套方法论即使以后换平台，核心思路也是通用的。