企业官网建设流程全解析

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG

导读：Nexent 提供一套双向资源集成体系——既能通过 MCP 协议、Skill 技能包和 A2A Agent 协议将外部 AI 资源「接入」平台供智能体调用，也能将平台内的 Agent 以 JSON/ZIP 配置、北向 RESTful API、A2A Agent 三种方式「导出」给外部系统。读完本文，你将掌握三种资源接入的完整操作步骤与配置参数、SKILL.md 技能包的格式规范、A2A Agent Card 的发现与管理方法，以及导出与发布 Agent 的适用场景，并了解这些能力在 Nexent 后端源码中的实现位置。

双向集成体系总览

Nexent 的第三方集成能力围绕「接入外部资源」与「导出平台能力」两个方向展开（英文文档入口见 doc/docs/en/integration/index.md，中文入口见 doc/docs/zh/integration/index.md）：

文档结构上，接入方向分为 Overview、MCP、Skills、Agents 四个页面，导出方向分为 Overview、Agent Export、Agent Publishing、Northbound API 四部分（英文侧实际可读页面位于 doc/docs/en/integration/integration-in/ 下的 overview.md、mcp.md、skills.md、agents.md）。

快速决策路径：目标是接入外部资源时——MCP 走「准备服务 → 选择接入方式 → 配置并测试 → 配置给智能体」；Skill 走「选择接入方式 → 准备技能内容 → 上传或生成 → 配置给智能体」；Agent 走「发现外部 Agent → 配置调用协议 → 设为协作智能体」。目标是导出平台能力时——「导出 Agent 配置」选择导出 JSON/ZIP 后导入到其他 Nexent 部署；「普通发布」发布后生成 API Key 再调用北向 API；「发布为 A2A Agent」发布时勾选 A2A 选项后获取调用信息。

接入外部 MCP 服务

MCP（Model Context Protocol）是 AI 工具的标准通信协议。Nexent 支持三种接入方式：远程链接（Remote URL）、容器部署（Container）与API 转 MCP（API-to-MCP）。

方式一：远程链接接入

适用于独立部署的 MCP 服务（如 ModelScope 提供的服务）。操作路径为MCP 仓库 → 我的 MCP，点击「添加 MCP 服务」并将接入类型选为「远程」后填写：

填写后点击「连通性测试」确认服务可达，再保存完成添加。以 ModelScope GitHub MCP 为例，其最小配置形如：

{ "name": "modelscope-github", "url": "https://api.modelscope.cn/mcp/servers/github", "headers": {} }

从后端模型看，「远程」与「容器」两类配置分别由 backend/consts/model.py 中的MCPServerConfig（含command、args、env、port、image字段）与MCPConfigRequest（mcpServers字典）承载；更新 MCP 服务时通过MCPUpdateRequest携带新旧服务名与 URL、可选的新授权令牌及custom_headers。服务实际以流式 SSE 方式对外提供，后端在 backend/mcp_service.py 中同时启动管理 API（端口 5015）与租户级 SSE 应用（/mcp/{tenant_id}/sse，端口 5011）。

方式二：容器接入

适用于以 Docker 容器运行的 MCP 服务（如通过 npx 启动的服务）。同样在「添加 MCP 服务」中选择「容器」，填写容器配置 JSON 与容器端口号：

{ "mcpServers": { "service-name": { "command": "npx", "args": ["-y", "@modelScope/mcp-server-package@version"] } } }

保存后系统会自动启动容器并完成配置。端口说明：Docker/Kubernetes 部署下容器端口由系统自动分配；本地部署时使用推荐端口或手动指定可用端口。实现上，MCPServerConfig.port用于指定宿主机暴露端口（例如 5020），image可覆盖默认的 MCP 代理容器镜像；配置导入与运维逻辑位于 backend/services/mcp_management_service.py，其会依据配置 JSON 是否为空判定传输类型（"container"或"url"）。删除容器类服务时，系统会同时清理对应容器。

方式三：API 转 MCP

