企业官网建设流程全解析

为了让 AI 更可靠，我做了个给 Agent 用的网站（含 skills）

作为一个常年跟 Agent 打交道的人，我最近半年最深的感受是：Agent 看起来能聊天、能写代码、能随手调各种工具，但真让它稳定地跑完一个像样的任务，往往会栽在特别小的细节上——返回格式不统一、参数传错、任务一长就开始自说自话。为了解决这个问题，我索性自己做了个给 Agent 用的网站，顺手沉淀了一套标准化 skills，在项目跑通之后整个事情变得顺了很多。这篇博客就是想把这个项目的来龙去脉、设计思路和实操细节完整记录下来，给同样在搞 Agent 工程化、尤其是被工具调用可靠性折磨过的朋友一个参考。

先说清楚这网站到底是干嘛的：它不是给人类用户刷的常规站点，而是一个专门面向 AI Agent 的工具与技能中心——网站里维护了一批经过封装、消毒、可观测的 skills，Agent 通过统一接口来发现技能、查询参数、执行调用、拿回规整结果。你把它理解为"给 Agent 装的标准化插座面板"也行。项目本身不复杂，但围绕可靠性做的取舍和设计，我觉得很值得展开聊聊。适合谁看呢？正在做 Agent 应用开发、研究工具调用范式、或者被"模型会用工具但用不牢"折磨过的工程师，这篇应该都能给你一些直接能抄的方案。

1. 为什么要给 Agent 做一套"配套网站"

1.1 Agent 最脆弱的不是"智力"，而是"接口"

先说一个我观察了很久的现象：模型本身的推理能力在快速进步，但你给 Agent 接上一个真实工具之后，失败率并没有想象中那么低。问题很少出在"模型不懂该调哪个工具"，而是出在调用层——工具返回的字段和预期不符、服务超时、参数类型校验不过、同样的请求这次成功下次失败、甚至工具端改了接口导致 Agent 直接把任务放弃了。

打个比方，Agent 像一个能力很强但经验不足的实习生。你给他一套排版混乱、字段随意的 API 文档，他大概率能调通一两次，但你绝不敢让他连续处理一百个工单。反过来，如果你把每个工具都整理成标准化的说明书，提供明确的输入输出约束，给他配好超时和重试的规则，那就算任务复杂一点，他也能稳稳当当干完。这个"标准化说明书 + 执行环境 + 兜底策略"的组合，就是我说的"给 Agent 用的网站"的核心价值。

所以可靠性这件事，本质上不是模型的智力问题，而是接口的工程问题。这也是我决定自己做一个配套系统的根本原因：市面上现成的工具插件生态不少，但真正以"Agent 为第一用户"设计的工具网关几乎没有，大家都在各自项目里临时拼凑。

1.2 通用 API 和"Agent 可用"之间还差着一层

普通的 Web API 是给人类开发者设计的。大家可以接受页面文档、 curl 示例、自己拼参数，但在 Agent 那里，这个逻辑走不通。

模型看到的不是完整页面，而是有限的上下文窗口；它需要通过一个尽量精简、规范、自解释的描述来决定"何时调用、传什么参数、怎么处理返回结果"。如果 API 文档写得不结构化、返回字段每次都不一样、错误码语义模糊，那 Agent 就会出现两种典型故障：一是犹豫不决，反复调用同一接口，白白消耗 token；二是把错误输出直接当作成功结果继续编，最后给你一个看起来合理实际是幻觉的"完成"。

通用 API 与 Agent 工具之间的这个差距，需要有人来填。我的网站做的就是这层"翻译+加固"：把传统 API 重新封装成符合 Agent 使用习惯的 skill，同时加上参数校验、超时保护、幂等控制、沙箱执行。这样一来，模型看到的工具是极大简化的，而背后的复杂性和风险由平台兜住。

1.3 这套网站服务了什么具体场景

我在项目里主要跑了三个场景，效果都比较明显。

