企业官网建设流程全解析

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

Agent 开发完成之后，如何让外部业务系统稳定、安全地调用它，是 Agent 工程落地的关键一环。Nexent 为此提供了两条对外发布通道：通过 Northbound RESTful API 进行常规发布，实现与业务系统的深度集成与工作流自动化；或发布为符合 A2A 1.0 协议的 Agent，实现跨平台 Agent 协作。本文将围绕 Agent Publishing 文档，完整讲解两种发布方式的步骤、鉴权、调用示例与版本管理，并结合仓库后端源码剖析其实现原理，帮助你在一线生产环境中正确完成 Agent 的上线发布与外部调用。

一、发布方式总览

Nexent 将平台上开发的 Agent 以"对外可调用服务"的形式发布出去，外部系统即可通过标准化方式与 Agent 集成。当前支持两种发布方法：

两种发布方式并不互斥：发布时既可以启用默认的 Northbound RESTful API，也可以同时勾选"发布为 A2A Agent"，让同一个 Agent 同时支持两种调用方式，具体可参考 Integration-Out 概览。

从后端实现看，两种通道统一承载在同一个北向应用中。在 northbound_base_app.py 中，northbound_app同时挂载了前缀为/nb/v1的常规北向路由（northbound_router）与前缀为/nb/a2a的 A2A 路由（a2a_router），说明两条通道在服务层面是共存的。

二、方式一：常规发布（Northbound RESTful API）

常规发布将 Agent 发布到平台，外部业务系统通过 Nexent 北向 RESTful API 与 Agent 通信，支持流式响应、附件上传和会话管理。

2.1 发布步骤

1. 进入Agent 开发页面，创建或编辑 Agent；
2. 完成 Agent 配置并保存；
3. 点击发布按钮；
4. 确认默认发布（不勾选 A2A 选项）；
5. 确认发布，生成 API Key 后即可开始调用。

2.2 获取 API Key

发布成功后，需要为调用方生成 API Key：

1. 登录 Nexent 平台；
2. 进入个人信息页面；
3. 点击生成 API Key；
4. 复制生成的 Access Key。

从源码看，API Key 的完整生命周期管理由 api_key_service.py 承担，它提供了create_api_users_batch（批量创建）、refresh_user_api_key（刷新密钥）、revoke_user_api_keys（吊销密钥）和list_tenant_api_keys（密钥列表）等能力，对应的北向接口位于 northbound_app.py：POST /nb/v1/api-users/batch、POST /nb/v1/api-keys/refresh、DELETE /nb/v1/api-keys。生产环境中建议为不同业务系统分配独立密钥，便于按调用方审计与吊销。

2.3 调用示例

curl -X POST "https://your-nexent-domain.com/nb/v1/chat/run" \ -H "Authorization: Bearer your-access-key-here" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "general-assistant", "query": "Hello, please introduce yourself" }'

2.4 /chat/run 请求参数详解

/nb/v1/chat/run是启动对话的核心接口，返回 SSE 流式响应。其完整请求体定义可在 northbound_app.py 中查到，除agent_name与query两个必填参数外，还支持以下可选参数：

其中tool_params用于在单次请求中覆盖工具默认参数，其结构与合并规则如下（详见 northbound-api.md）：

{ "agents": { "<agent_name>": { "tools": { "<tool_name>": { "<param_name>": "<param_value>" } } } } }

合并规则：请求参数优先级高于数据库持久化参数；工具匹配先按tool.name、再按tool.class_name；传入不支持的参数名会返回400 ValidationError；vdb_core、embedding_model等元数据派生字段会自动基于合并后的参数重新计算。例如为common_sense_qa_assistant的知识库检索工具临时调高top_k、开启rerank：

curl -X POST "https://your-nexent-domain.com/nb/v1/chat/run" \ -H "Authorization: Bearer your-access-key-here" \ -H "Content-Type: application/json" \ -d '{ "agent_name": "common_sense_qa_assistant", "query": "Summarize this document", "attachments": ["s3://nexent/attachments/user123/doc.pdf"], "tool_params": { "agents": { "common_sense_qa_assistant": { "tools": { "analyze_text_file": {"chunk_size": 4000, "summary_only": true}, "knowledge_base_search": { "top_k": 10, "rerank": true, "rerank_model_name": "gte-rerank-v2", "index_names": ["nexent-docs", "faq-index"] } } } } } }'

