系列:Once Upon Agentic AI。

尽管拥有了新的力量和无所畏惧的心,我们的英雄们仍未击败所有敌人。一只更强大的怪物正在等待着他们,比他们面对过的任何东西都更强大。这一次,我们的英雄需要的不只是自身的力量才能取胜。

TheWitcherish finds a Tool left from the tavern, a green orb labelled MCP client

本系列分三部分讲述这段冒险:

  • 第 1 部分:创建你的第一个智能体,为它配备一个 Vended 工具,然后编写你自己的工具。
  • 本文:通过 MCP Inspector 和 Strands Agents Harness SDK 探索 MCP(Model Context Protocol)。
  • 第 3 部分:RAG(检索增强生成)、A2A(Agent2Agent)以及结构化输出,由一个编排智能体领导多个专用智能体。

你需要 Python、uv、一个终端,以及可访问 Amazon Bedrock 的 AWS 凭证。

代码位于aws-samples/sample-once-upon-agentic-ai。main分支包含带有# TODO标记的骨架代码。让我们一起 Learn and Be Curious!

使用与第 1 部分相同的设置:

git clone https://github.com/aws-samples/sample-once-upon-agentic-ai.git ~/sample-once-upon-agentic-ai
cd ~/sample-once-upon-agentic-ai
uv sync
export AWS_PROFILE=YOUR_AWS_PROFILE AWS_REGION=YOUR_AWS_REGION

还没有 AWS 配置文件?Strands Agents 的Amazon Bedrock 模型提供方指南展示了如何设置 AWS 凭证(使用aws configure、环境变量、boto3 会话或aws login),并列出了你的智能体调用模型所需的 IAM 权限。Strands 会自动读取这些凭证。

什么是 MCP?

在第 1 部分中,整个智能体循环都在一个 Python 进程内运行:模型读取工具规范,决定调用roll_dice,Strands 运行该函数,然后模型读取结果。MCP(Model Context Protocol)是一个开放标准,让智能体能够使用存在于另一个程序中的能力。工具就是其中之一,服务器还可以共享数据和可复用的提示词,如下表所示。在本文中,我们把骰子工具移入一个服务器。智能体循环保持不变:模型仍然决定调用哪个工具,改变的只是函数运行的位置。

谁与谁通信?MCP 采用客户端/服务器架构:可以理解为面向 AI 智能体的 HTTP。Web 浏览器向 Web 服务器发送请求并读取其响应;MCP 客户端对 MCP 服务器做同样的事,服务器用它的工具及其结果来回应。宿主是 AI 应用,在这里是一个 Strands 智能体。对于它使用的每个服务器,宿主都会创建一个客户端,与该服务器保持一条专用连接。那个客户端就是 TheWitcherish 的绿色球体。服务器是提供能力的程序:当客户端用tools/list请求时,它会列出自己的工具,并在客户端发送tools/call时运行其中一个。在这两个请求之间,智能体循环的运行方式与第 1 部分完全相同。

服务器能提供什么?服务器有三种原语,按由谁控制其使用来分组:

原语 控制方 示例
提示词 用户 系统提示词、少样本示例
资源 应用 文件内容、数据库模式、API 响应
工具 模型 一次 API 调用、一次数据库写入

消息是如何编写的?每条 MCP 消息都是 JSON-RPC 2.0,这是一个用 JSON 调用另一个程序的小型标准。请求携带一个id、一个method和params,其响应重复相同的id,并带有result或error。通知没有id,因为它不期望回复。下面是一个工具调用:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"q":"otters"}}}

消息是如何传输的?MCP 定义了两种传输方式。使用 stdio 时,客户端将服务器作为子进程启动,并通过其标准输入和输出交换消息。这是最简单的选项,没有网络端口,也没有身份验证,但只有那一个客户端能使用该服务器。使用 Streamable HTTP 时,服务器作为自己的进程运行,并在一个端点接收 HTTP POST 请求。许多客户端可以共享它,无论是在你的机器上还是跨网络,但它会打开一个端口,而共享到你机器之外的服务器需要 MCP 规范中描述的授权。

如果你想深入了解,可以在这里找到MCP 规范。

第 1 步:MCP 服务器只是另一个程序中的工具吗?

差不多。服务器可以提供我们之前看到的三种 MCP 原语中的任何一种:工具、资源和提示词。在我们的英雄任务中,我们专注于工具。绿色球体需要有东西可以对话,所以TheWitcherish,Amagash和Tagazok构建服务器,它将到达。他们把 Lady Luck 的骰子从智能体中移出,放进自己的文件,4_mcp_integration/dice_roll_mcp_server.py。

