摘要：Agentic AI开发者需重视文档编写！本文揭示了在AI玩龙与地下城游戏中，良好文档对工具使用的重要性。通过Spring AI的MCP库，开发者可构建如NPC动机预言机等工具，并利用自然语言描述指导AI。详细的工具描述和示例，能显著提升AI自主性和游戏体验，

Agentic AI开发者需重视文档编写！本文揭示了在AI玩龙与地下城游戏中，良好文档对工具使用的重要性。通过Spring AI的MCP库，开发者可构建如NPC动机预言机等工具，并利用自然语言描述指导AI。详细的工具描述和示例，能显著提升AI自主性和游戏体验，企业级AI用例亦如此。

译自：Playing D&D With AI: The Agentic AI Developer's Achilles Heel

作者：Michael Coté

为了开发出优秀的 agentic AI 应用，开发者需要擅长他们不擅长的领域：文档编写。这是因为 Agentic AI 应用会使用大量的工具，为了理解何时以及为何使用这些工具，AI 需要良好的文档。

我一直在编写 模型上下文协议 (MCP) 服务器，以帮助我与 Claude 一起玩单人龙与地下城游戏，正如我在 之前关于此主题的文章 中所介绍的那样。仅与 AI 机器人一起玩龙与地下城游戏既有趣又令人愉快。加入 agentic AI 工作流程 会大大改善它：它为 AI 增加了随机性，可以使其摆脱可预测的情节。在制作这些小型 MCP 工具时，我发现我大部分时间都在编写每个工具的功能描述，并在测试工具时完善这些描述。这就是为什么我认为在 agentic AI 方面，文档比以往任何时候都重要，无论是有趣地探索令人毛骨悚然的森林，还是协调区域采购订单。

当您查看 MCP 代码示例时，您会发现告诉 AI 工具做什么的主要方式是使用工具的自然语言描述。每个工具都有一个描述，并且每个工具的参数也有一个描述。因此，如果您正在编写一堆 MCP 工具，那么您向机器人描述它们的方式就变得很重要。

这些 MCP 工具描述不是典型的 API 描述。典型的 API 描述记录了 什么 东西做了。真正好的描述还会描述代码 如何 执行它，包括错误处理和行为。

这对于 agentic AI 文档当然很重要，但您还希望描述 AI 何时应该使用工具、为什么要使用它以及如何应用工具的结果。您希望对该工具的用途有一个明确的观点。一旦您加载示例，您的文档最终看起来就像一个故事。

编写 MCP 工具以充当单人角色扮演中的“预言”就是一个很好的例子。顾名思义，在单人角色扮演中，您自己玩游戏，在进行过程中编造故事。在这些情况下，您通常需要随机的想法来推动故事的发展，从而帮助您提出意想不到的曲折。预言是一种在您进行单人角色扮演时生成这些随机想法的方式。例如，您可能有一个预言可以为您提供有关事物气味的提示：新鲜的、像培根、三天大的豆腐、苹果等。可以有 20 个或 100 个这样的列表。当您的角色走进一个房间并看到一堆东西时，要找出这堆东西是什么，您会掷一些骰子并使用从此预言中随机选择的条目之一。您掷出 54：“旧鞋”。因此，在您的单人角色扮演日记中，您写道“侏儒斯文走进马厩后面一间光线昏暗的房间，发现了一堆东西。凭借他敏锐的嗅觉，他闻到了一种不会错的气味：地精鞋。”

在我最喜欢的单人角色扮演系统 情节展开机器 中，有 40 多个预言，用于描述气味、非玩家角色 (NPC) 的意图、对话主题、任何给定对象的外观等等。

当我与 Claude 一起玩单人龙与地下城游戏时，它在回应我的侏儒接下来会发生什么方面做得还不错。但是，按照设计，它的回复非常可预测。毕竟，这就是生成式 AI 所做的：它告诉你紧随你刚刚输入的内容之后的下一个可能的单词（当然，是 token）。在这种情况下，最可预测的事情是，一些怪物藏在那堆鞋子下面，或者它是一些模仿一堆鞋子的怪物。