一个是客服工单分类：Agent 需要读取用户诉求，调用一个"工单结构化"技能来提取意图、优先级、责任分组，然后再走后续流程。以前这个技能直接暴露给 Agent 调用时，经常因为用户输入格式千奇百怪，返回结构不稳定，导致下游逻辑判断崩掉。封装成 skill 以后，不管原始内容多脏，返回的 JSON 永远是固定 schema，缺失字段用 null 补齐，下游再也不用写一堆防御代码。

另一个是代码仓库的"能力巡检"：Agent 每隔一段时间去扫描仓库目录，调用带沙箱的"执行命令"技能来跑测试或静态检查。我给它统一加了超时 30 秒、最多重试 1 次、输出截断到 2000 字符的规则。实测下来，以前经常出现的"Agent 在超时后胡编输出"的毛病几乎绝迹，因为它拿到的永远是明确的 success 或 error。

第三个是内容摘要流程：Agent 抓取一批网页，调用"网页正文提取"技能，再把结果交给"长文摘要"技能。网页提取经常遇到的编码混乱、广告夹杂、结构缺失问题，全部在技能内部消化了，模型只需要处理干干净净的正文。这三个场景让我确信，与其寄希望于模型自己在调用工具时越来越"聪明"，不如先把工具层做成傻瓜级。

2. Skills 的核心设计思路

2.1 Skill 到底是什么形态

做这个网站之前，我先给 Skill 下了一个比较严格的定义：它不是一个 prompt 模板，也不是一段普通 API 封装，而是一个"可执行能力 + 元数据描述 + 参数规范 + 返回规范 + 安全策略"的组合体。

简单来说，一个 Skill 至少需要包含五样东西：

• 名称与命名空间：如web.fetch_text，全局唯一，语义清晰
• 描述信息：用两三句话说明这个技能干什么、什么时候用、什么时候不要用
• 输入参数定义：用 JSON Schema 声明每个参数的类型、是否必填、默认值、取值范围、示例
• 执行逻辑：指向实际被调用的内部函数或外部服务，由平台侧负责调度
• 返回结构：统一封装成{ success, data, error, trace_id }，无论底层成功还是失败都走这个结构
• 安全策略：包括超时上限、允许的重试次数、是否需要人工确认、可访问的外部网络范围等

这个设计最核心的思路是"把不确定性消灭在进入 Agent 上下文之前"。模型不需要知道技能内部是怎么实现的，它只需要读到一个干净、确定、可预期的接口契约。既然模型总是对复杂工具理解不准确，那就由平台把这些复杂性收敛在内部。

在设计 Skill 格式时，也踩了一个差点走偏的坑：一开始我想把 Skill 描述写得很详细，觉得信息越多模型越容易理解。后来发现完全反了——描述过长反而稀释注意力，模型经常忽略最关键的触发条件。最后我把描述压缩到两句话以内，一句触发场景，一句禁止场景，实测调用准确率反而提升了。人的注意力有限，模型的上下文注意力同样有限。

2.2 我把 Skills 分成了四类

为了维护方便，我把所有技能按照使用模式分成了四类，每一类的可靠性设计侧重点都不一样：

这里面，工具型是最容易出问题的，因为涉及真实外部副作用；知识型最容易产生"看似答了但信息过时"的问题；流程型需要考虑任务中途挂了怎么恢复；校验型反而是我后期加的一个很有用的类别，它可以对模型的输出做规则性检查，拦截明显的事实错误。

例如，我做过一个"输出日期格式校验"的校验型 skill，用来拦截模型在生成报告时误把2024-11-03写成2024/11/03的情况。这种小技能单独拆出来，比在每个 prompt 后面加"注意日期格式"要可靠得多，因为它是执行确定性校验，不会因为模型状态波动就失效。校验型技能是典型的"给 AI 装上检查工具"的思路。

2.3 设计 Skill 时反复踩的坑

在做了十几个 Skills 以后，我总结出三条比较重要的设计经验，也可以说是教训。

