From 1fb2d6cb31342d02639d759aca94ed6b880c3781 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Wed, 19 Aug 2026 13:13:49 +0800 Subject: [PATCH] docs: clarify transport lifecycles and task status Signed-off-by: Zhoujie628 --- docs/en/DESIGN.md | 10 +++++----- docs/en/INTEGRATION_GUIDE.md | 16 ++++++++++++---- docs/zh/DESIGN.md | 12 +++++++----- docs/zh/INTEGRATION_GUIDE.md | 16 ++++++++++++---- 4 files changed, 36 insertions(+), 18 deletions(-) diff --git a/docs/en/DESIGN.md b/docs/en/DESIGN.md index b77a28ec..d9ae5b29 100644 --- a/docs/en/DESIGN.md +++ b/docs/en/DESIGN.md @@ -63,14 +63,14 @@ state, and metadata. Notification-T subscriptions *before* the workflow starts. It bypasses Task-T generation and the negotiation loop; Notification-T events use the subscription callback rather than the workflow-global callback. -#### Why a shared transport with two facades? +#### Why reusable transport machinery with two facades? Both the workflow send path and the pre-positioning path need the same wire-level machinery: an HTTP client, TLS configuration, auth interceptors, agent-card resolution, and SSE parsing. Putting that machinery on either facade would either (a) force a caller that only wants to pre-position to hold the full workflow facade, or (b) duplicate the -wire code across two classes. The shared-transport / two-facade design avoids both: +wire code across two classes. The reusable transport / two-facade design avoids both: the wire layer is written once on `A2ATransport`, and each facade delegates all wire work to it while keeping its own -orchestration concern isolated. +orchestration concern isolated. The facades may use task-scoped or workbench-scoped transport lifetimes. ### 2.2 Layer 1 - Traversal @@ -273,9 +273,9 @@ The SDK is standalone: it does not depend on the orchestration center. ## 9. Design Decisions Summary -1. **Shared transport, two facades** - wire machinery written once on +1. **Reusable transport, two facades** - wire machinery written once on `A2ATransport`; `WorkflowEngineClient` and `ExtensionSender` each own one orchestration concern and delegate wire - work. Avoids both forced-facade coupling and wire-code duplication. + work, with task-scoped or workbench-scoped transport lifetimes. Avoids forced-facade coupling and wire-code duplication. 2. **In-workflow vs pre-positioning extensions** - Task-T and Negotiation-T are part of the `sendMessage` chain; Authorization-T is a one-shot request sent before the workflow, while Notification-T is a long-lived subscription diff --git a/docs/en/INTEGRATION_GUIDE.md b/docs/en/INTEGRATION_GUIDE.md index 820efd6b..eb7869e1 100644 --- a/docs/en/INTEGRATION_GUIDE.md +++ b/docs/en/INTEGRATION_GUIDE.md @@ -97,10 +97,16 @@ public class MyControlPoint extends DefaultControlPoint { TaskRequest request, WorkflowEngineClient engineClient) { return engineClient.sendMessage( request.getAgentName(), request.getMessage()) - .thenApply(r -> TaskResponse.builder() - .success(r.getText() != null && !r.getText().isEmpty()) - .output(r.getText()) - .build()); + .thenApply(r -> { + String state = r.getTaskState(); + boolean success = state == null || state.isBlank() + ? r.getText() != null && !r.getText().isBlank() + : state.endsWith("COMPLETED"); + return TaskResponse.builder() + .success(success) + .output(r.getText()) + .build(); + }); } @Override @@ -388,6 +394,8 @@ AgentCards declare extensions via `capabilities.extensions`: Extension URIs must match the A2A-T definitions exactly. +Both `securitySchemes` and `securityRequirements` are optional. The former lists authentication methods the agent supports; the latter marks methods required by this integration. `securityRequirements: []` disables built-in credential authentication. + ## 7. A2A-T Extensions The engine handles four A2A-T extensions automatically. You do not need to deal with protocol details: diff --git a/docs/zh/DESIGN.md b/docs/zh/DESIGN.md index 66dc9379..3de9fa6b 100644 --- a/docs/zh/DESIGN.md +++ b/docs/zh/DESIGN.md @@ -55,12 +55,13 @@ graph TD - **`ExtensionSender`** — 前置下发门面。在工作流启动前发送一次性 Authorization-T 请求或建立长连接 Notification-T 订阅。 绕过 Task-T 生成和协商循环，不通过全局回调发射事件 — 返回的结果就是回调。 -#### 为什么共享 transport + 两个门面？ +#### 为什么复用 transport 实现 + 两个门面？ 工作流发送路径和前置下发路径都需要相同的通信层机制：HTTP 客户端、TLS 配置、 认证拦截器、智能体卡片解析、SSE 解析。把这些机制放在任一门面上要么 (a) 强制只想做前置下发的 -调用方持有完整工作流门面，要么 (b) 在两个类中重复通信代码。共享 transport + 两个门面的设计 -避免了这两个问题。 +调用方持有完整工作流门面，要么 (b) 在两个类中重复通信代码。复用 `A2ATransport` 实现 + 两个门面的设计 +避免了这两个问题。两个门面可以持有不同生命周期的 transport 实例：工作流发送使用任务级 transport， +Notification-T 订阅使用工作台级 transport。 ### 2.2 Layer 1 - 遍历层 @@ -247,8 +248,9 @@ SDK 是独立的：不依赖编排中心。 ## 9. 设计决策总结 -1. **共享 transport，两个门面** — 通信层机制在 `A2ATransport` 上写一次； - `WorkflowEngineClient` 和 `ExtensionSender` 各自拥有一个编排职责，委托通信工作。 +1. **复用 transport 实现，两个门面** — 通信层机制在 `A2ATransport` 上写一次； + `WorkflowEngineClient` 和 `ExtensionSender` 各自拥有一个编排职责，委托通信工作， + 并可使用任务级或工作台级 transport 生命周期。 避免强制门面耦合和通信代码重复。 2. **工作流内扩展 vs 前置下发扩展** — Task-T 和 Negotiation-T 是 `sendMessage` 链的一部分； diff --git a/docs/zh/INTEGRATION_GUIDE.md b/docs/zh/INTEGRATION_GUIDE.md index 6f1c6700..535ebe54 100644 --- a/docs/zh/INTEGRATION_GUIDE.md +++ b/docs/zh/INTEGRATION_GUIDE.md @@ -95,10 +95,16 @@ public class MyControlPoint extends DefaultControlPoint { TaskRequest request, WorkflowEngineClient engineClient) { return engineClient.sendMessage( request.getAgentName(), request.getMessage()) - .thenApply(r -> TaskResponse.builder() - .success(r.getText() != null && !r.getText().isEmpty()) - .output(r.getText()) - .build()); + .thenApply(r -> { + String state = r.getTaskState(); + boolean success = state == null || state.isBlank() + ? r.getText() != null && !r.getText().isBlank() + : state.endsWith("COMPLETED"); + return TaskResponse.builder() + .success(success) + .output(r.getText()) + .build(); + }); } @Override @@ -384,6 +390,8 @@ AgentCard 通过 `capabilities.extensions` 声明扩展点： 扩展 URI 必须与 A2A-T 定义完全一致。 +`securitySchemes` 与 `securityRequirements` 都是可选字段。前者表示智能体支持的认证方式，后者表示当前对接强制要求的认证方式；`securityRequirements: []` 表示不启用内置凭证认证。 + ## 7. A2A-T 扩展能力 引擎自动处理四个 A2A-T 扩展，你无需关心协议细节：