这是 Nexent 提供的免写 MCP Server 代码的转换能力，适用于以下场景：企业已有 REST API 希望快速赋予智能体调用能力、第三方服务只有 HTTP API 而无 MCP 适配器、需要快速原型验证。操作路径为智能体开发 → MCP 配置，选择「API to MCP」后填写：

支持的 OpenAPI 3.x 特性包括：GET/POST/PUT/DELETE 方法、Path/Query/Header 三类参数、JSON 格式的请求体，以及 Bearer Token、API Key（Query/Header）、Basic Auth 等认证方式。下面是一个内部工单系统转 MCP 的完整示例：

{ "openapi": "3.0.0", "info": {"title": "Ticket System", "version": "1.0.0"}, "paths": { "/tickets": { "get": { "summary": "Get ticket list", "parameters": [ {"name": "status", "in": "query", "schema": {"type": "string"}} ] }, "post": { "summary": "Create ticket", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "title": {"type": "string"}, "description": {"type": "string"} } } } } } } } } }

转换完成后，智能体即可通过自然语言调用这些接口（例如「查询所有待处理工单」）。从代码上看，此类由平台转换出的服务在 backend/mcp_service.py 中以owner="api-to-mcp"标识，说明其由管理线程独立托管、与其他来源的服务区分管理。

管理接入的 MCP 服务

每个服务卡片展示四种状态：已启用（决定工具是否出现在智能体工具选择中）、审核中（等待管理员审批的发布申请）、已发布（在同租户仓库内共享）、已拒绝（发布申请未通过）。常用操作包括编辑配置、连通性测试、申请发布共享给同租户成员、删除（容器服务会同步清理容器）。

在智能体中调用 MCP 工具

1. 进入智能体开发页；
2. 在「选择智能体工具」中切换到MCP标签；
3. 找到已添加的 MCP 服务并展开查看工具列表；
4. 勾选所需工具并配置必要参数；
5. 保存智能体配置。

分配工具时可通过工具卡片上的「测试」按钮验证：填写测试参数 → 点击「执行测试」→ 查看返回结果。

最佳实践：安全上应使用平台密钥管理能力、避免 Token 明文落盘、遵循最小权限原则并定期轮换 API Key；性能上要确保 MCP 服务稳定（避免拖慢智能体响应）、为耗时操作设置合理超时、善用工具测试提前暴露问题；维护上要跟踪服务版本更新、监控调用日志、记录服务依赖关系。

FAQ：连接失败时依次排查服务 URL 可达性、网络与防火墙、认证信息、服务运行状态；API-to-MCP 当前支持 Bearer Token、API Key（Query/Header）、Basic Auth；如需自研 MCP 服务可参考仓库中的 MCP 工具开发文档（backend/tool_collection/mcp/ 下有相关实现）。

接入第三方 Skill 技能

Skill 是 Nexent 扩展智能体能力的核心机制，支持两种接入方式：上传 SKILL.md（单文件、适合简单场景）与上传 ZIP 包（多文件、可携带脚本与资源）。

单文件技能（.md）

文件要求：文件名为SKILL.md（也可使用任意文件名）、UTF-8 编码、必须包含带name与description必填字段的 YAML Front Matter。基本结构如下：

--- name: csv-analyzer description: | Analyze CSV files and generate>--- name: skill-name # 必选：技能名（仅限英文小写、连字符分隔） description: | # 必选：功能描述（建议 1-3 句、第三人称） A description that explains what this skill does and when it should be used. Recommended to write in the third person. tags: # 可选：标签列表 - tag1 - tag2 ---

参数定义（config/schema.yaml）：需要用户填参时创建，支持string、number、boolean、array、object类型：

query: type: string required: true description: "Search query string" description_zh: "Search keyword" default: "" top_k: type: number required: false description: "Number of results to return" description_zh: "Number of returned results" default: 3

参数默认值（config/config.yaml）：

# Initial working path init_path: "/mnt/nexent" # Maximum number of returned items top_k: 5

特殊标签：

<reference path="examples.md" />

<reference>：按需加载技能包内文件。

<use_script path="scripts/analyze.py" />

<use_script>：声明技能包内捆绑的脚本。

