@alis-build/a2a 1.0.515 → 1.0.517

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +91 -37
  2. package/package.json +1 -1
  3. package/transport/jsonrpc/client.ts +11 -4
  4. package/transport/jsonrpc/types.ts +7 -0
package/README.md CHANGED
@@ -1,6 +1,11 @@
1
1
  # a2a-ts
2
2
 
3
- TypeScript client and types for the Agent-to-Agent (A2A) API. Uses JSON-RPC 2.0 over HTTP with support for both unary and streaming (SSE) operations.
3
+ TypeScript types and a **JSON-RPC 2.0** client for the **Agent-to-Agent (A2A)** API: unary requests (single JSON response) and **Server-Sent Events (SSE)** streaming for live updates.
4
+
5
+ ## Requirements
6
+
7
+ - **Runtime**: `fetch`, `TextDecoderStream`, and `AbortSignal` (e.g. **Node.js 18+** or modern browsers).
8
+ - **Types**: Request/response shapes use `*.AsObject` types from `lf/a2a/v1/a2a_pb` (protobuf JS).
4
9
 
5
10
  ## Installation
6
11
 
@@ -8,88 +13,137 @@ TypeScript client and types for the Agent-to-Agent (A2A) API. Uses JSON-RPC 2.0
8
13
  npm install @alis-build/a2a
9
14
  ```
10
15
 
11
- ## Quick Start
16
+ Configure your bundler or `package.json` `exports` so `transport/jsonrpc` resolves, or import from this repository path:
17
+
18
+ ```typescript
19
+ import { A2AClient } from "./transport/jsonrpc";
20
+ ```
21
+
22
+ ## Quick start
12
23
 
13
24
  ```typescript
14
- import { A2AClient } from "@alis-build/a2a/transport/jsonrpc";
25
+ import { A2AClient } from "./transport/jsonrpc";
15
26
 
16
27
  const client = new A2AClient({
17
- baseUrl: "https://api.example.com",
28
+ baseUrl: "https://agent.example.com/jsonrpc",
18
29
  getToken: async () => "your-bearer-token", // optional
30
+ extensionUris: ["https://agent.example.com/extensions"], // optional
31
+ extraHeaders: { "X-Custom-Header": "value" }, // optional
19
32
  });
20
33
 
21
- // Unary: send message, wait for full response
34
+ // Unary — one JSON-RPC response
22
35
  const response = await client.sendMessage({
36
+ tenant: "",
23
37
  message: { text: { text: "Hello" } },
24
38
  configuration: { acceptedOutputModesList: ["text"], blocking: true },
25
39
  });
26
40
 
27
- // Streaming: send message, receive incremental updates
41
+ // Streaming — SSE frames, each parsed as JSON-RPC
28
42
  const controller = new AbortController();
29
43
  for await (const event of client.sendStreamingMessage(
30
44
  {
45
+ tenant: "",
31
46
  message: { text: { text: "Hello" } },
32
47
  configuration: { acceptedOutputModesList: ["text"], blocking: false },
33
48
  },
34
- controller.signal
49
+ controller.signal,
35
50
  )) {
36
51
  console.log(event);
37
52
  }
