服务注册与分布式协调 / 系统课时
接入 Agent 客户端运行时
接入 Agent 客户端运行时
这一课把 Nacos MCP Router 接到 Agent 运行时:Agent 启动时只加载 Router 的 MCP 工具,由模型在运行过程中搜索服务、选择目标、建立连接并代理调用。你还会用同一任务的两次运行验证 Registry 目录变化确实进入下一次发现结果。
学习目标
- 在 Agent 运行时中把 Router 配置为 MCP 发现入口并加载其工具定义
- 让支持 tool calling 的模型驱动
search_mcp_server、add_mcp_server与use_tool - 通过新会话对比发现结果,验证服务、版本或工具可见性变化的影响
把 Router 放在模型与 Registry 之间
Agent 不需要把整个 MCP 目录一次性塞进模型上下文。它只连接 Router,先加载 Router 自身的少量工具;真正需要某类能力时,模型再让 Router 查询 Nacos MCP Registry。Router 官方定位就是为 MCP Client 提供服务搜索、安装/初始化和代理能力,并可结合 Registry 做服务与工具可见性、版本管理。([Nacos 官网][1])

这一结构把职责分得很清楚:模型负责根据任务决定“需要什么能力”,Router 负责把能力需求映射到 MCP Server 并执行代理,Registry 负责提供可治理的服务和工具目录。目录越动态,越应该在运行时重新搜索,而不是长期缓存一份静态服务清单。
让模型驱动 Router 工具
下面的主示例使用 MCP Python SDK 连接 Router,再把 Router 返回的工具 schema 转成模型可用的 function tools。模型被要求按“搜索 → 添加 → 调用”的顺序完成任务,但具体选择哪个 MCP Server、哪个业务工具以及参数,仍由模型根据 Router 返回内容决定。
运行前准备 ROUTER_URL、MODEL_API_KEY、MODEL_NAME;如果模型服务需要自定义兼容端点,可额外设置 MODEL_BASE_URL。AGENT_TASK 用来传入本次自然语言任务。
import asyncio
import json
import os
from typing import Any
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.types import TextContent
from openai import AsyncOpenAI
ROUTER_URL = os.environ["ROUTER_URL"]
MODEL_NAME = os.environ["MODEL_NAME"]
AGENT_TASK = os.getenv(
"AGENT_TASK",
"寻找合适的 MCP 服务并调用工具完成这个任务",
)
def mcp_result_text(result) -> str:
if result.structured_content is not None:
return json.dumps(result.structured_content, ensure_ascii=False)
texts = [
block.text
for block in result.content
if isinstance(block, TextContent)
]
return "\n".join(texts) if texts else "<EMPTY_RESULT>"
def to_model_tool(tool) -> dict[str, Any]:
return {
"type": "function",
"function": {
"name": tool.name,
"description": tool.description or "",
"parameters": tool.input_schema,
},
}
def build_model_client() -> AsyncOpenAI:
kwargs: dict[str, Any] = {
"api_key": os.environ["MODEL_API_KEY"],
}
if os.getenv("MODEL_BASE_URL"):
kwargs["base_url"] = os.environ["MODEL_BASE_URL"]
return AsyncOpenAI(**kwargs)
async def main() -> None:
model = build_model_client()
async with streamable_http_client(ROUTER_URL) as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
listed = await session.list_tools()
router_tools = [to_model_tool(tool) for tool in listed.tools]
names = {
tool["function"]["name"]
for tool in router_tools
}
required = {"search_mcp_server", "add_mcp_server", "use_tool"}
print("router tools ready:", required.issubset(names))
messages: list[dict[str, Any]] = [
{
"role": "system",
"content": (
"你通过 Nacos MCP Router 使用外部工具。"
"目标服务未知时先调用 search_mcp_server;"
"选定服务后调用 add_mcp_server;"
"最后用 use_tool 执行业务工具。"
),
},
{"role": "user", "content": AGENT_TASK},
]
for _ in range(6):
response = await model.chat.completions.create(
model=MODEL_NAME,
messages=messages,
tools=router_tools,
tool_choice="auto",
)
message = response.choices[0].message
assistant_message: dict[str, Any] = {
"role": "assistant",
"content": message.content,
}
if message.tool_calls:
assistant_message["tool_calls"] = [
{
"id": call.id,
"type": "function",
"function": {
"name": call.function.name,
"arguments": call.function.arguments,
},
}
for call in message.tool_calls
]
messages.append(assistant_message)
if not message.tool_calls:
print("final:", message.content or "")
return
for call in message.tool_calls:
arguments = json.loads(call.function.arguments or "{}")
print("model tool:", call.function.name)
result = await session.call_tool(
call.function.name,
arguments,
)
text = mcp_result_text(result)
print("tool result:", text[:500])
messages.append(
{
"role": "tool",
"tool_call_id": call.id,
"content": text,
}
)
raise RuntimeError("模型工具调用轮次超过上限")
if __name__ == "__main__":
asyncio.run(main())预期输出(模型可能在单轮中发出一个或多个工具调用,尖括号内容随目录、模型和目标服务变化):
router tools ready: True
model tool: search_mcp_server
tool result: <DISCOVERY_RESULT>
model tool: add_mcp_server
tool result: <TARGET_TOOL_LIST>
model tool: use_tool
tool result: <TARGET_TOOL_RESULT>
final: <MODEL_ANSWER>MCP SDK 返回的每个工具定义都包含名称、描述和输入 schema,这些信息可以直接成为模型进行工具选择所需的描述;真正调用时仍由 MCP Client 通过 call_tool() 把参数交给 Router。([GitHub][3])
验证目录变化影响下一次发现
第一次运行时保留 search_mcp_server 的 tool result。随后在 Nacos MCP Registry 中做一个可观察的目录变更,例如新增一个更匹配的 MCP Server、下线旧服务、调整服务版本,或切换某个工具的可见性。Nacos 的 MCP 管理能力支持服务动态管理以及工具描述、工具开关等运行时治理。([Nacos 官网][4])
完成变更后,用同一个 AGENT_TASK 新建一次 Agent/MCP 会话并重新运行脚本。验收重点不是最终自然语言答案必须逐字不同,而是新的 search_mcp_server 返回候选或工具信息已经反映 Registry 的当前状态,并进一步改变模型后续的服务选择或可调用工具集合。
运行时发现的边界
目录变化首先影响的是后续搜索与初始化,不会自动改写一个已经在途的 use_tool 请求。模型也不是直接访问 Nacos:它只看到 Router 暴露的 MCP 工具及每次工具调用返回的内容,因此鉴权、命名空间和 Registry 可见性问题应在 Router/Nacos 链路排查,而模型提示词主要解决工具选择与参数生成问题。
当同一 Agent 需要面对频繁变化的 MCP 服务目录时,这种“固定接入 Router、运行时再发现目标服务”的方式,比把实例地址或完整工具目录固化进 Agent 配置更适合持续治理。