使用预言的结果可以打破这种可预测性。现在，通常情况下，我会在我拥有的预言上掷骰子，然后将结果输入到 Claude 中。但是，使用 MCP 工具，我可以创建一个小工具 并 让 Claude 决定何时调用预言。我不再需要管理在预言中查找“旧鞋”之类的内容并将其传递给 Claude。

正如我们将看到的，结果是我可以更多地“参与游戏”，而不必决定何时需要调用预言。

让我们看一个 Claude 桌面进行推理以使用工具然后使用该工具的示例。首先，我们将查看最终结果，然后查看代码。这将显示该工具的文档为何如此有价值。 下面，我让 Claude 开始玩 D&D，并告诉它一些关于情况的信息，一个行商走在路上。在 UI 中，你可以看到它调用了 EasyChatDM 工具，总共有三个：

你所看到的是 Claude 正在执行一个简单的 Agentic AI 工作流程：

这是一个非常简单的工作流程，但它展示了“Agentic”的显著特征。

Claude 正在自主行动。它已经决定调用这些工具中的每一个，制定一个计划并响应结果。这导致 Claude 想出了行商的下一步行动。根据你的玩法，这个过程可能会变得更加详细。对于创建冒险等更复杂的事情，我看到它在一个 Agentic 链中调用了 10 个或更多的工具。

我在这里使用的工具很简单——NPC 动机预言机只是从文件中选择一个随机的文本行。但是，很容易看到你如何在工具背后做更复杂的事情，比如检索自定义记录、搜索库存，甚至进行文档验证。这些工具可以做任何你想做的事情，它只是代码。

除了只是一行代码，你还可以返回更多结构化的输出，比如 JSON。你可以启动 Claude 之外的其他事件链，比如用于进一步分析的批处理作业。但是，就我而言，仅仅知道行商想要提高人们对其智力的看法就足够了。

正如我在之前的文章中所说，实际的预言机代码非常枯燥。我正在使用 Spring AI 的 MCP 库，所以我真的不必做太多的脚手架工作来创建一个 MCP 服务器。当你最终得到代码并去掉所有的错误处理和日志记录时，所有的代码所做的只是从一个文本文件中随机选择 303 行中的一行。

我发现重要的是 NPC 动机的文档。对工具的作用以及何时使用它的描述是一项有趣的工作：

对工具的描述在我的游戏中效果很好：它经常被调用，我喜欢它被融入到正在进行的故事中的方式。现在，我可以没有文档，只是将 MCP 工具称为“NPC 动机”。AI 可能会弄清楚该怎么做。我也可以只提供说“NPC 动机的描述”的文档。这两种都是我通常遇到的文档类型：要么什么都没有，要么是对方法名称不太聪明的改写。

这两种记录方法并没有给 AI 提供太多关于何时调用它、用它做什么以及何时不调用它的指导。文档是你给 AI 提供方向和游戏风格的机会。

NPC 动机的那个相对简单。但是，通常你需要大量的想象力和细微差别来解释预言机的结果。例如，另一种类型的预言机告诉你某事发生的程度。你可能会问：“在那堆鞋子里藏着一个好战的哥布林吗？一个简单的“是/否”预言机会回答……是或否。但是，也有更细微的预言机，它们会返回一个答案梯度，比如“是的，但是……”或“不，还没……”

在这种情况下，我喜欢用一些如何解释结果的例子来指导 AI，正如你在 EasyChatDM_Subjective_Oracle 的文档中看到的那样：

我在 EasyChatDM_Subjective_Oracle 文档中，以及在其他工具 中所做的是，指导 AI 如何思考和使用这些工具。像往常一样，给出例子也很重要。这就是为什么文档很重要，而且我认为，以更详细、更人性化的方式记录你的 AI 工具非常重要。

当然，我们知道大多数代码文档的现实情况：它什么也没告诉你，因为开发者没有编写它。大多数人会说文档很重要，但根据我们所看到的，它在优先级列表中很低。

我发现文档越好，与机器人的 D&D 会话就越好。而且，我非常确定对于所有那些激动人心的企业 AI 用例来说也是如此。 最好擅长编写文档。

来源：承光君