@notic/agent-engine 1.1.1 → 2.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/CHANGELOG.md +46 -0
- package/README.md +434 -292
- package/dist/adapter/AnthropicAdapter.d.ts +3 -1
- package/dist/adapter/AnthropicAdapter.d.ts.map +1 -1
- package/dist/adapter/AnthropicAdapter.js +40 -2
- package/dist/adapter/AnthropicAdapter.js.map +1 -1
- package/dist/adapter/GeminiAdapter.d.ts +3 -1
- package/dist/adapter/GeminiAdapter.d.ts.map +1 -1
- package/dist/adapter/GeminiAdapter.js +76 -3
- package/dist/adapter/GeminiAdapter.js.map +1 -1
- package/dist/adapter/MessageAdapter.d.ts +17 -0
- package/dist/adapter/MessageAdapter.d.ts.map +1 -1
- package/dist/adapter/MessageAdapter.js.map +1 -1
- package/dist/adapter/OpenAIAdapter.d.ts +3 -1
- package/dist/adapter/OpenAIAdapter.d.ts.map +1 -1
- package/dist/adapter/OpenAIAdapter.js +19 -2
- package/dist/adapter/OpenAIAdapter.js.map +1 -1
- package/dist/adapter/OpenAIResponsesAdapter.d.ts +23 -0
- package/dist/adapter/OpenAIResponsesAdapter.d.ts.map +1 -0
- package/dist/adapter/OpenAIResponsesAdapter.js +231 -0
- package/dist/adapter/OpenAIResponsesAdapter.js.map +1 -0
- package/dist/adapter/index.d.ts +2 -1
- package/dist/adapter/index.d.ts.map +1 -1
- package/dist/adapter/index.js +3 -1
- package/dist/adapter/index.js.map +1 -1
- package/dist/agent/Agent.d.ts +57 -16
- package/dist/agent/Agent.d.ts.map +1 -1
- package/dist/agent/Agent.js +292 -54
- package/dist/agent/Agent.js.map +1 -1
- package/dist/agent/index.d.ts +1 -1
- package/dist/agent/index.d.ts.map +1 -1
- package/dist/agent/index.js +4 -1
- package/dist/agent/index.js.map +1 -1
- package/dist/client/ModelClient.d.ts +74 -0
- package/dist/client/ModelClient.d.ts.map +1 -0
- package/dist/client/ModelClient.js +85 -0
- package/dist/client/ModelClient.js.map +1 -0
- package/dist/client/index.d.ts +2 -0
- package/dist/client/index.d.ts.map +1 -0
- package/dist/client/index.js +11 -0
- package/dist/client/index.js.map +1 -0
- package/dist/index.d.ts +11 -6
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +31 -5
- package/dist/index.js.map +1 -1
- package/dist/media/BrowserMediaResolver.d.ts +14 -0
- package/dist/media/BrowserMediaResolver.d.ts.map +1 -0
- package/dist/media/BrowserMediaResolver.js +52 -0
- package/dist/media/BrowserMediaResolver.js.map +1 -0
- package/dist/media/index.d.ts +1 -0
- package/dist/media/index.d.ts.map +1 -1
- package/dist/media/index.js +3 -1
- package/dist/media/index.js.map +1 -1
- package/dist/message/Message.d.ts +7 -0
- package/dist/message/Message.d.ts.map +1 -1
- package/dist/message/Message.js +52 -0
- package/dist/message/Message.js.map +1 -1
- package/dist/message/MessagePart.d.ts +2 -0
- package/dist/message/MessagePart.d.ts.map +1 -1
- package/dist/node.d.ts +3 -0
- package/dist/node.d.ts.map +1 -0
- package/dist/node.js +6 -0
- package/dist/node.js.map +1 -0
- package/dist/provider/Provider.d.ts +48 -0
- package/dist/provider/Provider.d.ts.map +1 -0
- package/dist/provider/Provider.js +73 -0
- package/dist/provider/Provider.js.map +1 -0
- package/dist/provider/index.d.ts +2 -0
- package/dist/provider/index.d.ts.map +1 -0
- package/dist/provider/index.js +10 -0
- package/dist/provider/index.js.map +1 -0
- package/dist/session/Session.d.ts +0 -3
- package/dist/session/Session.d.ts.map +1 -1
- package/dist/session/Session.js +0 -13
- package/dist/session/Session.js.map +1 -1
- package/dist/stream/AnthropicStreamParser.d.ts +26 -0
- package/dist/stream/AnthropicStreamParser.d.ts.map +1 -0
- package/dist/stream/AnthropicStreamParser.js +176 -0
- package/dist/stream/AnthropicStreamParser.js.map +1 -0
- package/dist/stream/GeminiStreamParser.d.ts +21 -0
- package/dist/stream/GeminiStreamParser.d.ts.map +1 -0
- package/dist/stream/GeminiStreamParser.js +144 -0
- package/dist/stream/GeminiStreamParser.js.map +1 -0
- package/dist/stream/MessageStreamParser.d.ts +13 -0
- package/dist/stream/MessageStreamParser.d.ts.map +1 -0
- package/dist/stream/MessageStreamParser.js +3 -0
- package/dist/stream/MessageStreamParser.js.map +1 -0
- package/dist/stream/OpenAIResponsesStreamParser.d.ts +30 -0
- package/dist/stream/OpenAIResponsesStreamParser.d.ts.map +1 -0
- package/dist/stream/OpenAIResponsesStreamParser.js +273 -0
- package/dist/stream/OpenAIResponsesStreamParser.js.map +1 -0
- package/dist/stream/StreamEvent.d.ts +13 -1
- package/dist/stream/StreamEvent.d.ts.map +1 -1
- package/dist/stream/StreamEvent.js +2 -0
- package/dist/stream/StreamEvent.js.map +1 -1
- package/dist/stream/StreamParser.d.ts +2 -1
- package/dist/stream/StreamParser.d.ts.map +1 -1
- package/dist/stream/StreamParser.js.map +1 -1
- package/dist/stream/index.d.ts +5 -1
- package/dist/stream/index.d.ts.map +1 -1
- package/dist/stream/index.js +7 -1
- package/dist/stream/index.js.map +1 -1
- package/dist/tool/ToolKit.d.ts +4 -0
- package/dist/tool/ToolKit.d.ts.map +1 -1
- package/dist/tool/ToolKit.js +50 -14
- package/dist/tool/ToolKit.js.map +1 -1
- package/dist/tool/index.d.ts +1 -1
- package/dist/tool/index.d.ts.map +1 -1
- package/dist/tool/index.js +2 -1
- package/dist/tool/index.js.map +1 -1
- package/docs/API.md +1676 -1455
- package/package.json +33 -9
package/docs/API.md
CHANGED
|
@@ -1,1455 +1,1676 @@
|
|
|
1
|
-
# AgentEngine API 教程
|
|
2
|
-
|
|
3
|
-
版本:1.
|
|
4
|
-
|
|
5
|
-
AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆成几个可以单独理解、测试和替换的模块:
|
|
6
|
-
|
|
7
|
-
- `Message`:统一的消息对象,支持文本、多模态、工具调用、思考内容和树形会话。
|
|
8
|
-
- `Session`:会话树,负责历史、分支、回退、查询和插入。
|
|
9
|
-
- `Tool`:工具定义、参数 schema、生命周期 Hook 和执行结果回传。
|
|
10
|
-
- `Stream`:把 OpenAI-compatible stream chunk 解析成结构化事件。
|
|
11
|
-
- `Prompt`:用声明式规则把临时提示词注入历史。
|
|
12
|
-
- `Config`:链式构建请求参数。
|
|
13
|
-
- `
|
|
14
|
-
- `
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
- [
|
|
23
|
-
- [
|
|
24
|
-
- [
|
|
25
|
-
- [
|
|
26
|
-
- [
|
|
27
|
-
- [
|
|
28
|
-
- [
|
|
29
|
-
- [
|
|
30
|
-
- [
|
|
31
|
-
- [
|
|
32
|
-
- [
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
});
|
|
68
|
-
|
|
69
|
-
const
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
```
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
```ts
|
|
146
|
-
const message = Message.user(
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
```ts
|
|
167
|
-
message.
|
|
168
|
-
message.
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
```ts
|
|
201
|
-
const
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
```ts
|
|
211
|
-
const
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
|
256
|
-
|
|
|
257
|
-
| `
|
|
258
|
-
| `
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
`
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
```
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
session.
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
session.
|
|
326
|
-
|
|
327
|
-
session.
|
|
328
|
-
session.
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
session.query.
|
|
354
|
-
session.query.
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
```ts
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
session.inserter
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
|
410
|
-
|
|
|
411
|
-
| `systemPrompt` |
|
|
412
|
-
| `
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
const
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
```
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
}
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
.
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
|
|
557
|
-
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
```ts
|
|
591
|
-
await toolkit.
|
|
592
|
-
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
|
630
|
-
|
|
|
631
|
-
| `
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
`
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
}
|
|
653
|
-
|
|
654
|
-
const
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
|
686
|
-
|
|
|
687
|
-
| `
|
|
688
|
-
| `
|
|
689
|
-
| `
|
|
690
|
-
| `
|
|
691
|
-
| `
|
|
692
|
-
| `
|
|
693
|
-
| `
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
);
|
|
733
|
-
```
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
`
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
builder.build(history, { strategy: "
|
|
789
|
-
```
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
builder
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
builder.
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
|
835
|
-
|
|
|
836
|
-
| `
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
|
841
|
-
|
|
|
842
|
-
| `
|
|
843
|
-
| `
|
|
844
|
-
| `
|
|
845
|
-
| `
|
|
846
|
-
| `
|
|
847
|
-
| `
|
|
848
|
-
| `
|
|
849
|
-
| `
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
|
|
853
|
-
|
|
|
854
|
-
|
|
|
855
|
-
|
|
856
|
-
|
|
857
|
-
|
|
858
|
-
`
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
```ts
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
config.
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
|
|
953
|
-
|
|
954
|
-
|
|
|
955
|
-
|
|
|
956
|
-
| `
|
|
957
|
-
| `
|
|
958
|
-
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
|
966
|
-
|
|
|
967
|
-
| `
|
|
968
|
-
| `
|
|
969
|
-
| `
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
});
|
|
1009
|
-
```
|
|
1010
|
-
|
|
1011
|
-
`
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
|
|
1059
|
-
|
|
1060
|
-
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
```
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
const
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
```
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
```
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
```
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
```
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
```
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
|
-
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
```
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1389
|
-
|
|
1390
|
-
|
|
1391
|
-
|
|
1392
|
-
|
|
1393
|
-
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
|
|
1402
|
-
|
|
1403
|
-
|
|
1404
|
-
|
|
1405
|
-
|
|
1406
|
-
|
|
1407
|
-
|
|
1408
|
-
|
|
1409
|
-
|
|
1410
|
-
|
|
1411
|
-
|
|
1412
|
-
|
|
1413
|
-
|
|
1414
|
-
|
|
1415
|
-
|
|
1416
|
-
const agent = new Agent({
|
|
1417
|
-
client,
|
|
1418
|
-
model: "your-model",
|
|
1419
|
-
session,
|
|
1420
|
-
|
|
1421
|
-
|
|
1422
|
-
|
|
1423
|
-
|
|
1424
|
-
|
|
1425
|
-
|
|
1426
|
-
|
|
1427
|
-
|
|
1428
|
-
|
|
1429
|
-
|
|
1430
|
-
|
|
1431
|
-
|
|
1432
|
-
|
|
1433
|
-
|
|
1434
|
-
|
|
1435
|
-
|
|
1436
|
-
|
|
1437
|
-
|
|
1438
|
-
|
|
1439
|
-
|
|
1440
|
-
|
|
1441
|
-
|
|
1442
|
-
|
|
1443
|
-
|
|
1444
|
-
|
|
1445
|
-
|
|
1446
|
-
|
|
1447
|
-
```
|
|
1448
|
-
|
|
1449
|
-
|
|
1450
|
-
|
|
1451
|
-
|
|
1452
|
-
|
|
1453
|
-
|
|
1454
|
-
|
|
1455
|
-
|
|
1
|
+
# AgentEngine API 教程
|
|
2
|
+
|
|
3
|
+
版本:1.2.x
|
|
4
|
+
|
|
5
|
+
AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆成几个可以单独理解、测试和替换的模块:
|
|
6
|
+
|
|
7
|
+
- `Message`:统一的消息对象,支持文本、多模态、工具调用、思考内容和树形会话。
|
|
8
|
+
- `Session`:会话树,负责历史、分支、回退、查询和插入。
|
|
9
|
+
- `Tool`:工具定义、参数 schema、生命周期 Hook 和执行结果回传。
|
|
10
|
+
- `Stream`:把 OpenAI-compatible stream chunk 解析成结构化事件。
|
|
11
|
+
- `Prompt`:用声明式规则把临时提示词注入历史。
|
|
12
|
+
- `Config`:链式构建请求参数。
|
|
13
|
+
- `Client`:只负责发送已经适配好的请求,返回 stream 或完整响应。
|
|
14
|
+
- `Adapter`:把统一消息模型序列化到 OpenAI / Anthropic / Gemini 等平台格式。
|
|
15
|
+
- `Provider`:以低耦合方式组合 Client、Adapter 和 Parser。
|
|
16
|
+
- `Agent`:把上面所有模块串起来,完成“请求 -> 解析 -> 工具执行 -> 再请求 -> 最终回复”的自动循环。
|
|
17
|
+
|
|
18
|
+
这份文档会像教程一样讲 API:先跑起来,再分模块深入。README 只做项目介绍和快速入口,完整用法以后主要看这里。
|
|
19
|
+
|
|
20
|
+
## 目录
|
|
21
|
+
|
|
22
|
+
- [安装与最小示例](#安装与最小示例)
|
|
23
|
+
- [核心心智模型](#核心心智模型)
|
|
24
|
+
- [Message:统一消息模型](#message统一消息模型)
|
|
25
|
+
- [Session:会话树](#session会话树)
|
|
26
|
+
- [Tool:工具系统](#tool工具系统)
|
|
27
|
+
- [Stream:流式事件](#stream流式事件)
|
|
28
|
+
- [Prompt:提示词构建](#prompt提示词构建)
|
|
29
|
+
- [Config:请求参数](#config请求参数)
|
|
30
|
+
- [Provider:平台能力组合](#provider平台能力组合)
|
|
31
|
+
- [Adapter:平台适配](#adapter平台适配)
|
|
32
|
+
- [Media:媒体解析](#media媒体解析)
|
|
33
|
+
- [Agent:智能体编排](#agent智能体编排)
|
|
34
|
+
- [Utils:工具函数](#utils工具函数)
|
|
35
|
+
- [常见组合方案](#常见组合方案)
|
|
36
|
+
|
|
37
|
+
## 安装与最小示例
|
|
38
|
+
|
|
39
|
+
安装 AgentEngine:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm install @notic/agent-engine
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
AgentEngine 不强绑定具体模型 SDK。你使用 OpenAI、DeepSeek、Qwen、Kimi 等 OpenAI-compatible 平台时,通常安装 `openai`:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
npm install openai
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
使用原生 Anthropic 或 Gemini Provider 时,安装对应官方 SDK:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install @anthropic-ai/sdk
|
|
55
|
+
npm install @google/genai
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
最小可运行示例:
|
|
59
|
+
|
|
60
|
+
```ts
|
|
61
|
+
import OpenAI from "openai";
|
|
62
|
+
import { Agent, Session, StreamEventType } from "@notic/agent-engine";
|
|
63
|
+
|
|
64
|
+
const client = new OpenAI({
|
|
65
|
+
apiKey: process.env.OPENAI_API_KEY,
|
|
66
|
+
baseURL: "https://api.openai.com/v1",
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
const agent = new Agent({
|
|
70
|
+
client,
|
|
71
|
+
model: "gpt-4o-mini",
|
|
72
|
+
session: Session.create("你是一个简洁、可靠的助手。"),
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
agent.on(StreamEventType.TEXT_DELTA, (event) => {
|
|
76
|
+
process.stdout.write(event.delta);
|
|
77
|
+
});
|
|
78
|
+
|
|
79
|
+
const reply = await agent.run("用一句话介绍 AgentEngine。");
|
|
80
|
+
console.log("\n\nfinal:", reply.text);
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
如果你接 DeepSeek、Qwen 或其他 OpenAI-compatible 平台,只需要替换 `baseURL` 和 `model`:
|
|
84
|
+
|
|
85
|
+
```ts
|
|
86
|
+
const client = new OpenAI({
|
|
87
|
+
apiKey: process.env.DEEPSEEK_API_KEY,
|
|
88
|
+
baseURL: "https://api.deepseek.com",
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
const agent = new Agent({
|
|
92
|
+
client,
|
|
93
|
+
model: "your-model-name",
|
|
94
|
+
session: Session.create("你是一个中文助手。"),
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## 核心心智模型
|
|
99
|
+
|
|
100
|
+
一次常规 Agent 运行大致是这样的:
|
|
101
|
+
|
|
102
|
+
```text
|
|
103
|
+
User input
|
|
104
|
+
-> Message.user()
|
|
105
|
+
-> Session 追加用户消息
|
|
106
|
+
-> PromptBuilder 注入临时上下文
|
|
107
|
+
-> Adapter 序列化成平台请求格式
|
|
108
|
+
-> ModelClient.stream() 或 ModelClient.complete()
|
|
109
|
+
-> Parser 解析流式 chunk,或 Adapter 解析完整响应
|
|
110
|
+
-> Agent 派发事件并生成 assistant Message
|
|
111
|
+
-> 如果有 tool_calls,ToolKit 执行工具并写回 Session
|
|
112
|
+
-> 再次请求模型,直到获得最终回复
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
你可以只用 `Agent`,也可以单独使用底层模块:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
import { Message, Session, Tool, ToolKit, StreamParser } from "@notic/agent-engine";
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
推荐学习顺序:
|
|
122
|
+
|
|
123
|
+
1. 先用 `Agent + Session` 跑通一次模型调用。
|
|
124
|
+
2. 再学习 `Tool + ToolKit`,让模型能调用你的函数。
|
|
125
|
+
3. 然后学习 `PromptBuilder`,把系统规则、短期上下文、动态提示注入对话。
|
|
126
|
+
4. 最后根据平台需要学习 `Provider`、`Adapter`、`MediaResolver` 和 `StreamParser`。
|
|
127
|
+
|
|
128
|
+
## Message:统一消息模型
|
|
129
|
+
|
|
130
|
+
`Message` 是 AgentEngine 的最小数据单位。无论是用户输入、模型回复、工具调用、工具结果,最终都会表示为 `Message`。
|
|
131
|
+
|
|
132
|
+
### 创建消息
|
|
133
|
+
|
|
134
|
+
```ts
|
|
135
|
+
import { Message } from "@notic/agent-engine";
|
|
136
|
+
|
|
137
|
+
const user = Message.user("你好");
|
|
138
|
+
const assistant = Message.assistant("你好,我在。");
|
|
139
|
+
const system = Message.system("你是一个严谨的助手。");
|
|
140
|
+
const emptyRoot = Message.emptySystem();
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
多模态内容用链式方法追加:
|
|
144
|
+
|
|
145
|
+
```ts
|
|
146
|
+
const message = Message.user("请分析这张图")
|
|
147
|
+
.addImage("https://example.com/chart.png", "image/png")
|
|
148
|
+
.addFile("./data.csv", { fileName: "data.csv" })
|
|
149
|
+
.tag("analysis")
|
|
150
|
+
.setMeta("source", "user-upload");
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
也可以直接传入 `MessagePart`:
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
const message = Message.user([
|
|
157
|
+
{ type: "text", text: "请总结这个文件" },
|
|
158
|
+
{ type: "file", url: "./report.pdf", mimeType: "application/pdf" },
|
|
159
|
+
]);
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### 读取消息内容
|
|
163
|
+
|
|
164
|
+
常用 getter:
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
message.text; // 拼接所有 text 和 tool_result 内容
|
|
168
|
+
message.thinking; // 拼接所有 thinking 内容
|
|
169
|
+
message.toolCalls; // 当前消息中的 tool_call 列表
|
|
170
|
+
message.hasMedia; // 是否包含 image/audio/file
|
|
171
|
+
message.hasThinking; // 是否包含 thinking
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
这些 getter 有缓存。如果你直接修改 `message.parts`,需要手动刷新:
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
message.parts.push({ type: "text", text: "追加内容" });
|
|
178
|
+
message.invalidateCache();
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
如果使用 `addText()`、`addImage()` 等内置方法,缓存会自动失效。
|
|
182
|
+
|
|
183
|
+
### 标签与元数据
|
|
184
|
+
|
|
185
|
+
标签适合做查询、分组和后续插入定位:
|
|
186
|
+
|
|
187
|
+
```ts
|
|
188
|
+
const msg = Message.user("这条消息需要重点处理")
|
|
189
|
+
.tag("important", "todo")
|
|
190
|
+
.setMeta("priority", 10);
|
|
191
|
+
|
|
192
|
+
msg.hasTag("important"); // true
|
|
193
|
+
msg.untag("todo");
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### 工具消息
|
|
197
|
+
|
|
198
|
+
模型发起工具调用时,消息里会出现 `tool_call` part。工具执行完成后,用 `Message.tool()` 创建结果:
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
const toolResult = Message.tool(
|
|
202
|
+
"call_123",
|
|
203
|
+
JSON.stringify({ temperature: 21 }),
|
|
204
|
+
"get_weather"
|
|
205
|
+
);
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
也可以手动构造 assistant 的工具调用消息,测试工具链时很有用:
|
|
209
|
+
|
|
210
|
+
```ts
|
|
211
|
+
const assistantCall = Message.assistantToolCalls([
|
|
212
|
+
{ id: "call_123", name: "get_weather", arguments: "{\"city\":\"北京\"}" },
|
|
213
|
+
]);
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### 树结构
|
|
217
|
+
|
|
218
|
+
`Message` 本身就是树节点。`Session` 会利用这个能力做分支会话。
|
|
219
|
+
|
|
220
|
+
```ts
|
|
221
|
+
const root = Message.system("系统提示");
|
|
222
|
+
const user = root.append(Message.user("第一轮问题"));
|
|
223
|
+
const assistant = user.append(Message.assistant("第一轮回答"));
|
|
224
|
+
|
|
225
|
+
assistant.getHistory().map((msg) => msg.text);
|
|
226
|
+
// ["系统提示", "第一轮问题", "第一轮回答"]
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
删除节点有两种模式:
|
|
230
|
+
|
|
231
|
+
```ts
|
|
232
|
+
message.remove("prune"); // 删除自己和所有后代
|
|
233
|
+
message.remove("graft"); // 删除自己,但把子节点接到父节点下面
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
### 序列化
|
|
237
|
+
|
|
238
|
+
```ts
|
|
239
|
+
const json = message.toJSON();
|
|
240
|
+
const restored = Message.fromJSON(json);
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
序列化会保留:
|
|
244
|
+
|
|
245
|
+
- `role`
|
|
246
|
+
- `parts`
|
|
247
|
+
- `metadata`
|
|
248
|
+
- `tags`
|
|
249
|
+
- `model`
|
|
250
|
+
- `usage`
|
|
251
|
+
- 子树结构
|
|
252
|
+
|
|
253
|
+
### Message API 摘要
|
|
254
|
+
|
|
255
|
+
| API | 说明 |
|
|
256
|
+
| --- | --- |
|
|
257
|
+
| `Message.user(content)` | 创建用户消息 |
|
|
258
|
+
| `Message.assistant(content)` | 创建助手消息 |
|
|
259
|
+
| `Message.system(content)` | 创建系统消息 |
|
|
260
|
+
| `Message.emptySystem()` | 创建空系统根节点 |
|
|
261
|
+
| `Message.tool(toolCallId, result, name?)` | 创建工具结果消息 |
|
|
262
|
+
| `Message.assistantToolCalls(calls)` | 创建带工具调用的助手消息 |
|
|
263
|
+
| `addText(text)` | 追加文本 |
|
|
264
|
+
| `addImage(url, mimeType?)` | 追加图片 |
|
|
265
|
+
| `addAudio(url, mimeType?)` | 追加音频 |
|
|
266
|
+
| `addFile(url, options?)` | 追加文件 |
|
|
267
|
+
| `setText(text)` | 替换全部文本并保留非文本 part |
|
|
268
|
+
| `setParts(content)` | 替换全部消息内容并自动失效缓存 |
|
|
269
|
+
| `tag(...names)` / `untag(...names)` | 管理标签 |
|
|
270
|
+
| `setMeta(key, value)` | 写入元数据 |
|
|
271
|
+
| `append(child)` | 追加子节点 |
|
|
272
|
+
| `remove("prune" \| "graft")` | 删除节点 |
|
|
273
|
+
| `getHistory(includeRoot?)` | 获取根节点到当前节点的路径 |
|
|
274
|
+
|
|
275
|
+
## Session:会话树
|
|
276
|
+
|
|
277
|
+
`Session` 管理一棵消息树。最常见的用法是让 `Agent` 自动写入用户消息、助手消息和工具结果。
|
|
278
|
+
|
|
279
|
+
### 创建会话
|
|
280
|
+
|
|
281
|
+
```ts
|
|
282
|
+
import { Session } from "@notic/agent-engine";
|
|
283
|
+
|
|
284
|
+
const session = Session.create("你是一个代码助手。");
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
如果不传系统提示,会创建一个空 system root。空 root 在 `history()` 中会被自动跳过,避免发给不支持空系统消息的平台。
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
const session = Session.create();
|
|
291
|
+
session.history(); // []
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
### 手动追加消息
|
|
295
|
+
|
|
296
|
+
```ts
|
|
297
|
+
session.addUser("你好");
|
|
298
|
+
session.addAssistant(Message.assistant("你好,我在。"));
|
|
299
|
+
|
|
300
|
+
session.history().map((msg) => msg.text);
|
|
301
|
+
// ["你好", "你好,我在。"]
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
如果你已经有完整 `Message` 对象,用 `addMessage()`:
|
|
305
|
+
|
|
306
|
+
```ts
|
|
307
|
+
const msg = Message.user("带标签的输入").tag("important");
|
|
308
|
+
session.addMessage(msg);
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
工具结果用 `addTool()`,它可以一次追加多条:
|
|
312
|
+
|
|
313
|
+
```ts
|
|
314
|
+
session.addTool([
|
|
315
|
+
Message.tool("call_1", "{\"ok\":true}", "save_file"),
|
|
316
|
+
Message.tool("call_2", "{\"ok\":true}", "run_test"),
|
|
317
|
+
]);
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### 历史与光标
|
|
321
|
+
|
|
322
|
+
`Session` 有一个当前光标 `cursor`,所有新增消息都会挂在光标后面。
|
|
323
|
+
|
|
324
|
+
```ts
|
|
325
|
+
session.cursor; // 当前消息
|
|
326
|
+
session.history(); // root -> cursor 的路径
|
|
327
|
+
session.history(false); // 不包含 root
|
|
328
|
+
session.messages; // history(true) 的别名
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
### 分支与回退
|
|
332
|
+
|
|
333
|
+
回退到旧消息后再追加新消息,会自然产生分支:
|
|
334
|
+
|
|
335
|
+
```ts
|
|
336
|
+
const first = session.addUser("方案 A 怎么做?");
|
|
337
|
+
session.addAssistant(Message.assistant("A 的回答"));
|
|
338
|
+
|
|
339
|
+
session.rewind(first);
|
|
340
|
+
session.addUser("那方案 B 呢?");
|
|
341
|
+
session.addAssistant(Message.assistant("B 的回答"));
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
这时 `first` 下面有两个子分支。你可以用分页器在兄弟分支间切换。
|
|
345
|
+
|
|
346
|
+
### Query:查询消息
|
|
347
|
+
|
|
348
|
+
`session.query` 返回查询器。它不是链式 builder,而是提供一组直接返回结果的方法:
|
|
349
|
+
|
|
350
|
+
```ts
|
|
351
|
+
import { Role } from "@notic/agent-engine";
|
|
352
|
+
|
|
353
|
+
const users = session.query.findByRole(Role.User);
|
|
354
|
+
const important = session.query.findByTags(["important"]);
|
|
355
|
+
|
|
356
|
+
const latestAnswer = session.query.findLast({ roles: [Role.Assistant] });
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
常见查询条件:
|
|
360
|
+
|
|
361
|
+
```ts
|
|
362
|
+
session.query.findByContent(["error"]);
|
|
363
|
+
session.query.findByTags(["todo"], { scope: "tree" });
|
|
364
|
+
session.query.findBy((msg) => msg.text.length > 100);
|
|
365
|
+
session.query.findFirst({ content: ["关键问题"] });
|
|
366
|
+
session.query.findLast({ roles: [Role.User] });
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
### Inserter:在历史中插入消息
|
|
370
|
+
|
|
371
|
+
`Inserter` 适合做会话修补、动态插入上下文等操作。
|
|
372
|
+
|
|
373
|
+
```ts
|
|
374
|
+
const anchor = session.query.findFirst({ content: ["关键问题"] });
|
|
375
|
+
|
|
376
|
+
if (anchor) {
|
|
377
|
+
session.inserter
|
|
378
|
+
.moveTo(anchor)
|
|
379
|
+
.insertAfter(Message.system("补充背景:这是一个高优先级任务"))
|
|
380
|
+
.execute();
|
|
381
|
+
}
|
|
382
|
+
```
|
|
383
|
+
|
|
384
|
+
常见操作:
|
|
385
|
+
|
|
386
|
+
```ts
|
|
387
|
+
session.inserter.moveTo(anchor).insertAfter(msg).execute();
|
|
388
|
+
session.inserter.moveTo(anchor).insertBefore(msg).execute();
|
|
389
|
+
session.inserter.bottom().insertUserAfter("追加一条用户消息").execute();
|
|
390
|
+
session.inserter.top().insertAssistantBefore("插到顶部之前").execute();
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### Paginator:切换分支
|
|
394
|
+
|
|
395
|
+
```ts
|
|
396
|
+
const paginator = session.paginator(parentMessage);
|
|
397
|
+
|
|
398
|
+
if (paginator) {
|
|
399
|
+
paginator.total; // 分支数量
|
|
400
|
+
paginator.currentIndex; // 当前分支序号
|
|
401
|
+
paginator.next(); // 切到下一个分支
|
|
402
|
+
paginator.prev(); // 切到上一个分支
|
|
403
|
+
paginator.goTo(0); // 切到指定分支
|
|
404
|
+
}
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
### Session API 摘要
|
|
408
|
+
|
|
409
|
+
| API | 说明 |
|
|
410
|
+
| --- | --- |
|
|
411
|
+
| `Session.create(systemPrompt?)` | 创建会话 |
|
|
412
|
+
| `addUser(content)` | 追加用户消息 |
|
|
413
|
+
| `addAssistant(message)` | 追加助手消息 |
|
|
414
|
+
| `addTool(messages)` | 追加工具结果 |
|
|
415
|
+
| `addMessage(message)` | 追加任意消息 |
|
|
416
|
+
| `history(includeRoot?)` | 获取当前路径 |
|
|
417
|
+
| `rewind(message)` | 把光标回退到指定消息 |
|
|
418
|
+
| `query` | 查询器 getter |
|
|
419
|
+
| `inserter` | 插入器 getter |
|
|
420
|
+
| `paginators` | 当前路径上的所有分支分页器 |
|
|
421
|
+
| `paginator(message)` | 创建指定父节点的分支分页器 |
|
|
422
|
+
| `clear()` | 清空会话到 root |
|
|
423
|
+
| `systemPrompt` | 读取或设置系统提示 |
|
|
424
|
+
| `toJSON()` / `fromJSON()` | 序列化与恢复 |
|
|
425
|
+
|
|
426
|
+
## Tool:工具系统
|
|
427
|
+
|
|
428
|
+
工具让模型可以调用你的 TypeScript 函数。AgentEngine 的工具系统包含四层:
|
|
429
|
+
|
|
430
|
+
- `Param`:定义参数 JSON Schema。
|
|
431
|
+
- `Tool`:定义函数、名称、描述、参数和生命周期 Hook。
|
|
432
|
+
- `ToolKit`:注册多个工具,并根据模型的 `tool_call` 执行对应函数。
|
|
433
|
+
- `Context`:工具执行期间共享的上下文,可读写参数、结果和错误。
|
|
434
|
+
|
|
435
|
+
### 定义第一个工具
|
|
436
|
+
|
|
437
|
+
```ts
|
|
438
|
+
import { Param, Tool, ToolKit } from "@notic/agent-engine";
|
|
439
|
+
|
|
440
|
+
const getWeather = Tool.create(async (args) => {
|
|
441
|
+
const city = args.city as string;
|
|
442
|
+
return { city, temperature: 21, unit: "celsius" };
|
|
443
|
+
})
|
|
444
|
+
.name("get_weather")
|
|
445
|
+
.description("查询城市天气")
|
|
446
|
+
.params(
|
|
447
|
+
Param.string("city").desc("城市名称,例如北京").required(),
|
|
448
|
+
Param.string("unit").desc("温度单位").enum(["celsius", "fahrenheit"])
|
|
449
|
+
)
|
|
450
|
+
.build();
|
|
451
|
+
|
|
452
|
+
const toolkit = new ToolKit().add(getWeather);
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
传给 Agent:
|
|
456
|
+
|
|
457
|
+
```ts
|
|
458
|
+
const agent = new Agent({
|
|
459
|
+
client,
|
|
460
|
+
model: "your-model",
|
|
461
|
+
session: Session.create("你可以在需要时调用工具。"),
|
|
462
|
+
toolkit,
|
|
463
|
+
});
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
当模型返回工具调用时,Agent 会自动:
|
|
467
|
+
|
|
468
|
+
1. 解析 `tool_call`
|
|
469
|
+
2. 审批工具调用
|
|
470
|
+
3. 调用 `ToolKit.execute()`
|
|
471
|
+
4. 把工具结果作为 `tool` 消息写回 `Session`
|
|
472
|
+
5. 再次请求模型生成最终答案
|
|
473
|
+
|
|
474
|
+
### 参数定义 Param
|
|
475
|
+
|
|
476
|
+
```ts
|
|
477
|
+
import { ValueType } from "@notic/agent-engine";
|
|
478
|
+
|
|
479
|
+
Param.string("name").required().desc("姓名");
|
|
480
|
+
Param.integer("age").desc("年龄");
|
|
481
|
+
Param.number("score");
|
|
482
|
+
Param.boolean("enabled");
|
|
483
|
+
Param.array("tags", ValueType.String);
|
|
484
|
+
Param.object("range", [
|
|
485
|
+
Param.number("min").required(),
|
|
486
|
+
Param.number("max").required(),
|
|
487
|
+
]);
|
|
488
|
+
```
|
|
489
|
+
|
|
490
|
+
数组元素可以是基本类型,也可以是对象参数:
|
|
491
|
+
|
|
492
|
+
```ts
|
|
493
|
+
const items = Param.array("items", [
|
|
494
|
+
Param.string("title").required(),
|
|
495
|
+
Param.integer("count").required(),
|
|
496
|
+
]);
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
### 生命周期 Hook
|
|
500
|
+
|
|
501
|
+
Hook 让你在工具执行的不同阶段插入逻辑:
|
|
502
|
+
|
|
503
|
+
```ts
|
|
504
|
+
import { Hook } from "@notic/agent-engine";
|
|
505
|
+
|
|
506
|
+
const tool = Tool.create(async (args) => {
|
|
507
|
+
return { ok: true, args };
|
|
508
|
+
})
|
|
509
|
+
.name("save")
|
|
510
|
+
.description("保存数据")
|
|
511
|
+
.params(Param.string("content").required())
|
|
512
|
+
.on(Hook.ON_VALIDATE, (ctx) => {
|
|
513
|
+
if ((ctx.arguments.content as string).length === 0) {
|
|
514
|
+
throw new Error("content 不能为空");
|
|
515
|
+
}
|
|
516
|
+
})
|
|
517
|
+
.on(Hook.AFTER_EXECUTE, (ctx) => {
|
|
518
|
+
ctx.result = { ...ctx.result as object, savedAt: new Date().toISOString() };
|
|
519
|
+
})
|
|
520
|
+
.on(Hook.ON_ERROR, (ctx) => {
|
|
521
|
+
ctx.result = { ok: false, error: ctx.error?.message };
|
|
522
|
+
})
|
|
523
|
+
.build();
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
Hook 顺序:
|
|
527
|
+
|
|
528
|
+
```text
|
|
529
|
+
ON_CREATE -> ON_VALIDATE -> BEFORE_EXECUTE -> function -> AFTER_EXECUTE -> ON_SERIALIZE
|
|
530
|
+
\-> ON_ERROR
|
|
531
|
+
```
|
|
532
|
+
|
|
533
|
+
常用 Hook:
|
|
534
|
+
|
|
535
|
+
| Hook | 用途 |
|
|
536
|
+
| --- | --- |
|
|
537
|
+
| `ON_CREATE` | 工具调用对象创建后 |
|
|
538
|
+
| `ON_VALIDATE` | 内置必填校验前后做额外校验 |
|
|
539
|
+
| `BEFORE_EXECUTE` | 真正执行函数前 |
|
|
540
|
+
| `AFTER_EXECUTE` | 函数成功执行后,可改写结果 |
|
|
541
|
+
| `ON_SERIALIZE` | 转成 `Message.tool()` 前 |
|
|
542
|
+
| `ON_ERROR` | 校验或执行出错时,可设置 fallback result |
|
|
543
|
+
|
|
544
|
+
### Context
|
|
545
|
+
|
|
546
|
+
工具函数和 Hook 都能访问 `Context`:
|
|
547
|
+
|
|
548
|
+
```ts
|
|
549
|
+
const tool = Tool.create(async (args, ctx) => {
|
|
550
|
+
ctx.throwIfAborted();
|
|
551
|
+
ctx.result = { ok: true };
|
|
552
|
+
return ctx.result;
|
|
553
|
+
});
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
常用字段:
|
|
557
|
+
|
|
558
|
+
- `ctx.id`
|
|
559
|
+
- `ctx.name`
|
|
560
|
+
- `ctx.arguments`
|
|
561
|
+
- `ctx.result`
|
|
562
|
+
- `ctx.error`
|
|
563
|
+
- `ctx.cancelled`
|
|
564
|
+
- `ctx.cancelReason`
|
|
565
|
+
- `ctx.signal`
|
|
566
|
+
- `ctx.cancel(reason)`
|
|
567
|
+
- `ctx.throwIfAborted()`
|
|
568
|
+
|
|
569
|
+
### ToolKit 执行工具
|
|
570
|
+
|
|
571
|
+
```ts
|
|
572
|
+
const result = await toolkit.execute({
|
|
573
|
+
type: "tool_call",
|
|
574
|
+
toolCallId: "call_1",
|
|
575
|
+
name: "get_weather",
|
|
576
|
+
arguments: "{\"city\":\"北京\"}",
|
|
577
|
+
});
|
|
578
|
+
|
|
579
|
+
console.log(result.text);
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
执行多个工具:
|
|
583
|
+
|
|
584
|
+
```ts
|
|
585
|
+
const results = await toolkit.executeAll(toolCalls);
|
|
586
|
+
```
|
|
587
|
+
|
|
588
|
+
错误策略:
|
|
589
|
+
|
|
590
|
+
```ts
|
|
591
|
+
await toolkit.execute(toolCall, { errorPolicy: "return_to_model" });
|
|
592
|
+
await toolkit.execute(toolCall, { errorPolicy: "throw" });
|
|
593
|
+
```
|
|
594
|
+
|
|
595
|
+
- `return_to_model`:工具异常会转成模型可读的 tool result。
|
|
596
|
+
- `throw`:抛出 `ToolExecutionError`。
|
|
597
|
+
|
|
598
|
+
### MCP 工具
|
|
599
|
+
|
|
600
|
+
如果你使用 Model Context Protocol,可以把 MCP client 的工具导入 `ToolKit`:
|
|
601
|
+
|
|
602
|
+
```ts
|
|
603
|
+
await toolkit.addMCP(mcpClient);
|
|
604
|
+
```
|
|
605
|
+
|
|
606
|
+
MCP client 需要提供:
|
|
607
|
+
|
|
608
|
+
```ts
|
|
609
|
+
interface McpClientLike {
|
|
610
|
+
listTools(): Promise<{
|
|
611
|
+
tools: Array<{
|
|
612
|
+
name: string;
|
|
613
|
+
description?: string;
|
|
614
|
+
inputSchema: Record<string, unknown>;
|
|
615
|
+
}>;
|
|
616
|
+
}>;
|
|
617
|
+
|
|
618
|
+
callTool(params: {
|
|
619
|
+
name: string;
|
|
620
|
+
arguments?: Record<string, unknown>;
|
|
621
|
+
}): Promise<{
|
|
622
|
+
content: Array<{ type: string; text?: string }>;
|
|
623
|
+
}>;
|
|
624
|
+
}
|
|
625
|
+
```
|
|
626
|
+
|
|
627
|
+
### Tool API 摘要
|
|
628
|
+
|
|
629
|
+
| API | 说明 |
|
|
630
|
+
| --- | --- |
|
|
631
|
+
| `Tool.create(fn)` | 创建工具 builder |
|
|
632
|
+
| `Tool.fromRaw(name, desc, schema, fn)` | 从已有 schema 创建工具 |
|
|
633
|
+
| `tool.name(name)` | 设置工具名 |
|
|
634
|
+
| `tool.description(desc)` | 设置描述 |
|
|
635
|
+
| `tool.params(...params)` | 添加参数 |
|
|
636
|
+
| `tool.on(hook, handler)` | 注册 Hook |
|
|
637
|
+
| `tool.build()` | 冻结 schema,进入运行态 |
|
|
638
|
+
| `tool.schema` | OpenAI tools schema |
|
|
639
|
+
| `tool.create(id, args, signal?)` | 创建一次具体工具调用 |
|
|
640
|
+
| `new ToolKit().add(...tools)` | 注册工具 |
|
|
641
|
+
| `toolkit.schemas` | 所有工具 schema |
|
|
642
|
+
| `toolkit.execute(call, options?)` | 执行单个工具调用 |
|
|
643
|
+
| `toolkit.executeAll(calls, options?)` | 执行多个工具调用 |
|
|
644
|
+
|
|
645
|
+
## Stream:流式事件
|
|
646
|
+
|
|
647
|
+
`StreamParser` 把 OpenAI-compatible 的流式 chunk 解析成结构化事件。你通常不需要手动使用它,因为 `Agent` 已经内置;但写底层测试、自定义客户端或调试流式协议时很有用。
|
|
648
|
+
|
|
649
|
+
### 手动解析 stream
|
|
650
|
+
|
|
651
|
+
```ts
|
|
652
|
+
import { StreamParser, StreamEventType } from "@notic/agent-engine";
|
|
653
|
+
|
|
654
|
+
const parser = new StreamParser();
|
|
655
|
+
|
|
656
|
+
for await (const chunk of stream) {
|
|
657
|
+
const events = parser.feed(chunk);
|
|
658
|
+
|
|
659
|
+
for (const event of events) {
|
|
660
|
+
if (event.type === StreamEventType.TEXT_DELTA) {
|
|
661
|
+
process.stdout.write(event.delta);
|
|
662
|
+
}
|
|
663
|
+
}
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
const finalEvents = parser.finish();
|
|
667
|
+
const done = finalEvents.find((event) => event.type === StreamEventType.MESSAGE_DONE);
|
|
668
|
+
console.log(done?.message.text);
|
|
669
|
+
```
|
|
670
|
+
|
|
671
|
+
### 支持的增量内容
|
|
672
|
+
|
|
673
|
+
`StreamParser` 支持:
|
|
674
|
+
|
|
675
|
+
- `delta.content`:文本
|
|
676
|
+
- `delta.reasoning_content`:DeepSeek / Qwen 等推理内容
|
|
677
|
+
- `delta.thinking`:Claude-like thinking 内容
|
|
678
|
+
- `delta.tool_calls`:工具调用增量
|
|
679
|
+
- `usage`:stream usage chunk
|
|
680
|
+
|
|
681
|
+
### 常用事件
|
|
682
|
+
|
|
683
|
+
| 事件 | 触发时机 |
|
|
684
|
+
| --- | --- |
|
|
685
|
+
| `TEXT_DELTA` | 收到文本增量 |
|
|
686
|
+
| `TEXT_DONE` | 文本流结束 |
|
|
687
|
+
| `THINKING_DELTA` | 收到思考增量 |
|
|
688
|
+
| `THINKING_DONE` | 思考流结束 |
|
|
689
|
+
| `TOOL_CALL_START` | 第一次拿到工具调用 id 和 name |
|
|
690
|
+
| `TOOL_CALL_DELTA` | 收到工具参数增量 |
|
|
691
|
+
| `TOOL_CALL_DONE` | 工具调用参数组装完成 |
|
|
692
|
+
| `MESSAGE_DONE` | 完整 assistant message 组装完成 |
|
|
693
|
+
| `ERROR` | chunk 解析异常 |
|
|
694
|
+
|
|
695
|
+
`Agent` 会额外派发:
|
|
696
|
+
|
|
697
|
+
| 事件 | 触发时机 |
|
|
698
|
+
| --- | --- |
|
|
699
|
+
| `TURN_START` | 新一轮模型调用开始 |
|
|
700
|
+
| `TURN_END` | 一轮模型调用结束 |
|
|
701
|
+
| `TOOL_APPROVAL_REQUIRED` | 工具调用需要审批 |
|
|
702
|
+
| `TOOL_APPROVAL_ACCEPTED` | 工具调用审批通过 |
|
|
703
|
+
| `TOOL_APPROVAL_REJECTED` | 工具调用审批拒绝 |
|
|
704
|
+
| `TOOL_EXECUTE_START` | 工具开始执行 |
|
|
705
|
+
| `TOOL_EXECUTE_DONE` | 工具执行完成 |
|
|
706
|
+
| `TOOL_EXECUTE_ERROR` | 工具执行失败 |
|
|
707
|
+
| `BEFORE_ASSISTANT_COMMIT` | Assistant 写入 Session 前;监听器会按注册顺序等待完成 |
|
|
708
|
+
|
|
709
|
+
## Prompt:提示词构建
|
|
710
|
+
|
|
711
|
+
`PromptBuilder` 用来在模型请求前动态改写上下文。它不会修改原始 `Session`,而是基于 `history` 生成一个临时消息数组。
|
|
712
|
+
|
|
713
|
+
适合这些场景:
|
|
714
|
+
|
|
715
|
+
- 在最近一条用户消息前插入临时规则。
|
|
716
|
+
- 在系统提示后追加运行时上下文。
|
|
717
|
+
- 按标签、角色、内容定位消息,然后插入补充说明。
|
|
718
|
+
- 在发送模型前过滤、裁剪或改写历史。
|
|
719
|
+
|
|
720
|
+
### 注入一条系统提示
|
|
721
|
+
|
|
722
|
+
```ts
|
|
723
|
+
import { PromptBuilder, Rule } from "@notic/agent-engine";
|
|
724
|
+
|
|
725
|
+
const builder = new PromptBuilder();
|
|
726
|
+
|
|
727
|
+
builder.injectSystem(
|
|
728
|
+
Rule.top().after(),
|
|
729
|
+
"运行时上下文:当前用户是高级开发者。"
|
|
730
|
+
);
|
|
731
|
+
|
|
732
|
+
const context = builder.build(session.history());
|
|
733
|
+
```
|
|
734
|
+
|
|
735
|
+
`Rule.top().after()` 的意思是:定位到第一条消息,在它后面插入。
|
|
736
|
+
|
|
737
|
+
### 按角色定位
|
|
738
|
+
|
|
739
|
+
```ts
|
|
740
|
+
import { Role } from "@notic/agent-engine";
|
|
741
|
+
|
|
742
|
+
builder.injectSystem(
|
|
743
|
+
Rule.byRole(Role.User).last().before(),
|
|
744
|
+
"请优先回答用户最近的问题。"
|
|
745
|
+
);
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
### 按内容或标签定位
|
|
749
|
+
|
|
750
|
+
```ts
|
|
751
|
+
builder.injectAssistant(
|
|
752
|
+
Rule.byContent(["数据库", "迁移"]).after(),
|
|
753
|
+
"已检测到数据库迁移相关上下文。"
|
|
754
|
+
);
|
|
755
|
+
|
|
756
|
+
builder.injectSystem(
|
|
757
|
+
Rule.byTags(["important"]).before(),
|
|
758
|
+
"下面是一条重要消息。"
|
|
759
|
+
);
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
### 生命周期、概率和优先级
|
|
763
|
+
|
|
764
|
+
```ts
|
|
765
|
+
builder.injectSystem(Rule.top().before(), "只生效一次", {
|
|
766
|
+
life: 1,
|
|
767
|
+
probability: 1,
|
|
768
|
+
priority: 10,
|
|
769
|
+
});
|
|
770
|
+
```
|
|
771
|
+
|
|
772
|
+
- `life: -1`:永久有效。
|
|
773
|
+
- `life: 1`:触发并构建一次后过期。
|
|
774
|
+
- `probability`:0 到 1,控制是否触发。
|
|
775
|
+
- `priority`:多个 injection 的执行优先级,数值越小越早执行。
|
|
776
|
+
|
|
777
|
+
清理过期 injection:
|
|
778
|
+
|
|
779
|
+
```ts
|
|
780
|
+
builder.prune();
|
|
781
|
+
```
|
|
782
|
+
|
|
783
|
+
### batch 与 immediate
|
|
784
|
+
|
|
785
|
+
`build()` 默认使用 `batch`:
|
|
786
|
+
|
|
787
|
+
```ts
|
|
788
|
+
builder.build(history, { strategy: "batch" });
|
|
789
|
+
```
|
|
790
|
+
|
|
791
|
+
- `batch`:所有 injection 都基于原始 history 定位。
|
|
792
|
+
- `immediate`:后面的 injection 能看到前面 injection 插入后的结果。
|
|
793
|
+
|
|
794
|
+
例子:
|
|
795
|
+
|
|
796
|
+
```ts
|
|
797
|
+
builder.injectSystem(Rule.bottom().after(), "第一条");
|
|
798
|
+
builder.injectSystem(Rule.byContent(["第一条"]).after(), "第二条");
|
|
799
|
+
|
|
800
|
+
builder.build(history, { strategy: "batch" }); // 第二条找不到第一条
|
|
801
|
+
builder.build(history, { strategy: "immediate" }); // 第二条能插入到第一条后面
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
### 数组操作管线
|
|
805
|
+
|
|
806
|
+
除了 injection,`PromptBuilder` 还可以像数组管线一样改写上下文:
|
|
807
|
+
|
|
808
|
+
```ts
|
|
809
|
+
builder
|
|
810
|
+
.filter((msg) => msg.text.length > 0)
|
|
811
|
+
.slice(-20)
|
|
812
|
+
.map((msg) => msg)
|
|
813
|
+
.insertAt(0, Message.system("最高优先级规则"));
|
|
814
|
+
|
|
815
|
+
const context = builder.build(session.history());
|
|
816
|
+
```
|
|
817
|
+
|
|
818
|
+
常用操作:
|
|
819
|
+
|
|
820
|
+
```ts
|
|
821
|
+
builder.use((messages) => messages);
|
|
822
|
+
builder.insertAt(index, message);
|
|
823
|
+
builder.removeAt(index, count);
|
|
824
|
+
builder.removeWhere((msg) => msg.hasTag("debug"));
|
|
825
|
+
builder.replaceWhere((msg) => msg.hasTag("old"), Message.system("new"));
|
|
826
|
+
builder.filter((msg) => msg.role !== Role.Tool);
|
|
827
|
+
builder.slice(-10);
|
|
828
|
+
builder.map((msg) => msg);
|
|
829
|
+
builder.transform((messages) => messages.reverse());
|
|
830
|
+
```
|
|
831
|
+
|
|
832
|
+
### Rule API 摘要
|
|
833
|
+
|
|
834
|
+
| API | 说明 |
|
|
835
|
+
| --- | --- |
|
|
836
|
+
| `Rule.top()` | 定位第一条消息 |
|
|
837
|
+
| `Rule.bottom()` | 定位最后一条消息 |
|
|
838
|
+
| `Rule.index(n)` | 定位指定索引,支持负数 |
|
|
839
|
+
| `Rule.byRole(role)` | 按角色定位 |
|
|
840
|
+
| `Rule.byContent(keywords, options?)` | 按内容关键词定位 |
|
|
841
|
+
| `Rule.byTags(tags)` | 按标签定位 |
|
|
842
|
+
| `Rule.by(fn)` | 自定义谓词 |
|
|
843
|
+
| `first()` / `last()` / `all()` | 匹配策略 |
|
|
844
|
+
| `before()` / `after()` | 插入方向 |
|
|
845
|
+
| `offset(n)` | 在匹配点上偏移 |
|
|
846
|
+
| `order(n)` | 同插入点展示顺序 |
|
|
847
|
+
| `scanDepth(n)` | 限制扫描深度 |
|
|
848
|
+
| `scanForward()` / `scanReverse()` | 扫描方向 |
|
|
849
|
+
| `resolve(messages)` | 返回插入索引 |
|
|
850
|
+
|
|
851
|
+
### PromptBuilder API 摘要
|
|
852
|
+
|
|
853
|
+
| API | 说明 |
|
|
854
|
+
| --- | --- |
|
|
855
|
+
| `inject(rule, message, options?)` | 注入任意消息 |
|
|
856
|
+
| `injectSystem(rule, content, options?)` | 注入 system 消息 |
|
|
857
|
+
| `injectUser(rule, content, options?)` | 注入 user 消息 |
|
|
858
|
+
| `injectAssistant(rule, content, options?)` | 注入 assistant 消息 |
|
|
859
|
+
| `injectAll(rule, messages, options?)` | 批量注入 |
|
|
860
|
+
| `remove(injection)` / `removeById(id)` / `removeByRule(rule)` | 删除 injection |
|
|
861
|
+
| `enable(injection)` / `disable(injection)` | 启用或禁用 |
|
|
862
|
+
| `clearInjections()` | 清空 injection |
|
|
863
|
+
| `clearOperations()` | 清空操作管线 |
|
|
864
|
+
| `clear()` | 清空 injection 和 operation |
|
|
865
|
+
| `build(history, options?)` | 生成临时上下文 |
|
|
866
|
+
| `buildBatch(history)` | batch 构建 |
|
|
867
|
+
| `buildImmediate(history)` | immediate 构建 |
|
|
868
|
+
|
|
869
|
+
## Config:请求参数
|
|
870
|
+
|
|
871
|
+
`RequestConfig` 用链式 API 构建模型请求参数。
|
|
872
|
+
|
|
873
|
+
```ts
|
|
874
|
+
import { RequestConfig } from "@notic/agent-engine";
|
|
875
|
+
|
|
876
|
+
const config = RequestConfig.create()
|
|
877
|
+
.temperature(0.3)
|
|
878
|
+
.topP(0.9)
|
|
879
|
+
.maxTokens(1024)
|
|
880
|
+
.stop("\n\nEND")
|
|
881
|
+
.seed(42);
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
传给 Agent:
|
|
885
|
+
|
|
886
|
+
```ts
|
|
887
|
+
const agent = new Agent({
|
|
888
|
+
client,
|
|
889
|
+
model: "your-model",
|
|
890
|
+
session,
|
|
891
|
+
config,
|
|
892
|
+
});
|
|
893
|
+
```
|
|
894
|
+
|
|
895
|
+
### 预设
|
|
896
|
+
|
|
897
|
+
```ts
|
|
898
|
+
RequestConfig.precise(); // 低温度,偏稳定
|
|
899
|
+
RequestConfig.balanced(); // 平衡
|
|
900
|
+
RequestConfig.creative(); // 高温度,偏发散
|
|
901
|
+
```
|
|
902
|
+
|
|
903
|
+
### 自定义参数
|
|
904
|
+
|
|
905
|
+
不同平台可能有额外字段,用 `set()`:
|
|
906
|
+
|
|
907
|
+
```ts
|
|
908
|
+
const config = RequestConfig.create()
|
|
909
|
+
.set("response_format", { type: "json_object" })
|
|
910
|
+
.set("parallel_tool_calls", false);
|
|
911
|
+
```
|
|
912
|
+
|
|
913
|
+
常用内置方法:
|
|
914
|
+
|
|
915
|
+
```ts
|
|
916
|
+
config.temperature(0.7);
|
|
917
|
+
config.topP(0.95);
|
|
918
|
+
config.topK(40);
|
|
919
|
+
config.maxTokens(2048);
|
|
920
|
+
config.frequencyPenalty(0.2);
|
|
921
|
+
config.presencePenalty(0.2);
|
|
922
|
+
config.stop("END");
|
|
923
|
+
config.seed(123);
|
|
924
|
+
config.responseFormat("json_object");
|
|
925
|
+
config.unset("seed");
|
|
926
|
+
```
|
|
927
|
+
|
|
928
|
+
### 参数优先级
|
|
929
|
+
|
|
930
|
+
一次 Agent 请求最终参数按这个顺序合并,后者覆盖前者:
|
|
931
|
+
|
|
932
|
+
```text
|
|
933
|
+
RequestConfig -> Agent.requestOptions -> agent.run(..., runOptions)
|
|
934
|
+
```
|
|
935
|
+
|
|
936
|
+
例子:
|
|
937
|
+
|
|
938
|
+
```ts
|
|
939
|
+
const agent = new Agent({
|
|
940
|
+
client,
|
|
941
|
+
model: "your-model",
|
|
942
|
+
session,
|
|
943
|
+
config: RequestConfig.create().temperature(0.2),
|
|
944
|
+
requestOptions: { temperature: 0.5 },
|
|
945
|
+
});
|
|
946
|
+
|
|
947
|
+
await agent.run("这一轮更发散一点", { temperature: 1.0 });
|
|
948
|
+
```
|
|
949
|
+
|
|
950
|
+
最终 `temperature` 是 `1.0`。
|
|
951
|
+
|
|
952
|
+
### Config API 摘要
|
|
953
|
+
|
|
954
|
+
| API | 说明 |
|
|
955
|
+
| --- | --- |
|
|
956
|
+
| `RequestConfig.create()` | 空配置 |
|
|
957
|
+
| `precise()` / `balanced()` / `creative()` | 预设 |
|
|
958
|
+
| `temperature(n)` | 温度,自动 clamp 到 0-2 |
|
|
959
|
+
| `topP(n)` | top_p,自动 clamp 到 0-1 |
|
|
960
|
+
| `topK(n)` | top_k,最小为 1 |
|
|
961
|
+
| `maxTokens(n)` | max_tokens,最小为 1 |
|
|
962
|
+
| `frequencyPenalty(n)` / `presencePenalty(n)` | 惩罚参数 |
|
|
963
|
+
| `stop(...seq)` | 停止序列,最多保留 4 个 |
|
|
964
|
+
| `seed(n)` | 随机种子 |
|
|
965
|
+
| `responseFormat(format, schema?)` | 响应格式 |
|
|
966
|
+
| `set(key, value)` | 自定义字段 |
|
|
967
|
+
| `unset(key)` | 删除字段 |
|
|
968
|
+
| `merge(other)` | 合并配置 |
|
|
969
|
+
| `clone()` | 克隆 |
|
|
970
|
+
| `build()` | 输出普通对象 |
|
|
971
|
+
|
|
972
|
+
## Provider:平台能力组合
|
|
973
|
+
|
|
974
|
+
Provider 是 AgentEngine 的平台边界。它不拥有 Agent 的 Session、工具循环或运行状态,
|
|
975
|
+
只组合三个可以独立替换的组件:
|
|
976
|
+
|
|
977
|
+
```text
|
|
978
|
+
Provider
|
|
979
|
+
├─ ModelClient 发送请求,返回 stream 或完整响应
|
|
980
|
+
├─ MessageAdapter Message[] <-> 平台请求/响应
|
|
981
|
+
└─ MessageStreamParser 平台 stream -> 统一事件和 Message
|
|
982
|
+
```
|
|
983
|
+
|
|
984
|
+
因此接入新平台时,不需要在 `Agent` 中增加平台判断。只需提供对应的 Client、Adapter
|
|
985
|
+
和 Parser,并保证最终仍然使用统一 `Message`。
|
|
986
|
+
|
|
987
|
+
### OpenAI Compatible Provider
|
|
988
|
+
|
|
989
|
+
适用于 OpenAI Chat Completions,以及 DeepSeek、Qwen、Kimi、GLM 等兼容接口:
|
|
990
|
+
|
|
991
|
+
```ts
|
|
992
|
+
import OpenAI from "openai";
|
|
993
|
+
import {
|
|
994
|
+
Agent,
|
|
995
|
+
OpenAICompatibleProvider,
|
|
996
|
+
Session,
|
|
997
|
+
} from "@notic/agent-engine";
|
|
998
|
+
|
|
999
|
+
const client = new OpenAI({
|
|
1000
|
+
apiKey: process.env.PROVIDER_API_KEY,
|
|
1001
|
+
baseURL: "https://your-provider.example/v1",
|
|
1002
|
+
});
|
|
1003
|
+
|
|
1004
|
+
const agent = new Agent({
|
|
1005
|
+
provider: new OpenAICompatibleProvider(client),
|
|
1006
|
+
model: "your-model",
|
|
1007
|
+
session: Session.create(),
|
|
1008
|
+
});
|
|
1009
|
+
```
|
|
1010
|
+
|
|
1011
|
+
为了兼容旧代码,也可以继续直接传 `client`。此时 Agent 默认使用
|
|
1012
|
+
`OpenAIAdapter + StreamParser`。
|
|
1013
|
+
|
|
1014
|
+
### OpenAI Responses Provider
|
|
1015
|
+
|
|
1016
|
+
```ts
|
|
1017
|
+
import OpenAI from "openai";
|
|
1018
|
+
import { Agent, OpenAIResponsesProvider, Session } from "@notic/agent-engine";
|
|
1019
|
+
|
|
1020
|
+
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
|
|
1021
|
+
const agent = new Agent({
|
|
1022
|
+
provider: new OpenAIResponsesProvider(client),
|
|
1023
|
+
model: "your-openai-model",
|
|
1024
|
+
session: Session.create(),
|
|
1025
|
+
});
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
该 Provider 使用原生 Responses API,并支持:
|
|
1029
|
+
|
|
1030
|
+
- `response.output_text.*` 文本事件
|
|
1031
|
+
- reasoning summary 与 encrypted reasoning item 回传
|
|
1032
|
+
- `function_call` / `function_call_output` 工具循环
|
|
1033
|
+
- `max_output_tokens`、结构化输出和 usage
|
|
1034
|
+
- 流式及非流式完整响应
|
|
1035
|
+
|
|
1036
|
+
### Anthropic Provider
|
|
1037
|
+
|
|
1038
|
+
```ts
|
|
1039
|
+
import Anthropic from "@anthropic-ai/sdk";
|
|
1040
|
+
import { Agent, AnthropicProvider, Session } from "@notic/agent-engine";
|
|
1041
|
+
|
|
1042
|
+
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
|
|
1043
|
+
const agent = new Agent({
|
|
1044
|
+
provider: new AnthropicProvider(client),
|
|
1045
|
+
model: "your-claude-model",
|
|
1046
|
+
session: Session.create(),
|
|
1047
|
+
});
|
|
1048
|
+
```
|
|
1049
|
+
|
|
1050
|
+
Anthropic Provider 使用原生 Messages API,处理 system 提取、content blocks、thinking
|
|
1051
|
+
signature、tool use 和原生 usage。
|
|
1052
|
+
|
|
1053
|
+
### Gemini Provider
|
|
1054
|
+
|
|
1055
|
+
```ts
|
|
1056
|
+
import { GoogleGenAI } from "@google/genai";
|
|
1057
|
+
import { Agent, GeminiProvider, Session } from "@notic/agent-engine";
|
|
1058
|
+
|
|
1059
|
+
const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
|
|
1060
|
+
const agent = new Agent({
|
|
1061
|
+
provider: new GeminiProvider(client),
|
|
1062
|
+
model: "your-gemini-model",
|
|
1063
|
+
session: Session.create(),
|
|
1064
|
+
});
|
|
1065
|
+
```
|
|
1066
|
+
|
|
1067
|
+
Gemini Provider 使用 `generateContentStream()` 和 `generateContent()`,处理 contents、
|
|
1068
|
+
systemInstruction、functionCall、functionResponse 和 thought signature。
|
|
1069
|
+
|
|
1070
|
+
### 流式与非流式
|
|
1071
|
+
|
|
1072
|
+
内置 Provider 同时支持两种运行方式:
|
|
1073
|
+
|
|
1074
|
+
```ts
|
|
1075
|
+
// 默认:增量事件
|
|
1076
|
+
const streamed = await agent.run("介绍一下这个项目");
|
|
1077
|
+
|
|
1078
|
+
// 完整响应:不经过 StreamParser
|
|
1079
|
+
const completed = await agent.run("介绍一下这个项目", {
|
|
1080
|
+
stream: false,
|
|
1081
|
+
});
|
|
1082
|
+
```
|
|
1083
|
+
|
|
1084
|
+
非流式模式仍然经过统一 Adapter,并保留 Session、PromptBuilder、工具审批、工具执行、
|
|
1085
|
+
自动多轮循环、timeout、abort、model 和 usage。它不产生 `TEXT_DELTA`,但会产生
|
|
1086
|
+
`TEXT_DONE`、`TOOL_CALL_DONE` 和 `MESSAGE_DONE`。
|
|
1087
|
+
|
|
1088
|
+
```ts
|
|
1089
|
+
provider.supportsComplete; // ModelClient 是否实现 complete()
|
|
1090
|
+
```
|
|
1091
|
+
|
|
1092
|
+
### 自定义 Provider
|
|
1093
|
+
|
|
1094
|
+
自定义 Client 只负责传输,不需要认识 Message、Session 或 Tool:
|
|
1095
|
+
|
|
1096
|
+
```ts
|
|
1097
|
+
import {
|
|
1098
|
+
Agent,
|
|
1099
|
+
ModelClient,
|
|
1100
|
+
Provider,
|
|
1101
|
+
Session,
|
|
1102
|
+
} from "@notic/agent-engine";
|
|
1103
|
+
|
|
1104
|
+
const client: ModelClient = {
|
|
1105
|
+
async stream(request, options) {
|
|
1106
|
+
return mySdk.createStream(request, { signal: options?.signal });
|
|
1107
|
+
},
|
|
1108
|
+
async complete(request, options) {
|
|
1109
|
+
return mySdk.create(request, { signal: options?.signal });
|
|
1110
|
+
},
|
|
1111
|
+
};
|
|
1112
|
+
|
|
1113
|
+
const provider = Provider.create({
|
|
1114
|
+
client,
|
|
1115
|
+
adapter: new MyAdapter(),
|
|
1116
|
+
parserFactory: () => new MyStreamParser(),
|
|
1117
|
+
});
|
|
1118
|
+
|
|
1119
|
+
const agent = new Agent({
|
|
1120
|
+
provider,
|
|
1121
|
+
model: "my-model",
|
|
1122
|
+
session: Session.create(),
|
|
1123
|
+
});
|
|
1124
|
+
```
|
|
1125
|
+
|
|
1126
|
+
`ModelClient.complete()` 是可选能力。只实现 `stream()` 的自定义 Provider 仍然兼容,
|
|
1127
|
+
但调用 `{ stream: false }` 时会收到明确错误。显式传给 Agent 的 `client`、`adapter`
|
|
1128
|
+
或 `parserFactory` 会覆盖 Provider 中的对应预设。
|
|
1129
|
+
|
|
1130
|
+
## Adapter:平台适配
|
|
1131
|
+
|
|
1132
|
+
AgentEngine 内部统一使用 `Message`,但不同平台请求格式不同。`Adapter` 负责把 `Message[]` 转成平台格式,也可以把平台响应转回 `Message`。
|
|
1133
|
+
|
|
1134
|
+
内置适配器:
|
|
1135
|
+
|
|
1136
|
+
| 适配器 | 常见平台 |
|
|
1137
|
+
| --- | --- |
|
|
1138
|
+
| `OpenAIAdapter` | OpenAI、DeepSeek、Qwen、Kimi、GLM 等 OpenAI-compatible API |
|
|
1139
|
+
| `AnthropicAdapter` | Claude Messages API |
|
|
1140
|
+
| `GeminiAdapter` | Gemini |
|
|
1141
|
+
|
|
1142
|
+
`Agent` 默认使用 `OpenAIAdapter`。
|
|
1143
|
+
|
|
1144
|
+
### 手动指定适配器
|
|
1145
|
+
|
|
1146
|
+
```ts
|
|
1147
|
+
import { Agent, OpenAIAdapter } from "@notic/agent-engine";
|
|
1148
|
+
|
|
1149
|
+
const agent = new Agent({
|
|
1150
|
+
client,
|
|
1151
|
+
model: "your-model",
|
|
1152
|
+
session,
|
|
1153
|
+
adapter: new OpenAIAdapter(),
|
|
1154
|
+
});
|
|
1155
|
+
```
|
|
1156
|
+
|
|
1157
|
+
### 自定义 MediaResolver
|
|
1158
|
+
|
|
1159
|
+
多模态消息里可能有本地文件、HTTP 文件或 data URI。Adapter 可以接收媒体解析器。根入口默认使用浏览器安全的 `BrowserMediaResolver`;Node.js 读取本地文件时使用显式子入口:
|
|
1160
|
+
|
|
1161
|
+
```ts
|
|
1162
|
+
import { OpenAIAdapter } from "@notic/agent-engine";
|
|
1163
|
+
import { DefaultMediaResolver } from "@notic/agent-engine/node";
|
|
1164
|
+
|
|
1165
|
+
const adapter = new OpenAIAdapter(new DefaultMediaResolver());
|
|
1166
|
+
```
|
|
1167
|
+
|
|
1168
|
+
### 思考内容序列化
|
|
1169
|
+
|
|
1170
|
+
AgentEngine 支持 thinking / reasoning 内容。序列化时可以控制是否回传给模型:
|
|
1171
|
+
|
|
1172
|
+
```ts
|
|
1173
|
+
await agent.run("继续", {
|
|
1174
|
+
serializeOptions: {
|
|
1175
|
+
thinking: {
|
|
1176
|
+
mode: "auto",
|
|
1177
|
+
scope: "last",
|
|
1178
|
+
},
|
|
1179
|
+
},
|
|
1180
|
+
});
|
|
1181
|
+
```
|
|
1182
|
+
|
|
1183
|
+
`mode`:
|
|
1184
|
+
|
|
1185
|
+
- `none`:不序列化 thinking。
|
|
1186
|
+
- `native`:使用平台原生 thinking 字段。
|
|
1187
|
+
- `message`:把 thinking 放进文本消息。
|
|
1188
|
+
- `auto`:根据 adapter 能力自动选择。
|
|
1189
|
+
|
|
1190
|
+
`scope`:
|
|
1191
|
+
|
|
1192
|
+
- `none`:不包含。
|
|
1193
|
+
- `last`:只包含最后一条。
|
|
1194
|
+
- `tool_call`:工具调用相关场景包含。
|
|
1195
|
+
- `all`:全部包含。
|
|
1196
|
+
|
|
1197
|
+
DeepSeek / Qwen 等模型如果要求工具调用时回传 reasoning 内容,可以在 `run()` 时显式设置。
|
|
1198
|
+
|
|
1199
|
+
## Media:媒体解析
|
|
1200
|
+
|
|
1201
|
+
`MediaResolver` 用来把图片、音频、文件 URL 转成模型平台需要的 base64 / MIME 信息。
|
|
1202
|
+
|
|
1203
|
+
接口:
|
|
1204
|
+
|
|
1205
|
+
```ts
|
|
1206
|
+
interface MediaResolver {
|
|
1207
|
+
resolve(url: string): Promise<{
|
|
1208
|
+
mimeType: string;
|
|
1209
|
+
base64: string;
|
|
1210
|
+
}>;
|
|
1211
|
+
}
|
|
1212
|
+
```
|
|
1213
|
+
|
|
1214
|
+
浏览器默认实现:
|
|
1215
|
+
|
|
1216
|
+
```ts
|
|
1217
|
+
import { BrowserMediaResolver } from "@notic/agent-engine";
|
|
1218
|
+
|
|
1219
|
+
const resolver = new BrowserMediaResolver();
|
|
1220
|
+
const file = await resolver.resolve("https://example.com/image.png");
|
|
1221
|
+
```
|
|
1222
|
+
|
|
1223
|
+
`BrowserMediaResolver` 支持:
|
|
1224
|
+
|
|
1225
|
+
- `data:` URI
|
|
1226
|
+
- HTTP / HTTPS URL
|
|
1227
|
+
- `blob:` URL
|
|
1228
|
+
|
|
1229
|
+
Node.js 本地文件解析器:
|
|
1230
|
+
|
|
1231
|
+
```ts
|
|
1232
|
+
import { DefaultMediaResolver } from "@notic/agent-engine/node";
|
|
1233
|
+
|
|
1234
|
+
const resolver = new DefaultMediaResolver();
|
|
1235
|
+
const file = await resolver.resolve("./image.png");
|
|
1236
|
+
```
|
|
1237
|
+
|
|
1238
|
+
`DefaultMediaResolver` 额外支持:
|
|
1239
|
+
|
|
1240
|
+
- 本地文件路径
|
|
1241
|
+
|
|
1242
|
+
无法识别 MIME 时,会退回到 `application/octet-stream`。
|
|
1243
|
+
|
|
1244
|
+
## Agent:智能体编排
|
|
1245
|
+
|
|
1246
|
+
`Agent` 是最常用入口。它把 `Session`、`Adapter`、`StreamParser`、`ToolKit`、`PromptBuilder` 和 `RequestConfig` 串起来。
|
|
1247
|
+
|
|
1248
|
+
### 创建 Agent
|
|
1249
|
+
|
|
1250
|
+
```ts
|
|
1251
|
+
import OpenAI from "openai";
|
|
1252
|
+
import { Agent, RequestConfig, Session } from "@notic/agent-engine";
|
|
1253
|
+
|
|
1254
|
+
const client = new OpenAI({
|
|
1255
|
+
apiKey: process.env.OPENAI_API_KEY,
|
|
1256
|
+
});
|
|
1257
|
+
|
|
1258
|
+
const agent = new Agent({
|
|
1259
|
+
client,
|
|
1260
|
+
model: "gpt-4o-mini",
|
|
1261
|
+
session: Session.create("你是一个可靠的助手。"),
|
|
1262
|
+
config: RequestConfig.create().temperature(0.3).maxTokens(1024),
|
|
1263
|
+
maxTurns: 8,
|
|
1264
|
+
});
|
|
1265
|
+
```
|
|
1266
|
+
|
|
1267
|
+
`client` 只需要满足这个最小接口:
|
|
1268
|
+
|
|
1269
|
+
```ts
|
|
1270
|
+
interface OpenAIClientLike {
|
|
1271
|
+
chat: {
|
|
1272
|
+
completions: {
|
|
1273
|
+
create(params: any, options?: any): Promise<any>;
|
|
1274
|
+
};
|
|
1275
|
+
};
|
|
1276
|
+
}
|
|
1277
|
+
```
|
|
1278
|
+
|
|
1279
|
+
这意味着你可以传官方 `openai` SDK,也可以传自己的兼容客户端。
|
|
1280
|
+
|
|
1281
|
+
### 运行
|
|
1282
|
+
|
|
1283
|
+
```ts
|
|
1284
|
+
const reply = await agent.run("帮我写一个提交说明。");
|
|
1285
|
+
console.log(reply.text);
|
|
1286
|
+
```
|
|
1287
|
+
|
|
1288
|
+
默认使用流式请求。需要等待一次完整响应时,设置 `stream: false`:
|
|
1289
|
+
|
|
1290
|
+
```ts
|
|
1291
|
+
const reply = await agent.run("直接返回完整结果", {
|
|
1292
|
+
stream: false,
|
|
1293
|
+
});
|
|
1294
|
+
|
|
1295
|
+
console.log(reply.text);
|
|
1296
|
+
console.log(reply.usage);
|
|
1297
|
+
```
|
|
1298
|
+
|
|
1299
|
+
非流式模式仍然支持 Session 写入、工具自动循环、工具审批、超时和中断。
|
|
1300
|
+
它不会产生 `TEXT_DELTA` 等增量事件,但会产生 `TEXT_DONE`、`TOOL_CALL_DONE`
|
|
1301
|
+
和 `MESSAGE_DONE` 等完成事件。
|
|
1302
|
+
|
|
1303
|
+
内置 Provider 都支持非流式请求。自定义 Provider 可以通过
|
|
1304
|
+
`provider.supportsComplete` 检查其 `ModelClient` 是否实现了 `complete()`。
|
|
1305
|
+
|
|
1306
|
+
传入已构建的消息:
|
|
1307
|
+
|
|
1308
|
+
```ts
|
|
1309
|
+
const input = Message.user("这条消息带标签").tag("task");
|
|
1310
|
+
const reply = await agent.runWith(input);
|
|
1311
|
+
```
|
|
1312
|
+
|
|
1313
|
+
当前 `Session` 已经准备好上下文时,直接生成 Assistant,不追加 User 消息:
|
|
1314
|
+
|
|
1315
|
+
```ts
|
|
1316
|
+
session.addUser("预先构建的上下文");
|
|
1317
|
+
const reply = await agent.generate();
|
|
1318
|
+
```
|
|
1319
|
+
|
|
1320
|
+
不写入 `Session`,直接跑一次 raw 请求:
|
|
1321
|
+
|
|
1322
|
+
```ts
|
|
1323
|
+
const reply = await agent.runRaw([
|
|
1324
|
+
Message.system("你是一个 JSON 助手。"),
|
|
1325
|
+
Message.user("输出 {\"ok\":true}"),
|
|
1326
|
+
], { stream: false });
|
|
1327
|
+
```
|
|
1328
|
+
|
|
1329
|
+
### 监听事件
|
|
1330
|
+
|
|
1331
|
+
```ts
|
|
1332
|
+
agent
|
|
1333
|
+
.on(StreamEventType.TEXT_DELTA, (event) => {
|
|
1334
|
+
process.stdout.write(event.delta);
|
|
1335
|
+
})
|
|
1336
|
+
.on(StreamEventType.TOOL_EXECUTE_START, (event) => {
|
|
1337
|
+
console.log("tool start:", event.name);
|
|
1338
|
+
})
|
|
1339
|
+
.on(StreamEventType.TOOL_EXECUTE_DONE, (event) => {
|
|
1340
|
+
console.log("tool done:", event.name, event.result.text);
|
|
1341
|
+
})
|
|
1342
|
+
.on(StreamEventType.ERROR, (event) => {
|
|
1343
|
+
console.error(event.error);
|
|
1344
|
+
});
|
|
1345
|
+
```
|
|
1346
|
+
|
|
1347
|
+
事件 handler 抛错默认会打印到 `console.error`,但不会中断 Agent。可以自定义处理器:
|
|
1348
|
+
|
|
1349
|
+
```ts
|
|
1350
|
+
agent.setHandlerErrorHandler((error, event) => {
|
|
1351
|
+
logger.warn({ error, event }, "Agent event handler failed");
|
|
1352
|
+
});
|
|
1353
|
+
```
|
|
1354
|
+
|
|
1355
|
+
普通 `emit()` 事件仍是非阻塞通知,异步 handler 失败只会上报。提交前转换使用可等待的生命周期:
|
|
1356
|
+
|
|
1357
|
+
```ts
|
|
1358
|
+
agent.on(StreamEventType.BEFORE_ASSISTANT_COMMIT, async (event) => {
|
|
1359
|
+
event.message.setText(await transformText(event.message.text));
|
|
1360
|
+
});
|
|
1361
|
+
```
|
|
1362
|
+
|
|
1363
|
+
该事件位于 `MESSAGE_DONE` 之后、Session 写入之前。监听器按注册顺序执行;失败会中止本轮提交,避免保存未转换文本。自定义流程也可以显式调用 `await agent.emitAsync(event)` 获得相同的等待和错误传播语义。
|
|
1364
|
+
|
|
1365
|
+
### 请求级参数
|
|
1366
|
+
|
|
1367
|
+
```ts
|
|
1368
|
+
await agent.run("这一轮限制更短", {
|
|
1369
|
+
temperature: 0,
|
|
1370
|
+
max_tokens: 128,
|
|
1371
|
+
timeoutMs: 30_000,
|
|
1372
|
+
});
|
|
1373
|
+
```
|
|
1374
|
+
|
|
1375
|
+
`AgentRunOptions` 中的特殊字段不会发送给模型:
|
|
1376
|
+
|
|
1377
|
+
- `signal`
|
|
1378
|
+
- `timeoutMs`
|
|
1379
|
+
- `promptBuildOptions`
|
|
1380
|
+
- `serializeOptions`
|
|
1381
|
+
- `stream`
|
|
1382
|
+
|
|
1383
|
+
其他字段会作为模型请求参数合并进去。
|
|
1384
|
+
|
|
1385
|
+
### 动态更新配置
|
|
1386
|
+
|
|
1387
|
+
```ts
|
|
1388
|
+
agent.setModel("another-model");
|
|
1389
|
+
agent.setMaxTurns(12);
|
|
1390
|
+
agent.setConfig(RequestConfig.precise());
|
|
1391
|
+
agent.setRequestOptions({ temperature: 0.1 });
|
|
1392
|
+
agent.setPromptBuilder(builder);
|
|
1393
|
+
agent.setToolErrorPolicy("pause");
|
|
1394
|
+
```
|
|
1395
|
+
|
|
1396
|
+
常用 getter:
|
|
1397
|
+
|
|
1398
|
+
```ts
|
|
1399
|
+
agent.model;
|
|
1400
|
+
agent.session;
|
|
1401
|
+
agent.config;
|
|
1402
|
+
agent.promptBuilder;
|
|
1403
|
+
agent.toolApproval;
|
|
1404
|
+
agent.toolErrorPolicy;
|
|
1405
|
+
agent.lastRunState;
|
|
1406
|
+
agent.canResume;
|
|
1407
|
+
agent.canContinue;
|
|
1408
|
+
agent.isRunning;
|
|
1409
|
+
```
|
|
1410
|
+
|
|
1411
|
+
### 工具审批
|
|
1412
|
+
|
|
1413
|
+
默认是自动批准工具调用。如果你想自己判断:
|
|
1414
|
+
|
|
1415
|
+
```ts
|
|
1416
|
+
const agent = new Agent({
|
|
1417
|
+
client,
|
|
1418
|
+
model: "your-model",
|
|
1419
|
+
session,
|
|
1420
|
+
toolkit,
|
|
1421
|
+
toolApproval: async (request) => {
|
|
1422
|
+
if (request.name === "delete_file") {
|
|
1423
|
+
return { approved: false, reason: "危险操作需要人工确认" };
|
|
1424
|
+
}
|
|
1425
|
+
return true;
|
|
1426
|
+
},
|
|
1427
|
+
});
|
|
1428
|
+
```
|
|
1429
|
+
|
|
1430
|
+
审批请求结构:
|
|
1431
|
+
|
|
1432
|
+
```ts
|
|
1433
|
+
interface ToolApprovalRequest {
|
|
1434
|
+
approvalId: string;
|
|
1435
|
+
toolCallId: string;
|
|
1436
|
+
name: string;
|
|
1437
|
+
arguments: Record<string, unknown>;
|
|
1438
|
+
rawArguments: string;
|
|
1439
|
+
turn: number;
|
|
1440
|
+
}
|
|
1441
|
+
```
|
|
1442
|
+
|
|
1443
|
+
### 手动审批模式
|
|
1444
|
+
|
|
1445
|
+
如果你要把审批交给 UI:
|
|
1446
|
+
|
|
1447
|
+
```ts
|
|
1448
|
+
const agent = new Agent({
|
|
1449
|
+
client,
|
|
1450
|
+
model: "your-model",
|
|
1451
|
+
session,
|
|
1452
|
+
toolkit,
|
|
1453
|
+
toolApprovalMode: "manual",
|
|
1454
|
+
toolApprovalTimeoutMs: 60_000,
|
|
1455
|
+
});
|
|
1456
|
+
|
|
1457
|
+
const run = agent.run("执行需要审批的任务");
|
|
1458
|
+
|
|
1459
|
+
// UI 轮询或订阅 pendingApprovals
|
|
1460
|
+
const [approval] = agent.pendingApprovals;
|
|
1461
|
+
agent.approve(approval.approvalId);
|
|
1462
|
+
// 或 agent.reject(approval.approvalId, "用户拒绝");
|
|
1463
|
+
|
|
1464
|
+
await run;
|
|
1465
|
+
```
|
|
1466
|
+
|
|
1467
|
+
也可以监听 `TOOL_APPROVAL_REQUIRED`:
|
|
1468
|
+
|
|
1469
|
+
```ts
|
|
1470
|
+
agent.on(StreamEventType.TOOL_APPROVAL_REQUIRED, (event) => {
|
|
1471
|
+
showApprovalDialog(event);
|
|
1472
|
+
});
|
|
1473
|
+
```
|
|
1474
|
+
|
|
1475
|
+
超时策略:
|
|
1476
|
+
|
|
1477
|
+
- `toolApprovalTimeoutPolicy: "reject"`:超时后拒绝工具调用。
|
|
1478
|
+
- `toolApprovalTimeoutPolicy: "abort"`:超时后中断本次运行。
|
|
1479
|
+
|
|
1480
|
+
### 工具错误策略
|
|
1481
|
+
|
|
1482
|
+
```ts
|
|
1483
|
+
const agent = new Agent({
|
|
1484
|
+
client,
|
|
1485
|
+
model: "your-model",
|
|
1486
|
+
session,
|
|
1487
|
+
toolkit,
|
|
1488
|
+
toolErrorPolicy: "return_to_model",
|
|
1489
|
+
});
|
|
1490
|
+
```
|
|
1491
|
+
|
|
1492
|
+
策略:
|
|
1493
|
+
|
|
1494
|
+
- `return_to_model`:默认。工具异常变成 tool result,让模型自己解释或重试。
|
|
1495
|
+
- `pause`:写入带 `paused: true` 的 tool result,Agent 进入可恢复失败状态。
|
|
1496
|
+
- `throw`:直接抛出错误,不写入可恢复状态。
|
|
1497
|
+
|
|
1498
|
+
### 中断、继续与恢复
|
|
1499
|
+
|
|
1500
|
+
中断当前运行:
|
|
1501
|
+
|
|
1502
|
+
```ts
|
|
1503
|
+
agent.abort("用户取消");
|
|
1504
|
+
```
|
|
1505
|
+
|
|
1506
|
+
用外部 `AbortSignal`:
|
|
1507
|
+
|
|
1508
|
+
```ts
|
|
1509
|
+
const controller = new AbortController();
|
|
1510
|
+
|
|
1511
|
+
await agent.run("长任务", {
|
|
1512
|
+
signal: controller.signal,
|
|
1513
|
+
});
|
|
1514
|
+
```
|
|
1515
|
+
|
|
1516
|
+
超时:
|
|
1517
|
+
|
|
1518
|
+
```ts
|
|
1519
|
+
await agent.run("最多等 10 秒", { timeoutMs: 10_000 });
|
|
1520
|
+
```
|
|
1521
|
+
|
|
1522
|
+
如果中断时已经有部分内容,Agent 会把 partial assistant message 写入 session,并设置 `canResume`:
|
|
1523
|
+
|
|
1524
|
+
```ts
|
|
1525
|
+
if (agent.canResume) {
|
|
1526
|
+
await agent.resume();
|
|
1527
|
+
}
|
|
1528
|
+
```
|
|
1529
|
+
|
|
1530
|
+
普通继续:
|
|
1531
|
+
|
|
1532
|
+
```ts
|
|
1533
|
+
if (agent.canContinue) {
|
|
1534
|
+
await agent.continue({
|
|
1535
|
+
prompt: "请继续上一条回答,不要重复已经说过的内容。",
|
|
1536
|
+
});
|
|
1537
|
+
}
|
|
1538
|
+
```
|
|
1539
|
+
|
|
1540
|
+
### 运行状态
|
|
1541
|
+
|
|
1542
|
+
```ts
|
|
1543
|
+
const state = agent.lastRunState;
|
|
1544
|
+
|
|
1545
|
+
state?.status; // "running" | "completed" | "interrupted" | "failed"
|
|
1546
|
+
state?.stopReason; // "final" | "timeout" | "abort" | "tool_execution_error" ...
|
|
1547
|
+
state?.turn; // 当前轮次
|
|
1548
|
+
state?.canResume; // 是否可恢复
|
|
1549
|
+
state?.lastMessage; // 最近完成的消息
|
|
1550
|
+
state?.partialMessage; // 部分消息
|
|
1551
|
+
state?.error; // 错误对象
|
|
1552
|
+
```
|
|
1553
|
+
|
|
1554
|
+
常见 `stopReason`:
|
|
1555
|
+
|
|
1556
|
+
| stopReason | 含义 |
|
|
1557
|
+
| --- | --- |
|
|
1558
|
+
| `final` | 正常完成 |
|
|
1559
|
+
| `abort` | 主动中断 |
|
|
1560
|
+
| `timeout` | 超时 |
|
|
1561
|
+
| `network_error` | 网络或 API 请求失败 |
|
|
1562
|
+
| `stream_error` | 流式解析或读取失败 |
|
|
1563
|
+
| `tool_approval_rejected` | 工具审批被拒绝 |
|
|
1564
|
+
| `tool_execution_error` | 工具执行失败 |
|
|
1565
|
+
| `max_tokens` | 模型输出达到 token 限制 |
|
|
1566
|
+
| `max_turns` | 工具循环超过最大轮数 |
|
|
1567
|
+
| `unknown_error` | 未分类错误 |
|
|
1568
|
+
|
|
1569
|
+
### AgentOptions 摘要
|
|
1570
|
+
|
|
1571
|
+
| 字段 | 说明 |
|
|
1572
|
+
| --- | --- |
|
|
1573
|
+
| `client` | OpenAI-compatible 客户端 |
|
|
1574
|
+
| `model` | 模型名 |
|
|
1575
|
+
| `session` | 会话 |
|
|
1576
|
+
| `adapter?` | 消息适配器,默认 `OpenAIAdapter` |
|
|
1577
|
+
| `toolkit?` | 工具包 |
|
|
1578
|
+
| `toolApproval?` | 自定义工具审批函数 |
|
|
1579
|
+
| `toolApprovalMode?` | `"auto"` 或 `"manual"` |
|
|
1580
|
+
| `toolApprovalTimeoutMs?` | 手动审批超时 |
|
|
1581
|
+
| `toolApprovalTimeoutPolicy?` | `"reject"` 或 `"abort"` |
|
|
1582
|
+
| `toolErrorPolicy?` | `"return_to_model"` / `"pause"` / `"throw"` |
|
|
1583
|
+
| `maxTurns?` | 最大自动循环轮数,默认 10 |
|
|
1584
|
+
| `promptBuilder?` | 提示词构建器 |
|
|
1585
|
+
| `config?` | 请求参数配置 |
|
|
1586
|
+
| `requestOptions?` | 额外请求参数 |
|
|
1587
|
+
|
|
1588
|
+
## Utils:工具函数
|
|
1589
|
+
|
|
1590
|
+
### generateId
|
|
1591
|
+
|
|
1592
|
+
```ts
|
|
1593
|
+
import { generateId } from "@notic/agent-engine";
|
|
1594
|
+
|
|
1595
|
+
generateId(); // 类似 "l3k..."
|
|
1596
|
+
generateId("msg"); // 类似 "msg-l3k..."
|
|
1597
|
+
```
|
|
1598
|
+
|
|
1599
|
+
它用于生成轻量 ID,不保证密码学安全。
|
|
1600
|
+
|
|
1601
|
+
## 常见组合方案
|
|
1602
|
+
|
|
1603
|
+
### 方案一:只做聊天
|
|
1604
|
+
|
|
1605
|
+
```ts
|
|
1606
|
+
const agent = new Agent({
|
|
1607
|
+
client,
|
|
1608
|
+
model: "your-model",
|
|
1609
|
+
session: Session.create("你是一个中文助手。"),
|
|
1610
|
+
});
|
|
1611
|
+
|
|
1612
|
+
const reply = await agent.run("你好");
|
|
1613
|
+
```
|
|
1614
|
+
|
|
1615
|
+
### 方案二:聊天 + 工具
|
|
1616
|
+
|
|
1617
|
+
```ts
|
|
1618
|
+
const toolkit = new ToolKit().add(getWeather, searchDocs);
|
|
1619
|
+
|
|
1620
|
+
const agent = new Agent({
|
|
1621
|
+
client,
|
|
1622
|
+
model: "your-model",
|
|
1623
|
+
session: Session.create("需要外部信息时请调用工具。"),
|
|
1624
|
+
toolkit,
|
|
1625
|
+
});
|
|
1626
|
+
|
|
1627
|
+
await agent.run("今天北京适合跑步吗?");
|
|
1628
|
+
```
|
|
1629
|
+
|
|
1630
|
+
### 方案三:聊天 + 动态提示词
|
|
1631
|
+
|
|
1632
|
+
```ts
|
|
1633
|
+
const promptBuilder = new PromptBuilder()
|
|
1634
|
+
.injectSystem(Rule.top().after(), "当前产品版本:1.1.x")
|
|
1635
|
+
.slice(-30);
|
|
1636
|
+
|
|
1637
|
+
const agent = new Agent({
|
|
1638
|
+
client,
|
|
1639
|
+
model: "your-model",
|
|
1640
|
+
session,
|
|
1641
|
+
promptBuilder,
|
|
1642
|
+
});
|
|
1643
|
+
```
|
|
1644
|
+
|
|
1645
|
+
### 方案四:人工审批危险工具
|
|
1646
|
+
|
|
1647
|
+
```ts
|
|
1648
|
+
const agent = new Agent({
|
|
1649
|
+
client,
|
|
1650
|
+
model: "your-model",
|
|
1651
|
+
session,
|
|
1652
|
+
toolkit,
|
|
1653
|
+
toolApproval: (request) => {
|
|
1654
|
+
if (request.name.startsWith("delete_")) {
|
|
1655
|
+
return { approved: false, reason: "禁止删除操作" };
|
|
1656
|
+
}
|
|
1657
|
+
return true;
|
|
1658
|
+
},
|
|
1659
|
+
});
|
|
1660
|
+
```
|
|
1661
|
+
|
|
1662
|
+
### 方案五:真实 API 测试
|
|
1663
|
+
|
|
1664
|
+
项目内建议把真实 API 测试和 fake 测试分开:
|
|
1665
|
+
|
|
1666
|
+
```bash
|
|
1667
|
+
npm test
|
|
1668
|
+
```
|
|
1669
|
+
|
|
1670
|
+
默认只跑本地 fake / 单元测试。真实 API 测试可以使用显式开关:
|
|
1671
|
+
|
|
1672
|
+
```bash
|
|
1673
|
+
RUN_REAL_DEEPSEEK_TESTS=1 DEEPSEEK_API_KEY=sk-... npm run test:real:deepseek
|
|
1674
|
+
```
|
|
1675
|
+
|
|
1676
|
+
这样 CI、开发机和发布前验证都不会误触发真实请求。
|