@kernel4632/agent-core 0.26.0 → 0.27.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -4
- package/dist/agent-core.d.ts +7 -0
- package/dist/agent-core.js +87 -80
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -601,6 +601,14 @@ const agent = Agent.create({
|
|
|
601
601
|
})
|
|
602
602
|
```
|
|
603
603
|
|
|
604
|
+
**人机审批的推荐结构**(实战里每个应用都会撞到的问题):
|
|
605
|
+
|
|
606
|
+
- 等用户点击的实现是"返回一个挂起的 Promise"——包保证取消信号一到就不再等它,但**等多久、谁来唤醒**由你的回调决定。常见做法:按 `toolCallId` 存一张 `Map<id, resolve>`,审批接口收到决定后 `resolve(true/false)`。
|
|
607
|
+
- **等待期间 `send` 仍处于"正在运行"**:想允许用户在审批时发新消息顶掉任务,按 `send` 的既有语义处理(新 send 会先 stop 旧的)。
|
|
608
|
+
- **服务重启会丢掉挂起的审批**:`Map` 在内存里。重启后要么给会话补发一条审批请求(凭 history 里的 assistant 工具调用就能还原 `toolCallId`),要么在启动时把该会话标记为"已中断"。
|
|
609
|
+
- **务必给每条路径都 `return`**:非布尔返回值一律按拒绝处理(0.26 起),漏 return 会让这次调用被静默拒绝。
|
|
610
|
+
- **拒绝/取消/无效调用现在也会触发 `onToolResult`**(0.27 起),`output.type` 分别是 `execution-denied` / `error-text`——界面统一从这一个回调翻状态即可,不用再监听 `onPermission` 补通知。
|
|
611
|
+
|
|
604
612
|
---
|
|
605
613
|
|
|
606
614
|
## API 参考
|
|
@@ -795,10 +803,10 @@ console.log(answer.text)
|
|
|
795
803
|
| `onPermission` | 工具执行前 | `{ toolName, input, sessionId, toolCallId, signal }` → 返回 `true/false` |
|
|
796
804
|
| `onToolCall` | 工具即将执行 | `{ toolCallId, toolName, input }` |
|
|
797
805
|
| `onToolOutput` | 工具有流式输出 | `{ toolName, stream, data, toolCallId, input? }`;`data` 是工具 yield / 打印出来的原值,类型不定 |
|
|
798
|
-
| `onToolResult` |
|
|
799
|
-
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }` |
|
|
806
|
+
| `onToolResult` | 工具执行完成(拒绝/取消/无效调用也触发) | `{ toolName, toolCallId, output, ... }` |
|
|
807
|
+
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }`;`toolResults` 是完整结果对象(`call` + `output`),和 `onToolResult` 同一种形状 |
|
|
800
808
|
| `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
|
|
801
|
-
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK
|
|
809
|
+
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK 事件(统一带 `request: 'compact'` 标记)/ `compact-finish`(带 `usage`,即压缩这一笔的用量) |
|
|
802
810
|
|
|
803
811
|
除了 `onPermission`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。
|
|
804
812
|
|
|
@@ -824,6 +832,7 @@ const result = await agent.send({
|
|
|
824
832
|
// result.steps → 这次 send 一共请求了模型几轮
|
|
825
833
|
// result.usage → 整次 send 的用量合计:{ inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens }
|
|
826
834
|
// 算钱、看缓存命中直接读这里;cacheReadTokens / inputTokens 就是缓存命中率
|
|
835
|
+
// 自动压缩那一笔的用量也计在合计里(0.27 起)——压缩也是真实的模型请求
|
|
827
836
|
// result.reason:
|
|
828
837
|
// 'finished' → 没注册工具,或结构化输出已校验成功:这就是最终回答
|
|
829
838
|
// 'no-tool' → 有工具,但连续 noToolRounds 轮(默认 3)没调用工具才结束
|
|
@@ -868,6 +877,18 @@ await agent.send({
|
|
|
868
877
|
await agent.stop() // 等待完全停止后返回 { ok: true };Agent 空闲时返回 { ok: false }
|
|
869
878
|
```
|
|
870
879
|
|
|
880
|
+
#### `agent.resume(options?)`
|
|
881
|
+
|
|
882
|
+
不发新消息,用现有历史的末尾接着跑——典型场景是停止后继续被中断的回复。它不往 `history` 里写任何东西:模型看到的末尾就是中断前的最后一条(assistant 或 tool 消息),所以**不会**出现"续跑后历史里多出一条假的用户消息"。
|
|
883
|
+
|
|
884
|
+
```js
|
|
885
|
+
const answer = await agent.resume() // 从上次停下的地方继续,返回值和 send 相同
|
|
886
|
+
const answer = await agent.resume({ config: { model: '新模型' } }) // 也可以像 send 一样按次覆盖 config / callbacks
|
|
887
|
+
```
|
|
888
|
+
|
|
889
|
+
- 历史末尾必须是 `assistant` 或 `tool` 消息(有"没说完的话"可续),否则直接报错;想发新内容用 `send`。
|
|
890
|
+
- `resume` 不接受 `input`;传了会报错,防止把"继续"误写成新指令。
|
|
891
|
+
|
|
871
892
|
#### 流式与网页实时推送
|
|
872
893
|
|
|
873
894
|
`send` 内部默认就是流式(`config.stream` 默认 `true`),`await` 拿到的是和流式一样的结果。想实时拿到每一块,用 `onLLMEvent`:模型每吐一段就调用一次,事件是包内 AI SDK 的原生事件。
|
|
@@ -1004,10 +1025,15 @@ const agent = Agent.create({ config, tools: safe })
|
|
|
1004
1025
|
|------|--------|
|
|
1005
1026
|
| `schema[name].name` | 工具名 |
|
|
1006
1027
|
| `schema[name].description` | 给模型看的工具说明 |
|
|
1028
|
+
| `schema[name].source` | **来源标记**:`'file'`(目录扫描)或 `'memory'`(内存工具,MCP 工具走这里)。应用判断"这个工具从哪来"读它,别靠工具名前缀猜 |
|
|
1007
1029
|
| `schema[name].inputSchema` | **已编译的校验器**(AI SDK 的 `jsonSchema()` 形态);原始 JSON Schema 在 `inputSchema.jsonSchema` 里 |
|
|
1008
1030
|
| `handlers[name]` | 执行器内部形状(文件工具是 `url`,内存工具是 `execute` 等);**不要自己构造**,原样传回 `merge` / `pick` / `omit` 或 `Agent.tool.execute` |
|
|
1009
1031
|
|
|
1010
|
-
工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers
|
|
1032
|
+
工具对象上的额外字段会被 `scan` / `adopt` 原样带进 `schema[name]`:比如工具自己声明 `touchesFiles: ['path']`,应用层就能从 `tools.schema[name].touchesFiles` 读到。注意 `schema` 是发给模型的那一份,别把不想让模型看到的内部标记放进去(`execute`、`toModelOutput`、`timeout` 不会被带进去,它们只留在 `handlers`)。**想要"只在宿主用、不进 schema"的字段**(比如内部钩子),把工具包一层、从闭包里取,别写在工具对象上:
|
|
1033
|
+
|
|
1034
|
+
```js
|
|
1035
|
+
const wrap = (tool, host) => ({ ...tool, execute: (input, options) => tool.execute(input, { ...options, host }) }) // host 从闭包取,不进 schema
|
|
1036
|
+
```
|
|
1011
1037
|
|
|
1012
1038
|
**MCP 工具直接可用,不需要包装**:`@ai-sdk/mcp` 的 `client.tools()` 自带 `execute` 和 `toModelOutput`,核心按 AI SDK 的签名调用它们,文字、图片都会正确交给模型。完整接入例子见前面的[「接入 MCP 和技能」](#接入-mcp-和技能)。
|
|
1013
1039
|
|
|
@@ -1024,6 +1050,8 @@ const agent = Agent.create({ config, tools: safe })
|
|
|
1024
1050
|
> 从 0.23 升级:内存工具(`Agent.tool.adopt`)现在也支持 `async *execute` 流式输出,和文件工具一致;`Tool.from` 接受一组目录(字符串数组);取消错误统一带 `error.kind === 'aborted'`。
|
|
1025
1051
|
>
|
|
1026
1052
|
> 从 0.25 升级(破坏性改名):上下文预算 `maxTokens` 改名为 **`maxContextTokens`**;`maxTokens` 现在指**单次生成的最大输出** token(映射到请求体的 `maxOutputTokens`)。这是把名字拨回 OpenAI / Anthropic 的习惯(它们的 `max_tokens` 就是输出上限,不是上下文)。另外:`onPermission` 现在要求**严格返回布尔**——非 `true`(含对象、漏 `return`)一律按拒绝处理;新增 `Agent.tool.pick` / `Agent.tool.omit` 用来取工具子集(做只读模式用 `omit` 去掉写工具)。
|
|
1053
|
+
>
|
|
1054
|
+
> 从 0.27 升级:`Compact.run` 的返回值从总结文本变成 `{ content, usage }`(单独用 `Agent.compact` 时注意解构);`onCompact` 的流事件统一带 `request: 'compact'` 标记、`compact-finish` 带 `usage`;工具被拒绝/取消/无效调用也触发 `onToolResult`,`onStep` 的 `toolResults` 是完整结果对象;自动压缩的用量计进 `send().usage`;新增 `agent.resume()` 从历史末尾续跑;工具的 `schema[name]` 带来源标记 `source: 'file' | 'memory'`;文件工具(子进程路径)的 `execute(input, options)` 现在也能拿到 `options.abortSignal`(取消即杀进程不变,信号仅供工具优雅收尾)。
|
|
1027
1055
|
|
|
1028
1056
|
#### `Agent.tool.execute(options)`
|
|
1029
1057
|
|
package/dist/agent-core.d.ts
CHANGED
|
@@ -110,12 +110,18 @@ export interface ToolSet {
|
|
|
110
110
|
handlers: Record<string, any> // 执行器内部形状,不要自己构造,原样传回 merge/pick/omit
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
+
// scan / adopt 会在每个工具的 schema 里盖上来源标记:file(目录扫描)/ memory(内存工具)。
|
|
114
|
+
// 应用判断"这个工具从哪来"读它,不要再靠工具名前缀猜(名字是应用拼的,拼法一变判断就失效)。
|
|
115
|
+
export type ToolSourceKind = 'file' | 'memory'
|
|
116
|
+
|
|
113
117
|
// 内存工具对象的形状(AI SDK tool() 产物、MCP client.tools() 的单项都符合这个形状)
|
|
114
118
|
export interface ToolLike {
|
|
115
119
|
name?: string // 数组形式必填;record 形式从键名取;单个对象直接传时也必填
|
|
116
120
|
description?: string
|
|
117
121
|
inputSchema?: any // 裸 JSON Schema / zod / AI SDK jsonSchema() 三种都认
|
|
118
122
|
execute: (input: any, options?: { signal?: AbortSignal; abortSignal?: AbortSignal }) => any | Promise<any>
|
|
123
|
+
// 两条路径的契约一致:内存工具和文件工具(子进程)的 execute 都拿得到第二参 { signal, abortSignal }。
|
|
124
|
+
// 注意:文件工具的"取消即杀进程"仍由包负责,signal 只是让工具能优雅收尾(比如通知孙进程清理)。
|
|
119
125
|
toModelOutput?: (options: { output: any; input?: any; toolCallId?: string }) => any
|
|
120
126
|
timeout?: number
|
|
121
127
|
[key: string]: any
|
|
@@ -221,6 +227,7 @@ export interface AgentInstance {
|
|
|
221
227
|
(input: string | any[], options?: Omit<SendOptions, 'input'>): Promise<Answer>
|
|
222
228
|
(options: SendOptions & { input: string | any[] }): Promise<Answer>
|
|
223
229
|
}
|
|
230
|
+
resume: (options?: Omit<SendOptions, 'input'>) => Promise<Answer> // 不发新消息,用现有历史末尾续跑(历史末尾须是 assistant/tool)
|
|
224
231
|
stop: () => Promise<{ ok: boolean }>
|
|
225
232
|
compact: (options?: { onCompact?: Callbacks['onCompact']; onRetry?: Callbacks['onRetry']; signal?: AbortSignal }) => Promise<string>
|
|
226
233
|
}
|