cleveragents/cleveragents-core
4
0
Fork 3
Code Issues 6.0k Pull Requests 115 Actions Packages Projects Releases Wiki Activity

docs(a2a): fix SSE streaming event example method name

Browse Source 
Corrects the Example Streaming Event in docs/reference/a2a.md to use
the correct JSON-RPC 2.0 notification method name `task/statusUpdate`
instead of the incorrect `message/stream`.

`message/stream` is the client→server REQUEST method that initiates
streaming. The actual SSE data payloads are JSON-RPC 2.0 notifications
(no `id` field) with method names `task/statusUpdate` or
`task/artifactUpdate`, as implemented in SseEventFormatter.

Closes #2519
This commit is contained in:
Jeffrey Phillips Freeman
2026-04-03 18:53:13 +00:00
committed by Forgejo
parent 3831632391
commit 9b64297eff
1 changed files with 55 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/a2a.md
+55 -34
View File
@@ -9,7 +9,7 @@ between the Presentation and Application layers.
**Module:** `cleveragents.a2a`
**Protocol:** JSON-RPC 2.0 binding (A2A specification Section 9)
**SDK:** `a2a-sdk` package ([a2aproject/a2a-python](https://github.com/a2aproject/a2a-python))
**SDK:** `a2a-sdk` package ([a2aprojects/a2a-python](https://github.com/a2aprojects/a2a-python))
## Table of Contents
@@ -88,8 +88,8 @@ via the `getExtendedAgentCard` operation.
## Transport Modes
| Mode | Transport | Class / SDK Component | Behaviour |
|--------|------------------------|------------------------------------|--------------------------------------------------------|
| Mode | Transport | Class / SDK Component | Behaviour |
|--------|------------------------|------------------------------------|--------------------------------------------------------------------|
| Local | A2A JSON-RPC over stdio | `A2aLocalFacade` + JSON-RPC stdio | Agent as subprocess; extensions resolved in-process |
| Server | A2A JSON-RPC over HTTP | A2A SDK HTTP transport | JSON-RPC 2.0 to CleverAgents server |
@@ -165,7 +165,7 @@ Pattern applies to all entity types (`actor`, `skill`, `tool`, `validation`,
### Context Operations
| Method | Service Method | Required Params |
|--------|---------------|-----------------|
|--------|----------------|-----------------|
| `_cleveragents/context/show` | `ContextService.show()` | `project_name` |
| `_cleveragents/context/inspect` | `ContextService.inspect()` | `project_name` |
| `_cleveragents/context/simulate` | `ContextService.simulate()` | `project_name`, simulation params |
@@ -174,7 +174,7 @@ Pattern applies to all entity types (`actor`, `skill`, `tool`, `validation`,
### Sync Operations
| Method | Service Method | Required Params |
|--------|---------------|-----------------|
|--------|----------------|-----------------|
| `_cleveragents/sync/pull` | `SyncService.pull()` | `namespace` |
| `_cleveragents/sync/push` | `SyncService.push()` | `namespace`, `entities` |
| `_cleveragents/sync/status` | `SyncService.status()` | `namespace` (optional) |
@@ -182,7 +182,7 @@ Pattern applies to all entity types (`actor`, `skill`, `tool`, `validation`,
### Namespace Operations
| Method | Service Method | Required Params |
|--------|---------------|-----------------|
|--------|----------------|-----------------|
| `_cleveragents/namespace/list` | `NamespaceService.list()` | -- |
| `_cleveragents/namespace/show` | `NamespaceService.show()` | `namespace` |
| `_cleveragents/namespace/members` | `NamespaceService.members()` | `namespace` |
@@ -198,13 +198,20 @@ Pattern applies to all entity types (`actor`, `skill`, `tool`, `validation`,
## Streaming Events
A2A streaming uses SSE via the `message/stream` operation, delivering typed
events as the task progresses:
A2A streaming uses SSE via the `message/stream` operation (client → server
request), delivering typed events as the task progresses. The SSE data
payloads are JSON-RPC 2.0 **notifications** (no `id` field):
| Event Type | Emitted When |
|-----------|-------------|
| `TaskStatusUpdateEvent` | Task state changes (submitted -> working -> completed, etc.) |
| `TaskArtifactUpdateEvent` | Agent produces output (response chunks, plan entries, tool results) |
| Event Type | JSON-RPC Method | Emitted When |
|------------|-----------------|--------------|
| `TaskStatusUpdateEvent` | `task/statusUpdate` | Task state changes (submitted -> working -> completed, etc.) |
| `TaskArtifactUpdateEvent` | `task/artifactUpdate` | Agent produces output (response chunks, plan entries, tool results) |
> **Note:** `message/stream` is the **request** method (client → server) that
> initiates streaming. The SSE data payloads use `task/statusUpdate` or
> `task/artifactUpdate` as the notification method name — not `message/stream`.
> Non-spec fields (`event_id`, `event_type`, `timestamp`) are carried in SSE
> envelope headers (`event:` and `id:` lines), not in the data payload.
### Task Lifecycle States
@@ -220,16 +227,30 @@ events as the task progresses:
### Example Streaming Event
SSE data payload for a task status update (JSON-RPC 2.0 notification):
```json
{
"jsonrpc": "2.0",
"method": "message/stream",
"method": "task/statusUpdate",
"params": {
"id": "task_01HXR...",
"status": { "state": "working" },
"artifacts": [{
"taskId": "task_01HXR...",
"status": { "state": "working" }
}
}
```
SSE data payload for an artifact update:
```json
{
"jsonrpc": "2.0",
"method": "task/artifactUpdate",
"params": {
"taskId": "task_01HXR...",
"artifact": {
"parts": [{ "text": "I'll start by extracting..." }]
}]
}
}
}
```
@@ -277,9 +298,9 @@ response = facade.dispatch(A2aRequest(
### Constructor
| Parameter | Type | Default | Description |
|------------|----------------------------|---------|-------------------------------|
| `services` | `dict[str, Any] \| None` | `None` | Named services for routing |
| Parameter | Type | Default | Description |
|------------|----------------------------------|---------|--------------------------------|
| `services` | `dict[str, Any] \| None` | `None` | Named services for routing |
### Methods
@@ -299,15 +320,15 @@ registered later with `register_service()`.
### Service Keys
| Key | Type | Wired Methods |
|------------------------------|-----------------------------|-------------------------------------|
| `session_service` | `SessionWorkflow` | Standard message operations |
| `plan_lifecycle_service` | `PlanLifecycleService` | `_cleveragents/plan/*` |
| `tool_registry` | `ToolRegistry` | `_cleveragents/registry/tool/*` |
| `resource_registry_service` | `ResourceRegistryService` | `_cleveragents/registry/resource/*` |
| `sync_service` | `SyncService` | `_cleveragents/sync/*` |
| `namespace_service` | `NamespaceService` | `_cleveragents/namespace/*` |
| `context_service` | `ContextService` | `_cleveragents/context/*` |
| Key | Type | Wired Methods |
|----------------------------------|----------------------------------|--------------------------------------------|
| `session_service` | `SessionWorkflow` | Standard message operations |
| `plan_lifecycle_service` | `PlanLifecycleService` | `_cleveragents/plan/*` |
| `tool_registry` | `ToolRegistry` | `_cleveragents/registry/tool/*` |
| `resource_registry_service` | `ResourceRegistryService` | `_cleveragents/registry/resource/*` |
| `sync_service` | `SyncService` | `_cleveragents/sync/*` |
| `namespace_service` | `NamespaceService` | `_cleveragents/namespace/*` |
| `context_service` | `ContextService` | `_cleveragents/context/*` |
---
@@ -402,8 +423,8 @@ CleverAgentsError
└── A2aOperationNotFoundError
```
| Exception | When Raised |
|-----------------------------|----------------------------------------------------|
| `A2aNotAvailableError` | Server-mode operation attempted without connection |
| `A2aVersionMismatchError` | Unsupported A2A version |
| `A2aOperationNotFoundError` | Unknown method dispatched |
| Exception | When Raised |
|------------------------------|--------------------------------------------------------------------|
| `A2aNotAvailableError` | Server-mode operation attempted without connection |
| `A2aVersionMismatchError` | Unsupported A2A version |
| `A2aOperationNotFoundError` | Unknown method dispatched |