1.集成生态全景解析：构建企业级智能体系统的集成之道
2.长期记忆集成深度解析：让智能体真正“记住“用户
3.Agent 状态存储（AgentStateStore）深度解析：构建可恢复、可扩展的智能体运行时
4.RAG 知识库集成全攻略：从自建向量库到第三方平台，一篇讲透
5.技能仓库（Skill Repository）完全实战指南
6.协议集成全景解析：A2A、AG-UI、Agent Protocol 三大开放协议实战指南
7.集成 Higress AI 网关：智能体流量治理的生产级实战
8.深度集成 Nacos：智能体注册发现、技能管理与动态治理全实战
9.集成 Scheduler 调度器：让智能体“按时上班“的生产级定时调度实战
10.集成 Chat Completions Web：一行依赖让你的 Agent 变身 OpenAI 兼容服务
11.集成在线训练（Training）：让你的 Agent 越用越聪明

一、引言：当智能体数量超过 5 个，你必须回答"它们在哪里"

随着企业 AI 应用从 POC 走向生产，一个绕不开的现实问题浮出水面：

Agent 越来越多，但它们彼此不知道对方的存在。

典型的企业场景中：

挑战具体表现
语言栈多样化核心业务团队用 Java/Go，算法团队用 Python，Agent 架构选型各异
框架割裂LangChain、AutoGen、CrewAI、AgentScope 各有各的接口规范
能力不透明不知道某个 Agent 能做什么、支持哪些技能、当前是否在线
变更失控Agent 上下线、版本更新、Prompt 修改缺乏统一管理
技能散落各团队各自维护 Skill 文件，无法复用、无法版本管控

传统微服务通过 Nacos 解决了"服务在哪里"的问题。2025 年发布的 Nacos 3.x 将定位升级为：

“易于构建 AI Agent 应用的动态服务发现、配置管理和 AI 治理平台”

新增 Agent Registry、MCP Registry、Prompt Registry、Skill Registry 四大 AI 原生能力。而 AgentScope Java 2.0 通过 agentscope-extensions-nacos 模块，将这些能力以"即插即用"的方式接入智能体运行时。

二、Nacos 在 AgentScope 体系中的完整角色

2.1 四大 Registry + 配置管理


┌─────────────────────────────────────────────────────────────────────┐
│                          Nacos 3.x                                   │
├───────────────┬───────────────┬───────────────┬────────────────────┤
│ Agent Registry│ MCP Registry  │ Skill Registry│ Prompt Registry    │
├───────────────┼───────────────┼───────────────┼────────────────────┤
│ Agent Card    │ MCP Server    │ SKILL.md      │ System Prompt      │
│ 注册 / 发现   │ 注册 / 路由   │ ZIP 包分发    │ 版本控制           │
│ 健康检查      │ 协议转换      │ 版本管理      │ 多环境隔离         │
│ 元数据管理    │ 权限管控      │ 热更新        │ 动态下发           │
│ 命名空间隔离  │ 动态调试      │ 标签/灰度     │ 变更监听           │
├───────────────┴───────────────┴───────────────┴────────────────────┤
│                    配置管理（Config Service）                        │
│         Agent 运行参数 / 模型配置 / 工具开关 动态下发                │
└─────────────────────────────────────────────────────────────────────┘
         ↕                ↕               ↕              ↕
┌─────────────────────────────────────────────────────────────────────┐
│                  AgentScope Java Agent 集群                          │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ ReActAgent   │  │ HarnessAgent │  │ A2A Server   │             │
│  └──────────────┘  └──────────────┘  └──────────────┘             │
└─────────────────────────────────────────────────────────────────────┘

2.2 AgentScope Java 侧的对应扩展