53
+ // controller.abort() ends the stream without treating it as a hard failure
38
54
  ```
39
55
 
40
- ## Transport (`transport/jsonrpc`)
56
+ ## `A2AClient` methods
41
57
 
42
- The JSON-RPC transport provides:
58
+ | Method | JSON-RPC method | Mode |
59
+ | ---------------------------------- | ---------------------------------- | -------------------------- |
60
+ | `sendMessage` | `SendMessage` | Unary |
61
+ | `getTask` | `GetTask` | Unary |
62
+ | `listTasks` | `ListTasks` | Unary |
63
+ | `cancelTask` | `CancelTask` | Unary |
64
+ | `getTaskPushNotificationConfig` | `GetTaskPushNotificationConfig` | Unary |
65
+ | `createTaskPushNotificationConfig` | `CreateTaskPushNotificationConfig` | Unary |
66
+ | `listTaskPushNotificationConfigs` | `ListTaskPushNotificationConfigs` | Unary |
67
+ | `deleteTaskPushNotificationConfig` | `DeleteTaskPushNotificationConfig` | Unary |
68
+ | `getExtendedAgentCard` | `GetExtendedAgentCard` | Unary |
69
+ | `sendStreamingMessage` | `SendStreamingMessage` | Streaming (async iterator) |
70
+ | `subscribeToTask` | `SubscribeToTask` | Streaming (async iterator) |
43
71
 
44
- | Mode | Methods | Use case |
45
- | ---------- | ------------------------------------------------------------- | --------------------------------- |
46
- | **Unary** | `sendMessage`, `getTask`, `listTasks`, `cancelTask`, etc. | Single request/response |
47
- | **Streaming** | `sendStreamingMessage`, `subscribeToTask` | Incremental updates via SSE |
72
+ Push-notification and extended-card helpers mirror the A2A protobuf service surface.
73
+
74
+ ## Transport (`transport/jsonrpc`)
48
75
 
49
76
  ### Architecture
50
77
 
51
78
  ```
52
79
  A2AClient
53
- ├── request() → POST JSON-RPC → parse single JSON response
54
- └── stream() → POST JSON-RPC → readSseStream() → yield each SSE frame as JSON-RPC response
80
+ ├── request() → POST JSON body → single JSON-RPC response
81
+ └── stream() → POST JSON body → readSseStream() → yield each SSE `data:` frame as JSON-RPC
55
82
  ```
56
83
 
57
- ### Error Handling
84
+ ### Errors
85
+
86
+ | Class | When |
87
+ | ----------------------- | ------------------------------------------------------------------------------------- |
88
+ | `JsonRpcTransportError` | Network failure, non-2xx HTTP, invalid JSON body, SSE read errors. Optional `status`. |
89
+ | `JsonRpcProtocolError` | JSON-RPC `error` in the response. Subclasses by `code`: |
58
90
 
59
- - **`JsonRpcTransportError`**: Network failures, non-2xx HTTP, stream read errors. Has optional `status` for HTTP status code.
60
- - **`JsonRpcProtocolError`**: Server returned a JSON-RPC error object. Use `code` or `instanceof` for typed handling:
61
- - `TaskNotFoundError` (-32001)
62
- - `TaskNotCancelableError` (-32002)
63
- - `PushNotificationNotSupportedError` (-32003)
64
- - `UnsupportedOperationError` (-32004)
65
- - `ContentTypeNotSupportedError` (-32005)
66
- - `InvalidAgentResponseError` (-32006)
67
- - `ExtendedCardNotConfiguredError` (-32007)
68
- - `UnauthenticatedError` (-31401)
69
- - `UnauthorizedError` (-31403)
91
+ | Subclass | Code |
92
+ | ----------------------------------- | ------ |
93
+ | `TaskNotFoundError` | -32001 |
94
+ | `TaskNotCancelableError` | -32002 |
95
+ | `PushNotificationNotSupportedError` | -32003 |
96
+ | `UnsupportedOperationError` | -32004 |
97
+ | `ContentTypeNotSupportedError` | -32005 |
98
+ | `InvalidAgentResponseError` | -32006 |
99
+ | `ExtendedCardNotConfiguredError` | -32007 |
100
+ | `UnauthenticatedError` | -31401 |
101
+ | `UnauthorizedError` | -31403 |
102
+
103
+ Use `createProtocolError(raw)` if you need the same mapping from a raw `JsonRpcError`.
70
104
 
71
105
  ### Exports
72
106
 
73
107
  ```typescript
