WebMCP 最佳实践

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

发布时间：2026 年 5 月 18 日

WebMCP 工具声明应清晰明了，无需开发者或代理查看输出并重试。无论您使用的是命令式 API 还是声明式 API，都应遵循以下最佳实践：

  • 在构建之前，请先制定工具策略。
  • 使用清晰的语言和语义 HTML。
  • 设计架构并处理输入。
  • 构建可靠的工具。
  • 测试和调试。

我们已另行撰写文章，介绍如何打造注重安全性的工具。

制定工具策略

与任何软件应用一样，您首先应规划工具策略：

  • 每项工具都应包含一个函数。例如，一项工具可用于引导用户前往特定表单类型，另一项工具则应将输入字段与用户信息相匹配。请注意不要创建重叠的工具，以免代理不知道该使用哪项工具。请问问自己：我能否使用同一函数来完成多项任务？
  • 管理工具注册。在工具在特定页面状态下有用时注册工具，然后在工具不再可用时取消注册。
    • 命令式 API：您可以使用 registerTool 动态管理注册。
    • 声明性 API：您可以通过在表单中添加或移除工具属性（使用 toolname 和 tooldescription）来动态管理注册。
  • 降低复杂性：对于大多数应用，静态注册应该是默认方法。
  • 信任智能体，让其完成任务。不要编写僵硬或负面的指令，而应假设智能体能够理解完成任务所需的内容，而不是期望智能体管理确切的步骤流程。

虽然没有允许的工具数量上限，但每个工具都会占用部分上下文窗口，并增加完成时间。您提供的工具越多，工具之间的重叠程度越高，智能体就越难正确选择工具。通过实验确定适合您应用的设置。

这有助于您构建用途不重叠的各个工具，并管理这些工具的可用时间。

使用清晰的语言和语义代码

使用清晰准确的语言来命名工具并描述其用途。这有助于智能体找到所需内容、了解找到的内容，并按照开发者的预期使用该信息。

在撰写工具名称时，请区分执行和启动，并使用准确描述所发生情况的动词。例如，create-event 是用于立即创建活动的工具，而 start-event-creation-process 是将用户重定向到表单以创建活动的工具。

清晰的说明应描述工具的功能以及何时使用它。请使用积极的语言和偏好设置，而不是消极的语言（例如限制）。

错误做法
“请勿将此工具用于天气查询。”

精心编写的说明应能体现出限制。

正确做法

“此工具可以创建安排在特定日期和时间的日历活动。”

这种语言不是告诉模型做什么，而是描述工具可以采取的操作。

尽量减少认知计算

正如您应尽量降低人类完成复杂任务时的认知负荷一样，您也应尽量降低模型的认知计算量：

  • 接受原始用户输入。避免要求代理执行数学运算或转换输入字符串。例如，如果用户说“11:00 至 15:00”，工具应将其视为字符串。避免要求模型计算这两个时间之间的分钟数。
  • 为参数声明特定类型，例如字符串、数字或枚举。
  • 说明您做出特定选择的原因。您所做的选择应能自行解释。“原因”有助于客服人员做出更明智的选择。例如，如果您经营的是电子商务商店，请使用自然语言声明配送类型，而不是使用含义模糊的 ID：shipping="Express" 而不是 shipping_id=1。

优先考虑可靠性

智能体和人类都可以从行为符合预期的工具中受益：

  • 为速率限制设置优雅失败。工具应允许合理的重复，例如用于价格比较。如果工具受到速率限制，请返回有意义的错误或建议用户手动执行任务。
  • 在函数完成后更新界面状态。代理可能依赖于界面来规划后续步骤，而函数可能需要比界面加载更长的时间才能完成。代理应在界面更新后确认函数是否已完成，或再次请求更新。
  • 在代码中严格验证，在架构中宽松验证。对于具有二元逻辑的函数和代码，应使用限制和测试。虽然架构限制可能很有用，但它们并非万无一失。请向函数代码添加描述性错误，以便模型能够自我更正并使用新的有效参数重试。

评估测试和调试

创建评估测试，并提供工具以供调试。与确定性单元测试不同，评估无法硬编码，因为输出可能会采用意想不到的形式。

  • 明确问题。您可以像定义 API 协定一样定义问题，包括输入类型、输出格式和任何其他限制条件。
  • 确定基准和理想结果。尤其是使用文本输入时，务必要了解哪些类型的结果可以为您带来预期的输出。
  • 确定如何评估输出。您可能会根据输入质量、实用性和完成后续任务的能力来识别和衡量主观的定性结果。您可以使用多种技术来评估输出，包括基于代码的检查（针对基于规则的输出，例如字符数限制）和 LLM-as-a-judge。

避免添加过于具体的规则来修补特定模型的问题。例如，如果您添加了用于选择敬称的选择字段，模型可能会做出错误的选择。与其添加过于具体的规则来修补此问题，不如抽象并调整您的工具。最好的做法可能是将此字段设置为可选。然后，让代理询问用户哪种选择有意义，以确保用户对结果感到满意。

互动和分享反馈

WebMCP 正在积极讨论中，未来可能会发生变化。如果您尝试使用这些 API 并有反馈，我们非常欢迎您提供宝贵的意见。