前言在前面的文章中我们介绍了单Agent模式的智能体创建与编排。然而在实际业务场景中智能体往往需要与外部服务进行交互——查询天气、预订酒店、处理支付等。本期文章将详细介绍A2AAgent-to-Agent模式这是鸿蒙智能体平台对外提供能力的关键模式。A2A模式允许开发者搭建自己的API服务让小艺智能体通过标准协议调用你的服务端能力。相较于单Agent模式的开箱即用A2A模式更灵活、可扩展适合需要集成三方服务或自有业务逻辑的场景。A2A是Google在2025年提出的开放智能体通信协议标准鸿蒙智能体平台在兼容该标准的基础上针对鸿蒙生态进行了深度适配和扩展。一、A2A协议概述1.1 协议起源与发展A2AAgent-to-Agent是Google在2025年提出的开放智能体通信协议旨在解决不同厂商构建的智能体之间无法互通的**孤岛问题**。它提供了一套标准的通信语言让智能体之间可以安全地交换信息、协调任务。核心设计理念基于JSON-RPC 2.0请求和响应采用标准化的JSON格式易于理解和实现单一端点所有方法通过/agent/message统一路由结构清晰会话管理内置Session机制支持多轮对话鉴权机制支持基于密钥的身份验证保证接口安全流式输出通过SSE协议支持实时结果推送1.2 鸿蒙A2A与Google A2A对比鸿蒙A2A在兼容Google A2A协议的基础上增加了鸿蒙生态特有的能力对比维度Google A2A鸿蒙A2A基础协议JSON-RPC 2.0 SSEJSON-RPC 2.0 SSE端点设计单一Endpoint单一Endpoint/agent/message会话模式基于session两种模式session模式/无session模式认证方案Bearer TokenAK/SK、API Key、OAuth多种流式类型message/streammessage/stream 增强artifact-update端侧能力不支持端侧插件、端侧指令、设备上下文授权机制标准OAuth华为账号一键授权登录特殊消息标准类型增加reasoningText、data等多种Part类型鸿蒙A2A在兼容Google标准的基础上重点强化了端云协同和账号授权能力这是鸿蒙生态的核心优势。二、A2A智能体架构2.1 三大核心角色A2A模式下智能体的工作涉及三个核心角色上图展示了A2A模式下智能体的整体架构和调用逻辑。小艺开放平台负责智能体的元数据注册和认证配置。开发者在平台上创建智能体时需要配置API URL、认证信息等元数据平台将这些信息注册到智能体执行引擎。智能体执行引擎平台的运行时核心负责智能体的规划澄清、路由分发和编排调度。当用户发起对话时执行引擎通过A2A协议调用开发者搭建的API服务并将返回的结果通知给智能体。应用智能体服务器开发者自行搭建的API服务接收智能体执行引擎发来的A2A请求处理业务逻辑并返回响应。2.2 整体调用流程完整的调用流程如下用户发起对话用户在设备上与小艺对话触发智能体意图识别智能体执行引擎接管请求进行意图理解和规划协议调用引擎通过A2A协议调用开发者的API服务业务处理开发者服务处理请求返回响应结果展示执行引擎处理结果通知呈现给用户主要特点服务器侧不需要维护长连接支持断线重连基于StreamableHTTP JSON RPC协议支持SSE流式输出首Token即可推送2.3 会话维持机制鸿蒙A2A提供两种会话模式模式一基于session维护状态推荐方案由服务器侧分配agent-session-id类似于MCP的mcp-session-id。客户端每次请求服务器侧时将agent-session-id放在header中带给服务器侧。服务器需要实现initialize和notifications/initialized方法需要对同一AK/SK同时分配多个agent-session-id建议不低于5个可防止多个客户端请求时的凭证吊销间隙问题模式二无session简化版客户端每次请求时都在header中携带认证凭据AK/SK、APIKey等。不需要实现initialize、notifications/initialized方法适用于轻量级场景三、创建智能体3.1 创建步骤进入小艺开放平台点击新建智能体选择**“A2A模式”**填写智能体名称和描述点击创建。创建时需要关注以下配置项配置项说明必填智能体名称智能体的展示名称最多20个字符是智能体描述简要说明智能体功能用于意图匹配是支持的设备和系统默认勾选手机-HarmonyOS NEXT和手机-HarmonyOS否模式选择选择A2A模式是3.2 配置开场对话智能体创建成功后需要配置开场对话和预置引导让用户快速了解智能体的功能开场语示例 你好我是你的智能助手可以帮你查询信息、处理任务。 预置问题示例 1. 你能帮我做什么 2. 如何开始使用 3. 查询我的订单核心配置要点开场语用户首次进入时的欢迎语建议简洁明了预置问题推荐给用户的3-5个常用问题帮助用户快速上手对话示例可选配置展示典型交互场景四、A2A基础配置基础配置是A2A模式的关键步骤必须完成此节点配置否则无法正常发布智能体。4.1 API URL配置服务端API地址格式如下https://your-domain.com/agent/message注意事项必须是公网可访问的HTTPS地址统一使用/agent/message作为端点支持自定义域名或IP地址推荐使用域名4.2 会话维持方式维持方式说明适用场景服务器侧分配Session服务器通过initialize方法分配agentSessionId推荐方案功能完整不维持Session每次请求携带认证凭据轻量级场景简化开发4.3 认证信息平台支持多种认证方式认证方式说明安全等级Access Key / Secret Key对称密钥认证高API Key单一密钥认证中OAuth 2.0标准授权协议高无认证不进行接口认证低不推荐设置Access Key和Secret Key后鸿蒙智能体调用时会携带认证信息用于服务端验证// 请求Header示例POST/agent/message Content-Type:application/jsonAuthorization:Beareraccess_keyagent-session-id:session_id4.4 方法声明在配置中声明支持的A2A方法让执行引擎知道你的服务器支持哪些操作方法说明是否必须initialize初始化会话推荐notifications/initialized通知初始化完成推荐message/stream流式消息处理是tasks/cancel取消任务否clearContext清理对话上下文否4.5 账号登录授权如果你的服务需要识别用户身份需要配置华为账号登录授权在华为开发者联盟申请appId在小艺开放平台注册appId配置用户授权回调地址用户在智能体内点击账号授权后流程如下已授权用户静默发起授权服务器返回新的agentLoginSessionId未授权用户弹框获取授权服务器基于华为账号授权码获取用户手机号后续请求携带agentLoginSessionId字段进行身份识别提示agentLoginSessionId超期失效后小艺APP会自动重新发起授权流程从服务器获取新的ID。五、A2A协议方法详解5.1 Initialize - 初始化会话initialize是A2A协议的第一个调用方法用于建立服务器之间的通信连接。// 请求POST/agent/message Content-Type:application/json{jsonrpc:2.0,id:msg-001,method:initialize}// 响应{jsonrpc:2.0,id:msg-001,result:{version:1.0,agentSessionId:8f01f3d172cd4396a0e535ae8aec6687,agentSessionTtl:604800},error:{code:0,message:success}}关键字段说明agentSessionId服务器返回的唯一会话标识符后续请求在header中携带agentSessionTtl会话有效期秒一般建议设置为7天604800秒5.2 Notifications/Initialized - 通知初始化完成初始化完成后客户端通知服务器准备就绪POST/agent/message Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{jsonrpc:2.0,id:msg-002,method:notifications/initialized}提示此方法HTTP返回200状态码即可无需响应体。5.3 Message/Stream - 流式消息处理核心的消息处理方法兼容Google A2A的message/streamPOST/agent/message Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{jsonrpc:2.0,id:msg-003,method:message/stream,params:{id:task-001,sessionId:session-001,message:{role:user,parts:[{kind:text,text:你好请帮我查询今天的天气}]}}}服务器通过SSE协议返回流式响应包含submitted状态表示请求已接收working状态正在处理中artifact-update输出处理结果completed状态任务完成5.4 Tasks/Cancel - 取消任务取消正在执行的任务POST/agent/message Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{jsonrpc:2.0,id:msg-004,method:tasks/cancel,params:{id:task-001}}5.5 ClearContext - 清理上下文清理当前对话的上下文信息POST/agent/message Content-Type:application/json agent-session-id:8f01f3d172cd4396a0e535ae8aec6687{jsonrpc:2.0,id:msg-005,method:clearContext,params:{sessionId:session-001}}方法用途是否需要Sessioninitialize初始化通信连接否notifications/initialized通知初始化完成是message/stream发送消息并获取流式响应是tasks/cancel取消正在执行的任務是clearContext清理对话上下文是六、协议整体交互流程完整的A2A协议交互时序如下阶段一初始化 客户端 服务器 |-- initialize ------------------| |-- agentSessionId TTL --------| |-- notifications/initialized ---| |-- 200 OK ----------------------| 阶段二消息处理可多次 |-- message/stream ---------------| |-- SSE: status-update(submitted)-| |-- SSE: status-update(working) --| |-- SSE: artifact-update(text) ---| |-- SSE: status-update(completed)-| 阶段三任务控制可选 |-- tasks/cancel -----------------| |-- status: canceled -------------| |-- clearContext ------------------| |-- status: cleared --------------|提示每个阶段可以在一个会话生命周期内多次执行message/stream支持并发多个任务。七、A2A 接口安全加固7.1 认证中间件示例以下是一个简单的 Bearer Token 校验中间件可集成到 FastAPI 服务中fromfastapiimportHTTPException,Headerasyncdefverify_bearer(auth:strHeader(...,aliasauthorization)):ifnotauth.startswith(Bearer ):raiseHTTPException(status_code401,detailMissing Bearer token)tokenauth.replace(Bearer ,)iftoken!EXPECTED_TOKEN:raiseHTTPException(status_code401,detailInvalid token)7.2 安全实践建议使用 HTTPS生产环境必须配置 SSL/TLS避免明文传输认证信息。密钥轮换定期更换 Access Key / Secret Key降低泄露风险。最小权限原则为每个智能体只分配必要的接口权限。八、A2A 开发常见问题8.1 初始化失败排查确认/agent/message端点公网可访问检查响应是否包含agentSessionId和agentSessionTtl确认initialize方法返回的 JSON-RPC 2.0 格式正确8.2 流式输出中断检查 Nginx/网关是否支持 SSE 长连接确认未在响应完成前设置final: true查看服务端日志定位异常提示建议在本地先用curl完成一轮完整的 initialize → message/stream 调用再接入真机测试。总结本文详细介绍了鸿蒙A2A模式智能体的创建和基础配置A2A协议概述了解协议起源、核心设计理念以及鸿蒙A2A与Google A2A的差异智能体架构理解小艺开放平台、智能体执行引擎、应用服务器三大角色的协作关系创建配置流程从创建智能体到基础配置的完整步骤A2A基础配置API URL、会话维持方式、认证信息、方法声明等核心配置协议方法详解initialize、notifications/initialized、message/stream等5种方法A2A模式是鸿蒙智能体对外提供能力的关键模式掌握本文内容你就能搭建自己的智能体服务。下一篇我们将从零编写一个A2A API服务通过代码实现鉴权、会话分配和消息处理等核心流程。如果这篇文章对你有帮助欢迎点赞、收藏⭐、关注你的支持是我持续创作的动力相关资源鸿蒙Agent通信协议技术规范总览 - 华为开发者联盟鸿蒙Agent通信协议消息指令定义 - 华为开发者联盟A2A基础配置参数详情 - 华为开发者联盟Google A2A协议规范JSON-RPC 2.0 规范SSE (Server-Sent Events) 规范华为开发者联盟账号服务 - 申请appId