第一条：参数越宽松，越容易出错。一开始我设计"网页抓取"技能时，觉得只让 Agent 传一个 URL 就够了。后来发现它经常还想传 header、代理、等待时间等参数，而每个新增的可选参数都会增加模型用错的概率。后来我把所有能固定的东西全部固化成平台配置，Agent 只需要传 URL 和必要的选项，其他一律不管。改动之后，参数校验错误率下降了一大截。

第二条：返回结构要"硬"到不容出错。底层返回的内容经常千奇百怪，但如果让模型直接接触这些原始输出，它就会自由发挥。我的做法是让每个技能内部都做清洗和规范化，保证返回的 JSON 字段固定、缺失字段用 null 补齐、超长内容自动截断。模型拿到的永远是"少量但规整"的数据，而不是原始的脏数据流。

第三条：千万不要把多个功能塞进一个 Skill。比如我曾经试图做一个"网页分析"技能，既能抓取正文，也能抽取关键词，还能做情感判断。结果就是模型经常纠结到底该启用哪个功能，参数组合爆炸式增长。后来我把它们拆成三个独立技能，每个只做一件事，效果好得多。工具的单一职责原则，在 Agent 场景下比在常规软件开发中更重要。

3. 实操过程：从零搭起这个网站

3.1 技术选型与整体结构

项目的技术栈其实挺常规，没有刻意追求花哨。后端用的 Python + FastAPI，主要原因是我对 Python 生态比较熟，JSON Schema 校验、异步任务、沙箱子进程这些都能比较顺手地组合起来。前端是一个简单的控制台页面，方便我手动查看技能注册状态、测试调用、查看日志。存储用了 SQLite 起步，后来线上换成了 PostgreSQL，但设计上数据访问层一开始就做了抽象，切换成本不高。

整体分三层：控制面、执行面、数据面。控制面负责技能注册、密钥管理、调用鉴权、人工审批；执行面负责真正的技能调用，每个技能跑在独立的子进程或容器里，强制沙箱；数据面负责存储调用日志、trace 链路、评估结果集。这三层隔离非常关键，不然"工具平台"很容易变成"一个包揽所有逻辑的大泥球"。

我需要补充一句选型理由：为什么不用类似 Node.js 或 Go 重写？主要是因为项目核心不在于高并发，而在于快速迭代和灵活实验。Python 的 FastAPI 能做自动 OpenAPI 文档、异步支持也好，调试起来非常顺手。Agent 调用场景有个特点，就是调用频率不会像 C 端接口那么高，但每个调用对正确性和可观测性的要求很高，这个前提下开发效率反而是更重要的指标。

3.2 Skill 注册与参数校验的实现

给 Skill 做注册入口时，我最看重的就是参数校验。模型调用工具时经常出现"缺参数、参数类型不对、枚举值乱传"的问题，所以必须在入口处就把不合法的调用拦截掉，不能让脏参数一路穿透到后端逻辑。

我用 JSON Schema 来描述参数规范，在 FastAPI 里写一个通用的注册接口。注册一个 Skill 时，除了填代码入口和描述信息，还需要提交一份 schema，比如这样：

from pydantic import BaseModel, Field class SkillRegisterRequest(BaseModel): name: str = Field(..., pattern="^[a-z0-9_.]+$") description: str version: str schema: dict timeout_ms: int = 30000 retry_count: int = 0 requires_confirmation: bool = False

注册时我会检查几件事：schema 是否合法、描述是否超过长度限制、超时是否在允许范围、技能名称是否与已有命名空间冲突。模型侧的调用请求进来以后，先做一次 JSON Schema 校验，不通过就直接返回错误结构，避免脏数据污染内部逻辑。

这里有个很关键的细节：参数校验的 schema 本身就暴露给模型看，所以 schema 里的描述字段也要写得足够清晰。比如一个参数url，我不仅写type: string，还会写constraints: http or https only，并且附一个合法示例。这样做的原因是模型不是直接看到代码，而是看到 schema 的描述文字来构造参数；描述越具体，模型传错参数的概率越低。

