WebMCP 最佳实践

Alexandra Klepper
Alexandra Klepper
GitHub Bluesky

发布时间：2026 年 5 月 18 日

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

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

制定工具策略

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

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

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

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

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

使用清晰直白的语言来命名工具并描述其用途。这有助于代理找到所需内容、了解找到的内容，并按照开发者的预期使用这些信息。

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

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

错误做法

“请勿将此工具用于天气查询。”

精心编写的说明应能体现出限制。
正确做法

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

尽量减少认知计算

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

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

优先考虑可靠性

行为符合预期的工具可让代理和人类受益：

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

评估测试和调试

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

  • 定义问题。您可以将问题框架化为 API 协定，包括输入类型、输出格式和任何其他限制。
  • 定义基准和理想结果。尤其是对于文本输入，了解哪些类型的结果可以生成您期望的输出非常重要。
  • 确定如何评估输出结果。您可能正在根据输入质量、实用性和完成后续任务的能力来识别和衡量主观的定性结果。您可以使用多种方法来评估输出，包括对基于规则的输出（字符数限制）进行基于代码的检查，以及使用 LLM-as-a-judge。

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

互动和分享反馈

WebMCP 正在积极讨论中，将来可能会发生变化。如果您尝试使用这些 API 并有反馈意见，欢迎随时告诉我们。