@skroyc/ag-ui-middleware-callbacks 0.1.1 → 0.1.2

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 (2) hide show
  1. package/README.md +76 -149
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,8 +1,6 @@
1
1
  # ag-ui-middleware-callbacks
2
2
 
3
- LangChain.js integration providing both middleware and callbacks for AG-UI protocol compatibility.
4
-
5
- Now with official `@ag-ui/core` types and `@ag-ui/proto` support for Protocol Buffer encoding!
3
+ LangChain.js integration providing middleware and callbacks for AG-UI protocol compatibility.
6
4
 
7
5
  ## Installation
8
6
 
@@ -10,35 +8,53 @@ Now with official `@ag-ui/core` types and `@ag-ui/proto` support for Protocol Bu
10
8
  bun install ag-ui-middleware-callbacks
11
9
  ```
12
10
 
13
- ## Features
11
+ ## Exports
14
12
 
15
- - **Official Protocol Types**: Uses `@ag-ui/core` for type definitions and validation schemas
16
- - **Protocol Buffer Support**: Binary encoding via `@ag-ui/proto` (60-80% smaller payloads)
17
- - **SSE Transport**: Traditional Server-Sent Events transport
18
- - **Middleware**: Lifecycle and state management (beforeAgent, afterAgent, state snapshots)
19
- - **Callbacks**: Streaming events (TEXT_MESSAGE_CONTENT, TOOL_CALL_ARGS, tool lifecycle)
20
- - **Validation**: Optional runtime validation using official Zod schemas
13
+ ### Factory Functions
21
14
 
22
- For complete specifications and implementation details, see [SPEC.md](./SPEC.md).
15
+ | Function | Description |
16
+ |----------|-------------|
17
+ | `createAGUIAgent(config)` | Creates LangChain agent with AG-UI integration |
18
+ | `createAGUIMiddleware(options)` | Creates middleware for lifecycle events |
19
+ | `createSSETransport(req, res)` | Server-Sent Events transport |
20
+ | `createProtobufTransport(req, res)` | Protocol Buffer binary transport |
21
+
22
+ ### Utilities
23
+
24
+ | Export | Description |
25
+ |--------|-------------|
26
+ | `AGUICallbackHandler` | Callback handler for streaming events |
27
+ | `encodeEventWithFraming(event)` | Encode protobuf with 4-byte length prefix |
28
+ | `decodeEventWithFraming(data)` | Decode framed protobuf event |
29
+ | `AGUI_MEDIA_TYPE` | `"application/vnd.ag-ui.event+proto"` |
30
+ | `validateEvent(event)` | Validate event against @ag-ui/core schemas |
31
+ | `isValidEvent(event)` | Boolean validation check |
32
+ | `createValidatingTransport(transport, options)` | Wrap transport with validation |
33
+
34
+ ### Types
35
+
36
+ | Type | Description |
37
+ |------|-------------|
38
+ | `AGUIAgentConfig` | Configuration for `createAGUIAgent` |
39
+ | `AGUIMiddlewareOptions` | Middleware configuration options |
40
+ | `AGUITransport` | Transport interface with `emit(event)` |
41
+ | `ProtobufTransport` | Extended transport with `signal`, `encodeEvent`, `decodeEvent` |
42
+ | `EventType` | Event type enum from @ag-ui/core |
43
+ | `EventSchemas` | Zod discriminated union for all events |
23
44
 
24
45
  ## Quick Start
25
46
 
26
- ### SSE Transport (Default)
27
-
28
47
  ```typescript
29
48
  import { createAGUIAgent, createSSETransport, AGUICallbackHandler } from "ag-ui-middleware-callbacks";
30
49
 
31
- // Create SSE transport
32
50
  const transport = createSSETransport(req, res);
33
51
 
34
- // Create AG-UI enabled agent
35
52
  const agent = createAGUIAgent({
36
53
  model,
37
54
  tools,
38
55
  transport,
39
56
  });
40
57
 
