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