Nacos 能力AgentScope Java 扩展核心类
Agent Registryagentscope-extensions-nacosNacosAgentRegistry / NacosAgentCardResolver
Skill Registryagentscope-extensions-nacos-skillNacosSkillRepository
MCP Registryagentscope-extensions-nacos（A2A 模块）NacosMcpResolver
Prompt RegistryNacos Config ServiceNacosConfigService + Prompt 模板
配置管理Nacos Config ServiceNacosConfigListener

三、Agent Registry：让"调 Agent 像调微服务一样自然"

3.1 核心概念：Agent Card

Agent Card 是 A2A 协议中定义的智能体能力名片，包含：

{
  "name": "TravelPlannerAgent",
  "description": "帮助用户规划旅行行程，支持国内外目的地推荐",
  "url": "http://travel-agent:8080",
  "version": "2.1.0",
  "skills": [
    {
      "id": "trip-planning",
      "name": "行程规划",
      "description": "根据用户偏好生成多日旅行方案"
    },
    {
      "id": "hotel-booking",
      "name": "酒店推荐",
      "description": "根据预算和位置推荐住宿"
    }
  ],
  "securitySchemes": {
    "bearerAuth": { "type": "http", "scheme": "bearer" }
  }
}

Agent Card 注册到 Nacos 后，任何框架、任何语言的 Agent 都可以通过 Nacos 发现并调用它。

3.2 将 Agent 自动注册到 Nacos

添加依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos</artifactId>
    <version>${agentscope.version}</version>
</dependency>

编程式注册

import io.agentscope.a2a.server.A2aServer;
import io.agentscope.extensions.nacos.NacosAgentRegistry;
import com.alibaba.nacos.api.PropertyKeyConst;
import java.util.Properties;

// 1. 配置 Nacos 连接
Properties nacosProps = new Properties();
nacosProps.put(PropertyKeyConst.SERVER_ADDR, "nacos-server:8848");
nacosProps.put(PropertyKeyConst.NAMESPACE, "agent-prod");
nacosProps.put(PropertyKeyConst.USERNAME, "nacos");
nacosProps.put(PropertyKeyConst.PASSWORD, "nacos");

// 2. 构建 Agent
ReActAgent agent = ReActAgent.builder()
    .name("TravelPlannerAgent")
    .description("帮助用户规划旅行行程")
    .model(model)
    .toolkit(toolkit)
    .build();

// 3. 创建 A2A Server 并注入 Nacos 注册
A2aServer a2aServer = A2aServer.builder()
    .agent(agent)
    .port(8080)
    .agentRegistry(new NacosAgentRegistry(nacosProps))  // 关键！
    .build();

// 4. 启动 → Agent Card 自动注册到 Nacos
a2aServer.start();

启动后，Nacos 控制台即可看到该 Agent 的注册信息，包括名称、技能列表、服务端点、健康状态等。

3.3 通过 Nacos 发现远端 Agent

import io.agentscope.extensions.nacos.NacosAgentCardResolver;
import io.agentscope.a2a.client.A2aClient;

// 创建 Nacos 发现器
NacosAgentCardResolver resolver = NacosAgentCardResolver.builder()
    .serverAddr("nacos-server:8848")
    .namespace("agent-prod")
    .username("nacos")
    .password("nacos")
    .build();

// 按名称查找可用 Agent
List<AgentCard> cards = resolver.resolve("TravelPlannerAgent");

// 创建 A2A Client 并发起调用
A2aClient client = A2aClient.fromAgentCard(cards.get(0));
Task task = client.sendTask(
    Message.of("帮我规划一个东京五日游，预算 15000 元")
);

// 订阅流式事件
client.subscribeEvents(task.getId(), event -> {
    System.out.println("[" + event.getType() + "] " + event.getData());
});

💡 关键价值：调用方无需硬编码目标 Agent 的地址。Agent 上下线、扩缩容、版本更新，调用方通过 Nacos 自动感知，实现"调 Agent 像调微服务一样自然"。

3.4 跨语言、跨框架互通

由于 Nacos Agent Registry 基于 A2A 标准协议，以下场景天然支持：

