@notic/agent-engine 2.0.0 → 2.2.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 +32 -0
- package/README.md +15 -0
- package/dist/agent/Agent.d.ts +6 -5
- package/dist/agent/Agent.d.ts.map +1 -1
- package/dist/agent/Agent.js +7 -1
- package/dist/agent/Agent.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -1
- package/dist/index.js.map +1 -1
- package/dist/message/Message.d.ts +9 -2
- package/dist/message/Message.d.ts.map +1 -1
- package/dist/message/Message.js +18 -10
- package/dist/message/Message.js.map +1 -1
- package/dist/prompt/PromptBuilder.d.ts +10 -2
- package/dist/prompt/PromptBuilder.d.ts.map +1 -1
- package/dist/prompt/PromptBuilder.js +14 -5
- package/dist/prompt/PromptBuilder.js.map +1 -1
- package/dist/session/AgentSession.d.ts +13 -0
- package/dist/session/AgentSession.d.ts.map +1 -0
- package/dist/session/AgentSession.js +3 -0
- package/dist/session/AgentSession.js.map +1 -0
- package/dist/session/ListSession.d.ts +64 -0
- package/dist/session/ListSession.d.ts.map +1 -0
- package/dist/session/ListSession.js +251 -0
- package/dist/session/ListSession.js.map +1 -0
- package/dist/session/index.d.ts +3 -0
- package/dist/session/index.d.ts.map +1 -1
- package/dist/session/index.js +3 -1
- package/dist/session/index.js.map +1 -1
- package/docs/API.md +163 -14
- package/package.json +1 -1
package/docs/API.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# AgentEngine API 教程
|
|
2
2
|
|
|
3
|
-
版本:1.
|
|
3
|
+
版本:2.1.x
|
|
4
4
|
|
|
5
5
|
AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆成几个可以单独理解、测试和替换的模块:
|
|
6
6
|
|
|
@@ -260,6 +260,8 @@ const restored = Message.fromJSON(json);
|
|
|
260
260
|
| `Message.emptySystem()` | 创建空系统根节点 |
|
|
261
261
|
| `Message.tool(toolCallId, result, name?)` | 创建工具结果消息 |
|
|
262
262
|
| `Message.assistantToolCalls(calls)` | 创建带工具调用的助手消息 |
|
|
263
|
+
| `isEmpty` | 判断是否为空消息 |
|
|
264
|
+
| `Message.pruneEmpty(messages)` | 返回移除空消息后的新数组 |
|
|
263
265
|
| `addText(text)` | 追加文本 |
|
|
264
266
|
| `addImage(url, mimeType?)` | 追加图片 |
|
|
265
267
|
| `addAudio(url, mimeType?)` | 追加音频 |
|
|
@@ -284,11 +286,12 @@ import { Session } from "@notic/agent-engine";
|
|
|
284
286
|
const session = Session.create("你是一个代码助手。");
|
|
285
287
|
```
|
|
286
288
|
|
|
287
|
-
如果不传系统提示,会创建一个空 system root
|
|
289
|
+
如果不传系统提示,会创建一个空 system root。这个 root 会保留在 `history()` 中,便于查询、插入和 `PromptBuilder` 定位;真正构建模型请求时,`Agent` 会自动移除空消息,避免发给不支持空系统消息的平台。
|
|
288
290
|
|
|
289
291
|
```ts
|
|
290
292
|
const session = Session.create();
|
|
291
|
-
session.history(); // []
|
|
293
|
+
session.history(); // [empty system root]
|
|
294
|
+
session.history(false); // []
|
|
292
295
|
```
|
|
293
296
|
|
|
294
297
|
### 手动追加消息
|
|
@@ -298,7 +301,7 @@ session.addUser("你好");
|
|
|
298
301
|
session.addAssistant(Message.assistant("你好,我在。"));
|
|
299
302
|
|
|
300
303
|
session.history().map((msg) => msg.text);
|
|
301
|
-
// ["你好", "你好,我在。"]
|
|
304
|
+
// ["", "你好", "你好,我在。"]
|
|
302
305
|
```
|
|
303
306
|
|
|
304
307
|
如果你已经有完整 `Message` 对象,用 `addMessage()`:
|
|
@@ -386,8 +389,19 @@ if (anchor) {
|
|
|
386
389
|
```ts
|
|
387
390
|
session.inserter.moveTo(anchor).insertAfter(msg).execute();
|
|
388
391
|
session.inserter.moveTo(anchor).insertBefore(msg).execute();
|
|
389
|
-
|
|
392
|
+
|
|
393
|
+
// 光标移动方法
|
|
390
394
|
session.inserter.top().insertAssistantBefore("插到顶部之前").execute();
|
|
395
|
+
session.inserter.bottom().insertUserAfter("追加一条用户消息").execute();
|
|
396
|
+
session.inserter.move(2); // 偏移移动,正数向后,负数向前
|
|
397
|
+
session.inserter.moveByContent(["关键词"]); // 按内容定位光标
|
|
398
|
+
session.inserter.moveByTags(["important"]); // 按标签定位光标
|
|
399
|
+
|
|
400
|
+
// 查询当前状态
|
|
401
|
+
session.inserter.current; // 光标当前指向的消息
|
|
402
|
+
session.inserter.position; // 光标索引
|
|
403
|
+
session.inserter.isExpired; // 插入器是否已执行(报废)
|
|
404
|
+
session.inserter.pendingCount;// 排队中的命令数量
|
|
391
405
|
```
|
|
392
406
|
|
|
393
407
|
### Paginator:切换分支
|
|
@@ -423,6 +437,61 @@ if (paginator) {
|
|
|
423
437
|
| `systemPrompt` | 读取或设置系统提示 |
|
|
424
438
|
| `toJSON()` / `fromJSON()` | 序列化与恢复 |
|
|
425
439
|
|
|
440
|
+
### ListSession:候选列表会话
|
|
441
|
+
|
|
442
|
+
`ListSession` 与树状 `Session` 并列,适合"每条回复可以左右切换候选"的列表式界面。它由若干 **行(row)** 线性组成,每行持有多个 **候选(candidate)**;一次工具循环产生的全部消息(assistant → tool → assistant)属于同一个候选,切换候选时整段轨迹一起切换。
|
|
443
|
+
|
|
444
|
+
`Agent` 通过 `AgentSession` 接口接受任意会话实现,并从传入的实例推断类型,所以 `agent.session` 仍保留具体类型:
|
|
445
|
+
|
|
446
|
+
```ts
|
|
447
|
+
import { Agent, ListSession } from "@notic/agent-engine";
|
|
448
|
+
|
|
449
|
+
const session = ListSession.create("你是一个助手");
|
|
450
|
+
const agent = new Agent({ client, model: "gpt-4o", session });
|
|
451
|
+
|
|
452
|
+
await agent.run("你好");
|
|
453
|
+
|
|
454
|
+
// 对第 2 行重新生成一个候选,只用它之前的行作为上下文
|
|
455
|
+
session.regenerate(session.rows[1].id);
|
|
456
|
+
await agent.generate();
|
|
457
|
+
|
|
458
|
+
// 切回旧候选,后面的行不会被删除
|
|
459
|
+
session.select(session.rows[1].id, session.rows[1].candidates[0].id);
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
切换靠前的候选不会创建分支、也不会抹掉后面的行,但后续行的上下文已经变了。这些行会出现在 `staleRowIds` 中,此时继续生成会抛错,需要显式选择处理方式:
|
|
463
|
+
|
|
464
|
+
| 处理方式 | 含义 |
|
|
465
|
+
| --- | --- |
|
|
466
|
+
| `acceptHistory()` | 承认保留下来的后续内容,按新上下文继续 |
|
|
467
|
+
| `truncateAfter(rowId)` | 丢弃该行之后的所有行 |
|
|
468
|
+
| `regenerate(rowId)` | 在该行重新生成,只使用它之前的行 |
|
|
469
|
+
|
|
470
|
+
`toJSON()` / `ListSession.fromJSON()` 会完整保存所有候选、轨迹和当前选择,恢复时对 id 唯一性、角色一致性和选中项做严格校验。
|
|
471
|
+
|
|
472
|
+
> 注意:候选切换只影响会话内容,**不会撤销工具已经产生的副作用**;应用重启后的 Agent 运行现场恢复也不由 `ListSession` 单独负责。
|
|
473
|
+
|
|
474
|
+
### ListSession API 摘要
|
|
475
|
+
|
|
476
|
+
| API | 说明 |
|
|
477
|
+
| --- | --- |
|
|
478
|
+
| `ListSession.create(systemPrompt?)` | 创建候选列表会话 |
|
|
479
|
+
| `rows` | 只读行列表,每行含候选与当前选中项 |
|
|
480
|
+
| `alternatives` | 二维投影,每行候选的最终消息 |
|
|
481
|
+
| `history(includeRoot?)` | 当前选择下的完整历史 |
|
|
482
|
+
| `addUser/addAssistant/addTool/addMessage` | 追加消息,与 `Session` 一致 |
|
|
483
|
+
| `addCandidate(rowId, message)` | 手动为某行添加候选 |
|
|
484
|
+
| `removeCandidate(rowId, candidateId)` | 删除候选(不可删到空行) |
|
|
485
|
+
| `select(rowId, candidateId)` | 切换某行的选中候选 |
|
|
486
|
+
| `regenerate(rowId)` | 标记下一次 `generate()` 在该行生成新候选 |
|
|
487
|
+
| `cancelRegeneration()` | 取消上面的标记 |
|
|
488
|
+
| `truncateAfter(rowId \| null)` | 截断该行之后的内容 |
|
|
489
|
+
| `staleRowIds` | 上下文已失效的行 |
|
|
490
|
+
| `acceptHistory()` | 接受保留的后续历史 |
|
|
491
|
+
| `beginGeneration()` / `endGeneration()` | 生成边界,由 `Agent` 自动调用 |
|
|
492
|
+
| `clear()` | 清空所有行 |
|
|
493
|
+
| `toJSON()` / `ListSession.fromJSON()` | 序列化与恢复 |
|
|
494
|
+
|
|
426
495
|
## Tool:工具系统
|
|
427
496
|
|
|
428
497
|
工具让模型可以调用你的 TypeScript 函数。AgentEngine 的工具系统包含四层:
|
|
@@ -590,10 +659,12 @@ const results = await toolkit.executeAll(toolCalls);
|
|
|
590
659
|
```ts
|
|
591
660
|
await toolkit.execute(toolCall, { errorPolicy: "return_to_model" });
|
|
592
661
|
await toolkit.execute(toolCall, { errorPolicy: "throw" });
|
|
662
|
+
await toolkit.execute(toolCall, { signal: abortController.signal }); // 传入 AbortSignal
|
|
593
663
|
```
|
|
594
664
|
|
|
595
|
-
- `return_to_model`:工具异常会转成模型可读的 tool result
|
|
665
|
+
- `return_to_model`:工具异常会转成模型可读的 tool result(默认)。
|
|
596
666
|
- `throw`:抛出 `ToolExecutionError`。
|
|
667
|
+
- `signal`:传入 `AbortSignal` 供工具内部响应取消。
|
|
597
668
|
|
|
598
669
|
### MCP 工具
|
|
599
670
|
|
|
@@ -678,6 +749,8 @@ console.log(done?.message.text);
|
|
|
678
749
|
- `delta.tool_calls`:工具调用增量
|
|
679
750
|
- `usage`:stream usage chunk
|
|
680
751
|
|
|
752
|
+
`reset()` 可重置解析器内部状态,重用解析器实例。
|
|
753
|
+
|
|
681
754
|
### 常用事件
|
|
682
755
|
|
|
683
756
|
| 事件 | 触发时机 |
|
|
@@ -734,6 +807,25 @@ const context = builder.build(session.history());
|
|
|
734
807
|
|
|
735
808
|
`Rule.top().after()` 的意思是:定位到第一条消息,在它后面插入。
|
|
736
809
|
|
|
810
|
+
如果 `history` 里包含空 system root,它也可以作为定位锚点。`build()` 会在所有注入和数组操作完成后默认移除空消息,因此空 root 可参与定位,但不会进入最终上下文:
|
|
811
|
+
|
|
812
|
+
```ts
|
|
813
|
+
const session = Session.create();
|
|
814
|
+
session.addUser("你好");
|
|
815
|
+
|
|
816
|
+
const builder = new PromptBuilder();
|
|
817
|
+
builder.injectSystem(Rule.top().after(), "运行时上下文");
|
|
818
|
+
|
|
819
|
+
builder.build(session.history()).map((msg) => msg.text);
|
|
820
|
+
// ["运行时上下文", "你好"]
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
需要保留空消息用于调试时,可以传入:
|
|
824
|
+
|
|
825
|
+
```ts
|
|
826
|
+
builder.build(session.history(), { dropEmptyMessages: false });
|
|
827
|
+
```
|
|
828
|
+
|
|
737
829
|
### 按角色定位
|
|
738
830
|
|
|
739
831
|
```ts
|
|
@@ -825,7 +917,7 @@ builder.removeWhere((msg) => msg.hasTag("debug"));
|
|
|
825
917
|
builder.replaceWhere((msg) => msg.hasTag("old"), Message.system("new"));
|
|
826
918
|
builder.filter((msg) => msg.role !== Role.Tool);
|
|
827
919
|
builder.slice(-10);
|
|
828
|
-
builder.map((msg) => msg);
|
|
920
|
+
builder.map((msg, i) => msg);
|
|
829
921
|
builder.transform((messages) => messages.reverse());
|
|
830
922
|
```
|
|
831
923
|
|
|
@@ -862,9 +954,14 @@ builder.transform((messages) => messages.reverse());
|
|
|
862
954
|
| `clearInjections()` | 清空 injection |
|
|
863
955
|
| `clearOperations()` | 清空操作管线 |
|
|
864
956
|
| `clear()` | 清空 injection 和 operation |
|
|
865
|
-
| `build(history, options?)` |
|
|
866
|
-
| `buildBatch(history)` | batch 构建 |
|
|
867
|
-
| `buildImmediate(history)` | immediate 构建 |
|
|
957
|
+
| `build(history, options?)` | 生成临时上下文,默认移除空消息 |
|
|
958
|
+
| `buildBatch(history, options?)` | batch 构建 |
|
|
959
|
+
| `buildImmediate(history, options?)` | immediate 构建 |
|
|
960
|
+
| `injections` | 只读注入列表 |
|
|
961
|
+
| `aliveCount` / `expiredCount` / `activeCount` | 注入统计 |
|
|
962
|
+
| `findByRule(rule)` / `findById(id)` | 查找注入 |
|
|
963
|
+
| `operations` | 只读操作管线列表 |
|
|
964
|
+
| `removeOperation(label)` | 按标签移除操作 |
|
|
868
965
|
|
|
869
966
|
## Config:请求参数
|
|
870
967
|
|
|
@@ -962,7 +1059,7 @@ await agent.run("这一轮更发散一点", { temperature: 1.0 });
|
|
|
962
1059
|
| `frequencyPenalty(n)` / `presencePenalty(n)` | 惩罚参数 |
|
|
963
1060
|
| `stop(...seq)` | 停止序列,最多保留 4 个 |
|
|
964
1061
|
| `seed(n)` | 随机种子 |
|
|
965
|
-
| `responseFormat(format, schema?)` |
|
|
1062
|
+
| `responseFormat(format, schema?)` | 响应格式:`"text"` / `"json_object"` / `"json_schema"` |
|
|
966
1063
|
| `set(key, value)` | 自定义字段 |
|
|
967
1064
|
| `unset(key)` | 删除字段 |
|
|
968
1065
|
| `merge(other)` | 合并配置 |
|
|
@@ -1194,6 +1291,29 @@ await agent.run("继续", {
|
|
|
1194
1291
|
- `tool_call`:工具调用相关场景包含。
|
|
1195
1292
|
- `all`:全部包含。
|
|
1196
1293
|
|
|
1294
|
+
`include`(可选自定义选择器,优先级高于 `scope`):
|
|
1295
|
+
|
|
1296
|
+
```ts
|
|
1297
|
+
serializeOptions: {
|
|
1298
|
+
thinking: {
|
|
1299
|
+
mode: "message",
|
|
1300
|
+
// 只回传包含工具调用的消息的 thinking
|
|
1301
|
+
include: (msg, index) => msg.toolCalls.length > 0,
|
|
1302
|
+
},
|
|
1303
|
+
},
|
|
1304
|
+
```
|
|
1305
|
+
|
|
1306
|
+
`messagePrefix`(可选,`message` 降级模式下的提示前缀,默认带有恢复语义):
|
|
1307
|
+
|
|
1308
|
+
```ts
|
|
1309
|
+
serializeOptions: {
|
|
1310
|
+
thinking: {
|
|
1311
|
+
mode: "message",
|
|
1312
|
+
messagePrefix: "[先前上下文]\n",
|
|
1313
|
+
},
|
|
1314
|
+
},
|
|
1315
|
+
```
|
|
1316
|
+
|
|
1197
1317
|
DeepSeek / Qwen 等模型如果要求工具调用时回传 reasoning 内容,可以在 `run()` 时显式设置。
|
|
1198
1318
|
|
|
1199
1319
|
## Media:媒体解析
|
|
@@ -1333,6 +1453,11 @@ agent
|
|
|
1333
1453
|
.on(StreamEventType.TEXT_DELTA, (event) => {
|
|
1334
1454
|
process.stdout.write(event.delta);
|
|
1335
1455
|
})
|
|
1456
|
+
// 批量注册:同一个 handler 响应多个事件类型
|
|
1457
|
+
.on(
|
|
1458
|
+
[StreamEventType.TOOL_CALL_START, StreamEventType.TOOL_CALL_DONE],
|
|
1459
|
+
(event) => console.log("tool event:", event.type, event.name)
|
|
1460
|
+
)
|
|
1336
1461
|
.on(StreamEventType.TOOL_EXECUTE_START, (event) => {
|
|
1337
1462
|
console.log("tool start:", event.name);
|
|
1338
1463
|
})
|
|
@@ -1344,6 +1469,14 @@ agent
|
|
|
1344
1469
|
});
|
|
1345
1470
|
```
|
|
1346
1471
|
|
|
1472
|
+
也支持自定义事件类型:
|
|
1473
|
+
|
|
1474
|
+
```ts
|
|
1475
|
+
agent.on("my_custom_event", (event) => {
|
|
1476
|
+
console.log(event.data);
|
|
1477
|
+
});
|
|
1478
|
+
```
|
|
1479
|
+
|
|
1347
1480
|
事件 handler 抛错默认会打印到 `console.error`,但不会中断 Agent。可以自定义处理器:
|
|
1348
1481
|
|
|
1349
1482
|
```ts
|
|
@@ -1391,6 +1524,8 @@ agent.setConfig(RequestConfig.precise());
|
|
|
1391
1524
|
agent.setRequestOptions({ temperature: 0.1 });
|
|
1392
1525
|
agent.setPromptBuilder(builder);
|
|
1393
1526
|
agent.setToolErrorPolicy("pause");
|
|
1527
|
+
agent.setToolApproval(customApprovalHandler);
|
|
1528
|
+
agent.setToolApprovalMode("manual");
|
|
1394
1529
|
```
|
|
1395
1530
|
|
|
1396
1531
|
常用 getter:
|
|
@@ -1406,6 +1541,7 @@ agent.lastRunState;
|
|
|
1406
1541
|
agent.canResume;
|
|
1407
1542
|
agent.canContinue;
|
|
1408
1543
|
agent.isRunning;
|
|
1544
|
+
agent.pendingApprovals;
|
|
1409
1545
|
```
|
|
1410
1546
|
|
|
1411
1547
|
### 工具审批
|
|
@@ -1532,7 +1668,16 @@ if (agent.canResume) {
|
|
|
1532
1668
|
```ts
|
|
1533
1669
|
if (agent.canContinue) {
|
|
1534
1670
|
await agent.continue({
|
|
1671
|
+
// mode: "auto" | "resume" | "continue"
|
|
1672
|
+
// auto=有中断则恢复,否则普通继续;resume=严格恢复;continue=普通继续
|
|
1673
|
+
mode: "auto",
|
|
1674
|
+
// 继续时追加的提示词
|
|
1535
1675
|
prompt: "请继续上一条回答,不要重复已经说过的内容。",
|
|
1676
|
+
// thinking 回传策略;resume 默认 auto,普通 continue 默认 none
|
|
1677
|
+
thinkingMode: "auto",
|
|
1678
|
+
// 也支持 AgentRunOptions 中的常用字段
|
|
1679
|
+
signal: controller.signal,
|
|
1680
|
+
timeoutMs: 30_000,
|
|
1536
1681
|
});
|
|
1537
1682
|
}
|
|
1538
1683
|
```
|
|
@@ -1556,11 +1701,13 @@ state?.error; // 错误对象
|
|
|
1556
1701
|
| stopReason | 含义 |
|
|
1557
1702
|
| --- | --- |
|
|
1558
1703
|
| `final` | 正常完成 |
|
|
1704
|
+
| `continue` | 通过 `agent.continue()` 继续 |
|
|
1559
1705
|
| `abort` | 主动中断 |
|
|
1560
1706
|
| `timeout` | 超时 |
|
|
1561
1707
|
| `network_error` | 网络或 API 请求失败 |
|
|
1562
1708
|
| `stream_error` | 流式解析或读取失败 |
|
|
1563
1709
|
| `tool_approval_rejected` | 工具审批被拒绝 |
|
|
1710
|
+
| `tool_approval_error` | 工具审批函数执行失败 |
|
|
1564
1711
|
| `tool_execution_error` | 工具执行失败 |
|
|
1565
1712
|
| `max_tokens` | 模型输出达到 token 限制 |
|
|
1566
1713
|
| `max_turns` | 工具循环超过最大轮数 |
|
|
@@ -1570,15 +1717,17 @@ state?.error; // 错误对象
|
|
|
1570
1717
|
|
|
1571
1718
|
| 字段 | 说明 |
|
|
1572
1719
|
| --- | --- |
|
|
1573
|
-
| `client
|
|
1720
|
+
| `client?` | 模型客户端,`OpenAIClientLike` 或自定义 `ModelClient`,与 `provider` 二选一 |
|
|
1721
|
+
| `provider?` | Client + Adapter + Parser 的预设组合,与 `client` 二选一 |
|
|
1574
1722
|
| `model` | 模型名 |
|
|
1575
1723
|
| `session` | 会话 |
|
|
1576
1724
|
| `adapter?` | 消息适配器,默认 `OpenAIAdapter` |
|
|
1725
|
+
| `parserFactory?` | 自定义 Parser 工厂,会覆盖 Provider 中的预设 |
|
|
1577
1726
|
| `toolkit?` | 工具包 |
|
|
1578
1727
|
| `toolApproval?` | 自定义工具审批函数 |
|
|
1579
1728
|
| `toolApprovalMode?` | `"auto"` 或 `"manual"` |
|
|
1580
|
-
| `toolApprovalTimeoutMs?` |
|
|
1581
|
-
| `toolApprovalTimeoutPolicy?` |
|
|
1729
|
+
| `toolApprovalTimeoutMs?` | 手动审批超时(毫秒) |
|
|
1730
|
+
| `toolApprovalTimeoutPolicy?` | 手动审批超时策略:`"reject"`(默认)或 `"abort"` |
|
|
1582
1731
|
| `toolErrorPolicy?` | `"return_to_model"` / `"pause"` / `"throw"` |
|
|
1583
1732
|
| `maxTurns?` | 最大自动循环轮数,默认 10 |
|
|
1584
1733
|
| `promptBuilder?` | 提示词构建器 |
|