MCP路由式AI代理系统教程揭示动态工具曝光与上下文注入全流程

背景与意义

随着大模型能力的提升，单一LLM已难以直接完成复杂任务。MCP（Model Context Protocol）通过工具发现、路由、规划和执行四步，将外部能力安全、可控地注入模型，显著提升效率并降低误用风险。本文提供的完整代码库，为想要快速搭建生产级代理系统的开发者提供了可直接复用的参考框架。

系统架构概览

Tool Server：基于Pydantic定义ToolSpec，统一管理工具名称、描述、输入Schema和标签；实现tools_list与tools_call两大JSON‑RPC接口。
Hybrid Router：先用关键词启发式打分生成候选工具集合，再让LLM在严格的JSON约束下完成最终曝光决策，确保最小化曝光原则。
Routed Agent：在路由结果基础上进行规划（是否需要工具、调用顺序、参数），随后安全执行并将工具输出注入模型提示，最终生成用户可读答案。

关键实现细节

1. 工具定义与安全执行

支持web_search、python_exec、vector_retrieve、dataset_loader四类常用工具。
python_exec仅开放安全的内置函数，并通过io.StringIO捕获标准输出，防止代码泄漏或无意的系统调用。
vector_retrieve利用TF‑IDF向量化本地文档，实现快速的本地知识检索，为MCP提供上下文注入基础。

2. 动态路由策略

关键字映射表将任务描述映射到工具得分，兼顾近期信息需求（启用web_search）与本地概念检索（启用vector_retrieve）。
LLM在instructions中被约束只能返回selected_tools、rationale和policy_notes三个字段，避免额外信息泄露。

3. 规划与执行流程

规划阶段限定最多3次工具调用，并要求调用必须在已曝光工具列表内。
run_tools统一捕获成功/失败结果，返回结构化ToolResult供后续答案生成使用。
最终答案阶段，模型被指示不提及隐藏工具，并在上下文中融合工具输出，保证答案的可解释性与完整性。

示例任务与效果

任务示例	关键工具	结果概述
解释MCP路由策略	`vector_retrieve`	检索本地文档并给出概念要点
查询最新MCP相关进展	`web_search`	返回最近三篇博客链接并概括要点
加载iris数据集并描述	`dataset_loader`	输出列名、数据形状及统计信息
计算数组均值并评估必要性	`python_exec`	给出均值并说明是否必需

通过上述任务演示，系统能够在不同需求之间灵活切换，始终保持最小工具曝光和上下文注入两大核心原则。

价值与展望

安全性提升：仅曝光与任务高度相关的工具，降低意外调用风险。
效率优化：减少不必要的工具搜索与调用，缩短响应时延。
可解释性：每一步均产生结构化日志，便于审计与调试。
可扩展性：框架支持新增工具，只需提供ToolSpec与实现函数，即可无缝集成。

未来可在路由阶段引入学习型评分模型，或加入记忆层实现跨会话上下文持久化，进一步逼近真正的生产级AI助理。

全文代码与 notebook 已在文章底部提供，欢迎下载体验。