Java Agent (AgentScope) ──→ Nacos ←── Python Agent (LangChain)
                              ↑
Go Agent (自研框架) ─────────┘

所有框架只要遵循 A2A 协议 + 注册到同一 Nacos 实例，即可互相发现与调用。

四、Skill Registry：技能的统一存储、版本管理与动态下发

4.1 为什么需要集中管理技能？

AgentScope Java 2.0 的 Harness 架构引入了 SKILL.md 文件协议——每个技能以标准化文件描述，Agent 按需加载。但在企业环境中：

  • 技能散落在各团队本地，无法复用
  • 技能更新需要重新部署 Agent
  • 无法按环境（dev / staging / prod）隔离技能版本
  • 缺乏审计与权限管控

Nacos Skill Registry 正是为解决这些问题而生。

4.2 NacosSkillRepository：从 Nacos 加载技能

添加依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
    <version>${agentscope.version}</version>
</dependency>

完整代码示例

import io.agentscope.core.nacos.skill.NacosSkillRepository;
import io.agentscope.core.skill.AgentSkill;
import io.agentscope.core.skill.SkillBox;
import java.util.Properties;

public class NacosSkillDemo {

    public static void main(String[] args) {
        // 1. 配置 Nacos 连接（阿里云 MSE 场景使用 AccessKey）
        Properties props = new Properties();
        props.put("serverAddr", "mse-xxx.nacos.mse.aliyuncs.com:8848");
        props.put("namespace", "skill-registry");
        props.put("accessKey", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
        props.put("secretKey", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

        // 2. 创建 NacosSkillRepository
        NacosSkillRepository skillRepo = new NacosSkillRepository(props, "agent-skills");

        // 3. 获取所有可用技能
        List<AgentSkill> skills = skillRepo.getAllSkills();
        skills.forEach(skill -> 
            System.out.println(skill.getName() + " - " + skill.getDescription())
        );

        // 4. 注册到 Agent 的 SkillBox
        SkillBox skillBox = new SkillBox();
        skills.forEach(skillBox::register);

        // 5. 绑定到 HarnessAgent
        HarnessAgent agent = HarnessAgent.builder()
            .name("SmartAssistant")
            .model(model)
            .skillRepository(skillRepo)  // 直接注入仓库
            .build();
    }
}

工作机制

Nacos Skill Registry
    │
    ├─ skill: data-analysis (v1.2.0)    ← SKILL.md + 资源文件（ZIP 包）
    ├─ skill: report-generator (v2.0.1)
    └─ skill: code-review (v1.0.0)
         │
         ↓  Agent 启动时 / 按需拉取
    NacosSkillRepository
         │
         ↓  下载 ZIP → 解压 → 解析 SKILL.md
    AgentSkill 对象
         │
         ↓  注册到 SkillBox
    HarnessAgent 按需调用

4.3 技能版本与标签管理

Nacos Skill Registry 支持版本（version）+ 标签（label） 双维度管理：

配置方式优先级示例
Properties 构造参数最高props.put(“version”, “2.0.1”)
JVM 系统属性 中 -Dagentscope.nacos.skill.version=2.0.1
环境变量 最低 AGENTSCOPE_NACOS_SKILL_VERSION=2.0.1

灰度发布场景：

// 生产环境使用稳定版
props.put("label", "stable");

// 预发环境使用最新版
props.put("label", "canary");

4.4 多层技能仓库链

AgentScope Java 2.0 支持 5 层技能仓库叠加，Nacos 是其中关键一环：

优先级（高 → 低）：
┌─────────────────────────────────────────┐
│ 1. 用户私有技能（用户级覆盖）            │
│ 2. 工作区公共技能（项目级）              │
│ 3. Nacos Skill Registry（企业级共享）    │  ← 本文重点
│ 4. Git 远程仓库（团队级）               │
│ 5. Classpath 内置技能（框架默认）        │
└─────────────────────────────────────────┘

同名技能按优先级覆盖，Nacos 层提供企业级统一管控，同时不阻止本地个性化覆盖。

4.5 动态更新：技能热加载

Nacos 支持配置变更监听。当管理员在 Nacos 控制台更新某个 Skill 后：

管理员更新 Skill (v1.0 → v1.1)
       ↓
Nacos 推送变更事件
       ↓
NacosSkillRepository 监听到变更
       ↓
自动下载新版 ZIP → 替换旧版
       ↓
Agent 下次调用即使用新版技能（无需重启）

💡 生产价值：技能更新不再需要重新部署 Agent 应用，实现"技能即配置"的运维模式。

五、MCP Registry：统一治理 Agent 的工具服务

5.1 Nacos MCP Registry 能力

Nacos 3.x 的 MCP Registry 支持三类 MCP 服务注册方式：

注册方式说明适用场景
原生 MCP Server直接注册 MCP 协议服务 新建 MCP 工具
REST-to-MCP 转换将存量 HTTP/RPC API 声明式转为 MCP 服务 存量系统改造
编排型 MCP多个 MCP 工具组合编排 复合工具场景

5.2 AgentScope 通过 Nacos 发现 MCP 服务

import io.agentscope.extensions.nacos.mcp.NacosMcpResolver;

// 通过 Nacos 发现可用的 MCP Server
NacosMcpResolver mcpResolver = NacosMcpResolver.builder()
    .serverAddr("nacos-server:8848")
    .namespace("mcp-registry")
    .build();

// 按名称/能力查找 MCP Server
List<McpServerInfo> servers = mcpResolver.resolve("weather-service");

// 将发现的 MCP Server 注册为 Agent 工具
Toolkit toolkit = new Toolkit();
servers.forEach(server -> toolkit.registerMcpServer(server));

ReActAgent agent = ReActAgent.builder()
    .name("WeatherAssistant")
    .model(model)
    .toolkit(toolkit)
    .build();

5.3 与 Higress 联动

Agent ──[MCP 协议]──→ Higress AI 网关 ──[协议转换]──→ 存量 REST API
                            ↑
                    Nacos MCP Registry
                    （注册 / 发现 / 路由）

Nacos 作为 MCP 服务的"控制面"，Higress 作为"数据面"执行实际的协议转换与流量转发。两者配合实现存量 API 零代码改造接入 AI Agent。

六、配置管理：Agent 运行参数的动态下发

6.1 典型场景

配置项示例变更频率
模型选择model=qwen-max → model=qwen-plus按需
温度参数temperature=0.7 → temperature=0.3调优期
工具开关enable_code_execution=true/false应急
System Prompt角色定义、行为约束持续优化
限流阈值max_tokens_per_request=4096成本管控

6.2 实现方式

import com.alibaba.nacos.api.config.ConfigService;
import com.alibaba.nacos.api.config.listener.Listener;

// 1. 创建 ConfigService
ConfigService configService = NacosFactory.createConfigService(nacosProps);

// 2. 获取初始配置
String agentConfig = configService.getConfig(
    "agent-config",        // dataId
    "travel-agent",        // group
    5000                   // 超时
);

// 3. 监听配置变更
configService.addListener("agent-config", "travel-agent", new Listener() {
    @Override
    public void receiveConfigInfo(String configInfo) {
        // 配置变更时自动回调
        agent.reloadConfig(configInfo);
        log.info("Agent 配置已热更新: {}", configInfo);
    }
    
    @Override
    public Executor getExecutor() { return null; }
});

6.3 多环境隔离

通过 Nacos Namespace 实现环境隔离：

Nacos
├── namespace: agent-dev        ← 开发环境
│   ├── agent-config (temperature=0.9, 宽松)
│   └── skill-registry (label=latest)
├── namespace: agent-staging    ← 预发环境
│   ├── agent-config (temperature=0.5)
│   └── skill-registry (label=canary)
└── namespace: agent-prod       ← 生产环境
    ├── agent-config (temperature=0.3, 严格)
    └── skill-registry (label=stable)

七、完整架构：Nacos 在智能体平台中的位置

┌─────────────────────────────────────────────────────────────────────┐
│                    用户 / 前端 / 管理后台                            │
└────────────────────────────┬────────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────────┐
│                    Higress AI 网关（流量治理）                       │
└────────────────────────────┬────────────────────────────────────────┘
                             ↓
┌─────────────────────────────────────────────────────────────────────┐
│                    Agent 集群（AgentScope Java）                     │
│                                                                     │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐       │
│  │ 客服 Agent     │  │ 分析 Agent     │  │ 运维 Agent     │       │
│  │ (Java/AS)      │  │ (Python/LC)    │  │ (Java/AS)      │       │
│  └───────┬────────┘  └───────┬────────┘  └───────┬────────┘       │
│          │                   │                    │                 │
│          └───────────────────┼────────────────────┘                 │
│                              ↓                                      │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │                    Nacos 3.x（控制面）                         │  │
│  │                                                               │  │
│  │  ┌─────────────┐ ┌─────────────┐ ┌──────────┐ ┌───────────┐ │  │
│  │  │Agent Registry│ │MCP Registry │ │Skill Reg.│ │Prompt Reg.│ │  │
│  │  └─────────────┘ └─────────────┘ └──────────┘ └───────────┘ │  │
│  │  ┌─────────────────────────────────────────────────────────┐ │  │
│  │  │              Config Service（动态配置）                   │ │  │
│  │  └─────────────────────────────────────────────────────────┘ │  │
│  └───────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

八、与阿里云 MSE 的集成（托管方案）

对于不想自行运维 Nacos 集群的企业，阿里云提供 MSE AI 治理中心（托管 Nacos）：

8.1 前提条件

  • 已开通阿里云 MSE AI 治理中心实例，并完成工作空间创建
  • 已准备好阿里云 AccessKey / SecretKey，且 RAM 子账号已授予相关权限
  • 已根据 Agent 运行环境完成网络接入配置（VPC / 公网）

8.2 接入配置

Properties props = new Properties();
props.put("serverAddr", "mse-xxxxxx.nacos.mse.aliyuncs.com:8848");
props.put("namespace", "your-workspace-id");
props.put("accessKey", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"));
props.put("secretKey", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));

// 后续使用方式与自建 Nacos 完全一致
NacosSkillRepository skillRepo = new NacosSkillRepository(props, "skills");

8.3 MSE 增强能力

能力说明
Agent Card 集中管理可视化查看所有注册 Agent 的能力、状态、版本
Skill 安全审核技能包上传后自动安全扫描
操作审计所有注册/变更操作留痕
高可用保障多可用区部署，99.95% SLA

九、生产环境最佳实践

9.1 安全与权限

措施实现方式
鉴权Nacos 3.x 默认开启鉴权；生产环境必须配置用户名密码或 AK/SK
命名空间隔离按环境（dev/staging/prod）+ 业务线划分 Namespace
RBACMSE 托管版支持 RAM 子账号细粒度权限（只读/读写）
传输加密启用 TLS，Agent ↔ Nacos 通信加密
技能审核Skill 包上传前进行安全扫描（MSE 支持）

9.2 高可用部署

自建方案：
  Nacos 集群 ≥ 3 节点（Raft 协议）
  跨可用区部署
  定期备份配置数据

托管方案（MSE）：
  多可用区自动容灾
  自动扩缩容
  99.95% SLA

9.3 命名规范建议

Namespace:  {env}-{business-unit}     例: prod-finance
Group:      {agent-name}              例: travel-planner
DataId:     {config-type}             例: agent-config / skill-registry

9.4 监控告警

监控项告警阈值说明
Agent 实例健康不健康实例 > 0 持续 30sAgent 掉线
注册变更频率> 10 次/分钟疑似异常上下线
Skill 拉取失败率> 5%网络或权限问题
配置推送延迟> 5sNacos 集群压力

9.5 与 Higress 联动

Nacos（控制面）：Agent 注册、Skill 管理、配置下发
     ↕ 服务发现同步
Higress（数据面）：流量路由、协议转换、限流鉴权

Nacos 作为 Higress 的服务发现源，实现"注册即路由"——Agent 注册到 Nacos 后，Higress 自动感知并更新路由规则。

十、选型决策：何时需要 Nacos 集成？

你的场景是否需要 Nacos关键理由
只有 1~2 个 Agent，固定部署❌ 暂不需要硬编码地址即可
Agent 数量 ≥ 3，需要互相调用✅ 强烈推荐统一发现，避免硬编码
跨语言（Java + Python）Agent 协作✅ 必须框架无关的服务发现
技能需要多团队共享与版本管控✅ 推荐Skill Registry 统一管理
需要不重启更新 Agent 配置✅ 推荐Config Service 动态下发
需要对接存量 REST API 作为 MCP 工具✅ 推荐MCP Registry + Higress 联动
生产环境多租户隔离✅ 必须Namespace + RBAC

十一、总结

Nacos 在 AgentScope Java 生态中扮演着"智能体控制面"的核心角色：

价值维度具体收益
统一发现Agent 像微服务一样注册、发现、健康检查，跨语言跨框架互通
技能治理SKILL.md 集中存储、版本管理、灰度发布、热更新，无需重新部署
工具治理MCP Server 统一注册、存量 API 零改造接入
动态配置模型参数、Prompt、工具开关实时下发，秒级生效
企业级治理命名空间隔离、RBAC 权限、操作审计、高可用集群

AgentScope Java 通过 agentscope-extensions-nacos 模块，将这些能力以最小侵入的方式接入：

  • 注册：一行 .agentRegistry(new NacosAgentRegistry(props))
  • 发现：一个 NacosAgentCardResolver 实例
  • 技能：一个 NacosSkillRepository 注入
  • 配置：标准 Nacos ConfigService API

这种设计哲学是：让 Agent 开发者专注业务逻辑，让基础设施处理治理复杂性。

# java # python # 人工智能
Logo
天工造物局

北京人形旗下天工造物具身智能开源社区，聚焦具身天工与慧思开物两大平台

更多推荐

graphify 视频音视频转写全流程解析：从 detect 结果到知识图谱文档的 Step 2.5

graphify 的核心能力是把任意语料（代码、文档、PDF、图片）转化为可查询的知识图谱，而视频与音频文件无法被直接阅读，必须先把它们转写成文本。本文围绕 `graphify` 运行手册中的转写参考文档 [transcribe.md](https://link.gitcode.com/i/d3285781588e0f1b84886dfdbc4fe7f6)，完整讲解 "Step 2.5 - Tra

avatar 天工造物局

ML-For-Beginners 终章：经典机器学习在金融、医疗、零售等八大行业中的真实落地场景

本篇技术指南基于开源课程仓库 ML-For-Beginners 的收尾课程《Postscript: Machine learning in the real world》（对应仓库目录 [9-Real-World/1-Applications](https://link.gitcode.com/i/6b23002df80861c20abf34d7db63ef41)）编写。该课此前 11 周的教学带

avatar 天工造物局

graphify 知识图谱查询实战：query / path / explain 与可审计的答案闭环

本指南以 graphify 的 Trae 版查询技能参考（[graphify/skills/trae/references/query.md](https://link.gitcode.com/i/72a7875d46ec6d3706d31791f3cdcbe0)）为主体，系统讲解如何针对**已构建好的知识图谱**执行三类查询：语义相关节点遍历（query）、两概念间最短路径（path）、单节点关

avatar 天工造物局