如果你只是用一段普通的 Pydantic 模型去接收参数，也同样可以在入口处做校验，效果类似。核心逻辑是先校验后执行，绝不把参数正确性寄托在模型自己的判断上。

3.3 沙箱执行与结果规范化

我常说一句话：不要让 Agent 直接碰底层能力，不然你不知道它会在里面搞出什么名堂。所谓的"碰"不只是说权限，还包括它能否拿到不受控的原生输出。

我的执行面是这样的：每个 Skill 对应一个进程内执行器，对于需要外部网络的技能，我把网络访问限制在一个可配置的白名单域名列表里；对于需要执行命令的技能，则开一个子进程，配上 CPU 和内存限制，设置严格超时。沙箱化执行带来的额外好处是，技能内部如果发生异常，我们可以捕获、格式化、然后返回给模型一个友好的错误信息，而不是一坨堆栈。

结果规范化是用统一封装来完成的，结构如下：

{ "success": true, "data": { "title": "示例标题", "content_preview": "..." }, "error": null, "trace_id": "01J...XYZ", "duration_ms": 230 }

成功时 success 为 true，data 里放规整后的结果字段；失败时 success 为 false，error 里放错误码和可读信息，data 为 null。整个结构固定，模型解析起来基本不用猜。

超时和重试策略方面，我的默认配置是：单次技能执行超时 10 秒到 30 秒，依据技能类型调节；重试次数默认不超过 2 次；重试退避采用指数退避，第一次等待 200ms，第二次等待 800ms。过重的重试策略会让 Agent 持续等待，反而拖垮整个任务。这里要特别提醒：只有对幂等技能才开启自动重试。对于"发邮件""删除数据"这类非幂等操作，默认不重试，宁可报错让人处理，也不能自动重复执行导致事故。

3.4 让 Agent 快速发现和调用 Skills

网站最贴近 Agent 的部分是一个"技能发现"接口。模型在调用工具之前，如果来自一个开放环境，通常需要先获取当前可用的技能列表。我做了两个接口：

• GET /skills/discover：返回精简的技能列表，只包含名称、简短描述、参数 schema 的概要
• POST /skills/invoke：传入技能名称和参数，返回统一封装的结果

这样做的考虑是，模型不需要一次性加载所有技能的全部细节，只需要根据任务类型选择候选技能，再进入 invoke 拉取完整 schema。这个设计大幅减少了对上下文的浪费。

在发现接口的返回里，我还加入了"召回关键词"机制。例如某个技能描述里刻意放入工单、客服、分类这些词，模型在做意图匹配时更容易选中正确的工具。这个细节很朴素，但确实提升了召回的准确性。

给 Agent 用的接口还有一点特殊：错误信息不能太复杂。如果模型调用技能失败，返回的 error 信息需要提供"怎么办"的线索，比如"参数 url 格式错误，需要 http 或 https 开头"，这样模型可以在下一轮智能地修正调用，而不是反复用同一个错误参数撞墙。这类"可修正错误"的设计对多轮 Agent 行为有明显改善。

4. 可靠性是怎么一点点堆出来的

4.1 可观测性先于一切

在我做这个项目的早期，最大的问题不是功能不够，而是"不知道哪里出了问题"。Agent 本身是一个多步骤的系统，模型决策、工具执行、外部依赖之间相互影响，一旦出错，定位链路非常痛苦。后来我痛下决心把所有调用都接上 trace_id，让一次 Agent 任务的所有动作可以串联起来。

具体实现上，我在 skill 调用开始前生成 trace_id，随请求传递给执行层；日志里记录模型决策前的上下文摘要（省略 prompt 全量，避免日志膨胀）、技能名称、输入参数脱敏后的摘要、返回结果大小、耗时、token 粗估。控制台里可以按 trace_id 拉出完整调用链：模型选了哪个工具、传了哪些参数、工具执行结果是什么、模型下一轮又做了什么。