他们用以下代码创建服务器FastMCP(port=8002),把@mcp.tool()放在同一个roll_dice函数(来自第 1 部分)之上,并以启动服务器的那一行结束文件:

import random
import logging
from mcp。server import FastMCP

logging。basicConfig(level=logging。INFO, format='%(asctime)s - %(levelname)s - %(message)s')

mcp = FastMCP(port=8002)

@mcp。tool()
def roll_dice(faces: int = 6) -> int:
    """掷一个具有给定面数的骰子并返回结果。
    ...
    """
    if faces < 1:
        raise ValueError("骰子必须至少有 1 个面")

    result = random。randint(1, faces)

    logging。info(f"... DICE ROLL: d{faces} = {result}")

    return result

if __name__ == "__main__":
    mcp。run(transport="streamable-http")

FastMCP来自官方 MCP Python SDK。与第 1 部分的@tool一样,@mcp.tool()把文档字符串和类型提示转换为工具描述和输入模式。函数保持熟悉,只是它的家变了。每次掷骰现在都会记录到服务器自己的日志中,为我们提供智能体之外的证据。

接下来的问题是,宝珠将如何到达他们的服务器:

"我们通过 stdio 通信吗?"

"SSE?"

"我知道了,Streamable HTTP!"

他们选择 Streamable HTTP,服务器以此启动transport="streamable-http"。

在一个终端中启动服务器并保持运行:

cd ~/sample-once-upon-agentic-ai/4_mcp_integration
uv run python dice_roll_mcp_server.py
INFO - StreamableHTTP session manager started
INFO:     Uvicorn running on http://127.0.0.1:8002 (Press CTRL+C to quit)

它监听127.0.0.1,这是 FastMCP 的默认主机,因此只有你的机器可以访问它。这里没有模型。服务器等待客户端。

第 2 步:在任何智能体调用它之前,服务器会响应吗?

此步骤使用 Node.js 运行 MCP Inspector。如果node --version在你的终端中没有打印版本号,请先从Node.js 下载页面安装 Node.js。

先测试服务器。如果智能体行为异常,你想知道是服务器还是模型的责任,所以在任何模型加入之前先单独检查服务器。MCP Inspector是用于测试和调试 MCP 服务器的参考工具。它是一个没有模型支持的 MCP 客户端,因此它向你准确展示智能体将收到什么。在你的 MCP 骰子服务器启动并运行后,打开第二个终端。

npx @modelcontextprotocol/inspector@2.15.0打开 Web 界面,你在其中添加服务器 URLhttp://127.0.0.1:8002/mcp使用 Streamable HTTP 传输。同一个工具还有命令行模式,会把每个答案以文本形式打印出来,所以下面的追踪记录都来自它。首先,与服务器握手:

npx @modelcontextprotocol/inspector@2.15.0 --cli http://127.0.0.1:8002/mcp --transport http --method initialize
{
  "serverInfo": {
    "name": "FastMCP",
    "version": "1.30.0"
  },
  "protocolVersion": "2025-11-25",
  "capabilities": {
    ...
    "tools": {
      "listChanged": false
    }
  }
}

服务器会宣告自身身份、它所使用的协议修订版本,以及它提供的能力。"protocolVersion": "2025-11-25"是这个版本的 MCP Python SDK 所使用的修订版本。现在问一个智能体在启动时会问的问题,tools/list:

npx @modelcontextprotocol/inspector@2.15.0 --cli http://127.0.0.1:8002/mcp --transport http --method tools/list
{
  "tools": [
    {
      "name": "roll_dice",
      "description": "Roll one die with a given number of faces and return the result.\n\n...faces: Number of faces on the die, 1 or more. ...",
      "inputSchema": {
        "type": "object",
        "properties": {
          "faces": {
            "default": 6,
            "title": "Faces",
            "type": "integer"
          }
        },
        "title": "roll_diceArguments"
      },
      "outputSchema": {
        ...
        "properties": {
          "result": {
            "title": "Result",
            "type": "integer"
          }
        },
        ...
      }
    }
  ]
}

这与第 1 部分的比较相同,tool_spec,只不过现在是通过网络读取的。docstring 变成了 description,类型提示变成了"type": "integer",默认值变成了"default": 6。服务器还会发送一个outputSchema,这是第 1 部分的本地工具所没有的。不过要注意这个约束:“1 或更多”只出现在描述文本里。schema 中没有 minimum,所以模型是通过阅读来得知这个约束的,而由函数来强制执行它。用一次合法值、一次非法值来调用这个工具:

npx @modelcontextprotocol/inspector@2.15.0 --cli http://127.0.0.1:8002/mcp --transport http --method tools/call --tool-name roll_dice --tool-arg 面=20
npx @modelcontextprotocol/inspector@2.15.0 --cli http://127.0.0.1:8002/mcp --transport http --method tools/call --tool-name roll_dice --tool-arg 面=0
{
  "content": [
    {
      "type": "text",
      "text": "19"
    }
  ],
  "structuredContent": {
    "result": 19
  },
  "isError": false
}
{
  "content": [
    {
      "type": "text",
      "text": "Error executing tool roll_dice: Dice must have at least 1 face"
    }
  ],
  "isError": true
}

骰子服务器的终端记录下了这两次访问,而合法的那次掷骰结果与之匹配:

2026-11-11 15:44:58,566 - INFO - Processing request of type ListToolsRequest
2026-11-11 15:44:58,570 - INFO - Processing request of type CallToolRequest
2026-11-11 15:44:58,570 - INFO - ... DICE ROLL: d20 = 19
...
2026-11-11 15:44:59,836 - INFO - Processing request of type ListToolsRequest
2026-11-11 15:44:59,839 - INFO - Processing request of type CallToolRequest

Inspector 在每次调用前都读取了工具列表,就像智能体所做的那样。faces=0通过了 schema,并在if faces < 1检查处停下,因此服务器返回了一个错误结果,带有"isError": true而不是崩溃,Inspector 以退出码 5 退出。

这个约束也可以放在 schema 里,这样模型就会把它当作规则来看,而不是在文字描述中读到它。这个改动不在仓库的代码中:在你自己的dice_roll_mcp_server.py副本里试试,通过声明faces,带有Annotated和一个 PydanticField:

from typing import Annotated
from pydantic import Field

@mcp.tool()
def roll_dice(faces: Annotated[int, Field(ge=1)] = 6) -> int:

重启服务器并再次运行tools/list。faces现在带上了这个约束:

"faces": {
  "default": 6,
  "minimum": 1,
  "title": "Faces",
  "type": "integer"
}

再用faces=0调用一次。这一次 Pydantic 会在roll_dice运行之前就拒绝这个值:

"text": "Error executing tool roll_dice: 1 validation error for roll_diceArguments\nfaces\n  Input should be greater than or equal to 1 [type=greater_than_equal, input_value=0, input_type=int]..."

服务器日志显示了CallToolRequest,但没有DICE ROLL这一行:函数从未运行。服务器给出了回答。现在该让智能体来调用它了。

第 3 步:智能体需要工具的代码吗?

不需要。服务器地址就够了。gamemaster_mcp_client.py定义了一个名为gamemaster的智能体,它以 Lady Luck 的口吻说话,其中不包含任何骰子实现:

from strands import Agent
from strands。tools。mcp import MCPClient

mcp_dice_client = MCPClient(url="http://localhost:8002/mcp")

gamemaster = Agent(
    system_prompt="""你是 Lady Luck,奇幻角色扮演冒险中骰子与命运的神秘守护者。
    ...""",
    tools=[mcp_dice_client]
)

gamemaster("帮我创建一个新的奇幻角色!用 4d6 去掉最低值的方法掷出力量、感知、魅力和智力属性值。")

给出MCPClient服务器的url,然后将其添加到tools。对于 Strands 来说,MCP 工具就只是一个工具。MCPClient是一个工具提供方:当智能体启动时,客户端会发送与tools/list你刚才用 Inspector 运行的那次相同的请求,它收到的每个工具都会以名称、描述和输入 schema 加入智能体的工具列表,完全就像 Part 1 中的@tool函数一样。模型会挑选roll_dice,然后 Strands 将调用转发给服务器。

在这三种原语中,只有工具会到达模型。服务器的 prompts 和 resources 仍可通过同一个客户端供你自己的代码使用,借助list_prompts_sync()、get_prompt_sync()、list_resources_sync()以及read_resource_sync(),因此由你决定何时使用它们。

是时候掷命运女神的骰子了!

TheWitcherish MCP tool invocation request accepted by the MCP Server