<code> result = run_skill_script( "csv-analyzer", "scripts/analyze.py", {"--file": "/path/to/data.csv"} ) </code>

<code>：展示代码示例。

辅助函数：run_skill_script(skill_name, script_path, params)执行技能包内脚本；read_skill_md(skill_name, files)读取技能包内文件。这两者在源码层面是注入智能体的内置工具：见 backend/agents/create_agent_info.py 中的RunSkillScriptTool（在 Docker 沙箱内执行技能捆绑脚本或运行工作区脚本，禁止通过subprocess/os.system等 shell 调用）与ReadSkillMdTool（总是先读 SKILL.md，再按需读附加文件）；此外还有读取config.yaml的ReadSkillConfigTool，返回技能工作流所需的配置变量。

在智能体中使用 Skill

1. 进入智能体开发页；
2. 在「选择智能体工具」中切换到Skills标签；
3. 点击「选择技能」，找到目标技能；
4. 若有必填参数则配置后保存。

Skill 与 Tool 的区别：Tool 是单个原子操作、每次对话都会消耗上下文 Token、参数 schema 固定、以代码级分发；Skill 是「多工具 + 配置 + 文档」的组合、仅在激活时加载（节省 Token）、参数模板可定制、以 ZIP 包形式即插即用地分发。

FAQ：ZIP 上传报「Missing SKILL.md」时，确认SKILL.md位于 ZIP 根目录而非子目录；技能描述不生效时，确认描述写在 YAML Front Matter 的description字段而非 Markdown 正文。

通过 A2A 协议接入外部 Agent

A2A（Agent-to-Agent）是面向不同平台、不同技术栈 AI 智能体互操作性的开放协议，提供标准化通信（统一的发现与调用机制）、能力抽象（无需了解彼此实现细节即可声明能力）与跨平台协作能力。

A2A 核心概念

Nexent 支持两种外部 A2A Agent 发现方式：URL 发现（已知 Agent Card 地址时使用）与Nacos 发现（批量发现注册在 Nacos 的 Agent）。

方式一：URL 发现

一个符合 A2A 1.0 规范的 Agent Card 示例：

{ "name": "data-analysis-agent", "description": "Professional data analysis assistant that can perform statistical analysis, generate charts, and interpret data trends", "url": "https://agent.example.com/nb/a2a/agent-123", "version": "1.0.0", "capabilities": { "streaming": true, "pushNotifications": false }, "skills": [ { "id": "statistical-analysis", "name": "Statistical Analysis", "description": "Perform descriptive and inferential statistics" }, { "id": "chart-generation", "name": "Chart Generation", "description": "Generate various types of charts based on data" } ], "endpoints": { "http": "https://agent.example.com/nb/a2a/agent-123" } }

操作步骤：进入智能体开发 → 协作智能体页 → 在「外部 A2A Agent」标签下点击「添加外部 Agent」→ 选择「URL 发现」标签 → 填入 Agent Card 地址（如https://example.com/.well-known/agent.json）→ 如需认证则填写自定义请求头（JSON 格式）→ 点击「发现」→ 核对返回的 Agent 信息 → 点击「添加到列表」。

{"Authorization": "Bearer <token>"}

注意事项：自定义请求头仅用于获取和刷新 Agent Card，不用于后续调用；对同一 URL 重新发现时留空会保留现有配置，填{}则会清空。

从源码看，Agent Card 的解析模型对应 backend/consts/a2a_models.py 中的A2AAgentCard：包含capabilities（streaming、pushNotifications）、skills列表、supportedInterfaces（多协议端点，协议绑定支持http-json-rpc、rest、grpc）、url（http-json-rpc 回退字段）、securitySchemes/securityRequirements（安全声明）等；外部 Agent 通常在/.well-known/agent-{id}.json提供该卡片。URL 发现接口DiscoverFromUrlRequest（backend/apps/a2a_client_app.py）携带url、可选显示名覆盖name与仅用于发现/刷新的custom_headers。

方式二：Nacos 发现

在「外部 A2A Agent」标签下选择「Nacos 发现」，首次使用需配置连接信息：

