@notic/agent-engine 1.1.1 → 1.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.
Files changed (95) hide show
  1. package/CHANGELOG.md +26 -0
  2. package/README.md +119 -2
  3. package/dist/adapter/AnthropicAdapter.d.ts +3 -1
  4. package/dist/adapter/AnthropicAdapter.d.ts.map +1 -1
  5. package/dist/adapter/AnthropicAdapter.js +38 -0
  6. package/dist/adapter/AnthropicAdapter.js.map +1 -1
  7. package/dist/adapter/GeminiAdapter.d.ts +3 -1
  8. package/dist/adapter/GeminiAdapter.d.ts.map +1 -1
  9. package/dist/adapter/GeminiAdapter.js +74 -1
  10. package/dist/adapter/GeminiAdapter.js.map +1 -1
  11. package/dist/adapter/MessageAdapter.d.ts +17 -0
  12. package/dist/adapter/MessageAdapter.d.ts.map +1 -1
  13. package/dist/adapter/MessageAdapter.js.map +1 -1
  14. package/dist/adapter/OpenAIAdapter.d.ts +3 -1
  15. package/dist/adapter/OpenAIAdapter.d.ts.map +1 -1
  16. package/dist/adapter/OpenAIAdapter.js +17 -0
  17. package/dist/adapter/OpenAIAdapter.js.map +1 -1
  18. package/dist/adapter/OpenAIResponsesAdapter.d.ts +23 -0
  19. package/dist/adapter/OpenAIResponsesAdapter.d.ts.map +1 -0
  20. package/dist/adapter/OpenAIResponsesAdapter.js +231 -0
  21. package/dist/adapter/OpenAIResponsesAdapter.js.map +1 -0
  22. package/dist/adapter/index.d.ts +2 -1
  23. package/dist/adapter/index.d.ts.map +1 -1
  24. package/dist/adapter/index.js +3 -1
  25. package/dist/adapter/index.js.map +1 -1
  26. package/dist/agent/Agent.d.ts +45 -16
  27. package/dist/agent/Agent.d.ts.map +1 -1
  28. package/dist/agent/Agent.js +250 -52
  29. package/dist/agent/Agent.js.map +1 -1
  30. package/dist/agent/index.d.ts +1 -1
  31. package/dist/agent/index.d.ts.map +1 -1
  32. package/dist/agent/index.js +4 -1
  33. package/dist/agent/index.js.map +1 -1
  34. package/dist/client/ModelClient.d.ts +74 -0
  35. package/dist/client/ModelClient.d.ts.map +1 -0
  36. package/dist/client/ModelClient.js +85 -0
  37. package/dist/client/ModelClient.js.map +1 -0
  38. package/dist/client/index.d.ts +2 -0
  39. package/dist/client/index.d.ts.map +1 -0
  40. package/dist/client/index.js +11 -0
  41. package/dist/client/index.js.map +1 -0
  42. package/dist/index.d.ts +8 -3
  43. package/dist/index.d.ts.map +1 -1
  44. package/dist/index.js +29 -3
  45. package/dist/index.js.map +1 -1
  46. package/dist/message/Message.d.ts.map +1 -1
  47. package/dist/message/Message.js +20 -0
  48. package/dist/message/Message.js.map +1 -1
  49. package/dist/message/MessagePart.d.ts +2 -0
  50. package/dist/message/MessagePart.d.ts.map +1 -1
  51. package/dist/provider/Provider.d.ts +48 -0
  52. package/dist/provider/Provider.d.ts.map +1 -0
  53. package/dist/provider/Provider.js +73 -0
  54. package/dist/provider/Provider.js.map +1 -0
  55. package/dist/provider/index.d.ts +2 -0
  56. package/dist/provider/index.d.ts.map +1 -0
  57. package/dist/provider/index.js +10 -0
  58. package/dist/provider/index.js.map +1 -0
  59. package/dist/session/Session.d.ts +0 -3
  60. package/dist/session/Session.d.ts.map +1 -1
  61. package/dist/session/Session.js +0 -13
  62. package/dist/session/Session.js.map +1 -1
  63. package/dist/stream/AnthropicStreamParser.d.ts +26 -0
  64. package/dist/stream/AnthropicStreamParser.d.ts.map +1 -0
  65. package/dist/stream/AnthropicStreamParser.js +176 -0
  66. package/dist/stream/AnthropicStreamParser.js.map +1 -0
  67. package/dist/stream/GeminiStreamParser.d.ts +21 -0
  68. package/dist/stream/GeminiStreamParser.d.ts.map +1 -0
  69. package/dist/stream/GeminiStreamParser.js +144 -0
  70. package/dist/stream/GeminiStreamParser.js.map +1 -0
  71. package/dist/stream/MessageStreamParser.d.ts +13 -0
  72. package/dist/stream/MessageStreamParser.d.ts.map +1 -0
  73. package/dist/stream/MessageStreamParser.js +3 -0
  74. package/dist/stream/MessageStreamParser.js.map +1 -0
  75. package/dist/stream/OpenAIResponsesStreamParser.d.ts +30 -0
  76. package/dist/stream/OpenAIResponsesStreamParser.d.ts.map +1 -0
  77. package/dist/stream/OpenAIResponsesStreamParser.js +273 -0
  78. package/dist/stream/OpenAIResponsesStreamParser.js.map +1 -0
  79. package/dist/stream/StreamParser.d.ts +2 -1
  80. package/dist/stream/StreamParser.d.ts.map +1 -1
  81. package/dist/stream/StreamParser.js.map +1 -1
  82. package/dist/stream/index.d.ts +4 -0
  83. package/dist/stream/index.d.ts.map +1 -1
  84. package/dist/stream/index.js +7 -1
  85. package/dist/stream/index.js.map +1 -1
  86. package/dist/tool/ToolKit.d.ts +4 -0
  87. package/dist/tool/ToolKit.d.ts.map +1 -1
  88. package/dist/tool/ToolKit.js +50 -14
  89. package/dist/tool/ToolKit.js.map +1 -1
  90. package/dist/tool/index.d.ts +1 -1
  91. package/dist/tool/index.d.ts.map +1 -1
  92. package/dist/tool/index.js +2 -1
  93. package/dist/tool/index.js.map +1 -1
  94. package/docs/API.md +193 -6
  95. package/package.json +23 -6