这一步做扎实之后，很多"灵异问题"立刻现出原形。比如有一次 Agent 总是生成低质量摘要，我一开始以为是模型能力问题，后来 trace 一看，发现是网页抓取技能经常返回空正文，模型只能根据空内容硬编摘要。问题根本不在摘要环节，而在上游抓取环节。如果没有 trace 串联，这种问题排查起来会绕很大一圈。

4.2 失败注入与回归测试

Agent 和普通程序不一样，它是概率性的。哪怕你修好了一个 bug，也不能保证同样的调用以后一定成功。所以我做了一个相对轻量的"回归评估集"，里面存放了几十个典型的任务样本，每个样本标注了期望的技能调用序列和关键输出约束。每次改完代码，我都会跑一遍这个评估集，统计技能选择准确率、参数校验通过率、任务完成率。

除了正常样本，我还往评估集里注入了大量异常场景：比如让网页抓取技能故意超时、让某个技能返回空结果、让外部接口返回乱码。对 Agent 来说，这些异常不是"如果发生"而是"一定会发生"，所以它在异常场景下怎么表现，才是可靠性的分水岭。通过反复跑这些失败注入样本，我改进了技能内部的重试逻辑和错误提示话术，Agent 的应对能力明显变强。

这里可以分享一个数据：改动前，异常场景下的任务完成率只有 62% 左右，其中大部分失败原因是 Agent 拿着错误信息原地打转，或者把错误信息误当成正常结果继续编。加上"可修正错误"的返回设计以后，完成率提升到了 88%——不是模型变聪明了，而是让它"知道自己错了、知道该怎么改"。与其让模型猜，不如在工具侧给它一条清晰的路。

4.3 人与 Agent 的协作边界

可靠性不光是系统能不能自动搞定一切，也包括在关键节点人能不能干预。我在网站上专门加了一条规则：凡是涉及"外部副作用且不可逆"的技能，比如发送消息、删除资源、修改线上配置，调用前必须有一个人工确认步骤。

实现上很简单：当 Agent 请求这些技能时，invoke 接口不会直接执行，而是返回一个pending_confirmation状态，同时把待执行的内容推送到控制台。操作者在网页上一键确认后，请求才真正进入执行面。这样既保留了 Agent 的自动化效率，又避免了"模型一旦抽风就闯祸"的极端情况。

一开始团队里有同事觉得这个设计太保守，认为纯自动流程体验更顺。但后来有一次 Agent 在测试环境里差点误删一批线上备份数据，大家才意识到这一个确认步骤的价值。它引发了我一个更深的思考：Agent 可靠性的目标不是"无人干预"，而是"在可控范围内尽量减少干预"。

5. 常见问题与排查实录（实测踩坑）

5.1 实测中最常遇到的几个问题

我在跑这个项目的过程中，积累了不少典型问题，先整理成一个速查表，后面再详细展开一两个有代表性的排查过程。

这个速查表不是一次性写出来的，是我们在实际运行中一点点积累沉淀下来的。每次在群里被问到一个问题，我都会同步把现象和解决方式记录在案，后续排查时效率提高很多。

5.2 一个典型的调试过程：网页抓取技能返回空内容

这里细讲一个最有代表性的排查案例。某次任务中 Agent 调用网页抓取技能，一直返回空字符串。我第一反应是外网页面结构变化，导致选择器失效。但查 trace 后发现，技能在内部做网络请求那一步就直接超时了，根本没到解析环节。

进一步看日志，发现不是所有 URL 都返回空，只有部分站点超时。我怀疑是沙箱网络的出口 IP 被目标站点限流或封禁，于是检查沙箱的网络策略，确认没有配代理和请求头，部分站点对非浏览器请求的响应处理会特别慢。

解决过程分两步：先给技能内部加上自定义请求头，模拟常见浏览器的 User-Agent，情况有所缓解；然后在沙箱网络配置里，给一批高频目标站点增加了超时时间白名单，并且对抓取技能单独放宽到 30 秒，其他技能保持 10 秒默认值。改动以后，这个技能的成功率从 71% 提升到了 93%。

