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