/chat/run还会透传可选请求头Idempotency-Key用于防止重复提交；对携带enable_hitl、hitl_run_id、hitl_after_event等遗留字段的请求会直接返回400（历史 HITL 相关引擎已移除）。

2.5 流式响应格式

/nb/v1/chat/run返回 SSE（Server-Sent Events）流，Agent 的输出以分块形式实时到达：

data: {"type":"model_output_thinking","content":"Analyzing data","unit_index":1} data: {"type":"model_output_thinking","content":", please wait...","unit_index":1} data: {"type":"final_answer","content":"Analysis complete","unit_index":2}

当 Agent 需要澄清关键信息时，会返回type为human_interaction的结构化澄清事件，其content为 JSON 对象（schema_version: 1与questions数组），同时final_answer会附带可读的问题文本作为回退。最多 5 个问题，支持text、single_choice、multiple_choice三种题型。客户端应在当前流结束后，把答案作为同会话的普通新查询发送，无需任何能力切换或恢复接口。

2.6 API 能力概览

此外，northbound_app.py 还提供了GET /nb/v1/agents（Agent 列表）、GET /nb/v1/agents/{agent_name}（按名称查询已发布 Agent）、GET /nb/v1/agents/{agent_name}/knowledge-bases（Agent 可用知识库）与GET /nb/v1/models（租户已配置模型）等发现类接口，便于调用方在集成前获取 Agent 元信息。

附件上传（POST /nb/v1/chat/attachments/upload）以multipart/form-data提交多个files字段，返回可复用的s3_url引用；该s3_url随后作为/chat/run的attachments字段值使用。实现层面，上传与附件 URL 校验逻辑位于 northbound_service.py，它同时兼容s3://URL、/nexent/路径和相对路径三种附件引用格式，并会调用validate_urls_access做访问权限校验。

2.7 本地开发路径前缀

三、方式二：A2A 发布

A2A 发布将已发布的 Agent 暴露为 A2A 服务，外部系统通过 A2A 1.0 协议发现并调用它，适用于跨平台 Agent 协作场景。

3.1 发布步骤

1. 进入Agent 开发页面，创建或编辑 Agent；
2. 完成 Agent 配置并保存；
3. 点击发布按钮；
4. 在发布选项中勾选发布为 A2A Agent；
5. 确认发布。

3.2 获取调用信息

发布成功后，系统会展示 A2A Agent 的调用信息：

从实现看，Endpoint ID 的生成规则为a2a_{agent_id}_{uuid4().hex[:8]}，见 a2a_server_service.py。外部系统可在 Agent 列表通过左侧最前端的图标查看具体调用信息（完整指南见 Publish as A2A Agent）。

3.3 REST 调用示例

# 获取 Agent Card（用于 Agent 发现） GET /nb/a2a/{endpoint_id}/.well-known/agent-card.json # 发送同步消息 POST /nb/a2a/{endpoint_id}/message:send Content-Type: application/json { "message": { "role": "user", "content": "Please help me analyze this sales data" } } # 发送流式消息（SSE） POST /nb/a2a/{endpoint_id}/message:stream Content-Type: application/json { "message": { "role": "user", "content": "Please help me analyze this sales data" } } # 查询任务状态 GET /nb/a2a/{endpoint_id}/tasks/{task_id}

3.4 JSON-RPC 2.0 调用示例

POST /nb/a2a/{endpoint_id}/v1 Content-Type: application/json { "jsonrpc": "2.0", "method": "SendMessage", "params": { "message": { "role": "user", "content": "Please help me analyze this sales data" } }, "id": 1 }

JSON-RPC 端点还支持SendStreamingMessage（流式消息，返回 SSE）与GetTask（查询任务）方法。方法分发与错误码映射实现在 northbound_base_app.py 中，协议级错误码包括：-32601（方法不存在 / 端点不存在）、-32603（内部错误）、-32001（任务不存在）、-32004（不支持的操作，如任务已终止）。

3.5 Agent Card 结构与缓存

A2A 发现机制的核心是 Agent Card。根据 A2A 1.0 规范，外部系统通过GET /nb/a2a/{endpoint_id}/.well-known/agent-card.json获取。Agent Card 的模型定义位于 a2a_models.py，包含name、description、version、provider、capabilities、skills、supportedInterfaces、securitySchemes等字段；其中capabilities通过A2AAgentCapabilities描述是否支持流式、推送通知、状态迁移报告与产物（artifacts），supportedTransportTypes支持http-streaming与http-polling。