package/docs/API.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AgentEngine API 教程
2
2
 
3
- 版本:1.1.x
3
+ 版本:1.2.x
4
4
 
5
5
  AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆成几个可以单独理解、测试和替换的模块:
6
6
 
@@ -10,8 +10,10 @@ AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆
10
10
  - `Stream`:把 OpenAI-compatible stream chunk 解析成结构化事件。
11
11
  - `Prompt`:用声明式规则把临时提示词注入历史。
12
12
  - `Config`:链式构建请求参数。
13
+ - `Client`:只负责发送已经适配好的请求,返回 stream 或完整响应。
13
14
  - `Adapter`:把统一消息模型序列化到 OpenAI / Anthropic / Gemini 等平台格式。
14
- - `Agent`:把上面所有模块串起来,完成“流式请求 -> 解析 -> 工具执行 -> 再请求 -> 最终回复”的自动循环。
15
+ - `Provider`:以低耦合方式组合 Client、Adapter 和 Parser。
16
+ - `Agent`:把上面所有模块串起来,完成“请求 -> 解析 -> 工具执行 -> 再请求 -> 最终回复”的自动循环。
15
17
 
16
18
  这份文档会像教程一样讲 API:先跑起来,再分模块深入。README 只做项目介绍和快速入口,完整用法以后主要看这里。
17
19
 
