From 20d6a40597cf34f62fa88e2b3ec6c7d5e1095469 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Fri, 4 Sep 2026 14:10:59 +0800 Subject: [PATCH 1/4] docs: add software module view to the design guide Expand the chapter-3 layer diagram into a module view covering Maven modules, package responsibilities, and dependency boundaries: host callbacks, the zero-A2A-T scheduling kernel guarded by the architecture test, the client adaptation layer as the only a2a-t-core reference site, the optional starter server assembly, and external SDKs and systems. Signed-off-by: Zhoujie628 --- docs/en/DESIGN.md | 74 +++++++++++++++++++++++++++++++++++++++++++++++ docs/zh/DESIGN.md | 72 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+) diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index 01e4178d..e99672c9 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -126,6 +126,80 @@ graph TD L0 -.-> F ``` +The layer view expands into the software module view (Maven modules, package responsibilities, and dependency boundaries): + +```mermaid +flowchart TB + subgraph HOST["Host Agent (business application · samples workbench)"] + direction LR + WB["WorkbenchOrchestrator
northbound task intake · workflow selection"] + BIZ["Business callbacks
onTask / onSelfTask / onRoute / onNegotiation"] + GEN["Content generation and validation
calls a2a-t-client directly"] + end + + subgraph KERNEL["workflow-engine scheduling kernel (zero A2A-T dependency, guarded by an architecture test)"] + direction LR + EXE["WorkflowExecutor
DAG validation · parallel dispatch · aggregation"] + CTXB["ContextBuilder
four-mode upstream window selection"] + ADAPT["FailureMapping · ProtocolResultAdapter
failure mapping · transport-to-business result adaptation"] + CP["ControlPoint callback contract
+ EventCallback event outlet"] + MODEL["model layer
workflow definitions · MessageContent · ReceivedMessage"] + end + + subgraph ADAPTER["client protocol adaptation layer"] + direction LR + WEC["DefaultWorkflowEngineClient
task dispatch · negotiation correlation and reply validation"] + EXT["DefaultExtensionSender
authorization / subscription (channels independent of the workflow)"] + TRANS["A2ATransport base
A2A runtime · authentication · SSE event extraction"] + OBSV["WireLog · ProtocolLogger
wire-level observation (redacted · bounded)"] + REGC["LoadPsop · RegistryClient
orchestration-center / registry-center clients"] + MSG["Thin conversion helpers
A2ATExtension · A2atMessages"] + end + + subgraph STARTER["spring-boot-starter (optional · A2A server assembly)"] + direction LR + AUTO["A2AAutoConfiguration
server-side component assembly"] + EP["A2AController
A2A server endpoints"] + end + + subgraph EXTSDK["External SDKs"] + direction LR + A2AJ["a2a-java-sdk
client transports · server handlers · A2A spec types"] + A2ATC["a2a-t-core
extension URIs · MetadataContent · NegotiationContext"] + end + + subgraph SYS["External systems"] + ORCH["Orchestration center (workflow definitions)"] + REGT["Registry center (AgentCards)"] + end + + WB -->|"selects workflow and starts"| EXE + BIZ -.->|"implements"| CP + GEN -->|"generates final message content"| BIZ + EXE -->|"invokes business during scheduling"| CP + EXE --- MODEL + CP --- MODEL + EXE --> CTXB + EXE --> ADAPT + EXE -->|"dispatch / late-result interception"| WEC + WEC --> TRANS + EXT --> TRANS + TRANS --> OBSV + TRANS --> A2AJ + MSG -.->|"only reference site inside the engine"| A2ATC + REGC --> ORCH + REGC --> REGT + AUTO --> EP + EP -->|"RestHandler protocol processing"| A2AJ +``` + +Key properties of the module view: the scheduling kernel (core/control/model packages) references no A2A-T +SDK types — a boundary guarded by the `ContentDependencyBoundaryTest` architecture test. The client +protocol adaptation layer (A2ATExtension, A2atMessages, DefaultWorkflowEngineClient) is the only place +inside the engine that references a2a-t-core. The starter assembles only the A2A server side; the engine +itself is embedded into the host process as a Maven dependency and driven by host code (for example +`ExecutePsop`). + ### 3.1 Layer 0 - Communication A2ATransport uses A2A SDK REST, JSON-RPC and gRPC bindings for authentication, delivery and complete response assembly. diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index ff98787e..5d6832ec 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -115,6 +115,78 @@ graph TD L0 -.-> F ``` +上面是分层视角，展开为软件模块视图（Maven 模块、包职责与依赖边界）： + +```mermaid +flowchart TB + subgraph HOST["宿主智能体（业务应用 · samples 工作台示例）"] + direction LR + WB["WorkbenchOrchestrator
北向任务接收 · 工作流选择"] + BIZ["业务回调实现
onTask / onSelfTask / onRoute / onNegotiation"] + GEN["内容生成与语义校验
直接调用 a2a-t-client"] + end + + subgraph KERNEL["workflow-engine 调度内核（零 A2A-T 依赖，架构测试守护）"] + direction LR + EXE["WorkflowExecutor
DAG 校验 · 并行分发 · 汇总推进"] + CTXB["ContextBuilder
上游窗口四模式选择"] + ADAPT["FailureMapping · ProtocolResultAdapter
失败映射 · 传输态转业务结果"] + CP["ControlPoint 回调契约
+ EventCallback 事件出口"] + MODEL["model 模型层
工作流定义 · MessageContent · ReceivedMessage"] + end + + subgraph ADAPTER["client 协议适配层"] + direction LR + WEC["DefaultWorkflowEngineClient
任务分发 · 协商关联与回复校验"] + EXT["DefaultExtensionSender
授权 / 订阅（独立于工作流的通道）"] + TRANS["A2ATransport 传输基座
A2A 运行时 · 认证 · SSE 事件提取"] + OBSV["WireLog · ProtocolLogger
真实报文观测（脱敏 · 有界）"] + REGC["LoadPsop · RegistryClient
编排中心 / 注册中心客户端"] + MSG["A2atMessages 等薄转换辅助
A2ATExtension · A2atMessages"] + end + + subgraph STARTER["spring-boot-starter（可选 · A2A 服务端装配）"] + direction LR + AUTO["A2AAutoConfiguration
服务端组件装配"] + EP["A2AController
A2A 服务端端点"] + end + + subgraph EXTSDK["外部 SDK"] + direction LR + A2AJ["a2a-java-sdk
客户端传输 · 服务端处理器 · A2A spec 类型"] + A2ATC["a2a-t-core
扩展 URI · MetadataContent · NegotiationContext"] + end + + subgraph SYS["外部系统"] + ORCH["编排中心（工作流定义）"] + REGT["注册中心（AgentCard）"] + end + + WB -->|"选择工作流并启动"| EXE + BIZ -.->|"实现"| CP + GEN -->|"生成最终消息内容"| BIZ + EXE -->|"调度时回调业务"| CP + EXE --- MODEL + CP --- MODEL + EXE --> CTXB + EXE --> ADAPT + EXE -->|"分发 / 晚到结果拦截"| WEC + WEC --> TRANS + EXT --> TRANS + TRANS --> OBSV + TRANS --> A2AJ + MSG -.->|"引擎内唯一引用位置"| A2ATC + REGC --> ORCH + REGC --> REGT + AUTO --> EP + EP -->|"RestHandler 协议处理"| A2AJ +``` + +模块视图要点：调度内核（core/control/model 包）不引用任何 A2A-T SDK 类型，该边界由 +`ContentDependencyBoundaryTest` 架构测试守护；client 协议适配层（A2ATExtension、A2atMessages、 +DefaultWorkflowEngineClient）是引擎内引用 a2a-t-core 的唯一位置；starter 只装配 A2A 服务端组件， +引擎本身以 Maven 依赖形式嵌入宿主进程，由宿主代码（如 `ExecutePsop`）驱动。 + ### 3.1 Layer 0 - 通信层 A2ATransport 使用 A2A SDK 的 REST、JSON-RPC、gRPC 绑定，负责认证头、实际传输和完整响应组装。 WorkflowEngineClient 接收 From 319fbaa7b0be1c7fed9edfd0cafee7e81f9d7a63 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Fri, 4 Sep 2026 14:52:31 +0800 Subject: [PATCH 2/4] docs: focus the module view on the engine and its external participants Drop the starter from the module view per review: the diagram now highlights the engine's relationships top-down - host agent (starts the engine and implements the callbacks), the scheduling kernel and protocol adaptation inside the engine, the two SDK layers (a2a-java-sdk transports, a2a-t-sdk types), and the external systems: orchestration center, registry center, and dispatched agents (OMC) with the four A2A-T interaction types. Signed-off-by: Zhoujie628 --- docs/en/DESIGN.md | 86 ++++++++++++++++++++++------------------------- docs/zh/DESIGN.md | 81 +++++++++++++++++++++----------------------- 2 files changed, 79 insertions(+), 88 deletions(-) diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index e99672c9..4be682fe 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -126,79 +126,75 @@ graph TD L0 -.-> F ``` -The layer view expands into the software module view (Maven modules, package responsibilities, and dependency boundaries): +The layer view expands into the software module view (the engine in relation to the host agent, the orchestration center, the registry center, the dispatched agents, and the two SDK layers): ```mermaid flowchart TB - subgraph HOST["Host Agent (business application · samples workbench)"] + subgraph HOST["Host Agent (business application)"] direction LR - WB["WorkbenchOrchestrator
northbound task intake · workflow selection"] + WB["Northbound task intake · workflow selection"] BIZ["Business callbacks
onTask / onSelfTask / onRoute / onNegotiation"] - GEN["Content generation and validation
calls a2a-t-client directly"] + GEN["Content generation and validation
(a2a-t-client)"] end - subgraph KERNEL["workflow-engine scheduling kernel (zero A2A-T dependency, guarded by an architecture test)"] - direction LR - EXE["WorkflowExecutor
DAG validation · parallel dispatch · aggregation"] - CTXB["ContextBuilder
four-mode upstream window selection"] - ADAPT["FailureMapping · ProtocolResultAdapter
failure mapping · transport-to-business result adaptation"] - CP["ControlPoint callback contract
+ EventCallback event outlet"] - MODEL["model layer
workflow definitions · MessageContent · ReceivedMessage"] - end - - subgraph ADAPTER["client protocol adaptation layer"] - direction LR - WEC["DefaultWorkflowEngineClient
task dispatch · negotiation correlation and reply validation"] - EXT["DefaultExtensionSender
authorization / subscription (channels independent of the workflow)"] - TRANS["A2ATransport base
A2A runtime · authentication · SSE event extraction"] - OBSV["WireLog · ProtocolLogger
wire-level observation (redacted · bounded)"] - REGC["LoadPsop · RegistryClient
orchestration-center / registry-center clients"] - MSG["Thin conversion helpers
A2ATExtension · A2atMessages"] - end - - subgraph STARTER["spring-boot-starter (optional · A2A server assembly)"] - direction LR - AUTO["A2AAutoConfiguration
server-side component assembly"] - EP["A2AController
A2A server endpoints"] + subgraph ENGINE["Workflow Execution Engine (Maven dependency, embedded in the host process)"] + subgraph KERNEL["Scheduling kernel (zero A2A-T dependency, guarded by an architecture test)"] + direction LR + EXE["WorkflowExecutor
DAG validation · parallel dispatch · aggregation"] + CTXB["ContextBuilder
upstream window selection"] + CP["ControlPoint callback contract
EventCallback event outlet"] + MODEL["model
workflow definitions · message carriers"] + end + subgraph ADAPTER["Protocol adaptation layer"] + direction LR + WEC["DefaultWorkflowEngineClient
task dispatch · negotiation correlation and reply validation"] + EXT["DefaultExtensionSender
authorization / subscription (independent channels)"] + TRANS["A2ATransport base
A2A runtime · authentication · SSE extraction"] + OBSV["WireLog · ProtocolLogger
wire-level observation"] + REGC["LoadPsop · RegistryClient
orchestration / registry clients"] + MSG["Thin conversion helpers (A2atMessages and peers)"] + end end - subgraph EXTSDK["External SDKs"] + subgraph SDK["Protocol SDK layer"] direction LR - A2AJ["a2a-java-sdk
client transports · server handlers · A2A spec types"] - A2ATC["a2a-t-core
extension URIs · MetadataContent · NegotiationContext"] + A2AJ["a2a-java-sdk
REST / JSON-RPC / gRPC transports · A2A types"] + A2ATC["a2a-t-sdk (a2a-t-core)
telecom extension URIs · negotiation context"] end subgraph SYS["External systems"] - ORCH["Orchestration center (workflow definitions)"] - REGT["Registry center (AgentCards)"] + direction LR + ORCH["Orchestration center
workflow definitions (PSOP)"] + REGT["Registry center
AgentCards"] + OMC["Dispatched agents (OMC)"] end - WB -->|"selects workflow and starts"| EXE + WB ==>|"selects workflow and starts"| EXE BIZ -.->|"implements"| CP - GEN -->|"generates final message content"| BIZ EXE -->|"invokes business during scheduling"| CP EXE --- MODEL CP --- MODEL EXE --> CTXB - EXE --> ADAPT EXE -->|"dispatch / late-result interception"| WEC WEC --> TRANS EXT --> TRANS TRANS --> OBSV TRANS --> A2AJ MSG -.->|"only reference site inside the engine"| A2ATC - REGC --> ORCH - REGC --> REGT - AUTO --> EP - EP -->|"RestHandler protocol processing"| A2AJ + A2AJ -->|"Task-T · Negotiation-T
Authorization-T · Notification-T"| OMC + REGC -->|"workflow search"| ORCH + REGC -->|"AgentCard retrieval"| REGT ``` -Key properties of the module view: the scheduling kernel (core/control/model packages) references no A2A-T -SDK types — a boundary guarded by the `ContentDependencyBoundaryTest` architecture test. The client -protocol adaptation layer (A2ATExtension, A2atMessages, DefaultWorkflowEngineClient) is the only place -inside the engine that references a2a-t-core. The starter assembles only the A2A server side; the engine -itself is embedded into the host process as a Maven dependency and driven by host code (for example -`ExecutePsop`). +Key properties of the module view: the engine is embedded in the host process as a Maven dependency, started +by host code and extended through the callbacks. The scheduling kernel (core/control/model packages) +references no A2A-T SDK types — a boundary guarded by the `ContentDependencyBoundaryTest` architecture test. +The client protocol adaptation layer (A2ATExtension, A2atMessages, DefaultWorkflowEngineClient) is the only +place inside the engine that references a2a-t-sdk. All four interaction types with dispatched agents (OMC) — +Task-T, Negotiation-T, Authorization-T, Notification-T — travel over a2a-java-sdk transports, with +authorization and subscription on channels independent of the workflow. The orchestration and registry +centers are only reached by the engine clients for workflow-definition search and AgentCard retrieval; the +selection strategy itself belongs to the host. ### 3.1 Layer 0 - Communication diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index 5d6832ec..fa1db1b9 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -115,77 +115,72 @@ graph TD L0 -.-> F ``` -上面是分层视角，展开为软件模块视图（Maven 模块、包职责与依赖边界）： +上面是分层视角，展开为软件模块视图（引擎与宿主、编排中心、注册中心、被调度智能体及两层 SDK 的关系）： ```mermaid flowchart TB - subgraph HOST["宿主智能体（业务应用 · samples 工作台示例）"] + subgraph HOST["宿主智能体（业务应用）"] direction LR - WB["WorkbenchOrchestrator
北向任务接收 · 工作流选择"] + WB["北向任务接收 · 工作流选择"] BIZ["业务回调实现
onTask / onSelfTask / onRoute / onNegotiation"] - GEN["内容生成与语义校验
直接调用 a2a-t-client"] + GEN["内容生成与语义校验
（a2a-t-client）"] end - subgraph KERNEL["workflow-engine 调度内核（零 A2A-T 依赖，架构测试守护）"] - direction LR - EXE["WorkflowExecutor
DAG 校验 · 并行分发 · 汇总推进"] - CTXB["ContextBuilder
上游窗口四模式选择"] - ADAPT["FailureMapping · ProtocolResultAdapter
失败映射 · 传输态转业务结果"] - CP["ControlPoint 回调契约
+ EventCallback 事件出口"] - MODEL["model 模型层
工作流定义 · MessageContent · ReceivedMessage"] - end - - subgraph ADAPTER["client 协议适配层"] - direction LR - WEC["DefaultWorkflowEngineClient
任务分发 · 协商关联与回复校验"] - EXT["DefaultExtensionSender
授权 / 订阅（独立于工作流的通道）"] - TRANS["A2ATransport 传输基座
A2A 运行时 · 认证 · SSE 事件提取"] - OBSV["WireLog · ProtocolLogger
真实报文观测（脱敏 · 有界）"] - REGC["LoadPsop · RegistryClient
编排中心 / 注册中心客户端"] - MSG["A2atMessages 等薄转换辅助
A2ATExtension · A2atMessages"] - end - - subgraph STARTER["spring-boot-starter（可选 · A2A 服务端装配）"] - direction LR - AUTO["A2AAutoConfiguration
服务端组件装配"] - EP["A2AController
A2A 服务端端点"] + subgraph ENGINE["工作流执行引擎（Maven 依赖，嵌入宿主进程）"] + subgraph KERNEL["调度内核（零 A2A-T 依赖，架构测试守护）"] + direction LR + EXE["WorkflowExecutor
DAG 校验 · 并行分发 · 汇总推进"] + CTXB["ContextBuilder
上游窗口选择"] + CP["ControlPoint 回调契约
EventCallback 事件出口"] + MODEL["model
工作流定义 · 消息载体"] + end + subgraph ADAPTER["协议适配层"] + direction LR + WEC["DefaultWorkflowEngineClient
任务分发 · 协商关联与回复校验"] + EXT["DefaultExtensionSender
授权 / 订阅（独立通道）"] + TRANS["A2ATransport 传输基座
A2A 运行时 · 认证 · SSE 提取"] + OBSV["WireLog · ProtocolLogger
真实报文观测"] + REGC["LoadPsop · RegistryClient
编排 / 注册中心客户端"] + MSG["A2atMessages 等薄转换辅助"] + end end - subgraph EXTSDK["外部 SDK"] + subgraph SDK["协议 SDK 层"] direction LR - A2AJ["a2a-java-sdk
客户端传输 · 服务端处理器 · A2A spec 类型"] - A2ATC["a2a-t-core
扩展 URI · MetadataContent · NegotiationContext"] + A2AJ["a2a-java-sdk
REST / JSON-RPC / gRPC 传输 · A2A 类型"] + A2ATC["a2a-t-sdk（a2a-t-core）
电信扩展 URI · 协商上下文"] end subgraph SYS["外部系统"] - ORCH["编排中心（工作流定义）"] - REGT["注册中心（AgentCard）"] + direction LR + ORCH["编排中心
工作流定义（PSOP）"] + REGT["注册中心
AgentCard"] + OMC["被调度智能体（OMC）"] end - WB -->|"选择工作流并启动"| EXE + WB ==>|"选择工作流并启动"| EXE BIZ -.->|"实现"| CP - GEN -->|"生成最终消息内容"| BIZ EXE -->|"调度时回调业务"| CP EXE --- MODEL CP --- MODEL EXE --> CTXB - EXE --> ADAPT EXE -->|"分发 / 晚到结果拦截"| WEC WEC --> TRANS EXT --> TRANS TRANS --> OBSV TRANS --> A2AJ MSG -.->|"引擎内唯一引用位置"| A2ATC - REGC --> ORCH - REGC --> REGT - AUTO --> EP - EP -->|"RestHandler 协议处理"| A2AJ + A2AJ -->|"Task-T · Negotiation-T
Authorization-T · Notification-T"| OMC + REGC -->|"检索工作流"| ORCH + REGC -->|"获取 AgentCard"| REGT ``` -模块视图要点：调度内核（core/control/model 包）不引用任何 A2A-T SDK 类型，该边界由 -`ContentDependencyBoundaryTest` 架构测试守护；client 协议适配层（A2ATExtension、A2atMessages、 -DefaultWorkflowEngineClient）是引擎内引用 a2a-t-core 的唯一位置；starter 只装配 A2A 服务端组件， -引擎本身以 Maven 依赖形式嵌入宿主进程，由宿主代码（如 `ExecutePsop`）驱动。 +模块视图要点：引擎以 Maven 依赖嵌入宿主进程，由宿主代码启动并实现回调；调度内核（core/control/model +包）不引用任何 A2A-T SDK 类型，该边界由 `ContentDependencyBoundaryTest` 架构测试守护；client 协议 +适配层（A2ATExtension、A2atMessages、DefaultWorkflowEngineClient）是引擎内引用 a2a-t-sdk 的唯一 +位置；与被调度智能体（OMC）的 Task-T、Negotiation-T、Authorization-T、Notification-T 四类交互全部 +经 a2a-java-sdk 传输，授权与订阅使用独立于工作流的通道；编排中心与注册中心仅在工作流定义检索和 +AgentCard 获取时被引擎客户端访问，检索与选择策略属宿主职责。 ### 3.1 Layer 0 - 通信层 From 9ca3eed0531b6ec4051ed1c9e449cbc166520de0 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Fri, 4 Sep 2026 14:57:22 +0800 Subject: [PATCH 3/4] docs: use precise wording for the late-result guarantee The edge label 'late-result interception' mixed a relationship with an implementation guard. The edge now states only 'task dispatch'; the guarantee is stated precisely in prose: a result completing after the callback budget expires or the run is cancelled is ignored and never sent. Signed-off-by: Zhoujie628 --- docs/en/DESIGN.md | 5 +++-- docs/zh/DESIGN.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index 4be682fe..611d7cad 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -175,7 +175,7 @@ flowchart TB EXE --- MODEL CP --- MODEL EXE --> CTXB - EXE -->|"dispatch / late-result interception"| WEC + EXE -->|"task dispatch"| WEC WEC --> TRANS EXT --> TRANS TRANS --> OBSV @@ -194,7 +194,8 @@ place inside the engine that references a2a-t-sdk. All four interaction types wi Task-T, Negotiation-T, Authorization-T, Notification-T — travel over a2a-java-sdk transports, with authorization and subscription on channels independent of the workflow. The orchestration and registry centers are only reached by the engine clients for workflow-definition search and AgentCard retrieval; the -selection strategy itself belongs to the host. +selection strategy itself belongs to the host. Once a task is dispatched, a result that completes after the +callback budget expires or the run is cancelled is ignored and never sent to the remote agent. ### 3.1 Layer 0 - Communication diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index fa1db1b9..4b6f7466 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -164,7 +164,7 @@ flowchart TB EXE --- MODEL CP --- MODEL EXE --> CTXB - EXE -->|"分发 / 晚到结果拦截"| WEC + EXE -->|"任务下发"| WEC WEC --> TRANS EXT --> TRANS TRANS --> OBSV @@ -180,7 +180,8 @@ flowchart TB 适配层（A2ATExtension、A2atMessages、DefaultWorkflowEngineClient）是引擎内引用 a2a-t-sdk 的唯一 位置；与被调度智能体（OMC）的 Task-T、Negotiation-T、Authorization-T、Notification-T 四类交互全部 经 a2a-java-sdk 传输，授权与订阅使用独立于工作流的通道；编排中心与注册中心仅在工作流定义检索和 -AgentCard 获取时被引擎客户端访问，检索与选择策略属宿主职责。 +AgentCard 获取时被引擎客户端访问，检索与选择策略属宿主职责。任务下发后，若回调超时或工作流已被 +取消，迟到完成的结果会被忽略，不再发送到远端。 ### 3.1 Layer 0 - 通信层 From afe8ff1dac85219878d2265635e6f988b65661b1 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Fri, 4 Sep 2026 20:49:04 +0800 Subject: [PATCH 4/4] docs: align the module view with the standard error contract The transport base now detects the standard A2A error envelope, so the module view gains that responsibility on the transport node, the key properties state the pre-creation / post-creation failure split (stable a2a. error codes versus HTTP 200 with TASK_STATE_FAILED), and the design-decisions summary records the same distinction. Chinese and English versions updated symmetrically. Signed-off-by: Zhoujie628 --- docs/en/DESIGN.md | 10 ++++++++-- docs/zh/DESIGN.md | 11 +++++++---- 2 files changed, 15 insertions(+), 6 deletions(-) diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index 611d7cad..550bb175 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -149,7 +149,7 @@ flowchart TB direction LR WEC["DefaultWorkflowEngineClient
task dispatch · negotiation correlation and reply validation"] EXT["DefaultExtensionSender
authorization / subscription (independent channels)"] - TRANS["A2ATransport base
A2A runtime · authentication · SSE extraction"] + TRANS["A2ATransport base
A2A runtime · authentication · SSE extraction · standard error-envelope detection"] OBSV["WireLog · ProtocolLogger
wire-level observation"] REGC["LoadPsop · RegistryClient
orchestration / registry clients"] MSG["Thin conversion helpers (A2atMessages and peers)"] @@ -194,7 +194,11 @@ place inside the engine that references a2a-t-sdk. All four interaction types wi Task-T, Negotiation-T, Authorization-T, Notification-T — travel over a2a-java-sdk transports, with authorization and subscription on channels independent of the workflow. The orchestration and registry centers are only reached by the engine clients for workflow-definition search and AgentCard retrieval; the -selection strategy itself belongs to the host. Once a task is dispatched, a result that completes after the +selection strategy itself belongs to the host. A call rejected before task creation with a non-2xx +response and the standard A2A error envelope is detected by the transport layer and projected to a +stable error code (`a2a.`); it enters no negotiation and is not retried automatically. A +business failure after task creation is still reported as HTTP 200 with `TASK_STATE_FAILED` +carrying the failure evidence. Once a task is dispatched, a result that completes after the callback budget expires or the run is cancelled is ignored and never sent to the remote agent. ### 3.1 Layer 0 - Communication @@ -364,5 +368,7 @@ Templates and slot schemas come from the pinned SDK jar, not sample resource ove Final content is separate from protocol scheduling; hosts do not maintain A2A envelopes. Local multiple outputs and complete remote evidence enter the selected upstream window without losing metadata or flattening arrays. Business owns negotiation reply content; the engine owns association, deduplication and bounded waiting. Stop and Abort are distinct. +Pre-creation protocol errors are projected from the standard A2A error envelope to stable error codes; post-creation +business failures are reported through the task's terminal state. Independent authorization/notification never gate the workflow; transport runtimes share the same callback contract. Protocol logs observe actual boundaries with mandatory redaction; see [Integration guide](INTEGRATION_GUIDE.md). diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index 4b6f7466..c8928e47 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -138,7 +138,7 @@ flowchart TB direction LR WEC["DefaultWorkflowEngineClient
任务分发 · 协商关联与回复校验"] EXT["DefaultExtensionSender
授权 / 订阅（独立通道）"] - TRANS["A2ATransport 传输基座
A2A 运行时 · 认证 · SSE 提取"] + TRANS["A2ATransport 传输基座
A2A 运行时 · 认证 · SSE 提取 · 标准错误信封检测"] OBSV["WireLog · ProtocolLogger
真实报文观测"] REGC["LoadPsop · RegistryClient
编排 / 注册中心客户端"] MSG["A2atMessages 等薄转换辅助"] @@ -180,8 +180,10 @@ flowchart TB 适配层（A2ATExtension、A2atMessages、DefaultWorkflowEngineClient）是引擎内引用 a2a-t-sdk 的唯一 位置；与被调度智能体（OMC）的 Task-T、Negotiation-T、Authorization-T、Notification-T 四类交互全部 经 a2a-java-sdk 传输，授权与订阅使用独立于工作流的通道；编排中心与注册中心仅在工作流定义检索和 -AgentCard 获取时被引擎客户端访问，检索与选择策略属宿主职责。任务下发后，若回调超时或工作流已被 -取消，迟到完成的结果会被忽略，不再发送到远端。 +AgentCard 获取时被引擎客户端访问，检索与选择策略属宿主职责。任务创建前被对端以非 2xx 和标准 +A2A 错误信封拒绝的调用，由传输层识别并投影为稳定错误码（`a2a.`），不进入协商、不自动重试； +任务创建后的业务失败仍以 HTTP 200 和 `TASK_STATE_FAILED` 携带失败证据上报。任务下发后，若回调超时 +或工作流已被取消，迟到完成的结果会被忽略，不再发送到远端。 ### 3.1 Layer 0 - 通信层 @@ -328,4 +330,5 @@ RegistryClient/LoadPsop 辅助接口或自己的实现。 模板和 slot schema ## 10. 设计决策总结 最终内容与协议调度分离，宿主不自行维护 A2A 信封。 本地多输出和远端完整证据统一进入下游窗口，不丢失 metadata、不拍平数组。 -协商回复内容归业务，任务关联／去重／有界等待归引擎；本地 Stop 与协议 Abort 分离。 独立授权和通知不成为工作流前提，业务回调与传输实现分离。 协议日志在实际边界采集并强制脱敏，详情见 [集成指南](INTEGRATION_GUIDE.md)。 +协商回复内容归业务，任务关联／去重／有界等待归引擎；本地 Stop 与协议 Abort 分离。 任务创建前的协议错误按标准 +A2A 错误信封投影为稳定错误码，任务创建后的业务失败随任务终态上报。 独立授权和通知不成为工作流前提，业务回调与传输实现分离。 协议日志在实际边界采集并强制脱敏，详情见 [集成指南](INTEGRATION_GUIDE.md)。