41
- // Stream with callbacks (required for TEXT_MESSAGE events)
42
58
  const eventStream = await agent.streamEvents(
43
59
  { messages },
44
60
  {
@@ -52,148 +68,59 @@ for await (const event of eventStream) {
52
68
  }
53
69
  ```
54
70
 
55
- ### Protobuf Transport (New!)
56
-
57
- For bandwidth-efficient binary encoding:
71
+ ## Middleware Configuration
58
72
 
59
73
  ```typescript
60
- import {
61
- createAGUIAgent,
62
- createProtobufTransport,
63
- AGUI_MEDIA_TYPE,
64
- AGUICallbackHandler
65
- } from "ag-ui-middleware-callbacks";
66
-
67
- app.post('/api/agent', (req, res) => {
68
- // Check client preference via Accept header
69
- const acceptProtobuf = req.headers.accept?.includes(AGUI_MEDIA_TYPE);
70
-
71
- const transport = acceptProtobuf
72
- ? createProtobufTransport(req, res)
73
- : createSSETransport(req, res);
74
-
75
- const agent = createAGUIAgent({
76
- model,
77
- tools,
78
- transport,
79
- });
80
-
81
- // ... stream events
82
- });
83
- ```
84
-
85
- ## API Reference
86
-
87
- ### Transports
88
-
89
- | Function | Description |
90
- |----------|-------------|
91
- | `createSSETransport(req, res)` | Server-Sent Events (text/event-stream) |
92
- | `createProtobufTransport(req, res)` | Protocol Buffer binary encoding |
93
-
94
- ### Protobuf Utilities
95
-
96
- ```typescript
97
- import {
98
- encodeEventWithFraming, // Encode event with 4-byte length prefix
99
- decodeEventWithFraming, // Decode framed protobuf event
100
- AGUI_MEDIA_TYPE, // "application/vnd.ag-ui.event+proto"
101
- } from "ag-ui-middleware-callbacks";
102
- ```
103
-
104
- ### Validation
105
-
106
- ```typescript
107
- import {
108
- validateEvent, // Validate event against @ag-ui/core schemas
109
- isValidEvent, // Boolean check for event validity
110
- createValidatingTransport, // Wrap transport with validation
111
- } from "ag-ui-middleware-callbacks";
112
-
113
- // Optional: Enable validation in development
114
- const validatingTransport = createValidatingTransport(transport, {
115
- throwOnInvalid: false, // Log warnings instead of throwing
116
- });
117
- ```
118
-
119
- ### @ag-ui/core Re-exports
120
-
121
- ```typescript
122
- import {
123
- EventType, // Event type enum (RUN_STARTED, TEXT_MESSAGE_CONTENT, etc.)
124
- EventSchemas, // Zod discriminated union for all events
125
- encodeProtobuf, // Direct access to @ag-ui/proto encode
126
- decodeProtobuf, // Direct access to @ag-ui/proto decode
127
- } from "ag-ui-middleware-callbacks";
128
- ```
129
-
130
- ## Configuration
131
-
132
- ### Middleware Options
133
-
134
- ```typescript
135
- const agent = createAGUIAgent({
136
- model,
137
- tools,
74
+ const middleware = createAGUIMiddleware({
138
75
  transport,
139
- middlewareOptions: {
140
- emitStateSnapshots: "initial", // "initial" | "final" | "none"
141
- emitActivities: false,
142
- validateEvents: false, // Enable for debugging
143
- // ... other options
144
- },
76
+ emitToolResults: true,
77
+ emitStateSnapshots: "initial", // "initial" | "final" | "all" | "none"
78
+ emitActivities: false,
79
+ maxUIPayloadSize: 50 * 1024,
80
+ chunkLargeResults: false,
81
+ errorDetailLevel: "message", // "full" | "message" | "code" | "none"
82
+ validateEvents: false, // true | "strict" | false
83
+ stateMapper: (state) => state,
84
+ resultMapper: (result) => result,
85
+ activityMapper: (node) => node,
145
86
  });
146
87
  ```
147
88
 
148
- ## Streaming Events
149
-
150
- For streaming events (TEXT_MESSAGE_CONTENT, TOOL_CALL_ARGS), callbacks must be passed at runtime:
89
+ ## Events
90
+
91
+ | Event | Source | Description |
92
+ |-------|--------|-------------|
93
+ | `RUN_STARTED` | Middleware | Agent execution started |
94
+ | `RUN_FINISHED` | Middleware | Agent execution completed |
95
+ | `RUN_ERROR` | Middleware | Agent execution failed |
96
+ | `STEP_STARTED` | Middleware | Model turn started |
97
+ | `STEP_FINISHED` | Middleware | Model turn completed |
98
+ | `TEXT_MESSAGE_START` | Callback | Text message streaming started |
99
+ | `TEXT_MESSAGE_CONTENT` | Callback | Text message chunk |
100
+ | `TEXT_MESSAGE_END` | Callback | Text message streaming ended |
101
+ | `TOOL_CALL_START` | Callback | Tool execution started |
102
+ | `TOOL_CALL_ARGS` | Callback | Tool call arguments chunk |
103
+ | `TOOL_CALL_END` | Callback | Tool execution ended |
104
+ | `TOOL_CALL_RESULT` | Callback | Tool execution result |
105
+ | `STATE_SNAPSHOT` | Middleware | State snapshot (after streaming) |
106
+ | `MESSAGES_SNAPSHOT` | Middleware | Messages snapshot |
107
+ | `ACTIVITY_SNAPSHOT` | Middleware | New activity detected |
108
+ | `ACTIVITY_DELTA` | Middleware | Activity update |
109
+
110
+ ## Protobuf Transport
151
111
 
152
112
  ```typescript
153
- import { AGUICallbackHandler } from "ag-ui-middleware-callbacks";
154
-
155
- const eventStream = await agent.streamEvents(
156
- { messages },
157
- {
158
- version: "v2",
159
- callbacks: [new AGUICallbackHandler(transport)] // REQUIRED for streaming
160
- }
161
- );
113
+ import { createProtobufTransport, AGUI_MEDIA_TYPE } from "ag-ui-middleware-callbacks";
162
114
 
163
- for await (const event of eventStream) {
164
- // Handle events
165
- }
115
+ const acceptProtobuf = req.headers.accept?.includes(AGUI_MEDIA_TYPE);
116
+ const transport = acceptProtobuf
117
+ ? createProtobufTransport(req, res)
118
+ : createSSETransport(req, res);
166
119
  ```
167
120
 
168
- Note: The AGUICallbackHandler must be passed at runtime for streaming events to work correctly. See SPEC.md for details.
169
-
170
- ## Protocol Compliance
171
-
172
- This package uses official `@ag-ui/core` (v0.0.42+) types and schemas:
173
- - All 26 stable event types are supported
174
- - Zod schemas for runtime validation
175
- - Protocol Buffer encoding via `@ag-ui/proto`
176
-
177
- ### Known Limitations
178
-
179
- Some events are not yet supported by `@ag-ui/proto` for binary encoding:
180
- - `TOOL_CALL_RESULT`
181
- - `ACTIVITY_SNAPSHOT`
182
- - `ACTIVITY_DELTA`
183
-
184
- These events will be encoded but may fail decoding. Use SSE transport for full event support.
185
-
186
- ## Development
187
-
188
- ```bash
189
- # Install dependencies
190
- bun install
191
-
192
- # Run tests
193
- bun test
194
-
195
- # Build
196
- bun run build
197
- ```
121
+ ## Dependencies
198
122
 
199
- This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
123
+ - `@ag-ui/core` (^0.0.42)
124
+ - `@ag-ui/proto` (^0.0.42)
125
+ - `langchain` (^1.2.3)
126
+ - `zod` (^3.22.4)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skroyc/ag-ui-middleware-callbacks",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "LangChain.js integration providing middleware and callbacks for AG-UI protocol compatibility",
5
5
  "keywords": ["langchain", "ag-ui", "middleware", "callbacks", "agent", "streaming"],
6
6
  "author": "SkrOYC <oscar@ocmasesorias.com>",