这个案例给我最大的启发是：Agent 技能出现问题时，先借助 trace 判断"问题发生在哪个环节"，然后再决定是改模型侧还是改工具侧。很多团队往往一上来就调 prompt 或换模型，其实大部分情况是工具执行层的问题。

5.3 被我砍掉的一些逆天设计

做项目的过程中我试过一些激进功能，后来发现方向不对，果断砍掉了。这里也聊聊，算是给后来者避坑。

第一个是被砍掉的"动态自然语言工具生成"。我当时想，能不能让 Agent 自己根据任务描述在系统里动态生成一个新技能？试了一段时间发现完全不可控。生成出来的技能质量参差不齐，参数不明确，还有可能被恶意注入利用。后来我意识到，技能本质上是"人定义的确定性能力"，必须先由人来编写、评审、注册，模型只能做"选择"和"调用"，绝不能让模型做"创造"。这条边界立住了，可靠性才真正往上走。

第二个是被砍掉的"全自动权限管理"。最初设想是根据 Agent 的任务目标自动分析需要哪些权限，然后动态发放。结果发现这等于把权限决策这个高风险动作也交给了模型。后来改成固定角色权限模板 + 人工审批机制，网站在中间只做推荐和提示，不替代人做最终权限决策。安全性提升明显，也避免了许多权限事故。

这两个被砍掉的功能让我形成了一条做 Agent 工程的原则：确定性部分越厚重越好，概率性部分越克制越好。凡是容易因为"模型发挥不稳定"而引入风险的环节，就让规则和人来兜底。

6. 后续还能这样扩展

6.1 从"单平台应用"到"跨平台协议"

目前这个网站基本是为单一 Agent 服务的。后续我打算把它改造成一个更通用的协议层，让不同的 Agent 框架都可以通过统一接口来使用这套 skills。关键工作是把技能注册、发现、调用这些接口抽象成与具体 Agent 实现无关的协议。

协议层的好处是平台还可以服务更多的团队和项目。比如公司里的不同项目组都在做 Agent 应用，如果每个组都各自封装一套抓取、检索、校验技能，重复劳动不说，质量还参差不齐。把它统一收拢到一个平台，各个组注册自己的技能、共享通用的基础技能，就能形成内部生态。

当然这也带来新的挑战：技能命名冲突、权限隔离、配额管理、技能质量审核，都需要更完善的机制。这是下一阶段的主要工作。

6.2 把评估集做成社区可共享的资源

我一直觉得评估集是这个项目最大的隐藏资产，比网站本身值钱得多。那些异常注入样本、正确调用序列标注、失败恢复记录，都是可以在团队内甚至外部社区共享的核心资源。后续我打算把脱敏后的评估集整理成一份公开数据集，让其他团队也能快速检验自己的 Agent 工具调用可靠性。

一份好的评估集应该包含三类样本：正确流程样本、异常容错样本、安全边界样本。正确流程样本用来测"能不能调对"；异常容错样本用来测"出了错能不能恢复"；安全边界样本则用来测"不该调用的会不会强行调用"。三者结合，覆盖了 Agent 可靠性的主要维度。

6.3 持续打磨技能内部的"可修正性"

我的另一个扩展想法是把技能的错误提示做得更加结构化，让模型拿到错误后能快速进入"修正循环"。目前我已经让错误信息包含可读的修正提示，但下一步可以做得更细：比如返回一个"建议修参列表"，直接告诉模型哪些字段不合法、建议改成什么。这样模型就不需要自己"猜"修正方案，而是基于明确的指引调整调用。

这个方向的本质是把"模型怎么用工具"从自由发挥变成"半填空式"交互。工具可以做到多细致，模型的调用可靠度就能堆多高。

说到底，我认可可靠性是可以靠工程手段一步步堆出来的。模型的不稳定性是客观存在的，但我们可以把系统边界上的确定性尽量放大。做一个给 Agent 用的网站，核心不是建一个漂亮的页面，而是建一层值得托付的接口契约、一套可控的执行沙箱、一条完整可查的调用链。这几件事做扎实，Agent 才真正敢交出去用。