74
- // Client and config
75
- import { A2AClient } from "@alis-build/a2a/transport/jsonrpc";
76
- import type { A2AClientConfig } from "@alis-build/a2a/transport/jsonrpc";
77
-
78
- // Errors
79
108
  import {
109
+ A2AClient,
110
+ createProtocolError,
80
111
  JsonRpcProtocolError,
81
112
  JsonRpcTransportError,
82
113
  TaskNotFoundError,
114
+ TaskNotCancelableError,
115
+ PushNotificationNotSupportedError,
116
+ UnsupportedOperationError,
117
+ ContentTypeNotSupportedError,
118
+ InvalidAgentResponseError,
119
+ ExtendedCardNotConfiguredError,
83
120
  UnauthenticatedError,
84
- // ... other typed errors
85
- } from "@alis-build/a2a/transport/jsonrpc";
121
+ UnauthorizedError,
122
+ } from "./transport/jsonrpc";
123
+
124
+ import type {
125
+ A2AClientConfig,
126
+ JsonRpcError,
127
+ JsonRpcRequest,
128
+ JsonRpcResponse,
129
+ } from "./transport/jsonrpc";
86
130
  ```
87
131
 
132
+ Protobuf message types (e.g. `SendMessageRequest`) live under `lf/a2a/v1/a2a_pb`.
133
+
134
+ ## Project layout
135
+
136
+ | Path | Purpose |
137
+ | -------------------- | ------------------------------------------ |
138
+ | `lf/a2a/v1/` | Generated protobuf JS/TS (A2A API) |
139
+ | `transport/jsonrpc/` | JSON-RPC client, SSE parser, errors, types |
140
+
88
141
  ## Dependencies
89
142
 
90
- - `google-protobuf` – Protobuf types for A2A messages
91
- - `@alis-build/google-common-protos` – Google common protos
143
+ - `google-protobuf` — runtime for generated messages
144
+ - `@alis-build/google-common-protos` — shared Google protos
145
+ - `grpc-web` / `@grpc/grpc-js` — gRPC definitions alongside JSON-RPC (optional for this client)
92
146
 
93
147
  ## License
94
148
 
95
- See project LICENSE file.
149
+ See [LICENSE](./LICENSE).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@alis-build/a2a",
3
- "version": "1.0.515",
3
+ "version": "1.0.517",
4
4
  "description": "Protobufs generated by Alis Build",
5
5
  "dependencies": {
6
6
  "@alis-build/google-common-protos": "^1.7.0",
package/transport/jsonrpc/client.ts CHANGED
@@ -16,10 +16,7 @@ import {
16
16
  Task,
17
17
  TaskPushNotificationConfig,
18
18
  } from "../../lf/a2a/v1/a2a_pb";
19
- import {
20
- createProtocolError,
21
- JsonRpcTransportError,
22
- } from "./errors";
19
+ import { createProtocolError, JsonRpcTransportError } from "./errors";
23
20
  import { readSseStream } from "./sse";
24
21
 
25
22
  /**
@@ -298,6 +295,16 @@ export class A2AClient {
298
295
  headers["Authorization"] = `Bearer ${token}`;
299
296
  }
300
297
 
298
+ if (this.config.extensionUris?.length) {
299
+ headers["A2A-Extensions"] = this.config.extensionUris.join(", ");
300
+ }
301
+
302
+ if (this.config.extraHeaders) {
303
+ for (const [k, v] of Object.entries(this.config.extraHeaders)) {
304
+ headers[k] = v;
305
+ }
306
+ }
307
+
301
308
  return headers;
302
309
  }
303
310
  }
package/transport/jsonrpc/types.ts CHANGED
@@ -86,4 +86,11 @@ export interface A2AClientConfig {
86
86
  * May be async to support token refresh.
87
87
  */
88
88
  getToken?: () => string | Promise<string>;
89
+ /**
90
+ * Optional A2A extension activation (comma-separated URIs per A2A spec).
91
+ * Sent as the `A2A-Extensions` HTTP header on every JSON-RPC request.
92
+ */
93
+ extensionUris?: string[];
94
+ /** Optional extra headers merged after Content-Type / Authorization. */
95
+ extraHeaders?: Record<string, string>;
89
96
  }