保存配置后填入要扫描的 Agent 服务名，点击「扫描」从 Nacos 获取匹配的 Agent 列表，勾选所需 Agent 后点击「添加」。前置条件：Nacos 服务正常运行、目标 Agent 已正确注册到 Nacos、服务元数据中包含 Agent Card 地址。对应接口见 backend/apps/a2a_client_app.py，DiscoverFromNacosRequest引用已保存的 Nacos 配置并按服务名批量发现，TestNacosConnectionRequest则用于不落库的连接性测试。

管理发现的外部 Agent

• 查看详情：点击 Agent 卡片查看名称、描述、版本、URL 端点、能力列表（Skills）与调用协议支持；
• 测试：点击「测试」向 Agent 发送测试消息验证其工作正常；
• 聊天：点击「聊天」打开聊天窗口进行实时交互验证；
• 配置调用协议：通过「协议配置」选择调用协议——HTTP + JSON（REST 风格调用，通用场景优先）或JSON-RPC（JSON-RPC 2.0 标准化 RPC 调用，仅在 Agent 明确要求时使用）；
• 配置认证：若 Agent Card 声明了securitySchemes，可点击「Agent 认证」填写认证信息，支持 Bearer Token、API Key（Header/Query）、Basic Auth；
• 刷新：Agent 信息变更后点击「刷新」重新获取最新 Agent Card；
• 移除：从发现列表中删除该 Agent。

设为协作智能体

发现并配置外部 Agent 后即可将其设为当前智能体的协作方：在智能体开发页进入「协作智能体」配置 → 在「外部 A2A Agent」列表中选择目标 Agent → 确认出现在「已选协作智能体」列表 → 保存配置。协作调用示意：主智能体分析任务后决定调用「数据分析 Agent」做统计计算、调用「图表生成 Agent」生成可视化、再综合结果产出最终报告。

实例：接入 DataAgent A2A Agent

以支持 A2A 协议的 DataAgent 平台为例：先按其文档以 A2A 服务模式启动（注意：当前 Nexent 暂不支持带认证的 Agent，启动时不要设置 auth-token）；启动后其 Agent Card 地址为http://<IP>:9999/.well-known/agent-card.json；在 Nexent 中选择「URL 发现」填入该地址并点击「发现」，添加成功后把调用协议配置为 HTTP + JSON；最后测试 Agent 响应、确认正常后设为协作智能体使用。

FAQ：发现失败时依次确认 Agent Card URL 可达、网络与防火墙、Agent 服务运行状态、认证信息正确；调用协议选择上 HTTP + JSON 兼容性更好、是多数场景首选，JSON-RPC 仅在 Agent 明确要求时使用；开发符合 A2A 规范的 Agent 可参考 Nexent 自身的 A2A 实现（如 backend/services/a2a_server_service.py 与 backend/consts/a2a_models.py）。

导出平台能力

除接入外部资源外，Nexent 还支持把平台内资源导出给外部系统，三种方式均围绕 Agent 展开：

操作速查：导出 Agent 配置= 选择 Agent → 导出 JSON/ZIP → 导入到其他 Nexent 部署；普通发布= 发布 Agent → 生成 API Key → 调用北向 API；发布为 A2A Agent= 发布 Agent → 勾选 A2A 选项 → 获取调用信息。北向 RESTful API 的详细参数参考对应「调用 Agent 北向 API」文档，后端实现可查阅 backend/apps/northbound_app.py 与 backend/apps/northbound_base_app.py。

相关资源与获取帮助

接入前可先阅读 Agent 开发指南 了解如何创建和配置智能体，以及 MCP 生态（doc/docs/en/mcp-ecosystem/overview）；接入过程中如需深入底层原理，可在 backend/services/mcp_management_service.py、backend/apps/a2a_client_app.py、backend/agents/create_agent_info.py 等处继续追踪。遇到集成问题可通过仓库的 GitHub Discussions 提问、GitHub Issues 报告问题，或加入 Discord 社区与成员交流。

• AI Agent
• AI 应用
• 后端
• 前端
• 大模型
• RAG