确保你的 MCP 骰子服务器仍在它的终端中运行。然后打开另一个终端,从那里进行投掷。这一次智能体会在 Amazon Bedrock 上调用模型,因此该终端需要有效的 AWS 凭证:导出与设置时相同的AWS_PROFILE和AWS_REGION,并在运行客户端之前用aws sts get-caller-identity检查它们:

cd ~/sample-once-upon-agentic-ai/4_mcp_integration
export AWS_PROFILE=YOUR_AWS_PROFILE AWS_REGION=YOUR_AWS_REGION
aws sts get-caller-identity
uv run python gamemaster_mcp_client.py

如果aws sts get-caller-identity返回的是错误而不是你的账户和角色,请先刷新你的凭证;否则客户端会在第一次模型调用时因NoCredentialsError或令牌过期错误而停止。

要查看 SDK 做了什么,请复用骰子服务器中位于gamemaster_mcp_client.py顶部的日志配置行,将DEBUG改为INFO:

import logging

logging。basicConfig(level=logging。DEBUG, format='%(asctime)s - %(levelname)s - %(message)s')

DEBUG在根 logger 上还会打印 AWS SDK 自身的请求和响应,因此输出很长:在其中搜索mcp和stop_reason。跟踪记录会逐步跟随 SDK:

2026-11-12 13:41:13,578 - DEBUG - [...] transport connection established
2026-11-12 13:41:13,584 - DEBUG - [...] session initialized successfully
2026-11-12 13:41:13,591 - DEBUG - [...] received 1 tools from MCP server
2026-11-12 13:41:13,591 - DEBUG - tool_name=<roll_dice> | creating mcp agent tool
...
2026-11-12 13:41:16,639 - DEBUG - stop_reason=<tool_use> | model call succeeded, resetting retry state
...
Tool #1: roll_dice
Tool #2: roll_dice
...
Tool #16: roll_dice

客户端连接,收到一个工具,并将其包装为智能体工具。模型以stop_reason=<tool_use>停止,并在同一轮中请求十六次投掷:四项能力各掷四颗骰子。命运女神报告了第一项能力值,已做修剪:

STRENGTH
掷骰:3、6、4、2→3 + 6 + 4 = 13

服务器日志遵循同样的路径:

INFO - Created new transport with session ID: 6b20ac77014340f8b57cbd4fa3443214
INFO - Processing request of type ListToolsRequest
INFO - Processing request of type CallToolRequest
INFO - ... DICE ROLL: d6 = 3
INFO - Processing request of type CallToolRequest
INFO - ... DICE ROLL: d6 = 6
INFO - Processing request of type CallToolRequest
INFO - ... DICE ROLL: d6 = 4
INFO - Processing request of type CallToolRequest
INFO - ... DICE ROLL: d6 = 2
...

ListToolsRequest是tools/list;每个CallToolRequest都是一次tools/call。在roll_dice运行之前,FastMCP 会用 Pydantic 根据工具的输入 schema 校验参数。这就是塔的“Request Validated”。

现在把两边并排放在一起。服务器记录了十六次投掷。模型的下一个请求携带了十六个工具结果:

第 1 到 16 次投掷
服务器日志 3 6 4 2 · 2 12 4· 5 4 1 3 · 5 4 5 6
模型收到 3 6 4 2 · 2 14 2· 5 4 1 3 · 5 4 5 6

相同的十六个值在两边都出现了。第 7 次和第 8 次掷骰交换了位置,因为 Strands 会并发执行同一回合的工具调用。因此,相邻的结果返回顺序可能与服务器记录的顺序不同。

所以每个数字在模型看到之前就已经存在于带时间戳的服务器日志中。模型只是复述了结果,它从未真正掷骰。当它的回复与服务器日志不一致时,请相信日志。

现在你来试试:让 Lady Luck 也掷一下敏捷和体质。然后数一数服务器日志中新增的DICE ROLL行数。你应该会发现多出八行。

跟随冒险者们

在第 3 部分中,编排器智能体会查阅我们角色扮演游戏的规则,因为 Tagazok 可能不被允许使用某种非常特定的能力,而 Amagash 则学会用结构化输出为她的工具赋予形状。

在那之前,请保持两个习惯:

  • 在你的智能体之前先测试你的 MCP 服务器。MCP Inspector 固定在你选择的版本上,可以展示智能体将收到什么,中间没有模型介入。
  • 在双方都能看到的地方写下边界。在 schema 中,模型将它们读作规则,而 Pydantic 会在你的函数运行之前守住这条线。

这篇博文中的漫画插图由以下人员创作和制作Holy Bird,基于 AWS 研讨会。

版权所有。