@ariaflowagents/config 0.4.6 → 0.4.7
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 +7 -7
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/loader.d.ts +18 -1
- package/dist/loader.d.ts.map +1 -1
- package/dist/loader.js +141 -0
- package/dist/loader.js.map +1 -1
- package/dist/types.d.ts +53 -1
- package/dist/types.d.ts.map +1 -1
- package/guide/CALLBACKS.md +332 -0
- package/guide/README.md +225 -7
- package/package.json +10 -10
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAExH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;AAEvD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC3D;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,332 @@
|
|
|
1
|
+
# HTTP Callbacks Guide
|
|
2
|
+
|
|
3
|
+
A comprehensive guide to using HTTP callbacks for real-time event streaming in AriaFlow.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
HTTP callbacks enable your AriaFlow agents to stream events (text tokens, tool calls, handoffs, etc.) to external webhooks in real-time. This is essential for:
|
|
8
|
+
- Real-time analytics and monitoring
|
|
9
|
+
- Live UI updates
|
|
10
|
+
- Audit logging and compliance
|
|
11
|
+
- Integration with external systems (Dash7, monitoring platforms, etc.)
|
|
12
|
+
|
|
13
|
+
## Quick Start
|
|
14
|
+
|
|
15
|
+
### 1. Add Callback to Configuration
|
|
16
|
+
|
|
17
|
+
Add a `callback` block to your `ariaflow.jsonc`:
|
|
18
|
+
|
|
19
|
+
```jsonc
|
|
20
|
+
{
|
|
21
|
+
"name": "my-agent",
|
|
22
|
+
"runtime": {
|
|
23
|
+
"defaultAgent": "support"
|
|
24
|
+
},
|
|
25
|
+
"callback": {
|
|
26
|
+
"url": "https://your-webhook.com/events",
|
|
27
|
+
"method": "POST"
|
|
28
|
+
}
|
|
29
|
+
}
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### 2. Run Your Agent
|
|
33
|
+
|
|
34
|
+
That's it! Events will now be streamed to your webhook in real-time.
|
|
35
|
+
|
|
36
|
+
## Configuration Reference
|
|
37
|
+
|
|
38
|
+
### Basic Options
|
|
39
|
+
|
|
40
|
+
```jsonc
|
|
41
|
+
{
|
|
42
|
+
"callback": {
|
|
43
|
+
"url": "https://webhook.example.com/events",
|
|
44
|
+
"method": "POST"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
| Option | Type | Default | Description |
|
|
50
|
+
|--------|------|---------|-------------|
|
|
51
|
+
| `url` | string | Required | Webhook endpoint URL |
|
|
52
|
+
| `method` | string | `"POST"` | HTTP method (`POST` or `PUT`) |
|
|
53
|
+
|
|
54
|
+
### Headers
|
|
55
|
+
|
|
56
|
+
```jsonc
|
|
57
|
+
{
|
|
58
|
+
"callback": {
|
|
59
|
+
"url": "https://webhook.example.com/events",
|
|
60
|
+
"headers": {
|
|
61
|
+
"Authorization": "Bearer $ENV.API_KEY",
|
|
62
|
+
"Content-Type": "application/json",
|
|
63
|
+
"X-Custom-Header": "custom-value"
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Headers support environment variables:
|
|
70
|
+
- `$ENV.VAR_NAME` - Direct substitution
|
|
71
|
+
- `${ENV.VAR_NAME}` - Bracket syntax
|
|
72
|
+
|
|
73
|
+
### Event Filtering
|
|
74
|
+
|
|
75
|
+
Control which events are sent using `allowList` and `denyList`:
|
|
76
|
+
|
|
77
|
+
```jsonc
|
|
78
|
+
{
|
|
79
|
+
"callback": {
|
|
80
|
+
"url": "https://webhook.example.com/events",
|
|
81
|
+
"allowList": ["text-delta", "tool-call", "tool-result"],
|
|
82
|
+
"denyList": ["step-start", "step-end"]
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
**Filtering Rules:**
|
|
88
|
+
1. `denyList` takes precedence over `allowList`
|
|
89
|
+
2. If `allowList` is empty, all non-denied events are sent
|
|
90
|
+
3. If `allowList` is non-empty, only those events are sent (unless denied)
|
|
91
|
+
|
|
92
|
+
### Available Event Types
|
|
93
|
+
|
|
94
|
+
| Event Type | Description |
|
|
95
|
+
|------------|-------------|
|
|
96
|
+
| `text-delta` | Text token as it streams |
|
|
97
|
+
| `tool-call` | Tool invocation starts |
|
|
98
|
+
| `tool-result` | Tool returns data |
|
|
99
|
+
| `tool-error` | Tool fails |
|
|
100
|
+
| `tool-start` | Tool begins (with filler) |
|
|
101
|
+
| `tool-done` | Tool completes |
|
|
102
|
+
| `handoff` | Agent handoff occurs |
|
|
103
|
+
| `agent-start` | Agent starts |
|
|
104
|
+
| `agent-end` | Agent completes |
|
|
105
|
+
| `step-start` | Step begins |
|
|
106
|
+
| `step-end` | Step completes |
|
|
107
|
+
| `node-enter` | Flow node entered |
|
|
108
|
+
| `node-exit` | Flow node exited |
|
|
109
|
+
| `flow-transition` | Flow transitions |
|
|
110
|
+
| `flow-end` | Flow completes |
|
|
111
|
+
| `error` | Error occurs |
|
|
112
|
+
| `done` | Session completes |
|
|
113
|
+
|
|
114
|
+
### Full Text Accumulation
|
|
115
|
+
|
|
116
|
+
When `includeFullText: true`, each payload includes accumulated text:
|
|
117
|
+
|
|
118
|
+
```jsonc
|
|
119
|
+
{
|
|
120
|
+
"callback": {
|
|
121
|
+
"url": "https://webhook.example.com/events",
|
|
122
|
+
"includeFullText": true
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**Example Payload:**
|
|
128
|
+
```json
|
|
129
|
+
{
|
|
130
|
+
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
|
|
131
|
+
"agentId": "support",
|
|
132
|
+
"timestamp": "2026-02-01T17:00:00.000Z",
|
|
133
|
+
"part": {
|
|
134
|
+
"type": "text-delta",
|
|
135
|
+
"text": "Hello"
|
|
136
|
+
},
|
|
137
|
+
"fullText": "Hello! How can I assist you today?"
|
|
138
|
+
}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
The `fullText` field accumulates all `text-delta` events for the current turn and is cleared at `turn-end`.
|
|
142
|
+
|
|
143
|
+
## Complete Example
|
|
144
|
+
|
|
145
|
+
```jsonc
|
|
146
|
+
{
|
|
147
|
+
"$schema": "https://mithushancj.com/config.json",
|
|
148
|
+
"name": "support-agent",
|
|
149
|
+
"version": "1.0.0",
|
|
150
|
+
"runtime": {
|
|
151
|
+
"defaultAgent": "support",
|
|
152
|
+
"defaultModel": "default"
|
|
153
|
+
},
|
|
154
|
+
"models": {
|
|
155
|
+
"default": "openai:gpt-4o-mini"
|
|
156
|
+
},
|
|
157
|
+
"callback": {
|
|
158
|
+
"url": "https://analytics.example.com/ariaflow-events",
|
|
159
|
+
"method": "POST",
|
|
160
|
+
"headers": {
|
|
161
|
+
"Authorization": "Bearer $ENV.ANALYTICS_API_KEY",
|
|
162
|
+
"X-Source": "production",
|
|
163
|
+
"X-Environment": "production"
|
|
164
|
+
},
|
|
165
|
+
"allowList": ["text-delta", "tool-call", "tool-result", "handoff", "error"],
|
|
166
|
+
"includeFullText": true
|
|
167
|
+
},
|
|
168
|
+
"agents": {
|
|
169
|
+
"support": {
|
|
170
|
+
"type": "llm",
|
|
171
|
+
"description": "Customer support agent",
|
|
172
|
+
"prompt": "You are a helpful customer support agent.",
|
|
173
|
+
"tools": ["search", "create_ticket"]
|
|
174
|
+
}
|
|
175
|
+
},
|
|
176
|
+
"tools": {
|
|
177
|
+
"search": {
|
|
178
|
+
"type": "module",
|
|
179
|
+
"entry": "./tools/search/index.ts"
|
|
180
|
+
},
|
|
181
|
+
"create_ticket": {
|
|
182
|
+
"type": "module",
|
|
183
|
+
"entry": "./tools/create_ticket/index.ts"
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Code-First Usage
|
|
190
|
+
|
|
191
|
+
For programmatic control, configure callbacks in code:
|
|
192
|
+
|
|
193
|
+
```typescript
|
|
194
|
+
import { Runtime, type AgentConfig, type HttpCallbackConfig } from '@ariaflowagents/core';
|
|
195
|
+
import { openai } from '@ai-sdk/openai';
|
|
196
|
+
|
|
197
|
+
const callbackConfig: HttpCallbackConfig = {
|
|
198
|
+
url: 'https://webhook.example.com/events',
|
|
199
|
+
method: 'POST',
|
|
200
|
+
headers: {
|
|
201
|
+
'Authorization': 'Bearer $ENV.API_KEY',
|
|
202
|
+
'X-Source': 'code-first-agent'
|
|
203
|
+
},
|
|
204
|
+
allowList: ['text-delta', 'tool-call'],
|
|
205
|
+
includeFullText: true
|
|
206
|
+
};
|
|
207
|
+
|
|
208
|
+
const runtime = new Runtime({
|
|
209
|
+
agents: [agent],
|
|
210
|
+
defaultAgentId: 'support',
|
|
211
|
+
callback: callbackConfig
|
|
212
|
+
});
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
## Security Best Practices
|
|
216
|
+
|
|
217
|
+
1. **Never commit API keys**: Always use environment variables
|
|
218
|
+
2. **Validate webhooks**: Verify signatures at the receiving end
|
|
219
|
+
3. **Use HTTPS**: Always use secure endpoints in production
|
|
220
|
+
4. **Sanitize headers**: Avoid logging sensitive header values
|
|
221
|
+
5. **Implement timeouts**: Configure reasonable timeouts on the webhook server
|
|
222
|
+
|
|
223
|
+
## Performance Considerations
|
|
224
|
+
|
|
225
|
+
The HTTP callback uses a **fire-and-forget** pattern to ensure the agent's main stream is not blocked.
|
|
226
|
+
|
|
227
|
+
### What This Means
|
|
228
|
+
|
|
229
|
+
- HTTP requests are sent without awaiting the response
|
|
230
|
+
- Failed requests log to console but don't affect the agent
|
|
231
|
+
- The agent continues processing even if the webhook is slow
|
|
232
|
+
|
|
233
|
+
### Recommendations
|
|
234
|
+
|
|
235
|
+
1. **Keep webhooks fast**: Response time should be < 100ms
|
|
236
|
+
2. **Use async processing**: Process events asynchronously on the receiver side
|
|
237
|
+
3. **Implement batching**: Consider batching events if volume is high
|
|
238
|
+
4. **Monitor failures**: Watch logs for failed webhook deliveries
|
|
239
|
+
5. **Consider message queues**: For critical events, use a queue instead of direct webhooks
|
|
240
|
+
|
|
241
|
+
## Debugging
|
|
242
|
+
|
|
243
|
+
### Enable Debug Logging
|
|
244
|
+
|
|
245
|
+
Set the `ARIAFLOW_DEBUG` environment variable to see callback activity:
|
|
246
|
+
|
|
247
|
+
```bash
|
|
248
|
+
ARIAFLOW_DEBUG=callback bun run run.ts
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
### Common Issues
|
|
252
|
+
|
|
253
|
+
**Events not received:**
|
|
254
|
+
- Verify webhook URL is correct and accessible
|
|
255
|
+
- Check firewall/network settings
|
|
256
|
+
- Ensure `allowList`/`denyList` aren't filtering all events
|
|
257
|
+
|
|
258
|
+
**Partial events:**
|
|
259
|
+
- Check `allowList` includes the expected event types
|
|
260
|
+
- Verify `denyList` isn't blocking events
|
|
261
|
+
|
|
262
|
+
**Missing fullText:**
|
|
263
|
+
- Ensure `includeFullText: true` is set
|
|
264
|
+
- Note: `fullText` is cleared at `turn-end`
|
|
265
|
+
|
|
266
|
+
## Integration Examples
|
|
267
|
+
|
|
268
|
+
### Receiving Events in Node.js
|
|
269
|
+
|
|
270
|
+
```javascript
|
|
271
|
+
const http = require('http');
|
|
272
|
+
|
|
273
|
+
const server = http.createServer((req, res) => {
|
|
274
|
+
let body = '';
|
|
275
|
+
|
|
276
|
+
req.on('data', chunk => {
|
|
277
|
+
body += chunk.toString();
|
|
278
|
+
});
|
|
279
|
+
|
|
280
|
+
req.on('end', () => {
|
|
281
|
+
try {
|
|
282
|
+
const event = JSON.parse(body);
|
|
283
|
+
console.log(`Received ${event.part.type} event`);
|
|
284
|
+
console.log('Full text:', event.fullText);
|
|
285
|
+
} catch (error) {
|
|
286
|
+
console.error('Failed to parse event:', error);
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
res.writeHead(200, { 'Content-Type': 'application/json' });
|
|
290
|
+
res.end(JSON.stringify({ success: true }));
|
|
291
|
+
});
|
|
292
|
+
});
|
|
293
|
+
|
|
294
|
+
server.listen(8765, () => {
|
|
295
|
+
console.log('Webhook server listening on port 8765');
|
|
296
|
+
});
|
|
297
|
+
```
|
|
298
|
+
|
|
299
|
+
### Sending to Multiple Endpoints
|
|
300
|
+
|
|
301
|
+
Use multiple agents or extend the configuration to support multiple callbacks:
|
|
302
|
+
|
|
303
|
+
```typescript
|
|
304
|
+
import { Runtime, createHttpCallback } from '@ariaflowagents/core';
|
|
305
|
+
|
|
306
|
+
const analyticsCallback = createHttpCallback({
|
|
307
|
+
url: 'https://analytics.example.com/events',
|
|
308
|
+
allowList: ['text-delta', 'tool-call']
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
const auditCallback = createHttpCallback({
|
|
312
|
+
url: 'https://audit.example.com/events',
|
|
313
|
+
allowList: ['tool-call', 'tool-result', 'handoff', 'error']
|
|
314
|
+
});
|
|
315
|
+
|
|
316
|
+
const runtime = new Runtime({
|
|
317
|
+
agents: [agent],
|
|
318
|
+
defaultAgentId: 'support',
|
|
319
|
+
hooks: {
|
|
320
|
+
onStreamPart: async (context, part) => {
|
|
321
|
+
await analyticsCallback(context, part);
|
|
322
|
+
await auditCallback(context, part);
|
|
323
|
+
}
|
|
324
|
+
}
|
|
325
|
+
});
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
## See Also
|
|
329
|
+
|
|
330
|
+
- [Config Guide README](./README.md) - General configuration documentation
|
|
331
|
+
- [Core Callbacks](../ariaflow-core/src/callbacks/README.md) - Core callback utilities
|
|
332
|
+
- [Examples](../examples/http-callback-demo/) - Working callback examples
|
package/guide/README.md
CHANGED
|
@@ -5,10 +5,11 @@ A comprehensive guide to creating and managing AriaFlow agent configurations.
|
|
|
5
5
|
## Overview
|
|
6
6
|
|
|
7
7
|
The AriaFlow Config package (`@ariaflowagents/config`) provides:
|
|
8
|
-
- Configuration loading from `
|
|
8
|
+
- Configuration loading from `ariaflow.jsonc` files
|
|
9
9
|
- Agent and flow definition parsing
|
|
10
10
|
- Tool registration and loading
|
|
11
11
|
- Runtime creation from config
|
|
12
|
+
- **HTTP Callbacks** for real-time event streaming
|
|
12
13
|
|
|
13
14
|
## Installation
|
|
14
15
|
|
|
@@ -16,13 +17,17 @@ The AriaFlow Config package (`@ariaflowagents/config`) provides:
|
|
|
16
17
|
npm install @ariaflowagents/config
|
|
17
18
|
```
|
|
18
19
|
|
|
20
|
+
## Quick Links
|
|
21
|
+
|
|
22
|
+
- [HTTP Callbacks Guide](./CALLBACKS.md) - Real-time event streaming to webhooks
|
|
23
|
+
|
|
19
24
|
## Configuration File
|
|
20
25
|
|
|
21
26
|
### Basic Structure
|
|
22
27
|
|
|
23
28
|
```jsonc
|
|
24
29
|
{
|
|
25
|
-
"$schema": "https://
|
|
30
|
+
"$schema": "https://mithushancj.com/config.json",
|
|
26
31
|
"name": "my-agent",
|
|
27
32
|
"version": "1.0.0",
|
|
28
33
|
"runtime": {
|
|
@@ -290,7 +295,7 @@ Configure API providers:
|
|
|
290
295
|
import { loadAriaflowConfig } from '@ariaflowagents/config';
|
|
291
296
|
|
|
292
297
|
const config = await loadAriaflowConfig({
|
|
293
|
-
configPath: './
|
|
298
|
+
configPath: './ariaflow.jsonc'
|
|
294
299
|
});
|
|
295
300
|
```
|
|
296
301
|
|
|
@@ -303,7 +308,7 @@ import { openai } from '@ai-sdk/openai';
|
|
|
303
308
|
const model = openai('gpt-4o-mini') as any;
|
|
304
309
|
|
|
305
310
|
const { config, summary, warnings } = await loadAriaflowConfigWithResult({
|
|
306
|
-
configPath: './
|
|
311
|
+
configPath: './ariaflow.jsonc',
|
|
307
312
|
modelRegistry: {
|
|
308
313
|
default: model,
|
|
309
314
|
'openai:gpt-4o-mini': model
|
|
@@ -319,7 +324,7 @@ console.log(`Loaded ${summary.agents} agents`);
|
|
|
319
324
|
import { createRuntimeFromConfig } from '@ariaflowagents/config';
|
|
320
325
|
|
|
321
326
|
const { config } = await loadAriaflowConfigWithResult({
|
|
322
|
-
configPath: './
|
|
327
|
+
configPath: './ariaflow.jsonc'
|
|
323
328
|
});
|
|
324
329
|
|
|
325
330
|
const runtime = createRuntimeFromConfig(config);
|
|
@@ -354,7 +359,7 @@ my-agent/
|
|
|
354
359
|
|
|
355
360
|
```jsonc
|
|
356
361
|
{
|
|
357
|
-
"$schema": "https://
|
|
362
|
+
"$schema": "https://mithushancj.com/config.json",
|
|
358
363
|
"name": "support-agent",
|
|
359
364
|
"version": "1.0.0",
|
|
360
365
|
"runtime": {
|
|
@@ -422,6 +427,7 @@ my-agent/
|
|
|
422
427
|
| `tools` | object | No | Tool definitions |
|
|
423
428
|
| `providers` | object | No | Provider configurations |
|
|
424
429
|
| `permissions` | object | No | Permission settings |
|
|
430
|
+
| `callback` | object | No | HTTP callback configuration |
|
|
425
431
|
|
|
426
432
|
### Runtime Properties
|
|
427
433
|
|
|
@@ -450,6 +456,19 @@ my-agent/
|
|
|
450
456
|
| `inline` | string | Inline prompt text |
|
|
451
457
|
| `file` | string | Path to prompt file |
|
|
452
458
|
|
|
459
|
+
### Callback Properties
|
|
460
|
+
|
|
461
|
+
See the [HTTP Callbacks Guide](./CALLBACKS.md) for complete documentation.
|
|
462
|
+
|
|
463
|
+
| Property | Type | Description |
|
|
464
|
+
|----------|------|-------------|
|
|
465
|
+
| `url` | string | Webhook endpoint URL (required) |
|
|
466
|
+
| `method` | string | HTTP method (`POST` or `PUT`) |
|
|
467
|
+
| `headers` | object | Custom headers |
|
|
468
|
+
| `allowList` | array | Event types to send |
|
|
469
|
+
| `denyList` | array | Event types to block |
|
|
470
|
+
| `includeFullText` | boolean | Include accumulated text |
|
|
471
|
+
|
|
453
472
|
## Best Practices
|
|
454
473
|
|
|
455
474
|
1. **Use file-based prompts** for complex prompts (>100 lines)
|
|
@@ -466,7 +485,7 @@ import { loadAriaflowConfigWithResult, createRuntimeFromConfig } from '@ariaflow
|
|
|
466
485
|
import { createAriaChatRouter } from '@ariaflowagents/hono-server';
|
|
467
486
|
|
|
468
487
|
const { config, summary } = await loadAriaflowConfigWithResult({
|
|
469
|
-
configPath: './
|
|
488
|
+
configPath: './ariaflow.jsonc',
|
|
470
489
|
modelRegistry: { default: model }
|
|
471
490
|
});
|
|
472
491
|
|
|
@@ -475,3 +494,202 @@ const runtime = createRuntimeFromConfig(config);
|
|
|
475
494
|
const app = new Hono();
|
|
476
495
|
app.route('/', createAriaChatRouter({ runtime }));
|
|
477
496
|
```
|
|
497
|
+
|
|
498
|
+
## HTTP Callbacks
|
|
499
|
+
|
|
500
|
+
The HTTP callback feature allows you to stream agent events (text deltas, tool calls, etc.) to external webhooks in real-time. This is useful for:
|
|
501
|
+
- Analytics and monitoring
|
|
502
|
+
- Real-time UI updates
|
|
503
|
+
- Audit logging
|
|
504
|
+
- Integration with external systems
|
|
505
|
+
|
|
506
|
+
### Basic Configuration
|
|
507
|
+
|
|
508
|
+
Add a `callback` block to your `ariaflow.jsonc`:
|
|
509
|
+
|
|
510
|
+
```jsonc
|
|
511
|
+
{
|
|
512
|
+
"name": "my-agent",
|
|
513
|
+
"runtime": {
|
|
514
|
+
"defaultAgent": "support",
|
|
515
|
+
"defaultModel": "default"
|
|
516
|
+
},
|
|
517
|
+
"callback": {
|
|
518
|
+
"url": "https://your-webhook.com/events",
|
|
519
|
+
"method": "POST"
|
|
520
|
+
}
|
|
521
|
+
}
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
### Complete Callback Configuration
|
|
525
|
+
|
|
526
|
+
```jsonc
|
|
527
|
+
{
|
|
528
|
+
"callback": {
|
|
529
|
+
"url": "https://your-webhook.com/events",
|
|
530
|
+
"method": "POST",
|
|
531
|
+
"headers": {
|
|
532
|
+
"Authorization": "Bearer $ENV.API_KEY",
|
|
533
|
+
"X-Source": "ariaflow",
|
|
534
|
+
"Content-Type": "application/json"
|
|
535
|
+
},
|
|
536
|
+
"allowList": ["text-delta", "tool-call", "tool-result", "handoff", "error"],
|
|
537
|
+
"denyList": ["step-start", "step-end"],
|
|
538
|
+
"includeFullText": true
|
|
539
|
+
}
|
|
540
|
+
}
|
|
541
|
+
```
|
|
542
|
+
|
|
543
|
+
### Configuration Options
|
|
544
|
+
|
|
545
|
+
| Property | Type | Default | Description |
|
|
546
|
+
|----------|------|---------|-------------|
|
|
547
|
+
| `url` | string | - | Webhook endpoint URL (required) |
|
|
548
|
+
| `method` | string | `"POST"` | HTTP method (`POST` or `PUT`) |
|
|
549
|
+
| `headers` | object | - | Custom headers for the request |
|
|
550
|
+
| `allowList` | array | `[]` (all events) | Only send these event types |
|
|
551
|
+
| `denyList` | array | `[]` (none) | Never send these event types |
|
|
552
|
+
| `includeFullText` | boolean | `false` | Include accumulated full text |
|
|
553
|
+
|
|
554
|
+
### Event Filtering
|
|
555
|
+
|
|
556
|
+
Use `allowList` to send only specific events:
|
|
557
|
+
|
|
558
|
+
```jsonc
|
|
559
|
+
{
|
|
560
|
+
"callback": {
|
|
561
|
+
"url": "https://analytics.example.com/events",
|
|
562
|
+
"allowList": ["text-delta", "tool-call"]
|
|
563
|
+
}
|
|
564
|
+
}
|
|
565
|
+
```
|
|
566
|
+
|
|
567
|
+
Use `denyList` to exclude specific events:
|
|
568
|
+
|
|
569
|
+
```jsonc
|
|
570
|
+
{
|
|
571
|
+
"callback": {
|
|
572
|
+
"url": "https://analytics.example.com/events",
|
|
573
|
+
"denyList": ["step-start", "step-end", "agent-start", "agent-end"]
|
|
574
|
+
}
|
|
575
|
+
}
|
|
576
|
+
```
|
|
577
|
+
|
|
578
|
+
**Filtering Rules:**
|
|
579
|
+
1. `denyList` takes precedence over `allowList`
|
|
580
|
+
2. If `allowList` is empty, all non-denied events are sent
|
|
581
|
+
3. Event types: `text-delta`, `tool-call`, `tool-result`, `tool-error`, `tool-start`, `tool-done`, `handoff`, `agent-start`, `agent-end`, `step-start`, `step-end`, `node-enter`, `node-exit`, `flow-transition`, `flow-end`, `error`, `done`
|
|
582
|
+
|
|
583
|
+
### Environment Variables
|
|
584
|
+
|
|
585
|
+
Use `$ENV.VAR_NAME` or `${ENV.VAR_NAME}` syntax for environment variables:
|
|
586
|
+
|
|
587
|
+
```jsonc
|
|
588
|
+
{
|
|
589
|
+
"callback": {
|
|
590
|
+
"url": "https://$ENV.WEBHOOK_HOST/events",
|
|
591
|
+
"headers": {
|
|
592
|
+
"Authorization": "Bearer $ENV.API_KEY",
|
|
593
|
+
"X-Custom-Header": "${ENV.CUSTOM_VALUE}"
|
|
594
|
+
}
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
```
|
|
598
|
+
|
|
599
|
+
### Full Text Accumulation
|
|
600
|
+
|
|
601
|
+
When `includeFullText: true`, each event payload includes the accumulated text from all `text-delta` events:
|
|
602
|
+
|
|
603
|
+
```jsonc
|
|
604
|
+
{
|
|
605
|
+
"callback": {
|
|
606
|
+
"url": "https://your-webhook.com/events",
|
|
607
|
+
"includeFullText": true
|
|
608
|
+
}
|
|
609
|
+
}
|
|
610
|
+
```
|
|
611
|
+
|
|
612
|
+
**Payload Structure:**
|
|
613
|
+
```json
|
|
614
|
+
{
|
|
615
|
+
"sessionId": "uuid",
|
|
616
|
+
"agentId": "support",
|
|
617
|
+
"timestamp": "2026-02-01T17:00:00.000Z",
|
|
618
|
+
"part": {
|
|
619
|
+
"type": "text-delta",
|
|
620
|
+
"text": "Hello"
|
|
621
|
+
},
|
|
622
|
+
"fullText": "Hello! How can I assist you today?"
|
|
623
|
+
}
|
|
624
|
+
```
|
|
625
|
+
|
|
626
|
+
### Performance Considerations
|
|
627
|
+
|
|
628
|
+
The HTTP callback uses a **fire-and-forget** pattern to avoid blocking the agent's main stream. HTTP requests are sent without awaiting the response.
|
|
629
|
+
|
|
630
|
+
**Best Practices:**
|
|
631
|
+
1. Ensure your webhook endpoint is fast and reliable
|
|
632
|
+
2. Consider adding rate limiting on the receiving end
|
|
633
|
+
3. For high-volume applications, consider batching events on the receiver side
|
|
634
|
+
4. Use HTTPS for production deployments
|
|
635
|
+
|
|
636
|
+
### Example: Complete Configuration with Callbacks
|
|
637
|
+
|
|
638
|
+
```jsonc
|
|
639
|
+
{
|
|
640
|
+
"$schema": "https://mithushancj.com/config.json",
|
|
641
|
+
"name": "support-agent",
|
|
642
|
+
"version": "1.0.0",
|
|
643
|
+
"runtime": {
|
|
644
|
+
"defaultAgent": "support",
|
|
645
|
+
"defaultModel": "default"
|
|
646
|
+
},
|
|
647
|
+
"models": {
|
|
648
|
+
"default": "openai:gpt-4o-mini"
|
|
649
|
+
},
|
|
650
|
+
"callback": {
|
|
651
|
+
"url": "https://analytics.example.com/ariaflow-events",
|
|
652
|
+
"method": "POST",
|
|
653
|
+
"headers": {
|
|
654
|
+
"Authorization": "Bearer $ENV.ANALYTICS_API_KEY",
|
|
655
|
+
"X-Source": "production-agent"
|
|
656
|
+
},
|
|
657
|
+
"allowList": ["text-delta", "tool-call", "tool-result", "handoff", "error"],
|
|
658
|
+
"includeFullText": true
|
|
659
|
+
},
|
|
660
|
+
"agents": {
|
|
661
|
+
"support": {
|
|
662
|
+
"type": "llm",
|
|
663
|
+
"description": "Customer support agent",
|
|
664
|
+
"prompt": "You are a helpful support agent.",
|
|
665
|
+
"tools": ["search", "create_ticket"]
|
|
666
|
+
}
|
|
667
|
+
},
|
|
668
|
+
"tools": {
|
|
669
|
+
"search": { "type": "module", "entry": "./tools/search/index.ts" },
|
|
670
|
+
"create_ticket": { "type": "module", "entry": "./tools/create_ticket/index.ts" }
|
|
671
|
+
}
|
|
672
|
+
}
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
### Code-First Usage
|
|
676
|
+
|
|
677
|
+
You can also configure HTTP callbacks programmatically:
|
|
678
|
+
|
|
679
|
+
```typescript
|
|
680
|
+
import { Runtime, createHttpCallback } from '@ariaflowagents/core';
|
|
681
|
+
|
|
682
|
+
const runtime = new Runtime({
|
|
683
|
+
agents: [agent],
|
|
684
|
+
defaultAgentId: 'support',
|
|
685
|
+
callback: {
|
|
686
|
+
url: 'https://webhook.com/events',
|
|
687
|
+
method: 'POST',
|
|
688
|
+
headers: {
|
|
689
|
+
'Authorization': 'Bearer $ENV.API_KEY'
|
|
690
|
+
},
|
|
691
|
+
allowList: ['text-delta', 'tool-call'],
|
|
692
|
+
includeFullText: true
|
|
693
|
+
}
|
|
694
|
+
});
|
|
695
|
+
```
|