ai4j A2A 实现机理（ai4j-agent · a2a 包）

ai4j A2A 实现机理（ai4j-agent · a2a 包） 由 Archify 生成的架构图。 宿主 Agent · ReAct / CodeAct · ai4j 进程 · 客户端角色 · 调用方 宿主 Agent ReAct / CodeAct 调用方 A2ATool · ToolExecutor 包装 · ai4j 进程 · 客户端角色 · a2a A2ATool ToolExecutor 包装 a2a A2AClient · discover · send · SSE · push · ai4j 进程 · 客户端角色 · a2a A2AClient discover · send · SSE · push a2a 外部 Agent（A2A 对端） · 任意 A2A 实现 · 互为客户端/服务端 · 架构组件 外部 Agent（A2A 对端） 任意 A2A 实现 · 互为客户端/服务端 CardHandler · AgentCard · GET /.well-known/* · 双卡缓存 · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） · 无鉴权 CardHandler · AgentCard GET /.well-known/* · 双卡缓存 无鉴权 TaskHandler · JSON-RPC · POST / · 鉴权 → 方法分发 · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） · 鉴权入口 TaskHandler · JSON-RPC POST / · 鉴权 → 方法分发 鉴权入口 workerExecutor · ≤32 线程 · 状态迁移 · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） › 鉴权后内域（X-API-Key / Bearer） · a2a workerExecutor ≤32 线程 · 状态迁移 a2a 内存任务表 A2ATaskRecord · ConcurrentHashMap ≤1024 · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） › 鉴权后内域（X-API-Key / Bearer） · 唯一事实源 内存任务表 A2ATaskRecord ConcurrentHashMap ≤1024 唯一事实源 Agent / AgentSession · run / runStreamResult · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） › 鉴权后内域（X-API-Key / Bearer） · ai4j 运行时 Agent / AgentSession run / runStreamResult ai4j 运行时 SseSink 扇出 · text/event-stream · ≤64 · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） › 鉴权后内域（X-API-Key / Bearer） · 流式 SseSink 扇出 text/event-stream · ≤64 流式 PushNotificationDelivery · ≤16 线程 · 公网 HTTPS · ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） › 鉴权后内域（X-API-Key / Bearer） · 推送 PushNotificationDelivery ≤16 线程 · 公网 HTTPS 推送 外部回调端点（调用方所有） · HTTPS 回调 endpoint · 架构组件 外部回调端点（调用方所有） HTTPS 回调 endpoint AgentToolCall → execute sendTask(message) ① 调用对端 ② 对端发现本端：GET /.well-known/agent-card.json ③ 对端调用本端：POST JSON-RPC registerTask · Get/List/Cancel startTask transition + artifact + latch run / runStreamResult publish statusUpdate / artifactUpdate publish → 回调投递 ④ SSE 回订阅方：data:{task|statusUpdate|artifactUpdate} POST · X-A2A-Notification-Token ai4j 进程 · 客户端角色 ai4j 进程 · A2AServer 服务端角色（JDK HttpServer） 鉴权后内域（X-API-Key / Bearer）

协议面与任务生命周期

  • • 角色对称：A2AClient/A2ATool 调任意对端 Agent；A2AServer 同时被任意 A2A 客户端调用——同一 JSON-RPC 协议面
  • • 方法：SendMessage · SendStreamingMessage · GetTask · ListTasks · CancelTask · SubscribeToTask · PushConfig CRUD
  • • 发现 /.well-known/agent-card.json（回退 agent.json）；别名 /tasks/send · /message:send · /message/send 同步 run 不入任务表
  • • TaskState：SUBMITTED→WORKING→{INPUT|AUTH_REQUIRED}→COMPLETED/FAILED/CANCELED/REJECTED；内存表 ≤1024，CancelTask→future.cancel(true)

事件扇出、推送与限额

  • • SSE：首帧完整 Task 快照（锁内注册防丢帧）→ statusUpdate / artifactUpdate；每任务 ≤64 订阅
  • • Push ≤32 配置/任务：同事件体 POST，X-A2A-Notification-Token + AuthenticationInfo；回调默认仅公网 HTTPS（SSRF 防护）
  • • 线程池 HTTP 64 · worker 32 · callback 16；请求体 / SSE 事件 ≤1MB；A2ATool=远端 Agent→ToolExecutor；A2ASkillMapper→AgentCard.skills