@skroyc/ag-ui-middleware-callbacks 0.3.0 → 1.0.0
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.
- package/README.md +46 -33
- package/dist/index.d.mts +12 -508
- package/dist/index.js +2 -4
- package/dist/index.js.map +1 -1
- package/package.json +3 -4
package/README.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
LangChain.js integration providing middleware and callbacks for AG-UI protocol compatibility.
|
|
4
4
|
|
|
5
|
+
## Package Scope
|
|
6
|
+
|
|
7
|
+
This package focuses exclusively on **intercepting LangChain execution and emitting AG-UI events as JavaScript objects**.
|
|
8
|
+
|
|
9
|
+
**Package responsibility:**
|
|
10
|
+
- Intercept LangChain execution via middleware + callbacks
|
|
11
|
+
- Emit AG-UI events as JavaScript objects (using `@ag-ui/core` types)
|
|
12
|
+
|
|
13
|
+
**Developer responsibility:**
|
|
14
|
+
- All HTTP/server setup
|
|
15
|
+
- Wire formatting (SSE framing, Protobuf framing)
|
|
16
|
+
- Content negotiation
|
|
17
|
+
- Client communication
|
|
18
|
+
|
|
5
19
|
## Installation
|
|
6
20
|
|
|
7
21
|
```bash
|
|
@@ -16,55 +30,42 @@ bun install ag-ui-middleware-callbacks
|
|
|
16
30
|
|----------|-------------|
|
|
17
31
|
| `createAGUIAgent(config)` | Creates LangChain agent with AG-UI integration |
|
|
18
32
|
| `createAGUIMiddleware(options)` | Creates middleware for lifecycle events |
|
|
19
|
-
| `createSSETransport(req, res)` | Server-Sent Events transport |
|
|
20
|
-
| `createProtobufTransport(req, res)` | Protocol Buffer binary transport |
|
|
21
33
|
|
|
22
|
-
###
|
|
34
|
+
### Callback Handler
|
|
23
35
|
|
|
24
36
|
| Export | Description |
|
|
25
37
|
|--------|-------------|
|
|
26
38
|
| `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 |
|
|
44
39
|
|
|
45
40
|
## Quick Start
|
|
46
41
|
|
|
47
42
|
```typescript
|
|
48
|
-
import { createAGUIAgent,
|
|
43
|
+
import { createAGUIAgent, AGUICallbackHandler } from "ag-ui-middleware-callbacks";
|
|
44
|
+
import { EventType } from "@ag-ui/core";
|
|
49
45
|
|
|
50
|
-
|
|
46
|
+
// Create callback to handle events
|
|
47
|
+
const handleEvent = (event) => {
|
|
48
|
+
console.log('AG-UI Event:', event.type, event);
|
|
49
|
+
};
|
|
51
50
|
|
|
51
|
+
// Create AG-UI enabled agent
|
|
52
52
|
const agent = createAGUIAgent({
|
|
53
53
|
model,
|
|
54
54
|
tools,
|
|
55
|
-
|
|
55
|
+
onEvent: handleEvent,
|
|
56
56
|
});
|
|
57
57
|
|
|
58
|
+
// Stream events with callback handler
|
|
58
59
|
const eventStream = await agent.streamEvents(
|
|
59
60
|
{ messages },
|
|
60
61
|
{
|
|
61
62
|
version: "v2",
|
|
62
|
-
callbacks: [new AGUICallbackHandler(
|
|
63
|
+
callbacks: [new AGUICallbackHandler({ onEvent: handleEvent })]
|
|
63
64
|
}
|
|
64
65
|
);
|
|
65
66
|
|
|
66
67
|
for await (const event of eventStream) {
|
|
67
|
-
// Events automatically emitted via
|
|
68
|
+
// Events automatically emitted via callback
|
|
68
69
|
}
|
|
69
70
|
```
|
|
70
71
|
|
|
@@ -72,7 +73,7 @@ for await (const event of eventStream) {
|
|
|
72
73
|
|
|
73
74
|
```typescript
|
|
74
75
|
const middleware = createAGUIMiddleware({
|
|
75
|
-
|
|
76
|
+
onEvent: (event) => console.log(event),
|
|
76
77
|
emitToolResults: true,
|
|
77
78
|
emitStateSnapshots: "initial", // "initial" | "final" | "all" | "none"
|
|
78
79
|
emitActivities: false,
|
|
@@ -107,20 +108,32 @@ const middleware = createAGUIMiddleware({
|
|
|
107
108
|
| `ACTIVITY_SNAPSHOT` | Middleware | New activity detected |
|
|
108
109
|
| `ACTIVITY_DELTA` | Middleware | Activity update |
|
|
109
110
|
|
|
110
|
-
##
|
|
111
|
+
## Wire Formatting (Developer Responsibility)
|
|
112
|
+
|
|
113
|
+
Developers must implement their own transport/wire formatting:
|
|
114
|
+
|
|
115
|
+
### SSE Example
|
|
116
|
+
|
|
117
|
+
```typescript
|
|
118
|
+
const handleEvent = (event) => {
|
|
119
|
+
res.write(`data: ${JSON.stringify(event)}\n\n`);
|
|
120
|
+
};
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Protobuf Example
|
|
111
124
|
|
|
112
125
|
```typescript
|
|
113
|
-
import {
|
|
126
|
+
import { encode, decode } from "@ag-ui/proto";
|
|
114
127
|
|
|
115
|
-
const
|
|
116
|
-
const
|
|
117
|
-
|
|
118
|
-
|
|
128
|
+
const handleEvent = (event) => {
|
|
129
|
+
const bytes = encode(event);
|
|
130
|
+
const lengthPrefix = createLengthPrefix(bytes);
|
|
131
|
+
res.write(Buffer.concat([lengthPrefix, bytes]));
|
|
132
|
+
};
|
|
119
133
|
```
|
|
120
134
|
|
|
121
135
|
## Dependencies
|
|
122
136
|
|
|
123
137
|
- `@ag-ui/core` (^0.0.42)
|
|
124
|
-
- `@ag-ui/proto` (^0.0.42)
|
|
125
138
|
- `langchain` (^1.2.3)
|
|
126
139
|
- `zod` (^3.22.4)
|