Card 的实际组装逻辑在 a2a_server_service.py：supportedInterfaces会生成两个协议绑定端点——{base}/nb/a2a/{endpoint_id}/v1（JSON-RPC）与{base}/nb/a2a/{endpoint_id}（REST）；skills由 Agent 配置自动生成（默认提供chat技能）。发布时的card_overrides可以对 Card 字段做部分覆盖定制。

关于缓存：Agent Card 端点响应带Cache-Control: public, max-age=3600与基于内容 MD5 的ETag（支持If-None-Match返回 304），见 northbound_base_app.py。Card 信息默认缓存 1 小时，如果需要立即生效，需重新发布 Agent。

3.6 A2A 调用链路与任务模型

A2A 调用不是简单的消息转发：协议层消息会先经过 a2a_agent_adapter.py 做格式转换（A2Aparts结构 → 内部query/history，ROLE_USER/ROLE_AGENT→ 内部user/assistant），再由a2a_server_service通过forward_agent_run转发给运行时执行。携带taskId、contextId或history的复杂请求会创建持久化 Task（TASK_STATE_*状态机），简单请求则直接返回；任务与消息的持久化由 a2a_agent_db.py 完成。流式场景下，Agent 运行事件会被逐条封装为 A2A JSON 数据 Part（application/json）经 SSE 下发。

3.7 本地开发路径前缀

• Docker 部署：将路径前缀/nb/a2a替换为http://localhost:5013/nb/a2a
• Kubernetes 部署：将路径前缀/nb/a2a替换为http://localhost:30013/nb/a2a
• 生产环境：替换为实际服务器域名或公网 IP 地址

四、认证与安全

4.1 调用鉴权

两种发布方式的调用都要求在请求头携带认证信息：

Authorization: Bearer {access_key}

access_key通过平台个人信息页面中的"生成 API Key"获取。鉴权处理在 northbound_app.py 的_get_northbound_context中统一完成：校验 Bearer Token 后，通过get_user_and_tenant_by_access_key从 access_key 解析出user_id、tenant_id与token_id；可选请求头X-Request-Id用于链路追踪（未提供时自动生成）。同时，接口会调用log_token_usage记录每次 API Key 的调用（/chat/run、/chat/stop、会话标题更新等计入用量），便于用量审计；超过限流阈值会返回429 Too Many Requests。

4.2 常见错误码

4.3 安全建议

1. 保护 API Key：不要硬编码在代码中，定期轮换；
2. 限制访问：只授权可信系统访问调用端点；
3. 监控日志：开启调用日志记录以便审计；
4. 数据隔离：注意不要向不受控的调用方发送敏感数据。

五、版本管理

5.1 发布版本

• Agent 可发布多个版本，每次发布都会生成一个新版本；
• 已发布版本不可修改，从而保证调用方获得一致的体验。

5.2 版本更新

1. 修改 Agent 配置；
2. 发布新版本（按需选择发布方式）；
3. 外部系统可通过新的 Agent Card 获取更新（A2A 场景）。

从源码看，平台维护了"已发布 Agent"的独立视图：list_published_agents_impl位于 agent_version_service.py，北向接口正是基于该视图校验并定位已发布 Agent，确保只有已发布版本才对外可见、未发布草稿不可被外部调用。

5.3 Agent Card 缓存

• Agent Card 信息会被缓存（A2A 场景），刷新间隔为 1 小时；
• 如需立即更新，请重新发布 Agent。

六、常见问题（FAQ）

Q：常规发布与 A2A 发布可以同时启用吗？

可以。发布时既可以启用默认的 Northbound RESTful API，也可以同时勾选"发布为 A2A Agent"，让 Agent 同时支持两种调用方式。

Q：A2A 调用返回 401 错误？

确认请求头包含有效的Authorization字段，且access_key正确。

Q：如何更新已发布的 A2A Agent？

重新发布 Agent 版本，更新后的信息会通过刷新的 Agent Card 对外暴露（注意 1 小时的 Card 缓存周期）。

Q：详细的 Northbound API 参数在哪里查看？

参见 Northbound API，其中包含完整的 API 参数、请求/响应示例与错误码。

七、相关资源

• Publish as A2A Agent —— 发布与调用 A2A Agent 的完整指南
• Northbound API —— Northbound RESTful API 详细参考
• Agent Export —— Agent 配置导出（JSON/ZIP）
• Agent Configuration —— Agent 配置详情
• Integration-Out 概览 —— 导出/发布方式对比与流程总览

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