@@ -25,6 +27,7 @@ AgentEngine 是一个 TypeScript AI Agent 框架。它把一次模型调用拆
25
27
  - [Stream:流式事件](#stream流式事件)
26
28
  - [Prompt:提示词构建](#prompt提示词构建)
27
29
  - [Config:请求参数](#config请求参数)
30
+ - [Provider:平台能力组合](#provider平台能力组合)
28
31
  - [Adapter:平台适配](#adapter平台适配)
29
32
  - [Media:媒体解析](#media媒体解析)
30
33
  - [Agent:智能体编排](#agent智能体编排)
@@ -45,6 +48,13 @@ AgentEngine 不强绑定具体模型 SDK。你使用 OpenAI、DeepSeek、Qwen、
45
48
  npm install openai
46
49
  ```
47
50
 
51
+ 使用原生 Anthropic 或 Gemini Provider 时,安装对应官方 SDK:
52
+
53
+ ```bash
54
+ npm install @anthropic-ai/sdk
55
+ npm install @google/genai
56
+ ```
57
+
48
58
  最小可运行示例:
49
59
 
50
60
  ```ts
@@ -95,8 +105,8 @@ User input
95
105
  -> Session 追加用户消息
96
106
  -> PromptBuilder 注入临时上下文
97
107
  -> Adapter 序列化成平台请求格式
98
- -> client.chat.completions.create({ stream: true })
99
- -> StreamParser 解析流式 chunk
108
+ -> ModelClient.stream() 或 ModelClient.complete()
109
+ -> Parser 解析流式 chunk,或 Adapter 解析完整响应
100
110
  -> Agent 派发事件并生成 assistant Message
101
111
  -> 如果有 tool_calls,ToolKit 执行工具并写回 Session
102
112
  -> 再次请求模型,直到获得最终回复
@@ -113,7 +123,7 @@ import { Message, Session, Tool, ToolKit, StreamParser } from "@notic/agent-engi
113
123
  1. 先用 `Agent + Session` 跑通一次模型调用。
114
124
  2. 再学习 `Tool + ToolKit`,让模型能调用你的函数。
115
125
  3. 然后学习 `PromptBuilder`,把系统规则、短期上下文、动态提示注入对话。
116
- 4. 最后根据平台需要学习 `Adapter`、`MediaResolver` 和 `StreamParser`。
126
+ 4. 最后根据平台需要学习 `Provider`、`Adapter`、`MediaResolver` 和 `StreamParser`。
117
127
 
118
128
  ## Message:统一消息模型
119
129
 
@@ -956,6 +966,164 @@ await agent.run("这一轮更发散一点", { temperature: 1.0 });
956
966
  | `clone()` | 克隆 |
957
967
  | `build()` | 输出普通对象 |
958
968
 
969
+ ## Provider:平台能力组合
970
+
971
+ Provider 是 AgentEngine 的平台边界。它不拥有 Agent 的 Session、工具循环或运行状态,
972
+ 只组合三个可以独立替换的组件:
973
+
974
+ ```text
975
+ Provider
976
+ ├─ ModelClient 发送请求,返回 stream 或完整响应
977
+ ├─ MessageAdapter Message[] <-> 平台请求/响应
978
+ └─ MessageStreamParser 平台 stream -> 统一事件和 Message
979
+ ```
980
+
981
+ 因此接入新平台时,不需要在 `Agent` 中增加平台判断。只需提供对应的 Client、Adapter
982
+ 和 Parser,并保证最终仍然使用统一 `Message`。
983
+
984
+ ### OpenAI Compatible Provider
985
+
986
+ 适用于 OpenAI Chat Completions,以及 DeepSeek、Qwen、Kimi、GLM 等兼容接口:
987
+
988
+ ```ts
989
+ import OpenAI from "openai";
990
+ import {
991
+ Agent,
992
+ OpenAICompatibleProvider,
993
+ Session,
994
+ } from "@notic/agent-engine";
995
+
996
+ const client = new OpenAI({
997
+ apiKey: process.env.PROVIDER_API_KEY,
998
+ baseURL: "https://your-provider.example/v1",
999
+ });
1000
+
1001
+ const agent = new Agent({
1002
+ provider: new OpenAICompatibleProvider(client),
1003
+ model: "your-model",
1004
+ session: Session.create(),
1005
+ });
1006
+ ```
1007
+
1008
+ 为了兼容旧代码,也可以继续直接传 `client`。此时 Agent 默认使用
1009
+ `OpenAIAdapter + StreamParser`。
1010
+
1011
+ ### OpenAI Responses Provider
1012
+
1013
+ ```ts
1014
+ import OpenAI from "openai";
1015
+ import { Agent, OpenAIResponsesProvider, Session } from "@notic/agent-engine";
1016
+
1017
+ const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
1018
+ const agent = new Agent({
1019
+ provider: new OpenAIResponsesProvider(client),
1020
+ model: "your-openai-model",
1021
+ session: Session.create(),
1022
+ });
1023
+ ```
1024
+
1025
+ 该 Provider 使用原生 Responses API,并支持:
1026
+
1027
+ - `response.output_text.*` 文本事件
1028
+ - reasoning summary 与 encrypted reasoning item 回传
1029
+ - `function_call` / `function_call_output` 工具循环
1030
+ - `max_output_tokens`、结构化输出和 usage
1031
+ - 流式及非流式完整响应
1032
+
1033
+ ### Anthropic Provider
1034
+
1035
+ ```ts
1036
+ import Anthropic from "@anthropic-ai/sdk";
1037
+ import { Agent, AnthropicProvider, Session } from "@notic/agent-engine";
1038
+
1039
+ const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
1040
+ const agent = new Agent({
1041
+ provider: new AnthropicProvider(client),
1042
+ model: "your-claude-model",
1043
+ session: Session.create(),
1044
+ });
1045
+ ```
1046
+
1047
+ Anthropic Provider 使用原生 Messages API,处理 system 提取、content blocks、thinking
1048
+ signature、tool use 和原生 usage。
1049
+
1050
+ ### Gemini Provider
1051
+
1052
+ ```ts
1053
+ import { GoogleGenAI } from "@google/genai";
1054
+ import { Agent, GeminiProvider, Session } from "@notic/agent-engine";
1055
+
1056
+ const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
1057
+ const agent = new Agent({
1058
+ provider: new GeminiProvider(client),
1059
+ model: "your-gemini-model",
1060
+ session: Session.create(),
1061
+ });
1062
+ ```
1063
+
1064
+ Gemini Provider 使用 `generateContentStream()` 和 `generateContent()`,处理 contents、
1065
+ systemInstruction、functionCall、functionResponse 和 thought signature。
1066
+
1067
+ ### 流式与非流式
1068
+
1069
+ 内置 Provider 同时支持两种运行方式:
1070
+
1071
+ ```ts
1072
+ // 默认:增量事件
1073
+ const streamed = await agent.run("介绍一下这个项目");
1074
+
1075
+ // 完整响应:不经过 StreamParser
1076
+ const completed = await agent.run("介绍一下这个项目", {
1077
+ stream: false,
1078
+ });
1079
+ ```
1080
+
1081
+ 非流式模式仍然经过统一 Adapter,并保留 Session、PromptBuilder、工具审批、工具执行、
1082
+ 自动多轮循环、timeout、abort、model 和 usage。它不产生 `TEXT_DELTA`,但会产生
1083
+ `TEXT_DONE`、`TOOL_CALL_DONE` 和 `MESSAGE_DONE`。
1084
+
1085
+ ```ts
1086
+ provider.supportsComplete; // ModelClient 是否实现 complete()
1087
+ ```
1088
+
1089
+ ### 自定义 Provider
1090
+
1091
+ 自定义 Client 只负责传输,不需要认识 Message、Session 或 Tool:
1092
+
1093
+ ```ts
1094
+ import {
1095
+ Agent,
1096
+ ModelClient,
1097
+ Provider,
1098
+ Session,
1099
+ } from "@notic/agent-engine";
1100
+
1101
+ const client: ModelClient = {
1102
+ async stream(request, options) {
1103
+ return mySdk.createStream(request, { signal: options?.signal });
1104
+ },
1105
+ async complete(request, options) {
1106
+ return mySdk.create(request, { signal: options?.signal });
1107
+ },
1108
+ };
1109
+
1110
+ const provider = Provider.create({
1111
+ client,
1112
+ adapter: new MyAdapter(),
1113
+ parserFactory: () => new MyStreamParser(),
1114
+ });
1115
+
1116
+ const agent = new Agent({
1117
+ provider,
1118
+ model: "my-model",
1119
+ session: Session.create(),
1120
+ });
1121
+ ```
1122
+
1123
+ `ModelClient.complete()` 是可选能力。只实现 `stream()` 的自定义 Provider 仍然兼容,
1124
+ 但调用 `{ stream: false }` 时会收到明确错误。显式传给 Agent 的 `client`、`adapter`
1125
+ 或 `parserFactory` 会覆盖 Provider 中的对应预设。
1126
+
959
1127
  ## Adapter:平台适配
960
1128
 
961
1129
  AgentEngine 内部统一使用 `Message`,但不同平台请求格式不同。`Adapter` 负责把 `Message[]` 转成平台格式,也可以把平台响应转回 `Message`。
@@ -1100,6 +1268,24 @@ const reply = await agent.run("帮我写一个提交说明。");
1100
1268
  console.log(reply.text);
1101
1269
  ```
1102
1270
 
1271
+ 默认使用流式请求。需要等待一次完整响应时,设置 `stream: false`:
1272
+
1273
+ ```ts
1274
+ const reply = await agent.run("直接返回完整结果", {
1275
+ stream: false,
1276
+ });
1277
+
1278
+ console.log(reply.text);
1279
+ console.log(reply.usage);
1280
+ ```
1281
+
1282
+ 非流式模式仍然支持 Session 写入、工具自动循环、工具审批、超时和中断。
1283
+ 它不会产生 `TEXT_DELTA` 等增量事件,但会产生 `TEXT_DONE`、`TOOL_CALL_DONE`
1284
+ 和 `MESSAGE_DONE` 等完成事件。
1285
+
1286
+ 内置 Provider 都支持非流式请求。自定义 Provider 可以通过
1287
+ `provider.supportsComplete` 检查其 `ModelClient` 是否实现了 `complete()`。
1288
+
1103
1289
  传入已构建的消息:
1104
1290
 
1105
1291
  ```ts
@@ -1113,7 +1299,7 @@ const reply = await agent.runWith(input);
1113
1299
  const reply = await agent.runRaw([
1114
1300
  Message.system("你是一个 JSON 助手。"),
1115
1301
  Message.user("输出 {\"ok\":true}"),
1116
- ]);
1302
+ ], { stream: false });
1117
1303
  ```
1118
1304
 
1119
1305
  ### 监听事件
@@ -1158,6 +1344,7 @@ await agent.run("这一轮限制更短", {
1158
1344
  - `timeoutMs`
1159
1345
  - `promptBuildOptions`
1160
1346
  - `serializeOptions`
1347
+ - `stream`
1161
1348
 
1162
1349
  其他字段会作为模型请求参数合并进去。
1163
1350
 
package/package.json CHANGED
@@ -1,20 +1,37 @@
1
1
  {
2
2
  "name": "@notic/agent-engine",
3
- "version": "1.1.1",
3
+ "version": "1.2.0",
4
4
  "description": "A lightweight, elegant, and feature-complete TypeScript AI Agent framework",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",
7
7
  "exports": {
8
- ".": {
9
- "types": "./dist/index.d.ts",
10
- "default": "./dist/index.js"
11
- }
8
+ ".": {
9
+ "types": "./dist/index.d.ts",
10
+ "default": "./dist/index.js"
11
+ },
12
+ "./adapter": {
13
+ "types": "./dist/adapter/index.d.ts",
14
+ "default": "./dist/adapter/index.js"
15
+ },
16
+ "./client": {
17
+ "types": "./dist/client/index.d.ts",
18
+ "default": "./dist/client/index.js"
19
+ },
20
+ "./provider": {
21
+ "types": "./dist/provider/index.d.ts",
22
+ "default": "./dist/provider/index.js"
23
+ },
24
+ "./stream": {
25
+ "types": "./dist/stream/index.d.ts",
26
+ "default": "./dist/stream/index.js"
27
+ }
12
28
  },
13
29
  "sideEffects": false,
14
30
  "files": [
15
31
  "dist",
16
32
  "docs",
17
33
  "README.md",
34
+ "CHANGELOG.md",
18
35
  "LICENSE"
19
36
  ],
20
37
  "scripts": {
@@ -22,7 +39,7 @@
22
39
  "clean": "rimraf dist",
23
40
  "test": "rimraf .test-dist && tsc -p tsconfig.test.json && node --test .test-dist/**/*.test.js",
24
41
  "test:real:deepseek": "rimraf .test-dist && tsc -p tsconfig.test.json && node --test .test-dist/test/agent/agent.real.test.js",
25
- "prepublishOnly": "npm run clean && npm run build"
42
+ "prepublishOnly": "npm test && npm run clean && npm run build"
26
43
  },
27
44
  "keywords": [
28
45
  "ai",