加工具与 MCP：@tool、file_editor、接 Cursor

你将得到什么

• 一个带 自定义 @tool 与官方 file_editor 的 Agent，能数字母并写出 answer.txt
• 本机 Strands MCP Server（uvx strands-agents-mcp-server），让 Cursor / Claude Code 能检索最新 Strands 文档
• 对「Agent 循环：推理 → 选工具 → 执行 → 再推理」有可观察的对照结果

开始前准备

1. 已完成本系列第 1 课：strands-agents 可 import，且所选 provider 凭证仍有效。
2. 接 MCP 时需已安装 uv（官方用 uvx 启动 MCP）。核对：

uv --version

对照结果：能打印出版本号。若未安装，按 uv 官方安装说明装好后再继续 MCP 小节（加工具本身不依赖 uv）。

步骤 1：在 `agent.py` 顶部加工具定义

官方说明：工具来自两处——SDK 自带的 vended tools（如改文件、跑 shell、HTTP），以及用 @tool 把任意 Python 函数变成工具。docstring 与类型注解是模型决定「何时调用、传什么参数」的依据。

把下列内容加到 agent.py 文件顶部（替换原先只有 from strands import Agent 的导入区）：

from strands import Agent, tool
from strands.vended_tools import file_editor


@tool
def letter_counter(word: str, letter: str) -> int:
    """
    Count occurrences of a specific letter in a word.

    Args:
        word (str): The input word to search in
        letter (str): The specific letter to count

    Returns:
        int: The number of occurrences of the letter in the word
    """
    if len(letter) != 1:
        raise ValueError("The 'letter' parameter must be a single character")

    return word.lower().count(letter.lower())

对照结果：保存后文件可被 Python 解析；letter_counter 与 file_editor 均已在作用域内。

步骤 2：把工具挂进 Agent 并换提示词

官方要求：两个工具都放进 tools= 列表；提示词要同时触发「计数」与「写文件」。若第 1 课已声明 model=，请保留该行，只改 Agent(...) 与最后的调用。

Bedrock（默认）

agent = Agent(tools=[letter_counter, file_editor])

agent('How many letter R\'s are in the word "strawberry"? Write the answer to answer.txt.')

Anthropic（保留 model）

model = AnthropicModel(model_id="claude-sonnet-5", max_tokens=4096)
agent = Agent(model=model, tools=[letter_counter, file_editor])

agent('How many letter R\'s are in the word "strawberry"? Write the answer to answer.txt.')

OpenAI / Gemini / Ollama

模式与上相同：Agent(model=model, tools=[letter_counter, file_editor])，提示词不变。 OpenAI 示例模型 ID 为官方文档中的 gpt-5.4；Gemini 为 gemini-2.5-flash； Ollama 为 llama3.1 + host="http://localhost:11434"。

完整最小示例（Bedrock）便于对照：

from strands import Agent, tool
from strands.vended_tools import file_editor


@tool
def letter_counter(word: str, letter: str) -> int:
    """
    Count occurrences of a specific letter in a word.

    Args:
        word (str): The input word to search in
        letter (str): The specific letter to count

    Returns:
        int: The number of occurrences of the letter in the word
    """
    if len(letter) != 1:
        raise ValueError("The 'letter' parameter must be a single character")

    return word.lower().count(letter.lower())


agent = Agent(tools=[letter_counter, file_editor])

agent('How many letter R\'s are in the word "strawberry"? Write the answer to answer.txt.')

步骤 3：再跑一遍并核对产物

python -u agent.py

对照结果（与官方描述一致）：

1. 终端流式输出中可见模型决定调用 letter_counter（统计 strawberry 中的 R）与 file_editor（写入文件）。
2. 工作目录出现 answer.txt（内容应体现字母 R 的个数；strawberry 中不区分大小写时为 3）。
3. 调用返回 AgentResult（含 messages / metrics / traces）；需要静默流式时可按官方说明传 callback_handler=None（本课可不改）。

若没有 answer.txt：确认当前工作目录就是运行 python -u 的目录；再检查 provider 是否真的执行了工具（Ollama 小模型偶发不调工具时可换更大本地模型或云上 provider 复测）。

步骤 4：把 Strands MCP 接到编码助手

官方说明：MCP 帮助你写代码时查当前文档，不是跑 Agent 的前置条件。通用配置：

• Command：uvx
• Args：["strands-agents-mcp-server"]

Cursor（写入 ~/.cursor/mcp.json）

与 Python Quickstart · Cursor 一致：

{
  "mcpServers": {
    "strands-agents": {
      "command": "uvx",
      "args": ["strands-agents-mcp-server"]
    }
  }
}

保存后重启 Cursor（或按客户端要求 Reload MCP）。对照结果：MCP 面板出现 strands-agents，工具列表中可见文档检索类工具（如 search_docs / fetch_doc，以客户端实际展示为准）。

Claude Code（一条命令）

claude mcp add strands uvx strands-agents-mcp-server

对照结果：claude mcp list 中可见该 server。

可选：MCP Inspector 自检

官方验证命令：

npx @modelcontextprotocol/inspector uvx strands-agents-mcp-server

对照结果：Inspector 能连上进程并列出工具，无启动失败栈。

Kiro / Codex / VS Code 等配置见官方同页各 Tab；通用形态均为 uvx + strands-agents-mcp-server。 更多示例可浏览 Examples 与可选工作坊 aws-samples/sample-strands-agents-hands-on-workshop。

本课检查清单

• @tool 的 letter_counter 与 file_editor 已挂到 tools=
• python -u agent.py 后工作目录有 answer.txt
• （可选）~/.cursor/mcp.json 或 Claude Code 已配置 strands-agents-mcp-server
• 理解：MCP 服务文档检索；Agent 运行时工具来自 tools= 列表，二者职责不同

设计与安全提醒

• 密钥继续只用环境变量；不要在 MCP JSON 或讲义里粘贴 API Key。
• file_editor 会改工作目录文件——在干净目录练习，避免误改重要项目。
• 标题层级：本课仅用二级标题组织步骤；步骤连续编号，不在正文重复站内侧栏目录。