Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/en/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down
16 changes: 12 additions & 4 deletions docs/en/INTEGRATION_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down
12 changes: 7 additions & 5 deletions docs/zh/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 - 遍历层

Expand Down Expand Up @@ -247,8 +248,9 @@ SDK 是独立的:不依赖编排中心。

## 9. 设计决策总结

1. **共享 transport,两个门面** — 通信层机制在 `A2ATransport` 上写一次;
`WorkflowEngineClient` 和 `ExtensionSender` 各自拥有一个编排职责,委托通信工作。
1. **复用 transport 实现,两个门面** — 通信层机制在 `A2ATransport` 上写一次;
`WorkflowEngineClient` 和 `ExtensionSender` 各自拥有一个编排职责,委托通信工作,
并可使用任务级或工作台级 transport 生命周期。
避免强制门面耦合和通信代码重复。

2. **工作流内扩展 vs 前置下发扩展** — Task-T 和 Negotiation-T 是 `sendMessage` 链的一部分;
Expand Down
16 changes: 12 additions & 4 deletions docs/zh/INTEGRATION_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -384,6 +390,8 @@ AgentCard 通过 `capabilities.extensions` 声明扩展点:

扩展 URI 必须与 A2A-T 定义完全一致。

`securitySchemes` 与 `securityRequirements` 都是可选字段。前者表示智能体支持的认证方式,后者表示当前对接强制要求的认证方式;`securityRequirements: []` 表示不启用内置凭证认证。

## 7. A2A-T 扩展能力

引擎自动处理四个 A2A-T 扩展,你无需关心协议细节:
Expand Down
Loading