服务注册与分布式协调 / 系统课时

接入 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])

Agent 运行时动态发现与目录变化

这一结构把职责分得很清楚:模型负责根据任务决定“需要什么能力”,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 用来传入本次自然语言任务。

python
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())

预期输出(模型可能在单轮中发出一个或多个工具调用,尖括号内容随目录、模型和目标服务变化):

text
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 配置更适合持续治理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

接入 Agent 客户端运行时

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通