本期学习ai-agent-book 第四章https://github.com/bojieli/ai-agent-book/blob/main/chapter4/README.md先大概理解一下本期的主要学习方向Tools 与 MCP。mcp协议、mcp服务、tools三个是独立的概念。MCP协议定义了通信规则MCP服务是规则的实现载体Tool是挂在MCP服务上对外暴露的具体能力单元。mcp的出现最开始也是因为各家大模型调用外部工具的标准不一样所以mcp解决了标准化的问题类似usb协议。也就是实现一次 MCP 客户端可以通吃所有 MCP 工具服务工具按 MCP 标准开发一次就能被所有 MCP 类型 Agent 调用。Q:那感知工具 MCP 服务器、执行工具 MCP 服务器的关系和区别是什么ans1关系感知工具 MCP 服务器、执行工具 MCP 服务器都是mcp服务的程序实例两者是独立的。MCP 协议本身只定义了三类能力Tools / Resources / Prompts。他们的层级关系是MCP 协议 → MCP 的 Tools 能力 → 业务层面再划分感知 Tools、执行 Tool。2区别感知工具 MCP 服务器它里面封装的是感知类工具只读、无副作用 能力示例读取指标文档、查询表元信息、检索知识库。 MCP 层面以 MCP Tool 形式对外提供只读查询能力。执行工具 MCP 服务器里面封装执行类工具调用后产生副作用修改外部状态 能力示例执行 SQL、生成文件、导出报表。 自带参数校验、权限控制、审计日志、高危操作人工确认。3两者和agent的关系Agent 只需要实现一份 MCP Client 代码就可以同时连接这两个 MCP 服务器需要读取文档、查元数据 → 请求感知 MCP Server需要跑 SQL、生成文件 → 请求执行 MCP Server工具的数量变多必然会带来新的问题也就是无法一次性吧全部工具的schema全部喂给llm。大量工具带来的上下文与选型难题催生了Active Tool Discovery主动工具发现。他的核心思路是不要一次性加载全部工具按需检索、按需加载。主动工具发现负责从感知 MCP、执行 MCP 提供的全部工具集中检索筛选少量候选工具按需加载给大模型它是 Agent 上层检索逻辑不属于 MCP 协议本身。实验4-4 Execution Tools MCP Server / 执行工具 MCP 服务器背景Agent 生成一条命令并不代表命令已经成功执行。本实验围绕执行工具学习完整动作链接收参数、检查条件、执行操作再把结果交回模型。# 1. 进入实验目录 cd /Users/td/Downloads/ai-agent-book/chapter4/execution-tools # 2. 激活项目虚拟环境 source ../../.venv/bin/activate # 3. 确认文件存在 ls # 4. 安装依赖 python -m pip install -r requirements.txt #5.复制env.example 为 .env cp env.example .env #6.配制参数文件 nano .env配制的参数为运行# 查看总帮助与所有子命令 python cli.py --help(.venv) tdair execution-tools % python cli.py --help usage: cli.py [-h] [--provider PROVIDER] [--workspace WORKSPACE] [--no-approval] [--no-verify] [--no-summarize] 子命令 ... 执行工具统一命令行入口实验 4-4执行工具 MCP 服务器。 positional arguments: 子命令 list 列出所有可用的执行工具 demo 运行端到端离线演示推荐先看这个 code 调用 code_interpreter 执行代码 shell 调用 virtual_terminal 执行 shell 命令 write 调用 file_write 写文件 edit 调用 file_edit 按搜索-替换编辑文件 calendar 调用 google_calendar_add 创建日历事件需要凭据 pr 调用 github_create_pr 创建 Pull Request需要 token options: -h, --help show this help message and exit --provider PROVIDER LLM 提供商覆盖 PROVIDER如 dashscope/qwen/bailian/kimi/doubao/siliconflow/openrouter --workspace WORKSPACE 工作目录覆盖 WORKSPACE_DIR文件操作被限制在此目录内 --no-approval 关闭危险操作的 LLM 事前审批 --no-verify 关闭写文件/代码的自动语法校验 --no-summarize 关闭长输出的 LLM 总结仍会截断持久化 示例 python cli.py list 列出所有执行工具 python cli.py demo 运行端到端离线演示 python cli.py code --code print(6*7) 执行 Python 代码 python cli.py shell ls -la 执行 shell 命令 python cli.py write --path a.txt --content hi --overwrite python cli.py --no-approval shell echo hello 关闭 --no-approval / --no-summarize / --no-verify 后 code/shell/write/edit 等命令可完全离线运行无需 API key。运行python cli.py list结果可用执行工具 工具名 类别 说明 -------------------- -------- ---------------------------------------- file_write 文件系统 写文件写入前自动做语法/linter 校验 file_edit 文件系统 按搜索-替换编辑文件附带 diff 预览与校验 code_interpreter 通用执行 多语言沙盒代码执行Python/JS/Go/Java/C/Rust/PHP/Bash virtual_terminal 通用执行 Shell 命令执行含危险命令检测与长输出截断 google_calendar_add 外部系统 创建 Google 日历事件需要 credentials.json github_create_pr 外部系统 创建 GitHub Pull Request需要 GITHUB_TOKEN 用 python cli.py 子命令 --help 查看每个工具的参数。 用 python cli.py demo 运行端到端离线演示。上面所有列出的工具file_write、file_edit、code_interpreter、virtual_terminal就是4-4实验里封装好的 MCP 执行工具集合cli.py 是 MCP 服务配套的命令行客户端用来测试这套 MCP 服务里的工具。运行mcp服务器在【execution-tools】目录里新建一个client.py文件吧教程里的代码复制进去cat client.py EOF import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def use_tools(): server_params StdioServerParameters( commandpython, args[server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # Use file write tool result await session.call_tool(file_write, { path: test.py, content: print(Hello, World!) }) print( file_write 结果 ) print(result) # Use code interpreter result await session.call_tool(code_interpreter, { code: import math\nprint(math.sqrt(16)) }) print(\n code_interpreter 结果 ) print(result) # Use virtual terminal result await session.call_tool(virtual_terminal, { command: ls -la }) print(\n virtual_terminal 结果 ) print(result) if __name__ __main__: asyncio.run(use_tools()) EOF之后可以检查一下这个目录下面文件有没有创建成功内容有没有正确粘贴进去ls -la client.py --能看到 client.py 文件就代表创建好了。 cat client.py ---核对内容 python client.py ----运行代码跑出来的结果就是(.venv) tdair execution-tools % ls -la client.py -rw-r--r-- 1 td staff 1224 10 20 10:40 client.py (.venv) tdair execution-tools % cat client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def use_tools(): server_params StdioServerParameters( commandpython, args[server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: await session.initialize() # Use file write tool result await session.call_tool(file_write, { path: test.py, content: print(Hello, World!) }) print( file_write 结果 ) print(result) # Use code interpreter result await session.call_tool(code_interpreter, { code: import math\nprint(math.sqrt(16)) }) print(\n code_interpreter 结果 ) print(result) # Use virtual terminal result await session.call_tool(virtual_terminal, { command: ls -la }) print(\n virtual_terminal 结果 ) print(result) if __name__ __main__: asyncio.run(use_tools()) (.venv) tdair execution-tools % python client.py file_write 结果 metaNone content[TextContent(typetext, text{\n success: true,\n path: /Users/td/Downloads/ai-agent-book/chapter4/execution-tools/test.py,\n bytes_written: 22,\n verification: passed\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalse code_interpreter 结果 metaNone content[TextContent(typetext, text{\n success: true,\n status: success,\n language: python,\n stdout: 4.0\\n,\n stderr: ,\n stdout_file: null,\n stderr_file: null,\n returncode: 0,\n error: null,\n compile_output: null,\n phase: null,\n execution_time: 0.011078119277954102,\n sandbox: {\n kind: local-process,\n degraded: true\n },\n verification: passed\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalse virtual_terminal 结果 metaNone content[TextContent(typetext, text{\n success: true,\n returncode: 0,\n stdout: total 760\\ndrwxr-xr-x 49 td staff 1568 Oct 20 10:40 .\\ndrwxr-xr-x 25 td staff 800 Oct 8 17:36 ..\\n-rw-r--r-- 1 td staff 6148 Oct 19 18:46 .DS_Store\\n-rw-r--r-- 1 td staff 1472 Oct 19 18:56 .env\\ndrwxr-xr-x 2 td staff 64 Oct 20 10:40 .execution-tmp\\n-rw-r--r-- 1 td staff 3537 Oct 8 17:20 Dockerfile\\n-rw-r--r-- 1 td staff 8552 Oct 8 17:20 EXPERIMENT.md\\n-rw-r--r-- 1 td staff 19737 Oct 8 17:20 README.md\\ndrwxr-xr-x 9 td staff 288 Oct 20 10:10 __pycache__\\n-rw-r--r-- 1 td staff 18673 Oct 8 17:20 cli.py\\n-rw-r--r-- 1 td staff 1224 Oct 20 10:40 client.py\\n-rw-r--r-- 1 td staff 7151 Oct 8 17:20 config.py\\n-rw-r--r-- 1 td staff 64 Oct 20 09:26 data.txt\\n-rw-r--r-- 1 td staff 1320 Oct 8 17:20 env.example\\n-rw-r--r-- 1 td staff 4332 Oct 8 17:20 examples.py\\n-rw-r--r-- 1 td staff 11340 Oct 8 17:20 execution_tools.py\\n-rw-r--r-- 1 td staff 917 Oct 8 17:20 experiment_protocol.json\\n-rw-r--r-- 1 td staff 19634 Oct 8 17:20 extended_tools.py\\n-rw-r--r-- 1 td staff 10508 Oct 8 17:20 external_tools.py\\n-rw-r--r-- 1 td staff 7296 Oct 8 17:20 file_tools.py\\n-rw-r--r-- 1 td staff 22095 Oct 8 17:20 filesystem_enhanced.py\\n-rw-r--r-- 1 td staff 155 Oct 8 17:20 hello.py\\n-rw-r--r-- 1 td staff 12206 Oct 8 17:20 llm_helper.py\\n-rw-r--r-- 1 td staff 25434 Oct 8 17:20 multilang_executor.py\\n-rw-r--r-- 1 td staff 2888 Oct 8 17:20 quickstart.py\\n-rw-r--r-- 1 td staff 1066 Oct 8 17:20 requirements.txt\\n-rw-r--r-- 1 td staff 14890 Oct 8 17:20 run_experiment_4_4.py\\n-rw-r--r-- 1 td staff 13978 Oct 8 17:20 server.py\\n-rw-r--r-- 1 td staff 15579 Oct 8 17:20 terminal_controller.py\\n-rw-r--r-- 1 td staff 22 Oct 20 10:40 test.py\\n-rw-r--r-- 1 td staff 3258 Oct 8 17:20 test_bash_lookup.py\\n-rw-r--r-- 1 td staff 5615 Oct 8 17:20 test_code_interpreter_python_runtime.py\\n-rw-r--r-- 1 td staff 961 Oct 8 17:20 test_command_history_count_zero.py\\n-rw-r--r-- 1 td staff 1774 Oct 8 17:20 test_config_env.py\\n-rw-r--r-- 1 td staff 1295 Oct 8 17:20 test_edit_reject_empty_search.py\\n-rw-r--r-- 1 td staff 5408 Oct 8 17:20 test_execution_tools.py\\n-rw-r--r-- 1 td staff 3149 Oct 8 17:20 test_external_tools.py\\n-rw-r--r-- 1 td staff 2835 Oct 8 17:20 test_file_tools.py\\n-rw-r--r-- 1 td staff 12977 Oct 8 17:20 test_filesystem_enhanced.py\\n-rw-r--r-- 1 td staff 1634 Oct 8 17:20 test_github_idempotency.py\\n-rw-r--r-- 1 td staff 682 Oct 8 17:20 test_gui_tools.py\\n-rw-r--r-- 1 td staff 4201 Oct 8 17:20 test_multilang.py\\n-rw-r--r-- 1 td staff 877 Oct 8 17:20 test_multilang_output.py\\n-rw-r--r-- 1 td staff 1669 Oct 8 17:20 test_null_language.py\\n-rw-r--r-- 1 td staff 98 Oct 8 17:20 test_script.py\\n-rw-r--r-- 1 td staff 6883 Oct 8 17:20 test_terminal_controller.py\\n-rw-r--r-- 1 td staff 1316 Oct 8 17:20 test_truncate_tail_lines_zero.py\\ndrwxr-xr-x 4 td staff 128 Oct 19 18:43 validation\\n-rw-r--r-- 1 td staff 332 Oct 20 09:26 wordcount.py\\n,\n stderr: ,\n stdout_file: null,\n stderr_file: null\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalse全部 3 个工具调用返回success: true看下回传结果file_write函数成功在当前目录生成test.pycode_interpreter负责在沙盒内运行代码virtual_terminal调用shell执行ls -la输出的结果均是json格式。把我们输入的代码和终端输出的结果串联起来复习下前面学的内容第一步红框里的“await session.initialize()“代码表示mcp握手初始化客户端发送初始化信息我是什么客户端支持哪些能力第二步Active Tool Discovery 主动工具发现握手成功之后客户端主动向服务端发送请求你都可以提供哪些工具发给我第三步seesion.call_tool()发起工具调用客户端知道工具列表之后按需发起调用高危动作会走 LLM 安全审批拦截。对应回传的结果就是call_tool(file_write, {path:test.py, content:print(hello)})客户端把这个请求打包成 MCP 协议 JSON 消息发给 server.py服务端收到执行对应的逻辑创建文件、写入内容执行结果打包返回给客户端客户端拿到返回结果打印输出简单理解就是client.py AI Agent大脑做决策server.py MCP 服务工具仓库干活的工具集合也可以进一步的吧主动工具发现这一步打印出来cat client.py EOF import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def use_tools(): server_params StdioServerParameters( commandpython, args[server.py], ) async with stdio_client(server_params) as (read, write): async with ClientSession(read, write) as session: print( Step1: MCP握手 initialize ) await session.initialize() print(握手完成\n) print( Step2: Active Tool Discovery 主动工具发现 ) tools_response await session.list_tools() for tool in tools_response.tools: print(f工具名称{tool.name}) print(f工具描述{tool.description}\n) print( Step3: 调用 file_write ) result await session.call_tool(file_write, { path: test.py, content: print(Hello, World!) }) print(result) print(\n Step3: 调用 code_interpreter ) result await session.call_tool(code_interpreter, { code: import math\nprint(math.sqrt(16)) }) print(result) print(\n Step3: 调用 virtual_terminal ) result await session.call_tool(virtual_terminal, { command: ls -la }) print(result) if __name__ __main__: asyncio.run(use_tools()) EOF结果是(.venv) tdair execution-tools % python client.py Step1: MCP握手 initialize 握手完成 Step2: Active Tool Discovery 主动工具发现 工具名称file_write 工具描述Write content to a file with automatic syntax verification 工具名称file_edit 工具描述Edit an existing file by searching and replacing content 工具名称code_interpreter 工具描述Execute code in multiple programming languages in a sandboxed environment with result analysis. Supports: Python, JavaScript, TypeScript, Go, Java, C, Rust, PHP, Bash 工具名称virtual_terminal 工具描述Execute shell commands with error summarization 工具名称google_calendar_add 工具描述Add an event to Google Calendar 工具名称github_create_pr 工具描述Create a GitHub Pull Request 工具名称excel_create_with_formula_and_screenshot 工具描述Create an XLSX workbook, apply formulas, and render a real screenshot with LibreOffice 工具名称webhook_post 工具描述POST JSON to a real HTTPS webhook endpoint 工具名称browser_navigate 工具描述Navigate with real headless Chromium, extract page content, and save a screenshot 工具名称virtual_desktop_execute 工具描述Drive a headful Chromium desktop through X11 keyboard events and retain a screenshot 工具名称virtual_mobile_execute 工具描述Operate a running AndroidWorld emulator through ADB and retain a screenshot 工具名称environment_capabilities 工具描述Inspect real Computer Use container and Android device availability Step3: 调用 file_write metaNone content[TextContent(typetext, text{\n success: false,\n error: Overwrite not approved: Approval check failed: API key not found for provider \openai\. Set OPENAI_API_KEY or OPENROUTER_API_KEY.\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalse Step3: 调用 code_interpreter metaNone content[TextContent(typetext, text{\n success: true,\n status: success,\n language: python,\n stdout: 4.0\\n,\n stderr: ,\n stdout_file: null,\n stderr_file: null,\n returncode: 0,\n error: null,\n compile_output: null,\n phase: null,\n execution_time: 0.0098419189453125,\n sandbox: {\n kind: local-process,\n degraded: true\n },\n verification: passed\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalse Step3: 调用 virtual_terminal metaNone content[TextContent(typetext, text{\n success: true,\n returncode: 0,\n stdout: total 760\\ndrwxr-xr-x 49 td staff 1568 Oct 20 10:40 .\\ndrwxr-xr-x 25 td staff 800 Oct 8 17:36 ..\\n-rw-r--r-- 1 td staff 6148 Oct 19 18:46 .DS_Store\\n-rw-r--r-- 1 td staff 1472 Oct 19 18:56 .env\\ndrwxr-xr-x 2 td staff 64 Oct 20 11:01 .execution-tmp\\n-rw-r--r-- 1 td staff 3537 Oct 8 17:20 Dockerfile\\n-rw-r--r-- 1 td staff 8552 Oct 8 17:20 EXPERIMENT.md\\n-rw-r--r-- 1 td staff 19737 Oct 8 17:20 README.md\\ndrwxr-xr-x 9 td staff 288 Oct 20 10:10 __pycache__\\n-rw-r--r-- 1 td staff 18673 Oct 8 17:20 cli.py\\n-rw-r--r-- 1 td staff 1543 Oct 20 11:01 client.py\\n-rw-r--r-- 1 td staff 7151 Oct 8 17:20 config.py\\n-rw-r--r-- 1 td staff 64 Oct 20 09:26 data.txt\\n-rw-r--r-- 1 td staff 1320 Oct 8 17:20 env.example\\n-rw-r--r-- 1 td staff 4332 Oct 8 17:20 examples.py\\n-rw-r--r-- 1 td staff 11340 Oct 8 17:20 execution_tools.py\\n-rw-r--r-- 1 td staff 917 Oct 8 17:20 experiment_protocol.json\\n-rw-r--r-- 1 td staff 19634 Oct 8 17:20 extended_tools.py\\n-rw-r--r-- 1 td staff 10508 Oct 8 17:20 external_tools.py\\n-rw-r--r-- 1 td staff 7296 Oct 8 17:20 file_tools.py\\n-rw-r--r-- 1 td staff 22095 Oct 8 17:20 filesystem_enhanced.py\\n-rw-r--r-- 1 td staff 155 Oct 8 17:20 hello.py\\n-rw-r--r-- 1 td staff 12206 Oct 8 17:20 llm_helper.py\\n-rw-r--r-- 1 td staff 25434 Oct 8 17:20 multilang_executor.py\\n-rw-r--r-- 1 td staff 2888 Oct 8 17:20 quickstart.py\\n-rw-r--r-- 1 td staff 1066 Oct 8 17:20 requirements.txt\\n-rw-r--r-- 1 td staff 14890 Oct 8 17:20 run_experiment_4_4.py\\n-rw-r--r-- 1 td staff 13978 Oct 8 17:20 server.py\\n-rw-r--r-- 1 td staff 15579 Oct 8 17:20 terminal_controller.py\\n-rw-r--r-- 1 td staff 22 Oct 20 10:40 test.py\\n-rw-r--r-- 1 td staff 3258 Oct 8 17:20 test_bash_lookup.py\\n-rw-r--r-- 1 td staff 5615 Oct 8 17:20 test_code_interpreter_python_runtime.py\\n-rw-r--r-- 1 td staff 961 Oct 8 17:20 test_command_history_count_zero.py\\n-rw-r--r-- 1 td staff 1774 Oct 8 17:20 test_config_env.py\\n-rw-r--r-- 1 td staff 1295 Oct 8 17:20 test_edit_reject_empty_search.py\\n-rw-r--r-- 1 td staff 5408 Oct 8 17:20 test_execution_tools.py\\n-rw-r--r-- 1 td staff 3149 Oct 8 17:20 test_external_tools.py\\n-rw-r--r-- 1 td staff 2835 Oct 8 17:20 test_file_tools.py\\n-rw-r--r-- 1 td staff 12977 Oct 8 17:20 test_filesystem_enhanced.py\\n-rw-r--r-- 1 td staff 1634 Oct 8 17:20 test_github_idempotency.py\\n-rw-r--r-- 1 td staff 682 Oct 8 17:20 test_gui_tools.py\\n-rw-r--r-- 1 td staff 4201 Oct 8 17:20 test_multilang.py\\n-rw-r--r-- 1 td staff 877 Oct 8 17:20 test_multilang_output.py\\n-rw-r--r-- 1 td staff 1669 Oct 8 17:20 test_null_language.py\\n-rw-r--r-- 1 td staff 98 Oct 8 17:20 test_script.py\\n-rw-r--r-- 1 td staff 6883 Oct 8 17:20 test_terminal_controller.py\\n-rw-r--r-- 1 td staff 1316 Oct 8 17:20 test_truncate_tail_lines_zero.py\\ndrwxr-xr-x 4 td staff 128 Oct 19 18:43 validation\\n-rw-r--r-- 1 td staff 332 Oct 20 09:26 wordcount.py\\n,\n stderr: ,\n stdout_file: null,\n stderr_file: null\n}, annotationsNone, metaNone)] structuredContentNone isErrorFalseMCP 服务一次性返回了它能提供的全部 12 个工具清单 每个工具的描述这些是执行工具mcp服务器感知 MCP 服务器工具一般是read_file、list_dir、get_file_metadata。也可以去看单个工具测试情况