@kernel4632/agent-core 0.24.17 → 0.25.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 +1416 -1388
- package/dist/agent-core.d.ts +13 -0
- package/dist/agent-core.js +64 -63
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,1388 +1,1416 @@
|
|
|
1
|
-
# @kernel4632/agent-core
|
|
2
|
-
|
|
3
|
-
[](https://github.com/kernel4632/agent-core/actions/workflows/ci.yml)
|
|
4
|
-
[](https://github.com/kernel4632/agent-core/releases/latest)
|
|
5
|
-
|
|
6
|
-
一个轻量的 AI Agent 核心包。给它一个 LLM 地址和一些工具(工具文件目录,或内存里的工具对象),它就能自动循环"问模型 → 执行工具 → 再问模型",直到任务完成。
|
|
7
|
-
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
## 目录
|
|
11
|
-
|
|
12
|
-
- [这个包是干什么的](#这个包是干什么的)
|
|
13
|
-
- [核心设计:为什么是它](#核心设计为什么是它)
|
|
14
|
-
- [安装](#安装)
|
|
15
|
-
- [5 分钟快速上手](#5-分钟快速上手)
|
|
16
|
-
- [三种用法:从纯聊天到接 MCP 和技能](#三种用法从纯聊天到接-mcp-和技能)
|
|
17
|
-
- [接入 MCP 和技能](#接入-mcp-和技能)
|
|
18
|
-
- [项目架构](#项目架构)
|
|
19
|
-
- [自定义工具:从零到完整](#自定义工具从零到完整)
|
|
20
|
-
- [API 参考](#api-参考)
|
|
21
|
-
- [上生产前](#上生产前)
|
|
22
|
-
- [可观测性](#可观测性)
|
|
23
|
-
- [示例](#示例)
|
|
24
|
-
- [长跑压测](#长跑压测)
|
|
25
|
-
- [运行测试](#运行测试)
|
|
26
|
-
- [打包成单文件](#打包成单文件)
|
|
27
|
-
- [这个包不做什么](#这个包不做什么)
|
|
28
|
-
- [常见问题](#常见问题)
|
|
29
|
-
|
|
30
|
-
---
|
|
31
|
-
|
|
32
|
-
## 这个包是干什么的
|
|
33
|
-
|
|
34
|
-
你可以把它理解成一个"AI 大脑驱动引擎":
|
|
35
|
-
|
|
36
|
-
```mermaid
|
|
37
|
-
flowchart TD
|
|
38
|
-
app["你的程序"] --> create["Agent.create()<br/>创建实例"]
|
|
39
|
-
create --> send["agent.send()<br/>发送指令"]
|
|
40
|
-
send --> loop["Loop<br/>自动循环"]
|
|
41
|
-
loop --> llm["LLM<br/>问模型"]
|
|
42
|
-
loop --> tool["Tool<br/>执行工具"]
|
|
43
|
-
tool --> loop
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
模型每次回复要么"调用某个工具",要么"我做完了"。这个包负责把这个循环跑起来,你只需要写工具文件就行。
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## 核心设计:为什么是它
|
|
51
|
-
|
|
52
|
-
两件事是这个包真正想做的,别的都围着它们转。**看清这两条,就理解了这个包的全部取舍。**
|
|
53
|
-
|
|
54
|
-
### 一、独特的 Agent 循环
|
|
55
|
-
|
|
56
|
-
循环骨架很简单(建上下文 → 问模型 → 要调工具就执行再回上去),难的是**什么时候停下来**。这个包在"停"这件事上有几个和别人不一样的决定。
|
|
57
|
-
|
|
58
|
-
```mermaid
|
|
59
|
-
flowchart TD
|
|
60
|
-
A["建上下文<br/>(太长先压缩一次)"] --> B["问一次模型"]
|
|
61
|
-
B --> C{"模型要调工具?"}
|
|
62
|
-
|
|
63
|
-
C -->|要| D["并行执行所有工具"]
|
|
64
|
-
D --> E["结果写回 history"]
|
|
65
|
-
E --> S{"有工具返回<br/>stop:true?"}
|
|
66
|
-
S -->|是| T1["返回 tool-stop"]
|
|
67
|
-
S -->|否| T2{"步数到 maxSteps?"}
|
|
68
|
-
T2 -->|是| T3["返回 step-limit"]
|
|
69
|
-
T2 -->|否| A
|
|
70
|
-
|
|
71
|
-
C -->|不要| F{"结束判定"}
|
|
72
|
-
F -->|结构化输出成功<br/>或没注册工具| R1["返回 finished"]
|
|
73
|
-
F -->|步数到 maxSteps| T3
|
|
74
|
-
F -->|连续不调工具<br/>达 noToolRounds| R2["返回 no-tool"]
|
|
75
|
-
F -->|还没到| P["继续下一轮<br/>(末轮前插一句提醒)"]
|
|
76
|
-
P --> A
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
**① 模型不调工具,不会立刻结束。** 很多模型在任务没做完时会"礼貌地"给一段总结就停下。直接结束会把没干完的活丢掉。所以有工具时,模型不调工具会先**临时**插一句提醒(`noToolPrompt`)再问一次,连续 `noToolRounds` 轮(默认 3)都不调才结束。这句提醒只挂在那一次请求上,**不写进 `history`**。不想要这个行为,把 `noToolRounds` 设成 `Infinity`。
|
|
80
|
-
|
|
81
|
-
**② `history` 是唯一的权威数据来源,只增不删。** 循环从不修改历史,模型消息、工具结果按发生的顺序追加。连压缩也只追加一条总结。原因:`history` 归你的应用所有(存库、渲染、多会话),核心替它丢弃数据是不可逆的错误——该留多少由持有它的你决定。
|
|
82
|
-
|
|
83
|
-
**③ 一轮里的工具并行执行。** 模型经常一次要求调好几个工具;串行会让任务慢好几倍。所以同一轮的工具同时开跑,结果按原顺序收齐再写回历史。每个工具独占一个子进程,所以死循环的工具能被一刀杀掉,崩溃的工具不会拖垮 Agent。
|
|
84
|
-
|
|
85
|
-
**④ 每次 `send` 只跑一个任务,"最新指令优先"。** 新的 `send` 会先停掉上一个(同一次 tick 里发出的请求,后者一定看得见前者并把它停掉)。原因:一台 Agent 只有一份 `history`,两个任务同时写会乱序。
|
|
86
|
-
|
|
87
|
-
**⑤ 每个出口都补一条模型能读的结果。** 取消 → 一条"已中断"结果;工具失败 → 一条错误结果;模型点了不存在的工具 → 一条"调用无效"结果。**绝不留下"有调用、没结果"的残缺记录**。原因:这种残缺序列会被 OpenAI / Anthropic 直接 400,而 `history` 只增不删,一次残缺就永久毒死这个会话,重启装回历史也一样。
|
|
88
|
-
|
|
89
|
-
### 二、独特的上下文压缩保留方案
|
|
90
|
-
|
|
91
|
-
大多数做法是"上下文满了就丢掉旧消息"。这个包**不丢,只追加总结**——它改的是"这一次发给模型的内容有多大",不是"历史能留多少"。
|
|
92
|
-
|
|
93
|
-
`history` 里原文一条不少;每次发请求时,只从里面**现挑**该带哪些回合:
|
|
94
|
-
|
|
95
|
-
| history 里的位置 | 内容 | 这一次发给模型吗 |
|
|
96
|
-
|------------------|------|------------------|
|
|
97
|
-
| 最初 | 用户最初的目标 | 保留:最多 3 个用户回合、≤20% 预算 |
|
|
98
|
-
| 中段 | 更早的回合 | 已被总结覆盖,不再单独发 |
|
|
99
|
-
| 总结 | 最新一条 `compact` 总结 | 折进 `system`(不是当消息) |
|
|
100
|
-
| 总结前 | 最近的现场回合 | 保留:最多 3 个回合、≤30% 预算 |
|
|
101
|
-
| 总结后 | 之后的全部新回合 | 全部保留(当前正在推进的) |
|
|
102
|
-
|
|
103
|
-
几个关键取舍,以及为什么:
|
|
104
|
-
|
|
105
|
-
- **裁剪的最小单位是「回合」,不是「消息」。** 一个回合 = 用户一次发言,或模型的一次响应连同它发起的全部工具调用和结果。工具结果按 `toolCallId` 回到发起它的回合,**同进同出**。所以裁剪结果永远不会切断"调用 / 结果"的配对——那种残缺会被供应商 400。
|
|
106
|
-
- **最新那条总结折进 system,而不是当成一条消息塞进对话。** 裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是从头重做整个任务。实测 `gpt-oss-120b` 折进 system 前只有 1/6 能正确接着做,之后 6/6。
|
|
107
|
-
- **总结里保留最初目标。** 挑内容时,最初那几轮用户发言(说不出的话)单独钉住,最多 3 个回合、占 20% 预算。就算预算装不下,总结本身也被要求保留"用户最初的目标",而总结在 `system` 里永远不会被裁掉。
|
|
108
|
-
- **二次压缩不会忘掉上一次的总结。** 压缩请求会把上一版总结作为"背景"并进提示词,新总结必须保留其中仍然有效的事实。直接丢掉旧总结,会越压越忘。
|
|
109
|
-
- **按预算保留,不按条数。** 用户第一条消息就粘一大段日志时,只按条数留会让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。所以旧内容按预算分:目标 20%、最近现场 30%。
|
|
110
|
-
- **每轮最多压一次。** 不为"压到达标"而连续调用模型——那样一轮能烧掉上千次请求(实测)。压完还超限就照常发出去,由服务端判断;下一轮还超自然会再压一次。
|
|
111
|
-
|
|
112
|
-
> 一句话:**history 永不删、总结折进 system、裁剪按回合。** 这三条一起保证——发给模型的永远是合法上下文,模型永远能"接着做"而不是"重做",而你的完整历史一条都没丢。
|
|
113
|
-
|
|
114
|
-
---
|
|
115
|
-
|
|
116
|
-
## 安装
|
|
117
|
-
|
|
118
|
-
这个包需要 [Bun](https://bun.sh) 运行时(不支持 Node.js)。
|
|
119
|
-
|
|
120
|
-
从 npm 安装:
|
|
121
|
-
|
|
122
|
-
```bash
|
|
123
|
-
bun add @kernel4632/agent-core
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
想锁死某个版本(比如 `0.24.
|
|
127
|
-
|
|
128
|
-
```bash
|
|
129
|
-
bun add @kernel4632/agent-core@0.24.
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
也可以从 GitHub Release 安装,永远拿到最新版:
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
bun add https://github.com/kernel4632/agent-core/releases/latest/download/agent-core.tgz
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
想锁死某个 GitHub 版本,把链接里的 `latest/download` 换成 `download/v0.24.
|
|
139
|
-
|
|
140
|
-
```bash
|
|
141
|
-
bun add https://github.com/kernel4632/agent-core/releases/download/v0.24.
|
|
142
|
-
```
|
|
143
|
-
|
|
144
|
-
以后升级到最新版,再运行一次安装命令就行。
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
## 5 分钟快速上手
|
|
149
|
-
|
|
150
|
-
### 第一步:写一个工具文件
|
|
151
|
-
|
|
152
|
-
新建 `tools/say-hello.js`:
|
|
153
|
-
|
|
154
|
-
```js
|
|
155
|
-
export default {
|
|
156
|
-
name: 'say_hello', // 工具名,模型通过这个名字调用它
|
|
157
|
-
description: '向指定的人打招呼', // 告诉模型这个工具是干什么的
|
|
158
|
-
inputSchema: { // 描述模型需要传哪些参数
|
|
159
|
-
type: 'object',
|
|
160
|
-
properties: {
|
|
161
|
-
name: { type: 'string', description: '要打招呼的人的名字' },
|
|
162
|
-
},
|
|
163
|
-
required: ['name'],
|
|
164
|
-
},
|
|
165
|
-
async execute(input) { // 真正执行的函数,input 就是模型传来的参数
|
|
166
|
-
return `你好,${input.name}!` // 返回值会原样告诉模型
|
|
167
|
-
},
|
|
168
|
-
}
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
### 第二步:创建 Agent 并发送指令
|
|
172
|
-
|
|
173
|
-
新建 `main.js`:
|
|
174
|
-
|
|
175
|
-
```js
|
|
176
|
-
import Agent from '@kernel4632/agent-core'
|
|
177
|
-
|
|
178
|
-
// 一行拿到工具:目录、内存工具(MCP / AI SDK)可以任意搭配
|
|
179
|
-
const tools = await Agent.tool.from('./tools')
|
|
180
|
-
|
|
181
|
-
// 创建一个 Agent 实例
|
|
182
|
-
const agent = Agent.create({
|
|
183
|
-
config: {
|
|
184
|
-
baseURL: 'https://你的模型地址/v1', // OpenAI 兼容接口地址
|
|
185
|
-
apiKey: 'sk-你的密钥',
|
|
186
|
-
model: '模型名称',
|
|
187
|
-
system: '你是一个助手,请使用工具完成用户的任务。',
|
|
188
|
-
},
|
|
189
|
-
tools, // 把扫描好的工具传进来
|
|
190
|
-
callbacks: {
|
|
191
|
-
onToolResult: result => { // 工具执行完时的回调
|
|
192
|
-
console.log('工具执行完了:', result.toolName, result.output)
|
|
193
|
-
},
|
|
194
|
-
},
|
|
195
|
-
})
|
|
196
|
-
|
|
197
|
-
// 发送指令,等待完成
|
|
198
|
-
const result = await agent.send('帮我向小明打个招呼')
|
|
199
|
-
console.log('Agent 结束,原因:', result.reason) // 有工具时通常是 'no-tool':模型停手后还会被追问最多 noToolRounds 轮(默认 3)才结束
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
> 上面这个例子里注册了工具,所以模型就算一次就把话说完了,`send` 也不会立刻返回——它会连续几轮确认模型真的不再用工具(这是这个包循环的特点,避免模型过早收手)。想一停手就结束,设 `noToolRounds: 1`;想明确收尾,写一个返回 `stop: true` 的 `finish` 工具。
|
|
203
|
-
|
|
204
|
-
运行:
|
|
205
|
-
|
|
206
|
-
```bash
|
|
207
|
-
bun main.js
|
|
208
|
-
```
|
|
209
|
-
|
|
210
|
-
---
|
|
211
|
-
|
|
212
|
-
## 三种用法:从纯聊天到接 MCP 和技能
|
|
213
|
-
|
|
214
|
-
先看清自己属于哪一种,再往下读:
|
|
215
|
-
|
|
216
|
-
| 你想做什么 | 怎么写 | 去哪看 |
|
|
217
|
-
|------------|--------|--------|
|
|
218
|
-
| 只聊天,不用工具 | `Agent.create({ config })` 然后 `agent.send('...')` | 上面的快速上手 |
|
|
219
|
-
| 用普通工具(自己写的文件) | `tools = await Agent.tool.from('./tools')`,传给 `create` | 「自定义工具」「`Agent.tool`」 |
|
|
220
|
-
| 用 MCP 工具、用技能(skills) | 应用自己连 MCP、读技能,再用 `Agent.tool.from(...)` 汇进来 | 下一节「接入 MCP 和技能」 |
|
|
221
|
-
|
|
222
|
-
一句话记住:**这个包只负责"循环 + 执行工具"**。MCP 的连接、技能的读取都不是它的事——你把它们变成普通工具对象交进来就行。
|
|
223
|
-
|
|
224
|
-
---
|
|
225
|
-
|
|
226
|
-
## 接入 MCP 和技能
|
|
227
|
-
|
|
228
|
-
MCP 和技能(skills)都由**你的应用**负责,核心只接收通用工具对象。两者的做法一样:先拿到"工具对象",再交给 `Agent.tool.from`。
|
|
229
|
-
|
|
230
|
-
```mermaid
|
|
231
|
-
flowchart TD
|
|
232
|
-
f["文件工具<br/>./tools"] --> from["Agent.tool.from(...)"]
|
|
233
|
-
m["MCP 工具<br/>mcp.tools()"] --> from
|
|
234
|
-
s["技能工具<br/>skills.readTool()"] --> from
|
|
235
|
-
from --> agent["Agent.create(...)"]
|
|
236
|
-
```
|
|
237
|
-
|
|
238
|
-
### 接 MCP
|
|
239
|
-
|
|
240
|
-
MCP 是"模型调用外部服务"的标准协议。用官方客户端 `@ai-sdk/mcp` 连上服务后,它给出的工具对象**直接就能用**,不需要任何包装:
|
|
241
|
-
|
|
242
|
-
```js
|
|
243
|
-
import { createMCPClient } from '@ai-sdk/mcp'
|
|
244
|
-
import { Experimental_StdioMCPTransport as Stdio } from '@ai-sdk/mcp/mcp-stdio' // stdio 传输要从子路径导入
|
|
245
|
-
|
|
246
|
-
// 连接由你的应用管理:什么时候连、连哪个、什么时候关
|
|
247
|
-
const mcp = await createMCPClient({
|
|
248
|
-
transport: new Stdio({ command: 'bun', args: ['./mcp-server.js'] }),
|
|
249
|
-
})
|
|
250
|
-
|
|
251
|
-
const tools = await Agent.tool.from('./tools', mcp.tools()) // 就这一句
|
|
252
|
-
const agent = Agent.create({ config, tools })
|
|
253
|
-
|
|
254
|
-
// ... 用完后
|
|
255
|
-
await mcp.close()
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
> MCP 工具的返回值(文字、图片)会自动转成模型能读的块。想自己改写,见「`Agent.tool.adopt`」。
|
|
259
|
-
|
|
260
|
-
### 接技能(skills)
|
|
261
|
-
|
|
262
|
-
技能是"现成的操作步骤":一个文件夹放一份 `SKILL.md`,开头写名字和说明,下面是正文。约定见 [agentskills.io](https://agentskills.io)。
|
|
263
|
-
|
|
264
|
-
```
|
|
265
|
-
skills/
|
|
266
|
-
└── review-pr/
|
|
267
|
-
└── SKILL.md # 开头是 name 和 description,下面是步骤正文
|
|
268
|
-
```
|
|
269
|
-
|
|
270
|
-
社区有现成的库负责**读取和校验**这些文件,比如 `agent-skills-ts-sdk`。它给你两样东西:一段"技能清单"(放进 `system` 让模型知道有哪些技能)和一个"按需读正文"的工具。扫描、组装仍由你写,就是下面这几行:
|
|
271
|
-
|
|
272
|
-
```js
|
|
273
|
-
import { createSkillRegistry, skillSourceFromEntries } from 'agent-skills-ts-sdk'
|
|
274
|
-
|
|
275
|
-
const sources = []
|
|
276
|
-
for await (const file of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
277
|
-
sources.push(skillSourceFromEntries(
|
|
278
|
-
[{ name: 'SKILL.md', content: await Bun.file(file).text() }],
|
|
279
|
-
{ id: file, location: file },
|
|
280
|
-
))
|
|
281
|
-
}
|
|
282
|
-
const skills = await createSkillRegistry(sources)
|
|
283
|
-
const decl = skills.readTool() // 技能清单 + 一个"读正文"的工具声明
|
|
284
|
-
|
|
285
|
-
const skillTool = {
|
|
286
|
-
description: decl.description,
|
|
287
|
-
inputSchema: decl.parametersJsonSchema,
|
|
288
|
-
execute: async args => {
|
|
289
|
-
const r = await skills.read(args)
|
|
290
|
-
return r.ok ? r.content : { output: { type: 'error-text', value: r.error } }
|
|
291
|
-
},
|
|
292
|
-
}
|
|
293
|
-
|
|
294
|
-
// 清单进 system,正文等模型需要时用 skill 工具读
|
|
295
|
-
const system = ['你是一个编程助手。', skills.systemPrompt()].filter(Boolean).join('\n\n')
|
|
296
|
-
const tools = await Agent.tool.from({ [decl.name]: skillTool })
|
|
297
|
-
const agent = Agent.create({ config: { ...config, system }, tools })
|
|
298
|
-
|
|
299
|
-
await agent.send('按 review-pr 技能审查这个改动')
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
### MCP 和技能一起用
|
|
303
|
-
|
|
304
|
-
一次性汇进去就行:
|
|
305
|
-
|
|
306
|
-
```js
|
|
307
|
-
const tools = await Agent.tool.from(
|
|
308
|
-
'./tools', // 文件工具
|
|
309
|
-
mcp.tools(), // MCP 工具
|
|
310
|
-
{ [decl.name]: skillTool }, // 技能加载工具
|
|
311
|
-
)
|
|
312
|
-
```
|
|
313
|
-
|
|
314
|
-
<details>
|
|
315
|
-
<summary>不想引库?自己读 SKILL.md 也就十几行</summary>
|
|
316
|
-
|
|
317
|
-
`SKILL.md` 的开头是一小段用 `---` 包起来的说明(`name` 和 `description`),下面是正文。自己切开即可:
|
|
318
|
-
|
|
319
|
-
```js
|
|
320
|
-
const skills = {}
|
|
321
|
-
for await (const path of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
322
|
-
const text = await Bun.file(path).text()
|
|
323
|
-
const name = text.match(/name:\s*(.+)/)?.[1]?.trim()
|
|
324
|
-
const description = text.match(/description:\s*(.+)/)?.[1]?.trim()
|
|
325
|
-
const body = text.replace(/^---[\s\S]*?---/, '').trim() // 去掉说明段,只留正文
|
|
326
|
-
if (name) skills[name] = { description, body }
|
|
327
|
-
}
|
|
328
|
-
|
|
329
|
-
const names = Object.keys(skills)
|
|
330
|
-
const system = names.length
|
|
331
|
-
? '可用技能(需要时用 skill 工具读正文):\n' + names.map(n => `- ${n}:${skills[n].description}`).join('\n')
|
|
332
|
-
: ''
|
|
333
|
-
|
|
334
|
-
const skillTool = {
|
|
335
|
-
skill: {
|
|
336
|
-
description: '按名字读取一个技能的完整步骤',
|
|
337
|
-
inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
|
|
338
|
-
execute: async ({ name }) => {
|
|
339
|
-
if (!Object.hasOwn(skills, name)) throw new Error(`没有技能 ${name}`)
|
|
340
|
-
return skills[name].body
|
|
341
|
-
},
|
|
342
|
-
},
|
|
343
|
-
}
|
|
344
|
-
|
|
345
|
-
// 拼装:提示词进 system,读正文的工具进 tools
|
|
346
|
-
const tools = await Agent.tool.from('./tools', skillTool)
|
|
347
|
-
const agent = Agent.create({ config: { ...config, system: ['你是一个助手。', system].filter(Boolean).join('\n\n') }, tools })
|
|
348
|
-
```
|
|
349
|
-
|
|
350
|
-
完整约定(frontmatter 字段、目录名等于技能名、正文按需加载)见 [agentskills.io](https://agentskills.io)。想要省事就直接用上面的 `agent-skills-ts-sdk` 之类的库。
|
|
351
|
-
|
|
352
|
-
</details>
|
|
353
|
-
|
|
354
|
-
---
|
|
355
|
-
|
|
356
|
-
## 项目架构
|
|
357
|
-
|
|
358
|
-
```
|
|
359
|
-
@kernel4632/agent-core
|
|
360
|
-
│
|
|
361
|
-
├── index.js ← 唯一入口:create / send / stop / compact,把下面的功能组合起来
|
|
362
|
-
│
|
|
363
|
-
├── features/ ← 功能:由入口或主循环组合起来用,每个文件一个主体
|
|
364
|
-
│ ├── loop.js ← 主循环:Context → TextTools → LLM → 工具 → ...
|
|
365
|
-
│ ├── llm.js ← 只负责和模型说话:四种协议、缓存、超时、错误分类
|
|
366
|
-
│ ├── text-tools.js ← 文字工具协议:让纯对话模型也能调用工具
|
|
367
|
-
│ ├── history.js ← 对话记录:造消息块、拆回合、渲染
|
|
368
|
-
│ ├── context.js ← 把历史消息裁剪成这一轮发给模型的上下文
|
|
369
|
-
│ ├── compact.js ← 上下文太长时写总结
|
|
370
|
-
│ ├── tool.js ← 工具:扫描文件工具、接纳内存工具、执行、合并(主线程这一半)
|
|
371
|
-
│ └── tool-process.js ← 文件工具真正跑起来的地方(子进程那一半)
|
|
372
|
-
│
|
|
373
|
-
└── utils/ ← 工具:被功能调用,不反过来依赖功能
|
|
374
|
-
├── retry.js ← 失败自动重试(指数退避)
|
|
375
|
-
├── notify.js ← 所有回调的统一出口
|
|
376
|
-
├── schema.js ← 工具参数格式归一化(scan 和 adopt 共用)
|
|
377
|
-
├── shape.js ← 工具返回值变成输出块(内存工具用;子进程里有一份副本)
|
|
378
|
-
└── tokens.js ← 上下文 token 估算:字符数 × 每字符 token 比,比例由真实 usage 自校准
|
|
379
|
-
```
|
|
380
|
-
|
|
381
|
-
`tool.js` 和 `tool-process.js` 是同一件事的两半,所以放在一起:前者在主线程里找工具、管工具进程,
|
|
382
|
-
后者被前者当成文本内联、在独立的 bun 子进程里加载并执行工具。分成两个文件是平台限制,不是分层。
|
|
383
|
-
|
|
384
|
-
**工具进程隔离的是生命周期,不是环境。** 工具在里面拥有和 Agent 完全相同的权限:读写任意文件、执行任意命令、联网、读到父进程的全部环境变量。这是有意的——电脑任务 agent 的工具本来就得能干这些。它真正隔离的是四样:**失控**(死循环工具能被一刀杀掉,实测 0ms)、**崩溃**(工具死了 Agent 继续跑)、**内存**(独立堆)、**Agent 状态**(工具碰不到 `history`、`config`、`running`)。
|
|
385
|
-
|
|
386
|
-
**为什么用子进程而不是 Worker 线程**:Worker 被 `terminate()` 之后 Bun 不归还它占的约 22MB,
|
|
387
|
-
而且杀线程带不走它 `Bun.spawn` 出来的孙进程。常驻 agent 天天要杀工具进程(工具崩溃、超时、用户打断),
|
|
388
|
-
两笔账会一直累积。换成子进程之后实测 200 次「起→用→杀」主进程只涨 2MB(Worker 版是 4.4GB),
|
|
389
|
-
孙进程一起带走,主进程退出时工具进程也全部跟着死。复用时单次调用 0.08ms,比 Worker 还快。
|
|
390
|
-
|
|
391
|
-
### 数据流
|
|
392
|
-
|
|
393
|
-
```mermaid
|
|
394
|
-
flowchart TD
|
|
395
|
-
send["agent.send(input)"] --> hu["History.user()"]
|
|
396
|
-
hu --> ctx["Context.build()<br/>裁剪上下文"]
|
|
397
|
-
ctx --> llm["LLM.chat()<br/>请求模型"]
|
|
398
|
-
llm --> q{"模型要调工具?"}
|
|
399
|
-
q -->|要| te["Tool.execute()<br/>并行执行"]
|
|
400
|
-
te --> wr["结果写入 history"]
|
|
401
|
-
wr --> ctx
|
|
402
|
-
q -->|不要| done["结束判定<br/>(分支见「核心设计」)"]
|
|
403
|
-
```
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
## 自定义工具:从零到完整
|
|
408
|
-
|
|
409
|
-
### 最简单的工具
|
|
410
|
-
|
|
411
|
-
```js
|
|
412
|
-
// tools/add.js
|
|
413
|
-
export default {
|
|
414
|
-
name: 'add',
|
|
415
|
-
description: '把两个数字加在一起',
|
|
416
|
-
inputSchema: {
|
|
417
|
-
type: 'object',
|
|
418
|
-
properties: {
|
|
419
|
-
a: { type: 'number' },
|
|
420
|
-
b: { type: 'number' },
|
|
421
|
-
},
|
|
422
|
-
required: ['a', 'b'],
|
|
423
|
-
},
|
|
424
|
-
async execute(input) {
|
|
425
|
-
return input.a + input.b // 直接返回结果
|
|
426
|
-
},
|
|
427
|
-
}
|
|
428
|
-
```
|
|
429
|
-
|
|
430
|
-
### 带流式输出的工具
|
|
431
|
-
|
|
432
|
-
工具可以用 `yield` 逐步返回内容,适合耗时较长的操作:
|
|
433
|
-
|
|
434
|
-
```js
|
|
435
|
-
// tools/count.js
|
|
436
|
-
export default {
|
|
437
|
-
name: 'count',
|
|
438
|
-
description: '从 1 数到 n,逐步输出',
|
|
439
|
-
inputSchema: {
|
|
440
|
-
type: 'object',
|
|
441
|
-
properties: { n: { type: 'number' } },
|
|
442
|
-
required: ['n'],
|
|
443
|
-
},
|
|
444
|
-
async *execute(input) { // 注意:async * 是异步生成器
|
|
445
|
-
for (let i = 1; i <= input.n; i++) {
|
|
446
|
-
yield `数到了 ${i}` // 每次 yield 都会立刻发给上层的 onOutput 回调
|
|
447
|
-
await new Promise(r => setTimeout(r, 100))
|
|
448
|
-
}
|
|
449
|
-
},
|
|
450
|
-
}
|
|
451
|
-
```
|
|
452
|
-
|
|
453
|
-
文件工具和内存工具都支持 `async *execute`(`Agent.tool.adopt` 接纳的内存工具也一样)。接收流式输出:
|
|
454
|
-
|
|
455
|
-
```js
|
|
456
|
-
const agent = Agent.create({
|
|
457
|
-
// ...
|
|
458
|
-
callbacks: {
|
|
459
|
-
onToolOutput: output => {
|
|
460
|
-
console.log('实时输出:', output.data) // 每次 yield 触发一次
|
|
461
|
-
},
|
|
462
|
-
},
|
|
463
|
-
})
|
|
464
|
-
```
|
|
465
|
-
|
|
466
|
-
### 调用子进程的工具
|
|
467
|
-
|
|
468
|
-
工具在独立子进程里运行,`Bun.spawn` 的 stdout/stderr 会自动转发给 `onToolOutput`,不需要额外处理:
|
|
469
|
-
|
|
470
|
-
```js
|
|
471
|
-
// tools/run-script.js
|
|
472
|
-
export default {
|
|
473
|
-
name: 'run_script',
|
|
474
|
-
description: '运行一个 shell 脚本',
|
|
475
|
-
inputSchema: {
|
|
476
|
-
type: 'object',
|
|
477
|
-
properties: { command: { type: 'string' } },
|
|
478
|
-
required: ['command'],
|
|
479
|
-
},
|
|
480
|
-
async execute(input) {
|
|
481
|
-
const proc = Bun.spawn(['bash', '-c', input.command], {
|
|
482
|
-
stdout: 'pipe',
|
|
483
|
-
stderr: 'pipe',
|
|
484
|
-
})
|
|
485
|
-
await proc.exited
|
|
486
|
-
return { exitCode: proc.exitCode } // stdout/stderr 已经自动转发了
|
|
487
|
-
},
|
|
488
|
-
}
|
|
489
|
-
```
|
|
490
|
-
|
|
491
|
-
### 一个文件导出多个工具
|
|
492
|
-
|
|
493
|
-
```js
|
|
494
|
-
// tools/math.js
|
|
495
|
-
const add = {
|
|
496
|
-
name: 'add',
|
|
497
|
-
description: '加法',
|
|
498
|
-
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
499
|
-
async execute(input) { return input.a + input.b },
|
|
500
|
-
}
|
|
501
|
-
|
|
502
|
-
const multiply = {
|
|
503
|
-
name: 'multiply',
|
|
504
|
-
description: '乘法',
|
|
505
|
-
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
506
|
-
async execute(input) { return input.a * input.b },
|
|
507
|
-
}
|
|
508
|
-
|
|
509
|
-
export default [add, multiply] // 导出数组
|
|
510
|
-
```
|
|
511
|
-
|
|
512
|
-
工具是按**名字**找到的,不是按它在数组里排第几。所以往文件里插入新工具、调换顺序都不会让模型调错工具。
|
|
513
|
-
|
|
514
|
-
### 工具目录里可以放共享代码
|
|
515
|
-
|
|
516
|
-
扫描时只把"形状对得上"(有 `name`、有 `execute`)的东西注册成工具,其余文件直接跳过。
|
|
517
|
-
所以下面这些都可以和工具放在同一个目录里,不会影响扫描:
|
|
518
|
-
|
|
519
|
-
```
|
|
520
|
-
tools/
|
|
521
|
-
├── read.js ← 工具
|
|
522
|
-
├── write.js ← 工具
|
|
523
|
-
├── shared.js ← 共享辅助函数,没有默认导出,自动跳过
|
|
524
|
-
└── read.test.js ← 测试文件,自动跳过
|
|
525
|
-
```
|
|
526
|
-
|
|
527
|
-
跳过的前提是这些文件**能被加载**。目录里任何一个 `.js` 有语法错误、或者 import 了装不上的依赖,
|
|
528
|
-
`scan` 会当场抛出来——这是有意的:工具目录是你自己的代码,坏了就该立刻知道,
|
|
529
|
-
静默跳过只会变成"某个工具莫名其妙不见了"。
|
|
530
|
-
|
|
531
|
-
### 主动停止 Agent 的工具
|
|
532
|
-
|
|
533
|
-
如果某个工具代表"任务完成",可以让它返回 `stop: true`,Agent 循环会立刻停止:
|
|
534
|
-
|
|
535
|
-
```js
|
|
536
|
-
// tools/finish.js
|
|
537
|
-
export default {
|
|
538
|
-
name: 'finish',
|
|
539
|
-
description: '任务完成时调用这个工具',
|
|
540
|
-
inputSchema: {
|
|
541
|
-
type: 'object',
|
|
542
|
-
properties: { summary: { type: 'string', description: '完成情况总结' } },
|
|
543
|
-
required: ['summary'],
|
|
544
|
-
},
|
|
545
|
-
async execute(input) {
|
|
546
|
-
return {
|
|
547
|
-
stop: true, // 告诉 Loop 停止循环
|
|
548
|
-
output: { type: 'text', value: input.summary },
|
|
549
|
-
}
|
|
550
|
-
},
|
|
551
|
-
}
|
|
552
|
-
```
|
|
553
|
-
|
|
554
|
-
### 返回图片的工具
|
|
555
|
-
|
|
556
|
-
工具可以直接返回一个成形的输出块。截图、生成图表这类工具就靠这个把图交给模型:
|
|
557
|
-
|
|
558
|
-
```js
|
|
559
|
-
// tools/screenshot.js
|
|
560
|
-
export default {
|
|
561
|
-
name: 'screenshot',
|
|
562
|
-
description: '截取当前屏幕',
|
|
563
|
-
inputSchema: { type: 'object', properties: {} },
|
|
564
|
-
async execute() {
|
|
565
|
-
const png = await grabScreen() // 你自己的截图实现,拿到 base64
|
|
566
|
-
return {
|
|
567
|
-
output: {
|
|
568
|
-
type: 'content', // 多模态输出块
|
|
569
|
-
value: [
|
|
570
|
-
{ type: 'text', text: '当前屏幕:' },
|
|
571
|
-
{ type: 'file', mediaType: 'image/png', data: { type: 'data', data: png } },
|
|
572
|
-
],
|
|
573
|
-
},
|
|
574
|
-
}
|
|
575
|
-
},
|
|
576
|
-
}
|
|
577
|
-
```
|
|
578
|
-
|
|
579
|
-
`content` 块里只能放 `text` / `file` / `file-data` / `file-url`,以及旧写法 `image` / `audio` / `video`(发出前会自动转成 `file`)。放别的(比如旧版 AI SDK 的 `media`)会被工具进程当场挡住、变成一条普通的工具失败——这是有意的:非法块一旦穿过去写进 `history`,AI SDK 会在本地校验时抛错、请求根本发不出去、重试也认不出来,而 `history` 只增不删,于是之后每次 `send` 都撞同一堵墙,重启装回历史也一样。
|
|
580
|
-
|
|
581
|
-
`output` 里给的块会被原样交给模型,不会再被套一层。`maxToolOutput` 的截断**只作用于文字块**——图截一刀就彻底废了,所以媒体内容一个字节都不动。
|
|
582
|
-
|
|
583
|
-
### 工具权限询问
|
|
584
|
-
|
|
585
|
-
在敏感操作前可以要求用户确认:
|
|
586
|
-
|
|
587
|
-
```js
|
|
588
|
-
const agent = Agent.create({
|
|
589
|
-
// ...
|
|
590
|
-
callbacks: {
|
|
591
|
-
onPermission: async ({ toolName, input: args }) => {
|
|
592
|
-
// 只有 delete_file 工具需要确认
|
|
593
|
-
if (toolName === 'delete_file') {
|
|
594
|
-
console.log(`即将删除文件: ${args.path}`)
|
|
595
|
-
// 实际项目里这里可以弹窗或读取用户输入
|
|
596
|
-
return true // 返回 true 允许,false 拒绝
|
|
597
|
-
}
|
|
598
|
-
return true // 其他工具直接放行
|
|
599
|
-
},
|
|
600
|
-
},
|
|
601
|
-
})
|
|
602
|
-
```
|
|
603
|
-
|
|
604
|
-
---
|
|
605
|
-
|
|
606
|
-
## API 参考
|
|
607
|
-
|
|
608
|
-
### `Agent`
|
|
609
|
-
|
|
610
|
-
从包里导入的唯一入口:
|
|
611
|
-
|
|
612
|
-
```js
|
|
613
|
-
import Agent from '@kernel4632/agent-core'
|
|
614
|
-
```
|
|
615
|
-
|
|
616
|
-
#### `Agent.create(options?)`
|
|
617
|
-
|
|
618
|
-
创建一个独立的 Agent 实例,多个实例互不影响。
|
|
619
|
-
|
|
620
|
-
| 参数 | 类型 | 说明 |
|
|
621
|
-
|------|------|------|
|
|
622
|
-
| `options.id` | `string` | Agent ID,默认自动生成 |
|
|
623
|
-
| `options.history` | `array` | 初始历史消息,默认 `[]` |
|
|
624
|
-
| `options.config` | `object` | 模型配置,见下表 |
|
|
625
|
-
| `options.tools` | `object \| array` | `scan()` / `adopt()` 的返回值,也可以直接传工具对象数组或 record,会自动归一化 |
|
|
626
|
-
| `options.callbacks` | `object` | 回调函数集合,见下表 |
|
|
627
|
-
|
|
628
|
-
**`config` 字段:**
|
|
629
|
-
|
|
630
|
-
| 字段 | 默认值 | 说明 |
|
|
631
|
-
|------|--------|------|
|
|
632
|
-
| `baseURL` | `''` | 模型服务地址;`model` 是字符串时必填 |
|
|
633
|
-
| `apiKey` | `''` | 本包创建模型连接时使用的 API 密钥 |
|
|
634
|
-
| `model` | `''` | 模型名称(需要 `baseURL`),或 AI SDK 创建的模型实例(自带连接配置) |
|
|
635
|
-
| `protocol` | `'chat'` | 本包创建模型连接时使用的协议:`chat` / `responses` / `anthropic` / `gemini` |
|
|
636
|
-
| `system` | `''` | 系统提示词 |
|
|
637
|
-
| `stream` | `true` | 是否流式请求模型。默认流式,`await send` 仍拿到完整结果;设为 `false` 才走非流式的旧式请求 |
|
|
638
|
-
| `cache` | `true` | 提示词缓存,默认开启。长会话的固定开头(system、工具、历史)会被服务端缓存,命中就是省时间和省钱 |
|
|
639
|
-
| `toolMode` | `'native'` | 默认只用原生工具,system 零注入。接纯对话模型时主动打开 `'text'`(模拟工具)或 `'auto'`(兼容降级),见下方「让没有原生工具的模型也能用工具」 |
|
|
640
|
-
| `capabilities` | 见下方 | 按模型能力逐项开关图片、音频、视频、文件、工具调用、结构化输出、toolChoice、思考内容和流式用量 |
|
|
641
|
-
| `mediaFallback` | `'error'` | 媒体能力关闭时的处理方式;改成 `'strip'` 后保留文字并丢掉不支持的媒体 |
|
|
642
|
-
| `provider` | `{}` | AI SDK 的生成参数,整份交给 AI SDK;不设时用模型自己的默认值 |
|
|
643
|
-
| `maxToolOutput` | `undefined` | 默认不截断工具输出;主动设置后超出部分从中间截断并告知模型 |
|
|
644
|
-
| `maxTokens` | `128000` | 上下文预算,**默认开启自动压缩**:估算的上下文超过预算的 `compactThreshold` 比例时就压缩一次。设 `Infinity` 关闭。注意区别于 `provider.maxOutputTokens`(那是单次生成上限) |
|
|
645
|
-
| `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
|
|
646
|
-
| `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
|
|
647
|
-
| `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
|
|
648
|
-
| `maxSteps` | `undefined` | 默认不限制模型轮数;主动设置正整数后,到上限先保存这一轮的工具结果,再返回 `step-limit` |
|
|
649
|
-
| `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
|
|
650
|
-
| `
|
|
651
|
-
| `
|
|
652
|
-
| `
|
|
653
|
-
| `
|
|
654
|
-
| `
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
682
|
-
|
|
683
|
-
|
|
684
|
-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
|
|
711
|
-
|
|
712
|
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
```
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
>
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
|
|
764
|
-
|
|
765
|
-
|
|
766
|
-
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
851
|
-
|
|
852
|
-
},
|
|
853
|
-
|
|
854
|
-
|
|
855
|
-
})
|
|
856
|
-
```
|
|
857
|
-
|
|
858
|
-
|
|
859
|
-
|
|
860
|
-
|
|
861
|
-
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
},
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
})
|
|
884
|
-
```
|
|
885
|
-
|
|
886
|
-
|
|
887
|
-
|
|
888
|
-
|
|
889
|
-
|
|
890
|
-
|
|
891
|
-
|
|
892
|
-
|
|
893
|
-
|
|
894
|
-
|
|
895
|
-
|
|
896
|
-
|
|
897
|
-
|
|
898
|
-
|
|
899
|
-
|
|
900
|
-
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
905
|
-
|
|
906
|
-
|
|
907
|
-
|
|
908
|
-
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
|
|
912
|
-
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
916
|
-
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
|
|
920
|
-
|
|
921
|
-
|
|
922
|
-
|
|
923
|
-
const
|
|
924
|
-
|
|
925
|
-
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
|
|
929
|
-
|
|
930
|
-
|
|
931
|
-
|
|
932
|
-
|
|
933
|
-
|
|
934
|
-
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
|
|
938
|
-
|
|
939
|
-
|
|
940
|
-
|
|
941
|
-
|
|
942
|
-
|
|
943
|
-
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
|
|
947
|
-
|
|
948
|
-
|
|
949
|
-
|
|
950
|
-
|
|
951
|
-
|
|
952
|
-
```
|
|
953
|
-
|
|
954
|
-
|
|
955
|
-
|
|
956
|
-
|
|
957
|
-
|
|
958
|
-
`
|
|
959
|
-
|
|
960
|
-
|
|
961
|
-
|
|
962
|
-
|
|
963
|
-
|
|
964
|
-
|
|
965
|
-
|
|
966
|
-
|
|
967
|
-
|
|
968
|
-
|
|
969
|
-
|
|
970
|
-
|
|
971
|
-
|
|
972
|
-
|
|
973
|
-
|
|
974
|
-
|
|
975
|
-
|
|
976
|
-
#### `Agent.tool.
|
|
977
|
-
|
|
978
|
-
|
|
979
|
-
|
|
980
|
-
```js
|
|
981
|
-
|
|
982
|
-
|
|
983
|
-
|
|
984
|
-
|
|
985
|
-
|
|
986
|
-
|
|
987
|
-
|
|
988
|
-
|
|
989
|
-
|
|
990
|
-
|
|
991
|
-
|
|
992
|
-
|
|
993
|
-
|
|
994
|
-
|
|
995
|
-
|
|
996
|
-
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
|
|
1002
|
-
|
|
1003
|
-
|
|
1004
|
-
|
|
1005
|
-
|
|
1006
|
-
|
|
1007
|
-
|
|
1008
|
-
|
|
1009
|
-
const
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
1022
|
-
|
|
1023
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
1026
|
-
|
|
1027
|
-
|
|
1028
|
-
|
|
1029
|
-
|
|
1030
|
-
|
|
1031
|
-
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
|
|
1035
|
-
|
|
1036
|
-
|
|
1037
|
-
|
|
1038
|
-
|
|
1039
|
-
```
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
|
|
1045
|
-
|
|
1046
|
-
|
|
1047
|
-
|
|
1048
|
-
|
|
1049
|
-
|
|
1050
|
-
|
|
1051
|
-
|
|
1052
|
-
|
|
1053
|
-
|
|
1054
|
-
|
|
1055
|
-
|
|
1056
|
-
|
|
1057
|
-
|
|
1058
|
-
})
|
|
1059
|
-
//
|
|
1060
|
-
//
|
|
1061
|
-
|
|
1062
|
-
|
|
1063
|
-
|
|
1064
|
-
|
|
1065
|
-
|
|
1066
|
-
|
|
1067
|
-
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
1073
|
-
|
|
1074
|
-
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
```
|
|
1090
|
-
|
|
1091
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
1102
|
-
|
|
1103
|
-
|
|
1104
|
-
|
|
1105
|
-
|
|
1106
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
1111
|
-
|
|
1112
|
-
|
|
1113
|
-
|
|
1114
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
1120
|
-
|
|
1121
|
-
|
|
1122
|
-
|
|
1123
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
1127
|
-
|
|
1128
|
-
|
|
1129
|
-
|
|
1130
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
|
|
1136
|
-
|
|
1137
|
-
|
|
1138
|
-
|
|
1139
|
-
|
|
1140
|
-
|
|
1141
|
-
|
|
1142
|
-
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
|
|
1155
|
-
|
|
1156
|
-
|
|
1157
|
-
|
|
1158
|
-
|
|
1159
|
-
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1170
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
1174
|
-
|
|
1175
|
-
|
|
1176
|
-
|
|
1177
|
-
|
|
1178
|
-
|
|
1179
|
-
|
|
1180
|
-
|
|
1181
|
-
|
|
1182
|
-
|
|
1183
|
-
|
|
1184
|
-
|
|
1185
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
1188
|
-
|
|
1189
|
-
|
|
1190
|
-
|
|
1191
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
1195
|
-
|
|
1196
|
-
|
|
1197
|
-
|
|
1198
|
-
|
|
1199
|
-
|
|
1200
|
-
|
|
1201
|
-
```
|
|
1202
|
-
|
|
1203
|
-
|
|
1204
|
-
|
|
1205
|
-
|
|
1206
|
-
|
|
1207
|
-
|
|
1208
|
-
|
|
1209
|
-
|
|
1210
|
-
|
|
1211
|
-
```
|
|
1212
|
-
|
|
1213
|
-
|
|
1214
|
-
|
|
1215
|
-
|
|
1216
|
-
|
|
1217
|
-
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1221
|
-
|
|
1222
|
-
|
|
1223
|
-
|
|
1224
|
-
|
|
1225
|
-
|
|
1226
|
-
|
|
1227
|
-
|
|
1228
|
-
|
|
1229
|
-
|
|
1230
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
1233
|
-
|
|
1234
|
-
|
|
1235
|
-
|
|
1236
|
-
|
|
1237
|
-
|
|
1238
|
-
|
|
1239
|
-
|
|
1240
|
-
|
|
1241
|
-
|
|
1242
|
-
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1249
|
-
|
|
1250
|
-
|
|
1251
|
-
|
|
1252
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
1255
|
-
|
|
1256
|
-
|
|
1257
|
-
|
|
1258
|
-
|
|
1259
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
1262
|
-
|
|
1263
|
-
|
|
1264
|
-
|
|
1265
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
1269
|
-
|
|
1270
|
-
|
|
1271
|
-
|
|
1272
|
-
|
|
1273
|
-
|
|
1274
|
-
|
|
1275
|
-
|
|
1276
|
-
|
|
1277
|
-
|
|
1278
|
-
|
|
1279
|
-
|
|
1280
|
-
|
|
1281
|
-
|
|
1282
|
-
|
|
1283
|
-
|
|
1284
|
-
|
|
1285
|
-
|
|
1286
|
-
|
|
1287
|
-
|
|
1288
|
-
|
|
1289
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
|
|
1295
|
-
|
|
1296
|
-
|
|
1297
|
-
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1303
|
-
|
|
1304
|
-
|
|
1305
|
-
|
|
1306
|
-
|
|
1307
|
-
|
|
1308
|
-
|
|
1309
|
-
|
|
1310
|
-
|
|
1311
|
-
|
|
1312
|
-
|
|
1313
|
-
|
|
1314
|
-
|
|
1315
|
-
|
|
1316
|
-
|
|
1317
|
-
|
|
1318
|
-
|
|
1319
|
-
|
|
1320
|
-
|
|
1321
|
-
|
|
1322
|
-
|
|
1323
|
-
|
|
1324
|
-
|
|
1325
|
-
|
|
1326
|
-
|
|
1327
|
-
|
|
1328
|
-
|
|
1329
|
-
|
|
1330
|
-
|
|
1331
|
-
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1335
|
-
|
|
1336
|
-
|
|
1337
|
-
|
|
1338
|
-
|
|
1339
|
-
|
|
1340
|
-
|
|
1341
|
-
|
|
1342
|
-
|
|
1343
|
-
|
|
1344
|
-
|
|
1345
|
-
|
|
1346
|
-
|
|
1347
|
-
|
|
1348
|
-
|
|
1349
|
-
|
|
1350
|
-
|
|
1351
|
-
|
|
1352
|
-
|
|
1353
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
1367
|
-
|
|
1368
|
-
|
|
1369
|
-
|
|
1370
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
1374
|
-
|
|
1375
|
-
|
|
1376
|
-
|
|
1377
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
1381
|
-
|
|
1382
|
-
|
|
1383
|
-
|
|
1384
|
-
|
|
1385
|
-
|
|
1386
|
-
|
|
1387
|
-
|
|
1388
|
-
|
|
1
|
+
# @kernel4632/agent-core
|
|
2
|
+
|
|
3
|
+
[](https://github.com/kernel4632/agent-core/actions/workflows/ci.yml)
|
|
4
|
+
[](https://github.com/kernel4632/agent-core/releases/latest)
|
|
5
|
+
|
|
6
|
+
一个轻量的 AI Agent 核心包。给它一个 LLM 地址和一些工具(工具文件目录,或内存里的工具对象),它就能自动循环"问模型 → 执行工具 → 再问模型",直到任务完成。
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 目录
|
|
11
|
+
|
|
12
|
+
- [这个包是干什么的](#这个包是干什么的)
|
|
13
|
+
- [核心设计:为什么是它](#核心设计为什么是它)
|
|
14
|
+
- [安装](#安装)
|
|
15
|
+
- [5 分钟快速上手](#5-分钟快速上手)
|
|
16
|
+
- [三种用法:从纯聊天到接 MCP 和技能](#三种用法从纯聊天到接-mcp-和技能)
|
|
17
|
+
- [接入 MCP 和技能](#接入-mcp-和技能)
|
|
18
|
+
- [项目架构](#项目架构)
|
|
19
|
+
- [自定义工具:从零到完整](#自定义工具从零到完整)
|
|
20
|
+
- [API 参考](#api-参考)
|
|
21
|
+
- [上生产前](#上生产前)
|
|
22
|
+
- [可观测性](#可观测性)
|
|
23
|
+
- [示例](#示例)
|
|
24
|
+
- [长跑压测](#长跑压测)
|
|
25
|
+
- [运行测试](#运行测试)
|
|
26
|
+
- [打包成单文件](#打包成单文件)
|
|
27
|
+
- [这个包不做什么](#这个包不做什么)
|
|
28
|
+
- [常见问题](#常见问题)
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## 这个包是干什么的
|
|
33
|
+
|
|
34
|
+
你可以把它理解成一个"AI 大脑驱动引擎":
|
|
35
|
+
|
|
36
|
+
```mermaid
|
|
37
|
+
flowchart TD
|
|
38
|
+
app["你的程序"] --> create["Agent.create()<br/>创建实例"]
|
|
39
|
+
create --> send["agent.send()<br/>发送指令"]
|
|
40
|
+
send --> loop["Loop<br/>自动循环"]
|
|
41
|
+
loop --> llm["LLM<br/>问模型"]
|
|
42
|
+
loop --> tool["Tool<br/>执行工具"]
|
|
43
|
+
tool --> loop
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
模型每次回复要么"调用某个工具",要么"我做完了"。这个包负责把这个循环跑起来,你只需要写工具文件就行。
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## 核心设计:为什么是它
|
|
51
|
+
|
|
52
|
+
两件事是这个包真正想做的,别的都围着它们转。**看清这两条,就理解了这个包的全部取舍。**
|
|
53
|
+
|
|
54
|
+
### 一、独特的 Agent 循环
|
|
55
|
+
|
|
56
|
+
循环骨架很简单(建上下文 → 问模型 → 要调工具就执行再回上去),难的是**什么时候停下来**。这个包在"停"这件事上有几个和别人不一样的决定。
|
|
57
|
+
|
|
58
|
+
```mermaid
|
|
59
|
+
flowchart TD
|
|
60
|
+
A["建上下文<br/>(太长先压缩一次)"] --> B["问一次模型"]
|
|
61
|
+
B --> C{"模型要调工具?"}
|
|
62
|
+
|
|
63
|
+
C -->|要| D["并行执行所有工具"]
|
|
64
|
+
D --> E["结果写回 history"]
|
|
65
|
+
E --> S{"有工具返回<br/>stop:true?"}
|
|
66
|
+
S -->|是| T1["返回 tool-stop"]
|
|
67
|
+
S -->|否| T2{"步数到 maxSteps?"}
|
|
68
|
+
T2 -->|是| T3["返回 step-limit"]
|
|
69
|
+
T2 -->|否| A
|
|
70
|
+
|
|
71
|
+
C -->|不要| F{"结束判定"}
|
|
72
|
+
F -->|结构化输出成功<br/>或没注册工具| R1["返回 finished"]
|
|
73
|
+
F -->|步数到 maxSteps| T3
|
|
74
|
+
F -->|连续不调工具<br/>达 noToolRounds| R2["返回 no-tool"]
|
|
75
|
+
F -->|还没到| P["继续下一轮<br/>(末轮前插一句提醒)"]
|
|
76
|
+
P --> A
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**① 模型不调工具,不会立刻结束。** 很多模型在任务没做完时会"礼貌地"给一段总结就停下。直接结束会把没干完的活丢掉。所以有工具时,模型不调工具会先**临时**插一句提醒(`noToolPrompt`)再问一次,连续 `noToolRounds` 轮(默认 3)都不调才结束。这句提醒只挂在那一次请求上,**不写进 `history`**。不想要这个行为,把 `noToolRounds` 设成 `Infinity`。
|
|
80
|
+
|
|
81
|
+
**② `history` 是唯一的权威数据来源,只增不删。** 循环从不修改历史,模型消息、工具结果按发生的顺序追加。连压缩也只追加一条总结。原因:`history` 归你的应用所有(存库、渲染、多会话),核心替它丢弃数据是不可逆的错误——该留多少由持有它的你决定。
|
|
82
|
+
|
|
83
|
+
**③ 一轮里的工具并行执行。** 模型经常一次要求调好几个工具;串行会让任务慢好几倍。所以同一轮的工具同时开跑,结果按原顺序收齐再写回历史。每个工具独占一个子进程,所以死循环的工具能被一刀杀掉,崩溃的工具不会拖垮 Agent。
|
|
84
|
+
|
|
85
|
+
**④ 每次 `send` 只跑一个任务,"最新指令优先"。** 新的 `send` 会先停掉上一个(同一次 tick 里发出的请求,后者一定看得见前者并把它停掉)。原因:一台 Agent 只有一份 `history`,两个任务同时写会乱序。
|
|
86
|
+
|
|
87
|
+
**⑤ 每个出口都补一条模型能读的结果。** 取消 → 一条"已中断"结果;工具失败 → 一条错误结果;模型点了不存在的工具 → 一条"调用无效"结果。**绝不留下"有调用、没结果"的残缺记录**。原因:这种残缺序列会被 OpenAI / Anthropic 直接 400,而 `history` 只增不删,一次残缺就永久毒死这个会话,重启装回历史也一样。
|
|
88
|
+
|
|
89
|
+
### 二、独特的上下文压缩保留方案
|
|
90
|
+
|
|
91
|
+
大多数做法是"上下文满了就丢掉旧消息"。这个包**不丢,只追加总结**——它改的是"这一次发给模型的内容有多大",不是"历史能留多少"。
|
|
92
|
+
|
|
93
|
+
`history` 里原文一条不少;每次发请求时,只从里面**现挑**该带哪些回合:
|
|
94
|
+
|
|
95
|
+
| history 里的位置 | 内容 | 这一次发给模型吗 |
|
|
96
|
+
|------------------|------|------------------|
|
|
97
|
+
| 最初 | 用户最初的目标 | 保留:最多 3 个用户回合、≤20% 预算 |
|
|
98
|
+
| 中段 | 更早的回合 | 已被总结覆盖,不再单独发 |
|
|
99
|
+
| 总结 | 最新一条 `compact` 总结 | 折进 `system`(不是当消息) |
|
|
100
|
+
| 总结前 | 最近的现场回合 | 保留:最多 3 个回合、≤30% 预算 |
|
|
101
|
+
| 总结后 | 之后的全部新回合 | 全部保留(当前正在推进的) |
|
|
102
|
+
|
|
103
|
+
几个关键取舍,以及为什么:
|
|
104
|
+
|
|
105
|
+
- **裁剪的最小单位是「回合」,不是「消息」。** 一个回合 = 用户一次发言,或模型的一次响应连同它发起的全部工具调用和结果。工具结果按 `toolCallId` 回到发起它的回合,**同进同出**。所以裁剪结果永远不会切断"调用 / 结果"的配对——那种残缺会被供应商 400。
|
|
106
|
+
- **最新那条总结折进 system,而不是当成一条消息塞进对话。** 裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是从头重做整个任务。实测 `gpt-oss-120b` 折进 system 前只有 1/6 能正确接着做,之后 6/6。
|
|
107
|
+
- **总结里保留最初目标。** 挑内容时,最初那几轮用户发言(说不出的话)单独钉住,最多 3 个回合、占 20% 预算。就算预算装不下,总结本身也被要求保留"用户最初的目标",而总结在 `system` 里永远不会被裁掉。
|
|
108
|
+
- **二次压缩不会忘掉上一次的总结。** 压缩请求会把上一版总结作为"背景"并进提示词,新总结必须保留其中仍然有效的事实。直接丢掉旧总结,会越压越忘。
|
|
109
|
+
- **按预算保留,不按条数。** 用户第一条消息就粘一大段日志时,只按条数留会让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。所以旧内容按预算分:目标 20%、最近现场 30%。
|
|
110
|
+
- **每轮最多压一次。** 不为"压到达标"而连续调用模型——那样一轮能烧掉上千次请求(实测)。压完还超限就照常发出去,由服务端判断;下一轮还超自然会再压一次。
|
|
111
|
+
|
|
112
|
+
> 一句话:**history 永不删、总结折进 system、裁剪按回合。** 这三条一起保证——发给模型的永远是合法上下文,模型永远能"接着做"而不是"重做",而你的完整历史一条都没丢。
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## 安装
|
|
117
|
+
|
|
118
|
+
这个包需要 [Bun](https://bun.sh) 运行时(不支持 Node.js)。
|
|
119
|
+
|
|
120
|
+
从 npm 安装:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
bun add @kernel4632/agent-core
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
想锁死某个版本(比如 `0.24.18`),在包名后写版本号:
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
bun add @kernel4632/agent-core@0.24.18
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
也可以从 GitHub Release 安装,永远拿到最新版:
|
|
133
|
+
|
|
134
|
+
```bash
|
|
135
|
+
bun add https://github.com/kernel4632/agent-core/releases/latest/download/agent-core.tgz
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
想锁死某个 GitHub 版本,把链接里的 `latest/download` 换成 `download/v0.24.18`:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
bun add https://github.com/kernel4632/agent-core/releases/download/v0.24.18/agent-core.tgz
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
以后升级到最新版,再运行一次安装命令就行。
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 5 分钟快速上手
|
|
149
|
+
|
|
150
|
+
### 第一步:写一个工具文件
|
|
151
|
+
|
|
152
|
+
新建 `tools/say-hello.js`:
|
|
153
|
+
|
|
154
|
+
```js
|
|
155
|
+
export default {
|
|
156
|
+
name: 'say_hello', // 工具名,模型通过这个名字调用它
|
|
157
|
+
description: '向指定的人打招呼', // 告诉模型这个工具是干什么的
|
|
158
|
+
inputSchema: { // 描述模型需要传哪些参数
|
|
159
|
+
type: 'object',
|
|
160
|
+
properties: {
|
|
161
|
+
name: { type: 'string', description: '要打招呼的人的名字' },
|
|
162
|
+
},
|
|
163
|
+
required: ['name'],
|
|
164
|
+
},
|
|
165
|
+
async execute(input) { // 真正执行的函数,input 就是模型传来的参数
|
|
166
|
+
return `你好,${input.name}!` // 返回值会原样告诉模型
|
|
167
|
+
},
|
|
168
|
+
}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
### 第二步:创建 Agent 并发送指令
|
|
172
|
+
|
|
173
|
+
新建 `main.js`:
|
|
174
|
+
|
|
175
|
+
```js
|
|
176
|
+
import Agent from '@kernel4632/agent-core'
|
|
177
|
+
|
|
178
|
+
// 一行拿到工具:目录、内存工具(MCP / AI SDK)可以任意搭配
|
|
179
|
+
const tools = await Agent.tool.from('./tools')
|
|
180
|
+
|
|
181
|
+
// 创建一个 Agent 实例
|
|
182
|
+
const agent = Agent.create({
|
|
183
|
+
config: {
|
|
184
|
+
baseURL: 'https://你的模型地址/v1', // OpenAI 兼容接口地址
|
|
185
|
+
apiKey: 'sk-你的密钥',
|
|
186
|
+
model: '模型名称',
|
|
187
|
+
system: '你是一个助手,请使用工具完成用户的任务。',
|
|
188
|
+
},
|
|
189
|
+
tools, // 把扫描好的工具传进来
|
|
190
|
+
callbacks: {
|
|
191
|
+
onToolResult: result => { // 工具执行完时的回调
|
|
192
|
+
console.log('工具执行完了:', result.toolName, result.output)
|
|
193
|
+
},
|
|
194
|
+
},
|
|
195
|
+
})
|
|
196
|
+
|
|
197
|
+
// 发送指令,等待完成
|
|
198
|
+
const result = await agent.send('帮我向小明打个招呼')
|
|
199
|
+
console.log('Agent 结束,原因:', result.reason) // 有工具时通常是 'no-tool':模型停手后还会被追问最多 noToolRounds 轮(默认 3)才结束
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
> 上面这个例子里注册了工具,所以模型就算一次就把话说完了,`send` 也不会立刻返回——它会连续几轮确认模型真的不再用工具(这是这个包循环的特点,避免模型过早收手)。想一停手就结束,设 `noToolRounds: 1`;想明确收尾,写一个返回 `stop: true` 的 `finish` 工具。
|
|
203
|
+
|
|
204
|
+
运行:
|
|
205
|
+
|
|
206
|
+
```bash
|
|
207
|
+
bun main.js
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
---
|
|
211
|
+
|
|
212
|
+
## 三种用法:从纯聊天到接 MCP 和技能
|
|
213
|
+
|
|
214
|
+
先看清自己属于哪一种,再往下读:
|
|
215
|
+
|
|
216
|
+
| 你想做什么 | 怎么写 | 去哪看 |
|
|
217
|
+
|------------|--------|--------|
|
|
218
|
+
| 只聊天,不用工具 | `Agent.create({ config })` 然后 `agent.send('...')` | 上面的快速上手 |
|
|
219
|
+
| 用普通工具(自己写的文件) | `tools = await Agent.tool.from('./tools')`,传给 `create` | 「自定义工具」「`Agent.tool`」 |
|
|
220
|
+
| 用 MCP 工具、用技能(skills) | 应用自己连 MCP、读技能,再用 `Agent.tool.from(...)` 汇进来 | 下一节「接入 MCP 和技能」 |
|
|
221
|
+
|
|
222
|
+
一句话记住:**这个包只负责"循环 + 执行工具"**。MCP 的连接、技能的读取都不是它的事——你把它们变成普通工具对象交进来就行。
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## 接入 MCP 和技能
|
|
227
|
+
|
|
228
|
+
MCP 和技能(skills)都由**你的应用**负责,核心只接收通用工具对象。两者的做法一样:先拿到"工具对象",再交给 `Agent.tool.from`。
|
|
229
|
+
|
|
230
|
+
```mermaid
|
|
231
|
+
flowchart TD
|
|
232
|
+
f["文件工具<br/>./tools"] --> from["Agent.tool.from(...)"]
|
|
233
|
+
m["MCP 工具<br/>mcp.tools()"] --> from
|
|
234
|
+
s["技能工具<br/>skills.readTool()"] --> from
|
|
235
|
+
from --> agent["Agent.create(...)"]
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
### 接 MCP
|
|
239
|
+
|
|
240
|
+
MCP 是"模型调用外部服务"的标准协议。用官方客户端 `@ai-sdk/mcp` 连上服务后,它给出的工具对象**直接就能用**,不需要任何包装:
|
|
241
|
+
|
|
242
|
+
```js
|
|
243
|
+
import { createMCPClient } from '@ai-sdk/mcp'
|
|
244
|
+
import { Experimental_StdioMCPTransport as Stdio } from '@ai-sdk/mcp/mcp-stdio' // stdio 传输要从子路径导入
|
|
245
|
+
|
|
246
|
+
// 连接由你的应用管理:什么时候连、连哪个、什么时候关
|
|
247
|
+
const mcp = await createMCPClient({
|
|
248
|
+
transport: new Stdio({ command: 'bun', args: ['./mcp-server.js'] }),
|
|
249
|
+
})
|
|
250
|
+
|
|
251
|
+
const tools = await Agent.tool.from('./tools', mcp.tools()) // 就这一句
|
|
252
|
+
const agent = Agent.create({ config, tools })
|
|
253
|
+
|
|
254
|
+
// ... 用完后
|
|
255
|
+
await mcp.close()
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
> MCP 工具的返回值(文字、图片)会自动转成模型能读的块。想自己改写,见「`Agent.tool.adopt`」。
|
|
259
|
+
|
|
260
|
+
### 接技能(skills)
|
|
261
|
+
|
|
262
|
+
技能是"现成的操作步骤":一个文件夹放一份 `SKILL.md`,开头写名字和说明,下面是正文。约定见 [agentskills.io](https://agentskills.io)。
|
|
263
|
+
|
|
264
|
+
```
|
|
265
|
+
skills/
|
|
266
|
+
└── review-pr/
|
|
267
|
+
└── SKILL.md # 开头是 name 和 description,下面是步骤正文
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
社区有现成的库负责**读取和校验**这些文件,比如 `agent-skills-ts-sdk`。它给你两样东西:一段"技能清单"(放进 `system` 让模型知道有哪些技能)和一个"按需读正文"的工具。扫描、组装仍由你写,就是下面这几行:
|
|
271
|
+
|
|
272
|
+
```js
|
|
273
|
+
import { createSkillRegistry, skillSourceFromEntries } from 'agent-skills-ts-sdk'
|
|
274
|
+
|
|
275
|
+
const sources = []
|
|
276
|
+
for await (const file of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
277
|
+
sources.push(skillSourceFromEntries(
|
|
278
|
+
[{ name: 'SKILL.md', content: await Bun.file(file).text() }],
|
|
279
|
+
{ id: file, location: file },
|
|
280
|
+
))
|
|
281
|
+
}
|
|
282
|
+
const skills = await createSkillRegistry(sources)
|
|
283
|
+
const decl = skills.readTool() // 技能清单 + 一个"读正文"的工具声明
|
|
284
|
+
|
|
285
|
+
const skillTool = {
|
|
286
|
+
description: decl.description,
|
|
287
|
+
inputSchema: decl.parametersJsonSchema,
|
|
288
|
+
execute: async args => {
|
|
289
|
+
const r = await skills.read(args)
|
|
290
|
+
return r.ok ? r.content : { output: { type: 'error-text', value: r.error } }
|
|
291
|
+
},
|
|
292
|
+
}
|
|
293
|
+
|
|
294
|
+
// 清单进 system,正文等模型需要时用 skill 工具读
|
|
295
|
+
const system = ['你是一个编程助手。', skills.systemPrompt()].filter(Boolean).join('\n\n')
|
|
296
|
+
const tools = await Agent.tool.from({ [decl.name]: skillTool })
|
|
297
|
+
const agent = Agent.create({ config: { ...config, system }, tools })
|
|
298
|
+
|
|
299
|
+
await agent.send('按 review-pr 技能审查这个改动')
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
### MCP 和技能一起用
|
|
303
|
+
|
|
304
|
+
一次性汇进去就行:
|
|
305
|
+
|
|
306
|
+
```js
|
|
307
|
+
const tools = await Agent.tool.from(
|
|
308
|
+
'./tools', // 文件工具
|
|
309
|
+
mcp.tools(), // MCP 工具
|
|
310
|
+
{ [decl.name]: skillTool }, // 技能加载工具
|
|
311
|
+
)
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
<details>
|
|
315
|
+
<summary>不想引库?自己读 SKILL.md 也就十几行</summary>
|
|
316
|
+
|
|
317
|
+
`SKILL.md` 的开头是一小段用 `---` 包起来的说明(`name` 和 `description`),下面是正文。自己切开即可:
|
|
318
|
+
|
|
319
|
+
```js
|
|
320
|
+
const skills = {}
|
|
321
|
+
for await (const path of new Bun.Glob('skills/*/SKILL.md').scan()) {
|
|
322
|
+
const text = await Bun.file(path).text()
|
|
323
|
+
const name = text.match(/name:\s*(.+)/)?.[1]?.trim()
|
|
324
|
+
const description = text.match(/description:\s*(.+)/)?.[1]?.trim()
|
|
325
|
+
const body = text.replace(/^---[\s\S]*?---/, '').trim() // 去掉说明段,只留正文
|
|
326
|
+
if (name) skills[name] = { description, body }
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
const names = Object.keys(skills)
|
|
330
|
+
const system = names.length
|
|
331
|
+
? '可用技能(需要时用 skill 工具读正文):\n' + names.map(n => `- ${n}:${skills[n].description}`).join('\n')
|
|
332
|
+
: ''
|
|
333
|
+
|
|
334
|
+
const skillTool = {
|
|
335
|
+
skill: {
|
|
336
|
+
description: '按名字读取一个技能的完整步骤',
|
|
337
|
+
inputSchema: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
|
|
338
|
+
execute: async ({ name }) => {
|
|
339
|
+
if (!Object.hasOwn(skills, name)) throw new Error(`没有技能 ${name}`)
|
|
340
|
+
return skills[name].body
|
|
341
|
+
},
|
|
342
|
+
},
|
|
343
|
+
}
|
|
344
|
+
|
|
345
|
+
// 拼装:提示词进 system,读正文的工具进 tools
|
|
346
|
+
const tools = await Agent.tool.from('./tools', skillTool)
|
|
347
|
+
const agent = Agent.create({ config: { ...config, system: ['你是一个助手。', system].filter(Boolean).join('\n\n') }, tools })
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
完整约定(frontmatter 字段、目录名等于技能名、正文按需加载)见 [agentskills.io](https://agentskills.io)。想要省事就直接用上面的 `agent-skills-ts-sdk` 之类的库。
|
|
351
|
+
|
|
352
|
+
</details>
|
|
353
|
+
|
|
354
|
+
---
|
|
355
|
+
|
|
356
|
+
## 项目架构
|
|
357
|
+
|
|
358
|
+
```
|
|
359
|
+
@kernel4632/agent-core
|
|
360
|
+
│
|
|
361
|
+
├── index.js ← 唯一入口:create / send / stop / compact,把下面的功能组合起来
|
|
362
|
+
│
|
|
363
|
+
├── features/ ← 功能:由入口或主循环组合起来用,每个文件一个主体
|
|
364
|
+
│ ├── loop.js ← 主循环:Context → TextTools → LLM → 工具 → ...
|
|
365
|
+
│ ├── llm.js ← 只负责和模型说话:四种协议、缓存、超时、错误分类
|
|
366
|
+
│ ├── text-tools.js ← 文字工具协议:让纯对话模型也能调用工具
|
|
367
|
+
│ ├── history.js ← 对话记录:造消息块、拆回合、渲染
|
|
368
|
+
│ ├── context.js ← 把历史消息裁剪成这一轮发给模型的上下文
|
|
369
|
+
│ ├── compact.js ← 上下文太长时写总结
|
|
370
|
+
│ ├── tool.js ← 工具:扫描文件工具、接纳内存工具、执行、合并(主线程这一半)
|
|
371
|
+
│ └── tool-process.js ← 文件工具真正跑起来的地方(子进程那一半)
|
|
372
|
+
│
|
|
373
|
+
└── utils/ ← 工具:被功能调用,不反过来依赖功能
|
|
374
|
+
├── retry.js ← 失败自动重试(指数退避)
|
|
375
|
+
├── notify.js ← 所有回调的统一出口
|
|
376
|
+
├── schema.js ← 工具参数格式归一化(scan 和 adopt 共用)
|
|
377
|
+
├── shape.js ← 工具返回值变成输出块(内存工具用;子进程里有一份副本)
|
|
378
|
+
└── tokens.js ← 上下文 token 估算:字符数 × 每字符 token 比,比例由真实 usage 自校准
|
|
379
|
+
```
|
|
380
|
+
|
|
381
|
+
`tool.js` 和 `tool-process.js` 是同一件事的两半,所以放在一起:前者在主线程里找工具、管工具进程,
|
|
382
|
+
后者被前者当成文本内联、在独立的 bun 子进程里加载并执行工具。分成两个文件是平台限制,不是分层。
|
|
383
|
+
|
|
384
|
+
**工具进程隔离的是生命周期,不是环境。** 工具在里面拥有和 Agent 完全相同的权限:读写任意文件、执行任意命令、联网、读到父进程的全部环境变量。这是有意的——电脑任务 agent 的工具本来就得能干这些。它真正隔离的是四样:**失控**(死循环工具能被一刀杀掉,实测 0ms)、**崩溃**(工具死了 Agent 继续跑)、**内存**(独立堆)、**Agent 状态**(工具碰不到 `history`、`config`、`running`)。
|
|
385
|
+
|
|
386
|
+
**为什么用子进程而不是 Worker 线程**:Worker 被 `terminate()` 之后 Bun 不归还它占的约 22MB,
|
|
387
|
+
而且杀线程带不走它 `Bun.spawn` 出来的孙进程。常驻 agent 天天要杀工具进程(工具崩溃、超时、用户打断),
|
|
388
|
+
两笔账会一直累积。换成子进程之后实测 200 次「起→用→杀」主进程只涨 2MB(Worker 版是 4.4GB),
|
|
389
|
+
孙进程一起带走,主进程退出时工具进程也全部跟着死。复用时单次调用 0.08ms,比 Worker 还快。
|
|
390
|
+
|
|
391
|
+
### 数据流
|
|
392
|
+
|
|
393
|
+
```mermaid
|
|
394
|
+
flowchart TD
|
|
395
|
+
send["agent.send(input)"] --> hu["History.user()"]
|
|
396
|
+
hu --> ctx["Context.build()<br/>裁剪上下文"]
|
|
397
|
+
ctx --> llm["LLM.chat()<br/>请求模型"]
|
|
398
|
+
llm --> q{"模型要调工具?"}
|
|
399
|
+
q -->|要| te["Tool.execute()<br/>并行执行"]
|
|
400
|
+
te --> wr["结果写入 history"]
|
|
401
|
+
wr --> ctx
|
|
402
|
+
q -->|不要| done["结束判定<br/>(分支见「核心设计」)"]
|
|
403
|
+
```
|
|
404
|
+
|
|
405
|
+
---
|
|
406
|
+
|
|
407
|
+
## 自定义工具:从零到完整
|
|
408
|
+
|
|
409
|
+
### 最简单的工具
|
|
410
|
+
|
|
411
|
+
```js
|
|
412
|
+
// tools/add.js
|
|
413
|
+
export default {
|
|
414
|
+
name: 'add',
|
|
415
|
+
description: '把两个数字加在一起',
|
|
416
|
+
inputSchema: {
|
|
417
|
+
type: 'object',
|
|
418
|
+
properties: {
|
|
419
|
+
a: { type: 'number' },
|
|
420
|
+
b: { type: 'number' },
|
|
421
|
+
},
|
|
422
|
+
required: ['a', 'b'],
|
|
423
|
+
},
|
|
424
|
+
async execute(input) {
|
|
425
|
+
return input.a + input.b // 直接返回结果
|
|
426
|
+
},
|
|
427
|
+
}
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
### 带流式输出的工具
|
|
431
|
+
|
|
432
|
+
工具可以用 `yield` 逐步返回内容,适合耗时较长的操作:
|
|
433
|
+
|
|
434
|
+
```js
|
|
435
|
+
// tools/count.js
|
|
436
|
+
export default {
|
|
437
|
+
name: 'count',
|
|
438
|
+
description: '从 1 数到 n,逐步输出',
|
|
439
|
+
inputSchema: {
|
|
440
|
+
type: 'object',
|
|
441
|
+
properties: { n: { type: 'number' } },
|
|
442
|
+
required: ['n'],
|
|
443
|
+
},
|
|
444
|
+
async *execute(input) { // 注意:async * 是异步生成器
|
|
445
|
+
for (let i = 1; i <= input.n; i++) {
|
|
446
|
+
yield `数到了 ${i}` // 每次 yield 都会立刻发给上层的 onOutput 回调
|
|
447
|
+
await new Promise(r => setTimeout(r, 100))
|
|
448
|
+
}
|
|
449
|
+
},
|
|
450
|
+
}
|
|
451
|
+
```
|
|
452
|
+
|
|
453
|
+
文件工具和内存工具都支持 `async *execute`(`Agent.tool.adopt` 接纳的内存工具也一样)。接收流式输出:
|
|
454
|
+
|
|
455
|
+
```js
|
|
456
|
+
const agent = Agent.create({
|
|
457
|
+
// ...
|
|
458
|
+
callbacks: {
|
|
459
|
+
onToolOutput: output => {
|
|
460
|
+
console.log('实时输出:', output.data) // 每次 yield 触发一次
|
|
461
|
+
},
|
|
462
|
+
},
|
|
463
|
+
})
|
|
464
|
+
```
|
|
465
|
+
|
|
466
|
+
### 调用子进程的工具
|
|
467
|
+
|
|
468
|
+
工具在独立子进程里运行,`Bun.spawn` 的 stdout/stderr 会自动转发给 `onToolOutput`,不需要额外处理:
|
|
469
|
+
|
|
470
|
+
```js
|
|
471
|
+
// tools/run-script.js
|
|
472
|
+
export default {
|
|
473
|
+
name: 'run_script',
|
|
474
|
+
description: '运行一个 shell 脚本',
|
|
475
|
+
inputSchema: {
|
|
476
|
+
type: 'object',
|
|
477
|
+
properties: { command: { type: 'string' } },
|
|
478
|
+
required: ['command'],
|
|
479
|
+
},
|
|
480
|
+
async execute(input) {
|
|
481
|
+
const proc = Bun.spawn(['bash', '-c', input.command], {
|
|
482
|
+
stdout: 'pipe',
|
|
483
|
+
stderr: 'pipe',
|
|
484
|
+
})
|
|
485
|
+
await proc.exited
|
|
486
|
+
return { exitCode: proc.exitCode } // stdout/stderr 已经自动转发了
|
|
487
|
+
},
|
|
488
|
+
}
|
|
489
|
+
```
|
|
490
|
+
|
|
491
|
+
### 一个文件导出多个工具
|
|
492
|
+
|
|
493
|
+
```js
|
|
494
|
+
// tools/math.js
|
|
495
|
+
const add = {
|
|
496
|
+
name: 'add',
|
|
497
|
+
description: '加法',
|
|
498
|
+
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
499
|
+
async execute(input) { return input.a + input.b },
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
const multiply = {
|
|
503
|
+
name: 'multiply',
|
|
504
|
+
description: '乘法',
|
|
505
|
+
inputSchema: { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] },
|
|
506
|
+
async execute(input) { return input.a * input.b },
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
export default [add, multiply] // 导出数组
|
|
510
|
+
```
|
|
511
|
+
|
|
512
|
+
工具是按**名字**找到的,不是按它在数组里排第几。所以往文件里插入新工具、调换顺序都不会让模型调错工具。
|
|
513
|
+
|
|
514
|
+
### 工具目录里可以放共享代码
|
|
515
|
+
|
|
516
|
+
扫描时只把"形状对得上"(有 `name`、有 `execute`)的东西注册成工具,其余文件直接跳过。
|
|
517
|
+
所以下面这些都可以和工具放在同一个目录里,不会影响扫描:
|
|
518
|
+
|
|
519
|
+
```
|
|
520
|
+
tools/
|
|
521
|
+
├── read.js ← 工具
|
|
522
|
+
├── write.js ← 工具
|
|
523
|
+
├── shared.js ← 共享辅助函数,没有默认导出,自动跳过
|
|
524
|
+
└── read.test.js ← 测试文件,自动跳过
|
|
525
|
+
```
|
|
526
|
+
|
|
527
|
+
跳过的前提是这些文件**能被加载**。目录里任何一个 `.js` 有语法错误、或者 import 了装不上的依赖,
|
|
528
|
+
`scan` 会当场抛出来——这是有意的:工具目录是你自己的代码,坏了就该立刻知道,
|
|
529
|
+
静默跳过只会变成"某个工具莫名其妙不见了"。
|
|
530
|
+
|
|
531
|
+
### 主动停止 Agent 的工具
|
|
532
|
+
|
|
533
|
+
如果某个工具代表"任务完成",可以让它返回 `stop: true`,Agent 循环会立刻停止:
|
|
534
|
+
|
|
535
|
+
```js
|
|
536
|
+
// tools/finish.js
|
|
537
|
+
export default {
|
|
538
|
+
name: 'finish',
|
|
539
|
+
description: '任务完成时调用这个工具',
|
|
540
|
+
inputSchema: {
|
|
541
|
+
type: 'object',
|
|
542
|
+
properties: { summary: { type: 'string', description: '完成情况总结' } },
|
|
543
|
+
required: ['summary'],
|
|
544
|
+
},
|
|
545
|
+
async execute(input) {
|
|
546
|
+
return {
|
|
547
|
+
stop: true, // 告诉 Loop 停止循环
|
|
548
|
+
output: { type: 'text', value: input.summary },
|
|
549
|
+
}
|
|
550
|
+
},
|
|
551
|
+
}
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
### 返回图片的工具
|
|
555
|
+
|
|
556
|
+
工具可以直接返回一个成形的输出块。截图、生成图表这类工具就靠这个把图交给模型:
|
|
557
|
+
|
|
558
|
+
```js
|
|
559
|
+
// tools/screenshot.js
|
|
560
|
+
export default {
|
|
561
|
+
name: 'screenshot',
|
|
562
|
+
description: '截取当前屏幕',
|
|
563
|
+
inputSchema: { type: 'object', properties: {} },
|
|
564
|
+
async execute() {
|
|
565
|
+
const png = await grabScreen() // 你自己的截图实现,拿到 base64
|
|
566
|
+
return {
|
|
567
|
+
output: {
|
|
568
|
+
type: 'content', // 多模态输出块
|
|
569
|
+
value: [
|
|
570
|
+
{ type: 'text', text: '当前屏幕:' },
|
|
571
|
+
{ type: 'file', mediaType: 'image/png', data: { type: 'data', data: png } },
|
|
572
|
+
],
|
|
573
|
+
},
|
|
574
|
+
}
|
|
575
|
+
},
|
|
576
|
+
}
|
|
577
|
+
```
|
|
578
|
+
|
|
579
|
+
`content` 块里只能放 `text` / `file` / `file-data` / `file-url`,以及旧写法 `image` / `audio` / `video`(发出前会自动转成 `file`)。放别的(比如旧版 AI SDK 的 `media`)会被工具进程当场挡住、变成一条普通的工具失败——这是有意的:非法块一旦穿过去写进 `history`,AI SDK 会在本地校验时抛错、请求根本发不出去、重试也认不出来,而 `history` 只增不删,于是之后每次 `send` 都撞同一堵墙,重启装回历史也一样。
|
|
580
|
+
|
|
581
|
+
`output` 里给的块会被原样交给模型,不会再被套一层。`maxToolOutput` 的截断**只作用于文字块**——图截一刀就彻底废了,所以媒体内容一个字节都不动。
|
|
582
|
+
|
|
583
|
+
### 工具权限询问
|
|
584
|
+
|
|
585
|
+
在敏感操作前可以要求用户确认:
|
|
586
|
+
|
|
587
|
+
```js
|
|
588
|
+
const agent = Agent.create({
|
|
589
|
+
// ...
|
|
590
|
+
callbacks: {
|
|
591
|
+
onPermission: async ({ toolName, input: args }) => {
|
|
592
|
+
// 只有 delete_file 工具需要确认
|
|
593
|
+
if (toolName === 'delete_file') {
|
|
594
|
+
console.log(`即将删除文件: ${args.path}`)
|
|
595
|
+
// 实际项目里这里可以弹窗或读取用户输入
|
|
596
|
+
return true // 返回 true 允许,false 拒绝
|
|
597
|
+
}
|
|
598
|
+
return true // 其他工具直接放行
|
|
599
|
+
},
|
|
600
|
+
},
|
|
601
|
+
})
|
|
602
|
+
```
|
|
603
|
+
|
|
604
|
+
---
|
|
605
|
+
|
|
606
|
+
## API 参考
|
|
607
|
+
|
|
608
|
+
### `Agent`
|
|
609
|
+
|
|
610
|
+
从包里导入的唯一入口:
|
|
611
|
+
|
|
612
|
+
```js
|
|
613
|
+
import Agent from '@kernel4632/agent-core'
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
#### `Agent.create(options?)`
|
|
617
|
+
|
|
618
|
+
创建一个独立的 Agent 实例,多个实例互不影响。
|
|
619
|
+
|
|
620
|
+
| 参数 | 类型 | 说明 |
|
|
621
|
+
|------|------|------|
|
|
622
|
+
| `options.id` | `string` | Agent ID,默认自动生成 |
|
|
623
|
+
| `options.history` | `array` | 初始历史消息,默认 `[]` |
|
|
624
|
+
| `options.config` | `object` | 模型配置,见下表 |
|
|
625
|
+
| `options.tools` | `object \| array` | `scan()` / `adopt()` 的返回值,也可以直接传工具对象数组或 record,会自动归一化 |
|
|
626
|
+
| `options.callbacks` | `object` | 回调函数集合,见下表 |
|
|
627
|
+
|
|
628
|
+
**`config` 字段:**
|
|
629
|
+
|
|
630
|
+
| 字段 | 默认值 | 说明 |
|
|
631
|
+
|------|--------|------|
|
|
632
|
+
| `baseURL` | `''` | 模型服务地址;`model` 是字符串时必填 |
|
|
633
|
+
| `apiKey` | `''` | 本包创建模型连接时使用的 API 密钥 |
|
|
634
|
+
| `model` | `''` | 模型名称(需要 `baseURL`),或 AI SDK 创建的模型实例(自带连接配置) |
|
|
635
|
+
| `protocol` | `'chat'` | 本包创建模型连接时使用的协议:`chat` / `responses` / `anthropic` / `gemini` |
|
|
636
|
+
| `system` | `''` | 系统提示词 |
|
|
637
|
+
| `stream` | `true` | 是否流式请求模型。默认流式,`await send` 仍拿到完整结果;设为 `false` 才走非流式的旧式请求 |
|
|
638
|
+
| `cache` | `true` | 提示词缓存,默认开启。长会话的固定开头(system、工具、历史)会被服务端缓存,命中就是省时间和省钱 |
|
|
639
|
+
| `toolMode` | `'native'` | 默认只用原生工具,system 零注入。接纯对话模型时主动打开 `'text'`(模拟工具)或 `'auto'`(兼容降级),见下方「让没有原生工具的模型也能用工具」 |
|
|
640
|
+
| `capabilities` | 见下方 | 按模型能力逐项开关图片、音频、视频、文件、工具调用、结构化输出、toolChoice、思考内容和流式用量 |
|
|
641
|
+
| `mediaFallback` | `'error'` | 媒体能力关闭时的处理方式;改成 `'strip'` 后保留文字并丢掉不支持的媒体 |
|
|
642
|
+
| `provider` | `{}` | AI SDK 的生成参数,整份交给 AI SDK;不设时用模型自己的默认值 |
|
|
643
|
+
| `maxToolOutput` | `undefined` | 默认不截断工具输出;主动设置后超出部分从中间截断并告知模型 |
|
|
644
|
+
| `maxTokens` | `128000` | 上下文预算,**默认开启自动压缩**:估算的上下文超过预算的 `compactThreshold` 比例时就压缩一次。设 `Infinity` 关闭。注意区别于 `provider.maxOutputTokens`(那是单次生成上限) |
|
|
645
|
+
| `compactThreshold` | `0.8` | 压缩触发比例,0.8 表示到达 80% 时压缩 |
|
|
646
|
+
| `compact` | `undefined` | 压缩单独用一套模型时写在这里,例如 `{ model: '便宜的小模型' }`;不写就和主模型共用 |
|
|
647
|
+
| `output` | `undefined` | 结构化输出格式,例如 `Agent.output.object({ schema })`;不写就返回普通文字 |
|
|
648
|
+
| `maxSteps` | `undefined` | 默认不限制模型轮数;主动设置正整数后,到上限先保存这一轮的工具结果,再返回 `step-limit` |
|
|
649
|
+
| `maxToolConcurrency` | `undefined` | 默认不限制**文件工具**的并发;主动设置后超出的排队。内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束 |
|
|
650
|
+
| `retryBaseDelay` | `5000` | 第一次退避的基数(毫秒),之后每次 ×2:5s、10s、20s…(照抄 Roo Code) |
|
|
651
|
+
| `retryMaxDelay` | `600000` | 单次退避上限(毫秒),到顶就按这个值等待、不再增长(默认 10 分钟,照抄 Roo Code) |
|
|
652
|
+
| `retryMaxElapsed` | `undefined` | 默认不限重试总时长;主动设置毫秒数后,到点把错误交给上层 |
|
|
653
|
+
| `retry` | `undefined` | 调用方过滤不想重试的错误,见下方「重试规则」。不设=默认全重试 |
|
|
654
|
+
| `requestTimeout` | `undefined` | 默认不限制单笔请求时长;主动设置毫秒数后,卡住的一笔会被中断 |
|
|
655
|
+
| `noToolPrompt` | 一条"请继续使用工具"的提醒 | 有工具但模型连续不调时,在结束前一轮临时发给模型;只挂在那一次请求上,不写进 `history`。设成 `''` 就不提醒 |
|
|
656
|
+
| `noToolRounds` | `3` | 有工具时,连续多少轮不调工具就结束一次 `send`;设成 `1` 就是模型不调工具即结束,设成 `Infinity` 就永不因不调工具结束。没注册工具时一轮就结束,不受它影响 |
|
|
657
|
+
|
|
658
|
+
### 重试规则
|
|
659
|
+
|
|
660
|
+
失败的重试由底层统一处理,默认行为照抄 Roo Code:**除"取消"和"上下文超长"外,任何错误都会重试**(401、400、格式错误都算),次数不限,也不设总时长上限;退避按 `retryBaseDelay × 2` 增长,单次最长到 `retryMaxDelay` 封顶。上下文超长不走重试,而是先压缩上下文再重发这笔请求,最多 3 次。取消(`agent.stop()` 或传 `signal`)永远不重试。
|
|
661
|
+
|
|
662
|
+
想收口或过滤,用三个配置:
|
|
663
|
+
|
|
664
|
+
```js
|
|
665
|
+
const agent = Agent.create({
|
|
666
|
+
config: {
|
|
667
|
+
retryBaseDelay: 5000, // 第一次等待 5s,之后 10s、20s…(默认)
|
|
668
|
+
retryMaxDelay: 600000, // 单次等待最多 10 分钟(默认)
|
|
669
|
+
retryMaxElapsed: 120000, // 一直失败最多再试 2 分钟,到点把错误交给上层(默认不限)
|
|
670
|
+
// 只对"不想重试的错误"下手,命中即不重试:
|
|
671
|
+
retry: {
|
|
672
|
+
skipCodes: [400, 401], // 按状态码
|
|
673
|
+
skipKinds: ['auth'], // 按 error.kind:aborted/auth/limit/timeout/server/network/request/unknown
|
|
674
|
+
skipText: /invalid api key/i, // 按报错文字(字符串或正则)
|
|
675
|
+
shouldRetry: error => error.statusCode !== 422, // 自定义判断,返回 false=不重试
|
|
676
|
+
},
|
|
677
|
+
// retry 也可以直接传一个函数:(error) => boolean,返回 false=不重试
|
|
678
|
+
},
|
|
679
|
+
})
|
|
680
|
+
```
|
|
681
|
+
|
|
682
|
+
`retry` 属于 **整份替换**(和 `provider` 一样,本次传了就用本次的整份,不与上次合并)。
|
|
683
|
+
|
|
684
|
+
陌生中转站建议先使用默认能力。遇到只支持文字、但接口声称兼容 OpenAI 的模型,可以按能力关闭:
|
|
685
|
+
|
|
686
|
+
```js
|
|
687
|
+
const agent = Agent.create({
|
|
688
|
+
config: {
|
|
689
|
+
baseURL: 'https://api.example.com/v1', model: 'model-name',
|
|
690
|
+
capabilities: {
|
|
691
|
+
image: false, audio: false, video: false, file: false,
|
|
692
|
+
tools: false, structuredOutput: false, toolChoice: false,
|
|
693
|
+
reasoning: false,
|
|
694
|
+
},
|
|
695
|
+
mediaFallback: 'strip',
|
|
696
|
+
},
|
|
697
|
+
})
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
`image`、`audio`、`video` 和 `file` 控制内容块;`tools` 控制是否发送工具描述;`structuredOutput` 控制是否发送 `response_format`;`toolChoice:false` 让请求省略 `tool_choice`(只对字符串模型 + `chat`/`responses`/`anthropic` 完整生效;`gemini` 按自身默认、不强制;传模型实例时会报错,因为它需要改写请求体);`reasoning:true` 才会把历史里的思考块发给模型;`usage:false` 关掉流式请求里的 `stream_options.include_usage`(个别不认这个字段的中转站会 400,关掉即可,代价是 token 估算拿不到真实数据、只能靠粗估)。旧式 `image`、`audio`、`video` 内容块会在真正请求模型时转换成 AI SDK 当前使用的 `file`,历史数组仍保留原始形状。
|
|
701
|
+
|
|
702
|
+
`provider` 直接放 AI SDK 的生成参数,例如:
|
|
703
|
+
|
|
704
|
+
```js
|
|
705
|
+
const agent = Agent.create({
|
|
706
|
+
config: {
|
|
707
|
+
baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx', model: 'model-name',
|
|
708
|
+
provider: {
|
|
709
|
+
temperature: 0.3, topP: 0.9, maxOutputTokens: 4096,
|
|
710
|
+
toolChoice: 'auto', // 默认 auto;不传时由底层使用 auto
|
|
711
|
+
providerOptions: { openai: {} }, // 厂商专用设置直接交给 AI SDK
|
|
712
|
+
headers: { 'X-App': 'example' }, // 额外请求头
|
|
713
|
+
body: { custom_field: true }, // 额外请求体字段
|
|
714
|
+
},
|
|
715
|
+
},
|
|
716
|
+
})
|
|
717
|
+
```
|
|
718
|
+
|
|
719
|
+
在 `agent.send({ input, config: { ... } })` 里传入的配置会**写回 Agent**、之后的 send 继续生效。合并规则分三种:`provider` 和 `retry` **整份替换**(传了就只用新的,未写的字段不再保留);`capabilities` 和 `compact` **按字段浅合并**(只传其中一项不丢另外的);其余字段直接覆盖。`maxTokens` 是上下文预算,和 `provider.maxOutputTokens`(单次生成量)不是一回事。
|
|
720
|
+
|
|
721
|
+
`cache` 默认开启。四种协议各按自己的方式让服务端复用固定的开头(system、工具描述、历史),命中后那部分不再重新计算,长会话能明显变快、变便宜:
|
|
722
|
+
|
|
723
|
+
| 协议 | 发的字段 |
|
|
724
|
+
|------|----------|
|
|
725
|
+
| `chat` / `responses` | `prompt_cache_key`,服务端按这个键把同一台 Agent 的连续请求路由到同一处缓存 |
|
|
726
|
+
| `anthropic` | 在 system 和最后一条消息上打 `cache_control` 断点;Anthropic 不会自动缓存,不打就是 0% |
|
|
727
|
+
| `gemini` | 隐式缓存由服务端自己决定,请求里没有可发的字段 |
|
|
728
|
+
|
|
729
|
+
实测(同一会话的多步工具循环,默认配置):`chat` 从第二步起命中约 99%,整个任务约 80%;`anthropic` 从第三步起每步命中整段开头,整个任务约 60%。键默认由 `baseURL + model + system` 推出,同一台 Agent 的连续请求自然落在同一个键上。也可以传对象自定义:
|
|
730
|
+
|
|
731
|
+
```js
|
|
732
|
+
cache: {
|
|
733
|
+
key: 'project:conversation-1',
|
|
734
|
+
retention: '1h',
|
|
735
|
+
body: { cache_namespace: 'agent' },
|
|
736
|
+
}
|
|
737
|
+
```
|
|
738
|
+
|
|
739
|
+
个别中转站不认这组字段、直接返回 400,那时设 `cache: false` 关掉,或把供应商自己的字段放进 `provider.body`。
|
|
740
|
+
|
|
741
|
+
#### 让没有原生工具的模型也能用工具
|
|
742
|
+
|
|
743
|
+
有的中转站模型只会对话:请求里一带 `tools` 字段就报错。也有的模型接口支持工具,模型自己却不会用,把调用当成一段文字写了出来。这两种情况各有一个兼容开关,**默认都关着**:
|
|
744
|
+
|
|
745
|
+
| `toolMode` | 行为 | 会不会改 system |
|
|
746
|
+
|------------|------|----------------|
|
|
747
|
+
| `'native'`(默认) | 只用原生工具字段,文字里的调用一律当成普通回答 | 不会,你写的 system 原样发出 |
|
|
748
|
+
| `'text'` | 模拟工具:不发 `tools` 字段,把工具说明写进 system,从模型的文字里读回调用 | 会,追加一段工具说明 |
|
|
749
|
+
| `'auto'` | 兼容降级:先用原生工具;接口拒收工具字段时,改用文字协议重发,并记住这个模型;模型没走原生调用、却在文字里写了调用时,也读出来执行 | 只在被拒收、改用文字协议之后才会 |
|
|
750
|
+
|
|
751
|
+
这个包的原则是**默认零注入**:不打开开关,发给模型的 system 就是你写的那段,一个字都不多。接特殊 API 时缺什么就打开什么。
|
|
752
|
+
|
|
753
|
+
文字协议的格式(参考 Roo Code / Cline 的文本工具调用):
|
|
754
|
+
|
|
755
|
+
```
|
|
756
|
+
<tool_call>
|
|
757
|
+
{"name": "add", "arguments": {"a": 1, "b": 2}}
|
|
758
|
+
</tool_call>
|
|
759
|
+
```
|
|
760
|
+
|
|
761
|
+
工具结果用 `<tool_result name="add">…</tool_result>` 作为一条 user 消息送回模型。读取时尽量宽容:一次回复里写多个调用、`arguments` 写成字符串、外面套一层 `{"type":"function","function":{…}}`、参数平铺在同一层、带 Markdown 代码围栏、多一个尾逗号、最后一块没闭合,都能读出来。Roo Code 风格的 XML 写法(`<read_file><path>a.js</path></read_file>`)也认,会按工具的 schema 把 `"7"` 还原成数字 `7`。JSON 坏到读不出来时,会生成一条无效调用告诉模型重写,不会悄悄当成普通回答。模型自己编了 `<tool_result>` 时,从那里往后的内容全部丢掉,免得假结果混进历史。
|
|
762
|
+
|
|
763
|
+
**历史始终是标准形状。** 文字协议只在发请求和读响应的时候转换,`agent.history` 里存的永远是标准的 `tool-call` 块和 `tool` 消息。同一台 Agent 中途从纯对话模型换成原生工具模型(或反过来),历史直接接着用。
|
|
764
|
+
|
|
765
|
+
流式输出时,文字协议的 `<tool_call>` 原文也会出现在 `onLLMEvent` 的 `text-delta` 里,前端想隐藏可以按这个标签过滤。`result.text` 和历史里的文字已经去掉了调用部分。
|
|
766
|
+
|
|
767
|
+
需要包内没有预设的 Provider 或模型中间件时,直接传 AI SDK 模型实例;实例由调用方创建,`baseURL`、`apiKey`、`protocol` 就不必重复写。下面的进阶用法需要调用方安装对应的 Provider 包:
|
|
768
|
+
|
|
769
|
+
```js
|
|
770
|
+
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
|
|
771
|
+
import Agent from '@kernel4632/agent-core'
|
|
772
|
+
|
|
773
|
+
const model = createOpenAICompatible({
|
|
774
|
+
name: 'custom', baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx',
|
|
775
|
+
}).chatModel('model-name')
|
|
776
|
+
const agent = Agent.create({ config: { model, provider: { temperature: 0.3 } } })
|
|
777
|
+
const answer = await agent.send('你好')
|
|
778
|
+
console.log(answer.text)
|
|
779
|
+
```
|
|
780
|
+
|
|
781
|
+
模型实例的额外请求头仍可写在 `provider.headers`;`provider.body`、自定义的 `cache` 对象、以及 `capabilities.toolChoice: false`(它要改写请求体才能生效)都需要本包创建连接,不能用于已创建的模型实例,设置时会明确报错。默认的 `cache: true` 对模型实例会安静跳过——实例的缓存设置由创建它的人负责。
|
|
782
|
+
|
|
783
|
+
> `provider.toolChoice` 保持 `auto` 时,模型才能在任务做完后正常收尾,`{ reason: 'no-tool' }` 这个结束方式也才有意义。
|
|
784
|
+
> 改成 `required` 会强制模型每轮都调工具,而且部分服务(实测 gpt-oss-120b)在模型不想调工具时会直接返回 `tool_use_failed`。
|
|
785
|
+
|
|
786
|
+
**`callbacks` 回调:**
|
|
787
|
+
|
|
788
|
+
| 回调 | 触发时机 | 参数 |
|
|
789
|
+
|------|----------|------|
|
|
790
|
+
| `onStart` | 循环开始 | 无 |
|
|
791
|
+
| `onLLMStart` | 每次请求模型前 | `{ messages, tools }` |
|
|
792
|
+
| `onLLMFinish` | 模型请求完成 | LLM 返回的完整结果 |
|
|
793
|
+
| `onLLMEvent` | 流式事件(每个 token) | AI SDK 原生事件 |
|
|
794
|
+
| `onPermission` | 工具执行前 | `{ toolName, input, sessionId, toolCallId, signal }` → 返回 `true/false` |
|
|
795
|
+
| `onToolCall` | 工具即将执行 | `{ toolCallId, toolName, input }` |
|
|
796
|
+
| `onToolOutput` | 工具有流式输出 | `{ toolName, stream, data, toolCallId, input? }`;`data` 是工具 yield / 打印出来的原值,类型不定 |
|
|
797
|
+
| `onToolResult` | 工具执行完成 | `{ toolName, output, ... }` |
|
|
798
|
+
| `onStep` | 一轮模型和工具都完成后 | `{ step, result, toolCalls, toolResults }` |
|
|
799
|
+
| `onRetry` | 请求失败重试 | `{ attempt, error, delay }`(主请求和压缩请求共用) |
|
|
800
|
+
| `onCompact` | 上下文压缩 | `compact-start` / AI SDK 事件 / `compact-finish` |
|
|
801
|
+
|
|
802
|
+
除了 `onPermission`,所有回调都只是通知:回调自己抛错会被忽略,任务照常进行,工具结果也不会被改写。`onPermission` 的返回值决定放不放行,所以它抛错时这次 `send` 会失败,交给你的 `.catch()`。注意它按"非 `true` 即拒绝"处理:**每个分支都要显式 `return true`**,忘了返回会让那次工具被拒。
|
|
803
|
+
|
|
804
|
+
#### `agent.send(input)` / `agent.send(options)`
|
|
805
|
+
|
|
806
|
+
只发送文字或内容块数组时直接传入;要覆盖配置、历史、工具或回调时传对象。如果上一次 `send` 还在运行,本次调用会先自动停止上一次任务,再启动新任务。
|
|
807
|
+
|
|
808
|
+
```js
|
|
809
|
+
await agent.send('继续')
|
|
810
|
+
|
|
811
|
+
const result = await agent.send({
|
|
812
|
+
input: '帮我写个函数', // 用户输入(必填)。也可以是内容块数组,见下方"发图片"
|
|
813
|
+
config: { model: '新模型' }, // 可选:覆盖部分配置(会写回 Agent,之后的 send 继续生效)
|
|
814
|
+
history: [], // 可选:整份替换历史(也写回 Agent)
|
|
815
|
+
tools: newTools, // 可选:整份替换工具集(也写回 Agent)
|
|
816
|
+
callbacks: { onLLMEvent: e => {} }, // 可选:合并回调(逐项写回 Agent,最后传的长期生效)
|
|
817
|
+
})
|
|
818
|
+
|
|
819
|
+
// 注意:这四项覆盖都写进 Agent 状态,本次 send 之后一直有效,不是"只作用这一次"。
|
|
820
|
+
// 想只影响一次,就在这次 send 里传对值,或之后再传一次恢复。
|
|
821
|
+
|
|
822
|
+
// result.text → 最后一轮模型生成的文字
|
|
823
|
+
// result.steps → 这次 send 一共请求了模型几轮
|
|
824
|
+
// result.usage → 整次 send 的用量合计:{ inputTokens, outputTokens, totalTokens, cacheReadTokens, cacheWriteTokens }
|
|
825
|
+
// 算钱、看缓存命中直接读这里;cacheReadTokens / inputTokens 就是缓存命中率
|
|
826
|
+
// result.reason:
|
|
827
|
+
// 'finished' → 没注册工具,或结构化输出已校验成功:这就是最终回答
|
|
828
|
+
// 'no-tool' → 有工具,但连续 noToolRounds 轮(默认 3)没调用工具才结束
|
|
829
|
+
// 'tool-stop' → 某个工具返回了 stop: true
|
|
830
|
+
// 'step-limit' → 达到 maxSteps,当前工具结果已保存,下一次 send 可继续
|
|
831
|
+
```
|
|
832
|
+
|
|
833
|
+
`send` 的出错方式只有一种:返回的 Promise 拒绝。空输入、非法配置、取消、模型报错全都从这里出来,所以只需要写 `.catch()`,不用另外包同步的 `try/catch`。取消造成的拒绝带 `error.kind === 'aborted'`;模型报错的 `error.kind` 见下方。
|
|
834
|
+
|
|
835
|
+
> 输入是在发请求**之前**就写进 `history` 的,所以一次 `send` 失败后,这条输入已经留在历史里(历史只增不删)。重试前记得先决定要不要把它去掉,否则会叠成连续两条同样的输入。
|
|
836
|
+
|
|
837
|
+
连续发送时,建议保存并处理旧任务的 Promise,避免出现未处理的中止错误:
|
|
838
|
+
|
|
839
|
+
```js
|
|
840
|
+
const oldTask = agent.send({ input: '执行旧任务' })
|
|
841
|
+
const newTask = agent.send({ input: '改执行新任务' }) // 自动停止旧任务
|
|
842
|
+
|
|
843
|
+
await oldTask.catch(() => {}) // 旧任务可能以 AbortError 结束
|
|
844
|
+
const result = await newTask
|
|
845
|
+
```
|
|
846
|
+
|
|
847
|
+
**发图片:** `input` 除了字符串,也可以是 AI SDK 风格的内容块数组。截图、用户在 IM 里发来的图都走这条路。
|
|
848
|
+
|
|
849
|
+
```js
|
|
850
|
+
await agent.send({
|
|
851
|
+
input: [
|
|
852
|
+
{ type: 'text', text: '这张截图里哪个按钮是提交?' },
|
|
853
|
+
{ type: 'image', image: 'data:image/png;base64,' + png }, // 也可以传 URL 或 Uint8Array
|
|
854
|
+
],
|
|
855
|
+
})
|
|
856
|
+
```
|
|
857
|
+
|
|
858
|
+
能不能看懂取决于模型本身。实测 `kimi-k2.6` 可以,`gpt-oss-120b` 没有视觉能力、会直接报 `content must be a string`——是大声失败,不是静默忽略。
|
|
859
|
+
|
|
860
|
+
> 直接 `send` 的内容块形状由你保证(工具返回的媒体会在边界自动校验并归一化;用户直接发的内容块不做校验)。图片块用 `{ type: 'image', image: <data URL 或 base64 或 URL 对象> }`,或 AI SDK 当前的 `{ type: 'file', mediaType, data }`。
|
|
861
|
+
|
|
862
|
+
#### `agent.stop()`
|
|
863
|
+
|
|
864
|
+
停止正在运行的 Agent。
|
|
865
|
+
|
|
866
|
+
```js
|
|
867
|
+
await agent.stop() // 等待完全停止后返回 { ok: true };Agent 空闲时返回 { ok: false }
|
|
868
|
+
```
|
|
869
|
+
|
|
870
|
+
#### 流式与网页实时推送
|
|
871
|
+
|
|
872
|
+
`send` 内部默认就是流式(`config.stream` 默认 `true`),`await` 拿到的是和流式一样的结果。想实时拿到每一块,用 `onLLMEvent`:模型每吐一段就调用一次,事件是包内 AI SDK 的原生事件。
|
|
873
|
+
|
|
874
|
+
```js
|
|
875
|
+
await agent.send({
|
|
876
|
+
input: '帮我查一下',
|
|
877
|
+
callbacks: {
|
|
878
|
+
onLLMEvent: event => {
|
|
879
|
+
if (event.type === 'text-delta') show(event.text) // 模型新吐的一段文字
|
|
880
|
+
},
|
|
881
|
+
onToolOutput: output => show(output.data), // 工具产生的实时输出
|
|
882
|
+
},
|
|
883
|
+
})
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
网页要边生成边推给浏览器时,用同样的回调,把内容写进一个标准 `Response` 流:
|
|
887
|
+
|
|
888
|
+
```js
|
|
889
|
+
// Bun.serve 的 fetch 里。开始请求,立刻把响应返回给浏览器,内容随后一块块写上。
|
|
890
|
+
app.get('/chat', async request => {
|
|
891
|
+
const encoder = new TextEncoder()
|
|
892
|
+
const stream = new ReadableStream({
|
|
893
|
+
async start(controller) {
|
|
894
|
+
const send = data => controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`))
|
|
895
|
+
try {
|
|
896
|
+
// send 里的 onLLMEvent 在流式过程中被反复调用,每段文字都及时写出去。
|
|
897
|
+
const result = await agent.send({
|
|
898
|
+
input: await request.text(),
|
|
899
|
+
callbacks: {
|
|
900
|
+
onLLMEvent: event => { if (event.type === 'text-delta') send({ text: event.text }) },
|
|
901
|
+
onStep: () => send({ status: 'step-done' }),
|
|
902
|
+
},
|
|
903
|
+
})
|
|
904
|
+
send({ done: true, reason: result.reason })
|
|
905
|
+
} catch (error) {
|
|
906
|
+
send({ error: error.message, kind: error.kind }) // 可传输的错误描述和分类。
|
|
907
|
+
} finally { controller.close() }
|
|
908
|
+
},
|
|
909
|
+
})
|
|
910
|
+
return new Response(stream, { headers: { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache' } })
|
|
911
|
+
})
|
|
912
|
+
```
|
|
913
|
+
|
|
914
|
+
要取消某次运行,给 `send` 传 `signal`(如 `request.signal`)或调用 `agent.stop()`,两者都能终止。
|
|
915
|
+
|
|
916
|
+
模型请求失败时抛出的错误带一个稳定的 `kind`:`aborted`(用户取消)、`auth`(密钥或权限,401/403)、`limit`(限流,429)、`timeout`(单笔超时或 408)、`server`(5xx)、`network`(没连上)、`request`(其余 4xx)、`unknown`(服务返回成功状态码,但回答格式对不上,常见于不完全兼容的中转站)。上层靠它决定该换模型、该等一下还是该直接报错,不用去认 AI SDK 的内部错误形状。`kind` 只补充信息;能不能重试由 Retry 的规则统一决定(见上方「重试规则」),默认除取消和上下文超长外都重试,调用方可用 `retry` 过滤。
|
|
917
|
+
|
|
918
|
+
#### `agent.compact(options?)`
|
|
919
|
+
|
|
920
|
+
手动压缩当前历史(会先停止正在进行的任务)。默认使用 `Agent.create` 中配置的 `onCompact`、`onRetry`;在本次调用中传入同名回调可以覆盖默认值。
|
|
921
|
+
|
|
922
|
+
```js
|
|
923
|
+
const summary = await agent.compact({
|
|
924
|
+
onCompact: event => console.log(event),
|
|
925
|
+
})
|
|
926
|
+
// summary 是压缩后的文本,同时会自动追加到 agent.history
|
|
927
|
+
```
|
|
928
|
+
|
|
929
|
+
#### `agent.history`
|
|
930
|
+
|
|
931
|
+
Agent 当前的完整历史消息数组,可直接读写。
|
|
932
|
+
|
|
933
|
+
#### `agent.running`
|
|
934
|
+
|
|
935
|
+
`null` 表示空闲;运行中时是 `{ controller, task }` 对象。
|
|
936
|
+
|
|
937
|
+
---
|
|
938
|
+
|
|
939
|
+
### `Agent.tool`
|
|
940
|
+
|
|
941
|
+
#### `Agent.tool.from(...sources)`
|
|
942
|
+
|
|
943
|
+
一行拼装工具集合。每个参数可以是目录、内存工具对象、数组、record、已经装好的集合,或它们的 Promise;同名时后面的覆盖前面的。
|
|
944
|
+
|
|
945
|
+
```js
|
|
946
|
+
const tools = await Agent.tool.from(
|
|
947
|
+
'./tools', // 目录:文件工具跑在子进程里
|
|
948
|
+
mcpClient.tools(), // 内存工具:MCP / AI SDK 给的工具对象,主进程直接调
|
|
949
|
+
{ skill: skillTool }, // record(一个对象,键是工具名):自定义函数;也可以传数组 [{ name, ... }, ...]
|
|
950
|
+
)
|
|
951
|
+
const agent = Agent.create({ config, tools })
|
|
952
|
+
```
|
|
953
|
+
|
|
954
|
+
`create` 收已经装好的工具(同步,不扫目录);`send` 收任意形状,目录会在发送的那一刻现扫。只有一个来源时也可以直接用下面的 `scan` / `adopt`。
|
|
955
|
+
|
|
956
|
+
#### `Agent.tool.scan(directory)`
|
|
957
|
+
|
|
958
|
+
扫描目录(含子目录)里所有 `.js` / `.mjs` / `.ts` / `.mts` 文件,把其中形状对得上的注册成工具,其余文件跳过。Bun 直接执行 TypeScript,所以工具可以直接写成 `.ts`;只有类型、没有代码的 `.d.ts` 会被跳过。
|
|
959
|
+
|
|
960
|
+
```js
|
|
961
|
+
Agent.tool.scan('./tools') // 路径字符串(相对宿主进程的当前目录)
|
|
962
|
+
Agent.tool.scan(new URL('./tools', import.meta.url)) // URL——嵌进别人项目时用这个
|
|
963
|
+
Agent.tool.scan(builtinDir, userDir) // 多个目录,后面的覆盖前面的同名工具
|
|
964
|
+
```
|
|
965
|
+
|
|
966
|
+
多目录那条顺带给了你一个免费的覆盖机制:内置工具目录在前、用户工具目录在后,用户放一个同名工具就能替换掉内置的,不需要任何注册逻辑。
|
|
967
|
+
|
|
968
|
+
```js
|
|
969
|
+
const tools = await Agent.tool.scan('./tools')
|
|
970
|
+
// tools.schema → 给模型看的工具描述,传给 create/send 的 tools(或 Loop.run 的 tools)
|
|
971
|
+
// tools.handlers → 执行器用的处理表,Tool.execute 需要它
|
|
972
|
+
```
|
|
973
|
+
|
|
974
|
+
每次调用都是独立的,多个 Agent 可以各扫描各的目录,互不影响。
|
|
975
|
+
|
|
976
|
+
#### `Agent.tool.adopt(input)`
|
|
977
|
+
|
|
978
|
+
把内存里的常规工具对象变成和 `scan` 一样的 `{ schema, handlers }`。内存工具在主进程直接执行,不走子进程。
|
|
979
|
+
|
|
980
|
+
```js
|
|
981
|
+
Agent.tool.adopt([{ name: 'add', description: '加法', inputSchema: {...}, execute: async input => input.a + input.b }]) // 数组
|
|
982
|
+
Agent.tool.adopt({ add: { description: '加法', inputSchema: {...}, execute } }) // record:AI SDK / MCP toolset 的形状
|
|
983
|
+
Agent.tool.adopt(await mcpClient.tools()) // MCP 客户端的工具直接传
|
|
984
|
+
```
|
|
985
|
+
|
|
986
|
+
`inputSchema` 可以是裸 JSON Schema、zod,或 AI SDK 的 `jsonSchema()`。`execute(input, { abortSignal })` 会收到取消信号(也接受别名 `signal`)。
|
|
987
|
+
|
|
988
|
+
文件工具和内存工具可以合并:`Agent.tool.merge(await Agent.tool.scan('./tools'), Agent.tool.adopt(mcpTools))`,或者直接用 `Agent.tool.from('./tools', mcpTools)`(见上)。
|
|
989
|
+
|
|
990
|
+
**MCP 工具直接可用,不需要包装**:`@ai-sdk/mcp` 的 `client.tools()` 自带 `execute` 和 `toModelOutput`,核心按 AI SDK 的签名调用它们,文字、图片都会正确交给模型。完整接入例子见前面的[「接入 MCP 和技能」](#接入-mcp-和技能)。
|
|
991
|
+
|
|
992
|
+
想自己改写某个工具的返回结果时,给它加一个 `toModelOutput`,签名和 AI SDK 一致(拿到的是 `{ output, input }`):`toModelOutput: ({ output }) => ({ type: 'content', value: output.content })`。
|
|
993
|
+
|
|
994
|
+
> 从 0.16 升级:`Agent.create({ mcp })`、`agent.mcp`、`Agent.skill` 和 `create({ skills })` 已删除。MCP 改为自己用 `@ai-sdk/mcp` 连接,再把工具传进 `tools`;技能的提示词自己拼进 `config.system`。
|
|
995
|
+
>
|
|
996
|
+
> 从 0.19 升级:`onPermission` 的 `arguments` 字段改名为 `input`;结束原因多了一个 `'finished'`(没注册工具、或结构化输出已校验成功,原先是 `'no-tool'`)。工具对象的 `execute(input, { abortSignal })`、`toModelOutput({ output, input })` 现在按 AI SDK 签名调用。
|
|
997
|
+
>
|
|
998
|
+
> 从 0.21 升级:去掉了 `gpt-tokenizer`,上下文 token 改用**自校准估算**(字符数 × 每字符 token 比,比例由真实 `usage` 学到,跟着模型走);`maxTokens` 默认变为 `128000`,**自动压缩默认开启**(想关掉设 `maxTokens: Infinity`)。产物从 ~3.9 MB 降到 ~1.3 MB。
|
|
999
|
+
>
|
|
1000
|
+
> 从 0.22 升级:内存工具声明的 `timeout` 现在真的生效;新增 `capabilities.usage`(关掉流式请求里的 `include_usage`);`compactThreshold`、字符串型 `maxTokens` 等非法配置现在会在 `send` 入口报错。
|
|
1001
|
+
>
|
|
1002
|
+
> 从 0.23 升级:内存工具(`Agent.tool.adopt`)现在也支持 `async *execute` 流式输出,和文件工具一致;`Tool.from` 接受一组目录(字符串数组);取消错误统一带 `error.kind === 'aborted'`。
|
|
1003
|
+
|
|
1004
|
+
#### `Agent.tool.execute(options)`
|
|
1005
|
+
|
|
1006
|
+
直接执行一个工具(通常不需要手动调用,Agent 内部会调用)。
|
|
1007
|
+
|
|
1008
|
+
```js
|
|
1009
|
+
const result = await Agent.tool.execute({
|
|
1010
|
+
name: 'add',
|
|
1011
|
+
input: { a: 1, b: 2 },
|
|
1012
|
+
handlers: tools.handlers,
|
|
1013
|
+
signal: abortController.signal, // 可选:取消信号
|
|
1014
|
+
onOutput: output => {}, // 可选:接收工具流式输出(文件工具的 stdout/生成器 yield,内存工具的生成器 yield)
|
|
1015
|
+
limit: 32000, // 可选:输出字符上限,超出从中间截断;不传则不截断
|
|
1016
|
+
concurrency: 8, // 可选:同一批(同一个 signal)最多同时跑几个文件工具,超出的排队
|
|
1017
|
+
})
|
|
1018
|
+
// result.output → 工具输出块,type 是 'text' | 'json' | 'content' | 'error-text' | 'error-json' | 'execution-denied'
|
|
1019
|
+
// result 还带:stop:true(工具要求结束循环)/ error(工具失败)/ interrupted:true(被取消)
|
|
1020
|
+
```
|
|
1021
|
+
|
|
1022
|
+
---
|
|
1023
|
+
|
|
1024
|
+
### `Agent.llm`
|
|
1025
|
+
|
|
1026
|
+
#### 结构化结果
|
|
1027
|
+
|
|
1028
|
+
```js
|
|
1029
|
+
const agent = Agent.create({
|
|
1030
|
+
config: {
|
|
1031
|
+
baseURL, apiKey, model,
|
|
1032
|
+
output: Agent.output.object({ // 要什么形状的结果,写在配置顶层
|
|
1033
|
+
schema: Agent.schema.object({ total: Agent.schema.number() }),
|
|
1034
|
+
}),
|
|
1035
|
+
},
|
|
1036
|
+
})
|
|
1037
|
+
const { output } = await agent.send('计算订单总数')
|
|
1038
|
+
console.log(output.total)
|
|
1039
|
+
```
|
|
1040
|
+
|
|
1041
|
+
`Agent.output` 是包内 AI SDK 的 Output,`Agent.schema` 是包内 Zod,无需另装一套。数组可用 `Agent.output.array({ element: Agent.schema.string() })`,普通 JSON 可用 `Agent.output.json()`。所选模型服务须支持对应输出格式。
|
|
1042
|
+
|
|
1043
|
+
有工具时先完成工具调用,再读取最终对象。工具轮、`tool-stop` 或轮数用尽不会凭空产生 `output`。最终对象校验成功立即结束;格式错误默认也会重试(重新生成不保证还是坏的),想让它立刻失败可用 `retry` 过滤或收紧 `retryMaxElapsed`。手动及自动压缩只生成文本总结,不继承任务的对象格式。流式和非流式都在最终结果上提供 `output`;流中仍会有生成时的文字片段。
|
|
1044
|
+
|
|
1045
|
+
直接使用底层 LLM,绕过 Agent 循环。
|
|
1046
|
+
|
|
1047
|
+
#### `Agent.llm.chat(options)`
|
|
1048
|
+
|
|
1049
|
+
```js
|
|
1050
|
+
const result = await Agent.llm.chat({
|
|
1051
|
+
baseURL: 'https://api.example.com/v1',
|
|
1052
|
+
apiKey: 'sk-xxx',
|
|
1053
|
+
model: 'gpt-4o',
|
|
1054
|
+
messages: [{ role: 'user', content: '你好' }],
|
|
1055
|
+
provider: { temperature: 0.3 }, // 生成参数原样转给 AI SDK
|
|
1056
|
+
stream: true, // 默认 true
|
|
1057
|
+
onLLMEvent: event => console.log(event), // 流式事件回调
|
|
1058
|
+
})
|
|
1059
|
+
// result.text → 模型回复的文字
|
|
1060
|
+
// result.toolCalls → 工具调用列表
|
|
1061
|
+
// result.usage → token 用量
|
|
1062
|
+
// result.finishReason → 停止原因
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
`Agent.llm.chat` 只负责和模型说话,不处理文字工具协议(`toolMode` 是 Agent 的配置,由主循环负责)。直接调它、又要让纯对话模型用工具时,自己在请求前后各调一次:
|
|
1066
|
+
|
|
1067
|
+
```js
|
|
1068
|
+
const spec = await Agent.textTools.prepare(tools.schema) // 把工具表写成说明书
|
|
1069
|
+
const reply = await Agent.llm.chat({ ...connection, messages: Agent.textTools.wrap(messages, spec) }) // 不带 tools 字段
|
|
1070
|
+
const result = Agent.textTools.read(reply, spec, { loose: true }) // result.toolCalls 就是读回来的调用
|
|
1071
|
+
```
|
|
1072
|
+
|
|
1073
|
+
---
|
|
1074
|
+
|
|
1075
|
+
### `Agent.context`
|
|
1076
|
+
|
|
1077
|
+
#### `Agent.context.build(options)`
|
|
1078
|
+
|
|
1079
|
+
把历史消息裁剪成模型能用的上下文,并估算 token 数。
|
|
1080
|
+
|
|
1081
|
+
```js
|
|
1082
|
+
const { messages, token } = Agent.context.build({
|
|
1083
|
+
history: agent.history,
|
|
1084
|
+
system: '你是助手',
|
|
1085
|
+
tools: tools.schema,
|
|
1086
|
+
})
|
|
1087
|
+
// messages → 可以直接传给 LLM.chat 的消息数组
|
|
1088
|
+
// token → 估算的 token 数(不装分词器:字符数 × 每字符 token 比,比例由 Loop 从真实 usage 自校准)
|
|
1089
|
+
```
|
|
1090
|
+
|
|
1091
|
+
裁剪的最小单位是**回合**,不是消息。一个回合 = 模型的一次响应 + 它发起的全部工具调用 + 这些调用的结果,
|
|
1092
|
+
永远同进同出。所以裁剪结果里不会出现"有调用没结果"或"有结果没调用"的残缺配对——那种序列会被
|
|
1093
|
+
OpenAI 和 Anthropic 直接 400。
|
|
1094
|
+
|
|
1095
|
+
压缩时自动保留:用户最初的 3 个回合(保留原始目标)+ 最新总结 + 总结前最近 3 个回合 + 总结后所有回合。
|
|
1096
|
+
|
|
1097
|
+
模型的思考内容(`reasoning`)会留在 `history` 里供上层 UI 渲染,但不会回传给模型:
|
|
1098
|
+
它是某一次响应的厂商产物,不是持久对话状态,回传还会被一些服务拒绝。
|
|
1099
|
+
|
|
1100
|
+
---
|
|
1101
|
+
|
|
1102
|
+
### `History`(从 `Agent.history` 获取)
|
|
1103
|
+
|
|
1104
|
+
```js
|
|
1105
|
+
const History = Agent.history // 从唯一入口拿,打包成单文件之后也一样
|
|
1106
|
+
|
|
1107
|
+
// 创建各种类型的历史块
|
|
1108
|
+
History.user({ content: '你好' })
|
|
1109
|
+
History.user({ content: [{ type: 'text', text: '这是什么' }, { type: 'image', image: dataUrl }] }) // 带图片
|
|
1110
|
+
History.assistant({ content: '你好', toolCalls: [{ id: 'call-1', name: 'add', arguments: { a: 1, b: 2 } }] })
|
|
1111
|
+
History.tool({ toolCallId: 'call-1', toolName: 'add', content: '3' })
|
|
1112
|
+
History.compact({ content: '之前的对话总结...' })
|
|
1113
|
+
```
|
|
1114
|
+
|
|
1115
|
+
**读历史**——渲染给用户看、数聊了几轮,这两件事的知识本来就在核心里,不用你照着内部结构重写:
|
|
1116
|
+
|
|
1117
|
+
```js
|
|
1118
|
+
History.render(agent.history)
|
|
1119
|
+
// user: 帮我读一下配置
|
|
1120
|
+
// assistant: [思考] 我来读 [调用 read {"path":"a.json"}]
|
|
1121
|
+
// tool: [read 返回] {"port":8080}
|
|
1122
|
+
// user: 这张图呢 [图片]
|
|
1123
|
+
|
|
1124
|
+
History.turns(agent.history) // 折成回合:[[user], [assistant, tool], [user]]
|
|
1125
|
+
```
|
|
1126
|
+
|
|
1127
|
+
`turns()` 的规则比看上去微妙——**工具结果认的是发起它的 `toolCallId`,不是它在数组里排在谁后面**。从数据库按 id 恢复会话时结果可能排在调用前面,自己推一遍很容易算错。`Context.build()` 裁剪上下文用的就是这同一份实现,所以"什么是一个回合"在整个包里只有一处定义。
|
|
1128
|
+
|
|
1129
|
+
想自己排版的,用 `turns()` 拿到回合,再按内容块类型(`text` / `reasoning` / `tool-call` / `tool-result` / `image` / `file`)自己拼。
|
|
1130
|
+
|
|
1131
|
+
---
|
|
1132
|
+
|
|
1133
|
+
## 上生产前
|
|
1134
|
+
|
|
1135
|
+
下面这些旋钮**默认都不限制**,本地玩没问题,生产必须显式设置。每个配一句为什么:
|
|
1136
|
+
|
|
1137
|
+
| 旋钮 | 默认 | 为什么生产必须设 |
|
|
1138
|
+
|------|------|------------------|
|
|
1139
|
+
| `maxToolOutput` | 不截断 | 工具输出不截断有 31 万 token 风险:一个 1MB 的文本(`cat` 一个日志文件)就够,超过多数模型的整个窗口,还会永久留在历史里,压缩也救不回来。设个字符数,比如 `32000`。 |
|
|
1140
|
+
| `maxToolConcurrency` | 不限制 | 默认不限文件工具并发:模型偶尔一轮返回几十个工具调用,会瞬间起几十个进程。设个上限,比如 `8`。 |
|
|
1141
|
+
| `requestTimeout` | 不限制 | 默认不限单笔时长:卡住的请求会一直等下去。设毫秒数,到点中断这一笔。 |
|
|
1142
|
+
| `retryMaxElapsed` | 不限制 | 默认重试所有错误且无总上限,等于无限重试。生产建议设毫秒数收口,或用 `retry` 过滤掉不该重试的错误(如 `auth`、`request`)。 |
|
|
1143
|
+
| `maxTokens` | `128000` | 上下文预算,要按你模型的窗口调。比窗口大会撑爆,比需求小会频繁压缩。 |
|
|
1144
|
+
|
|
1145
|
+
## 可观测性
|
|
1146
|
+
|
|
1147
|
+
每一轮里模型花了多久、工具花了多久、什么时候压缩,用现成的回调就能拼出来。它们只是通知,抛错也不影响任务:
|
|
1148
|
+
|
|
1149
|
+
```js
|
|
1150
|
+
const startedAt = new Map() // toolCallId → 开始时间
|
|
1151
|
+
|
|
1152
|
+
const agent = Agent.create({
|
|
1153
|
+
config,
|
|
1154
|
+
callbacks: {
|
|
1155
|
+
// 一次模型请求的耗时和用量
|
|
1156
|
+
onLLMStart: () => { startedAt.set('llm', performance.now()) },
|
|
1157
|
+
onLLMFinish: result => {
|
|
1158
|
+
console.log('模型耗时', (performance.now() - startedAt.get('llm')).toFixed(0), 'ms', result.usage)
|
|
1159
|
+
},
|
|
1160
|
+
// 每个工具的耗时和结果
|
|
1161
|
+
onToolCall: ({ toolCallId, toolName, input }) => {
|
|
1162
|
+
startedAt.set(toolCallId, performance.now())
|
|
1163
|
+
console.log('工具开始', toolName, input)
|
|
1164
|
+
},
|
|
1165
|
+
onToolResult: ({ toolCallId, toolName, output }) => {
|
|
1166
|
+
console.log('工具结束', toolName, (performance.now() - startedAt.get(toolCallId)).toFixed(0), 'ms', output)
|
|
1167
|
+
},
|
|
1168
|
+
// 一轮(模型 + 全部工具)结束
|
|
1169
|
+
onStep: ({ step, toolCalls }) => {
|
|
1170
|
+
console.log('第', step, '轮结束', toolCalls.length, '个工具')
|
|
1171
|
+
},
|
|
1172
|
+
// 压缩开始 / 完成
|
|
1173
|
+
onCompact: event => console.log('压缩', event.type, event),
|
|
1174
|
+
},
|
|
1175
|
+
})
|
|
1176
|
+
```
|
|
1177
|
+
|
|
1178
|
+
把这些按 `step` 或 `toolCallId` 串起来写进日志或时序库,就是每一轮的完整观测数据。
|
|
1179
|
+
|
|
1180
|
+
想直接接 AI SDK 的 OpenTelemetry,把 `experimental_telemetry` 放进 `config.provider` 即可——本包把 `provider` 整份转给模型调用,不截留字段:
|
|
1181
|
+
|
|
1182
|
+
```js
|
|
1183
|
+
config: {
|
|
1184
|
+
// ...
|
|
1185
|
+
provider: {
|
|
1186
|
+
experimental_telemetry: { isEnabled: true, functionId: 'my-agent' },
|
|
1187
|
+
},
|
|
1188
|
+
}
|
|
1189
|
+
```
|
|
1190
|
+
|
|
1191
|
+
## 示例
|
|
1192
|
+
|
|
1193
|
+
[`examples/minimal/`](examples/minimal/) 是一个能直接跑起来的最小项目:用本地假模型,不需要任何密钥,注册一个工具跑完一圈,适合拿来当起点。
|
|
1194
|
+
|
|
1195
|
+
```bash
|
|
1196
|
+
bun examples/minimal/main.js
|
|
1197
|
+
```
|
|
1198
|
+
|
|
1199
|
+
[`examples/app/`](examples/app/) 是一个更完整的 chat 服务示例:同样的本地假模型,演示会话管理 / 持久化 / 流式 / 权限 / 观测 / 取消 / 生产设置,适合要写真实应用的人参考。
|
|
1200
|
+
|
|
1201
|
+
```bash
|
|
1202
|
+
bun examples/app/server.js
|
|
1203
|
+
```
|
|
1204
|
+
|
|
1205
|
+
## 长跑压测
|
|
1206
|
+
|
|
1207
|
+
`bun scripts/stress.js` 会跑多会话 × 多轮,打印完成情况和内存增量。生产长期运行前,先在你自己的负载上压一遍。
|
|
1208
|
+
|
|
1209
|
+
## 运行测试
|
|
1210
|
+
|
|
1211
|
+
```bash
|
|
1212
|
+
bun test
|
|
1213
|
+
```
|
|
1214
|
+
|
|
1215
|
+
测试在 [`tests/`](tests/) 里按 Agent、模型、上下文、工具等模块分文件;模型测试使用本地模拟服务。
|
|
1216
|
+
|
|
1217
|
+
查看覆盖率:
|
|
1218
|
+
|
|
1219
|
+
```bash
|
|
1220
|
+
bun test --coverage
|
|
1221
|
+
```
|
|
1222
|
+
|
|
1223
|
+
---
|
|
1224
|
+
|
|
1225
|
+
## 打包成单文件
|
|
1226
|
+
|
|
1227
|
+
```bash
|
|
1228
|
+
bun run build
|
|
1229
|
+
```
|
|
1230
|
+
|
|
1231
|
+
只生成 `dist/agent-core.js`:Bun 运行时使用的依赖全部内联并压缩。同时把手写的类型声明 `index.d.ts` 复制成 `dist/agent-core.d.ts`,TypeScript 用户导入时有参数补全和类型检查。构建脚本在没有 `node_modules` 的临时目录中导入产物,实际运行一次工具和模型模拟请求,成功后才替换 `dist/agent-core.js`。发布包只包含 `dist/agent-core.js`、`dist/agent-core.d.ts`、`README.md`、`LICENSE` 和 `package.json`;`npm pack` / `npm publish` 前会自动构建。产物顶部写有版本号和提交号,压缩不是加密。
|
|
1232
|
+
|
|
1233
|
+
```js
|
|
1234
|
+
import Agent from './agent-core.js'
|
|
1235
|
+
|
|
1236
|
+
// 工具目录用 URL 指,永远相对你自己这份代码,不受宿主进程当前目录影响
|
|
1237
|
+
const tools = await Agent.tool.scan(new URL('./tools', import.meta.url))
|
|
1238
|
+
const agent = Agent.create({ config: { /* ... */ }, tools })
|
|
1239
|
+
```
|
|
1240
|
+
|
|
1241
|
+
`default` 导出就是全部入口,嵌入方需要的东西都挂在上面:
|
|
1242
|
+
|
|
1243
|
+
| | |
|
|
1244
|
+
|---|---|
|
|
1245
|
+
| `Agent.version` | 包版本,排查问题时报得出来 |
|
|
1246
|
+
| `Agent.create(...)` | 创建 Agent 实例 |
|
|
1247
|
+
| `Agent.tool` | `.from()` / `.scan()` / `.adopt()` / `.execute()` / `.merge()` |
|
|
1248
|
+
| `Agent.history` | `.user()` / `.assistant()` / `.tool()` / `.compact()` 造消息块;`.turns()` / `.render()` 读历史 |
|
|
1249
|
+
| `Agent.context` | `.build()` |
|
|
1250
|
+
| `Agent.compact` | `.run()` |
|
|
1251
|
+
| `Agent.llm` | `.chat()` |
|
|
1252
|
+
| `Agent.textTools` | 文字工具协议:`.prepare()` / `.wrap()` / `.read()`,直接调 `llm.chat` 时用 |
|
|
1253
|
+
| `Agent.output` / `Agent.schema` | 结构化输出的 Output 与 Zod,包内同一份,无需另装 |
|
|
1254
|
+
|
|
1255
|
+
`Agent.history` 和 `Agent.textTools` 还导出一些底层方法(`stored` / `model` / `parts` / `answeredCalls`,以及文字协议的 `parse` / `downgrade` / `refused` / `remember` / `remembered`),完整列表见 `index.d.ts`。
|
|
1256
|
+
|
|
1257
|
+
`Agent.history` 是嵌入时最常用的那个:把 IM 消息转成 user 块、往历史里塞一条系统通知、从数据库恢复会话,都要靠它造出格式正确的消息。
|
|
1258
|
+
|
|
1259
|
+
**工具进程需要一个 bun 运行时。** 普通 `bun run` 时用的就是宿主自己(`process.execPath`,不依赖 PATH);宿主被 `bun build --compile` 成单可执行文件时,会退回 PATH 上的 `bun`——这种分发方式需要目标机器装了 bun。
|
|
1260
|
+
|
|
1261
|
+
工具目录不会被打包——它本来就该是运行时扫描的,放文件即加功能这件事在打包后照样成立。
|
|
1262
|
+
|
|
1263
|
+
工具进程那一半(`features/tool-process.js`)在打包时会被当成文本内联进单文件,运行时通过 `bun -` 从 stdin 喂给一个新的子进程,
|
|
1264
|
+
所以产物挪到任何目录都能正常执行工具,也不会往磁盘上写临时文件。
|
|
1265
|
+
这也是 `tool-process.js` 里不能出现任何 `import` 的原因:它以匿名程序的身份运行,相对路径和裸包名会按进程当前目录解析,必然出错。
|
|
1266
|
+
(用 stdin 而不是 `bun -e`:后者在 8KB 到 32KB 之间就会 `ENAMETOOLONG`,而工具进程源码已经接近这个量级。)
|
|
1267
|
+
|
|
1268
|
+
---
|
|
1269
|
+
|
|
1270
|
+
## 这个包不做什么
|
|
1271
|
+
|
|
1272
|
+
一个包被失望,通常不是因为它功能少,是因为它没说清自己不管什么。下面是明确的边界,请先确认这些是你想要的,再决定用它。
|
|
1273
|
+
|
|
1274
|
+
**不替你保存会话。** `history` 就是一个普通数组,一直放在内存里。进程一退就没了。要让它跨重启、跨设备,由你把 `history` 存进数据库、下次再传回来——怎么存、存多久、怎么按用户隔离,属于你的应用层。核心包不做这件事,也不猜测你用什么存储。
|
|
1275
|
+
|
|
1276
|
+
**不算钱。** 返回的 `usage` 是原始 token 数,不乘单价、不累加账单、不按模型区分价格。价格表会变,缓存命中怎么计价各家不同,这些属于上层。
|
|
1277
|
+
|
|
1278
|
+
**不做用户和权限系统。** 它只有一个 `onPermission` 回调,在工具执行前问一句"放不放行"。谁是用户、谁登录了、谁能用哪个工具,由你的应用判断后通过这个回调告诉它。
|
|
1279
|
+
|
|
1280
|
+
**不隔离多租户。** 一台 Agent 是一个独立对象,`history`、`config`、`running` 都在自己的实例里,实例之间互不影响。但"张三的对话不能跑到李四那里"要靠你给每个用户各自创建 Agent、各自保管 history 来实现,核心包不提供账号、鉴权、数据隔离。
|
|
1281
|
+
|
|
1282
|
+
**不管并发排队和限流。** 同一台 Agent 上后一次 `send` 会停掉前一次(这是有意设计的"最新指令优先")。要让多个用户同时用,就为每个会话建一台 Agent;要限制总并发、总费用,由你的应用做。核心包没有全局任务队列。
|
|
1283
|
+
|
|
1284
|
+
**不管 MCP 连接和技能。** 核心只接收通用工具对象。MCP 服务的连接、开关和关闭由你的应用管理,再用 `Agent.tool.adopt` 把工具交进来;技能提示词自己拼进 `system`。
|
|
1285
|
+
|
|
1286
|
+
**不做工具的安全检查。** 工具子进程和 Agent 拥有完全相同的权限:读写任意文件、执行任意命令、联网、读到父进程的全部环境变量。这是有意的——电脑任务 agent 的工具本来就得能干这些。**沙箱、白名单、危险命令拦截属于你的应用层**,核心包只提供 `onPermission` 这一个挂钩点。
|
|
1287
|
+
|
|
1288
|
+
**不保证所有模型/中转站的兼容性。** 它针对四种协议做了适配,也在真实网关上验证过,但中转站千奇百怪:有的返回的状态码和实际结果不符,有的字段缺失。遇到不兼容时,`error.kind` 会告诉你大概是哪一类问题,但没法替那个服务端修好它。
|
|
1289
|
+
|
|
1290
|
+
**不保证长跑和多会话并发下的表现。** 这两项只在小规模下验证过。要在生产环境长期运行,请先按你自己的负载压测。
|
|
1291
|
+
|
|
1292
|
+
**没有 GUI、没有服务端、没有命令行工具。** 它只是一个库,被别的程序 `import` 使用。开箱即用的聊天应用不在它的范围内。
|
|
1293
|
+
|
|
1294
|
+
---
|
|
1295
|
+
|
|
1296
|
+
## 常见问题
|
|
1297
|
+
|
|
1298
|
+
**Q:支持 Node.js 吗?**
|
|
1299
|
+
|
|
1300
|
+
不支持,而且这是刻意的。工具进程用 [`Bun.spawn` + IPC](features/tool-process.js),扫描用 [`Bun.Glob`](features/tool.js),打包靠 `import ... with { type: 'text' }`,都只有 Bun 有。
|
|
1301
|
+
|
|
1302
|
+
---
|
|
1303
|
+
|
|
1304
|
+
**Q:支持哪些模型提供商?**
|
|
1305
|
+
|
|
1306
|
+
通过 `config.protocol` 控制:
|
|
1307
|
+
|
|
1308
|
+
| protocol 值 | 适用场景 |
|
|
1309
|
+
|-------------|----------|
|
|
1310
|
+
| `chat`(默认) | OpenAI 以及任何兼容 OpenAI Chat 接口的中转站 |
|
|
1311
|
+
| `responses` | OpenAI Responses API |
|
|
1312
|
+
| `anthropic` | Anthropic 官方接口 |
|
|
1313
|
+
| `gemini` | Google Gemini 接口 |
|
|
1314
|
+
|
|
1315
|
+
---
|
|
1316
|
+
|
|
1317
|
+
**Q:上下文太长会怎样?**
|
|
1318
|
+
|
|
1319
|
+
上下文超过 `config.maxTokens` 的 `compactThreshold`(默认 0.8,即 80%)时,Loop 会自动调用 Compact 把历史压缩成一段总结,然后继续运行。**默认就开着**:`maxTokens` 默认 `128000`,不配置也会在接近上限时自动压缩,避免把上下文撑爆。你的模型窗口比这小就把它调小;想彻底关掉设 `maxTokens: Infinity`。
|
|
1320
|
+
|
|
1321
|
+
**上下文 token 怎么估**:不装分词器,用"字符数 × 每字符多少 token"。这个比例是**会自校准**的——每轮模型都会回 `usage.inputTokens`(这次请求真实的输入 token 数),拿它反推这个模型真实的"每字符 token 比"记下来给下一轮。换模型(`config.compact` 的压缩模型、`send` 时覆盖 `model`、换 provider)就换一条记录,越用越准,也不怕分词器对不上模型。
|
|
1322
|
+
|
|
1323
|
+
**压缩只往 `agent.history` 里追加一条总结,永远不删任何东西。** `history` 是唯一权威数据来源,该保留多少由持有它的你来决定——压缩控制的是"这一轮发给模型的内容有多大",不是"历史能留多少"。
|
|
1324
|
+
|
|
1325
|
+
**压缩可以另配一套模型。** 总结不需要主模型那么聪明,用便宜的小模型就够,写在 `config.compact` 里:
|
|
1326
|
+
|
|
1327
|
+
```js
|
|
1328
|
+
config: {
|
|
1329
|
+
baseURL: 'https://api.example.com/v1', apiKey: 'sk-xxx', model: '主模型',
|
|
1330
|
+
compact: { model: '便宜的小模型' }, // 也能一起换 baseURL / apiKey / provider
|
|
1331
|
+
}
|
|
1332
|
+
```
|
|
1333
|
+
|
|
1334
|
+
不写 `compact` 就和主模型共用。自动压缩和手动 `agent.compact()` 用的都是这一套。
|
|
1335
|
+
|
|
1336
|
+
> 用更小的小模型做压缩时注意:那笔压缩请求的**大小是由主模型的 `maxTokens` 决定的**,跟压缩模型自己的窗口无关。如果压缩模型的窗口比主模型预算小,压缩请求会先在小模型这边撑爆。让压缩模型的窗口 ≥ 主模型预算,或把 `maxTokens` 调小。
|
|
1337
|
+
|
|
1338
|
+
**最新的那条总结会折进 `system`,而不是当成一条用户消息塞进对话里**,并且带一句"这是你自己之前做过的工作,数据已由工具确认"。裸的 `role:'user'` 总结会被模型读成"用户塞给我一张表",于是它从头重做整个任务——真实端点实测 `gpt-oss-120b` 改之前 1/6 能正确续跑,改之后 6/6。
|
|
1339
|
+
|
|
1340
|
+
保留多少旧内容是**按预算**算的,不是按条数:最初目标最多占 20%、总结前的现场最多占 30%,总结之后的新回合不受限。只按条数留的话,用户第一条消息粘一大段日志就能让压缩永远收敛不了(实测 120/120 轮压完仍超阈值)。放不下的最初目标不会丢——总结本身就被要求保留用户的原始目标,而总结在 `system` 里,永远不会被裁掉。
|
|
1341
|
+
|
|
1342
|
+
每轮最多压一次。压完还超限就照常发出去,由模型服务判断收不收;下一轮还超自然会再压。**不会**为了压到达标而连续调用模型——那样一轮能烧掉上千次请求。
|
|
1343
|
+
|
|
1344
|
+
---
|
|
1345
|
+
|
|
1346
|
+
**Q:工具返回一个巨大的结果会怎样?**
|
|
1347
|
+
|
|
1348
|
+
默认不截断(`maxToolOutput` 默认 `undefined`)。设置 `config.maxToolOutput`(字符数)后,超出的部分会从中间截断,头尾都保留,并插入一段明确的提示告诉模型"输出过长、请缩小范围或分页重新获取"。
|
|
1349
|
+
|
|
1350
|
+
截断**只作用于文字**。多模态输出块里的图片、文件一个字节都不动——截一刀就彻底废了,截图工具的返回值本来就大。
|
|
1351
|
+
|
|
1352
|
+
建议主动设置它(比如 `maxToolOutput: 32000`):实测一个返回 1MB 文本的工具(`cat` 一个日志文件就够了)= **31 万 token**,超过大多数模型的整个上下文窗口,而且它会永久留在历史里——连压缩都救不回来,因为压缩本身要把这坨东西发给模型去总结。
|
|
1353
|
+
|
|
1354
|
+
---
|
|
1355
|
+
|
|
1356
|
+
**Q:工具卡住不返回会怎样?**
|
|
1357
|
+
|
|
1358
|
+
默认会一直等——因为**阻塞型工具是被支持的正常用法**:等 IM 消息、盯文件变化、守着一个长任务,这些工具就是要长期不返回。有全局超时反而会把它们全废掉。
|
|
1359
|
+
|
|
1360
|
+
需要超时保护的工具自己在工具文件里声明:
|
|
1361
|
+
|
|
1362
|
+
```js
|
|
1363
|
+
export default {
|
|
1364
|
+
name: 'fetch_page',
|
|
1365
|
+
description: '抓一个网页',
|
|
1366
|
+
timeout: 30000, // 毫秒。超时后工具进程被直接杀掉,模型收到一条超时结果
|
|
1367
|
+
inputSchema: { /* ... */ },
|
|
1368
|
+
async execute(input) { /* ... */ },
|
|
1369
|
+
}
|
|
1370
|
+
```
|
|
1371
|
+
|
|
1372
|
+
`agent.stop()` 任何时候都能立刻掐断,不管工具声没声明超时。
|
|
1373
|
+
|
|
1374
|
+
---
|
|
1375
|
+
|
|
1376
|
+
**Q:工具执行失败会让 Agent 崩溃吗?**
|
|
1377
|
+
|
|
1378
|
+
不会。工具失败会被捕获,错误信息会作为工具结果告诉模型,模型可以自行决定是否重试或换一种方式。
|
|
1379
|
+
|
|
1380
|
+
这条覆盖得相当彻底:工具自己抛错、工具文件语法错误、工具返回了没法序列化的值(循环引用、函数、类实例)、
|
|
1381
|
+
`toModelOutput` 自己抛错、甚至工具调 `process.exit` 把整个工具进程干掉——
|
|
1382
|
+
全都会变成一条模型能读的工具结果,而不是让这次调用永远挂着。
|
|
1383
|
+
|
|
1384
|
+
---
|
|
1385
|
+
|
|
1386
|
+
**Q:多个工具是串行还是并行执行的?**
|
|
1387
|
+
|
|
1388
|
+
并行。模型在一轮里要求调用多个工具时,所有工具同时开跑,结果按原顺序收集后一起写回历史。
|
|
1389
|
+
|
|
1390
|
+
同一个 Agent 内,**文件工具**同时最多跑 `config.maxToolConcurrency` 个(默认不限制,一个工具独占一个工具进程),超出的排队。模型偶尔会一轮返回几十个工具调用,建议设一个上限(比如 8)避免瞬间起几十个进程。不同 Agent 各自计算,互不影响。**内存工具(`Agent.tool.adopt` / MCP)在主进程直接跑,不受这个上限约束**——要限它们得在自己的 `execute` 里做。
|
|
1391
|
+
|
|
1392
|
+
注意阻塞型工具会**长期占着名额**:上限设成 8、又有 8 个会话各挂一个 `wait_for_message`,第 9 个会话的任何工具都排不进来。多会话的 bot 要按会话数把这个值调大。
|
|
1393
|
+
|
|
1394
|
+
---
|
|
1395
|
+
|
|
1396
|
+
**Q:怎么让 Agent 在任务完成时自动停止?**
|
|
1397
|
+
|
|
1398
|
+
有两种方式:
|
|
1399
|
+
|
|
1400
|
+
1. 写一个 `finish` 工具,让它 `return { stop: true }`,并在系统提示词里告诉模型"完成任务时调用 finish 工具"。
|
|
1401
|
+
2. 不写 finish 工具,依赖默认行为:有工具时模型连续 `noToolRounds` 轮(默认 3,最后一轮请求前会插一次提醒)不调用任何工具,Loop 自动返回 `{ reason: 'no-tool' }`。想让模型一不调工具就结束,设 `noToolRounds: 1`。
|
|
1402
|
+
|
|
1403
|
+
---
|
|
1404
|
+
|
|
1405
|
+
**Q:怎么中途停止 Agent?**
|
|
1406
|
+
|
|
1407
|
+
```js
|
|
1408
|
+
const runPromise = agent.send({ input: '...' })
|
|
1409
|
+
|
|
1410
|
+
// 3 秒后强制停止
|
|
1411
|
+
setTimeout(() => agent.stop(), 3000)
|
|
1412
|
+
|
|
1413
|
+
await runPromise.catch(() => {}) // stop() 会让 send() 以 AbortError 结束
|
|
1414
|
+
```
|
|
1415
|
+
|
|
1416
|
+
或者在 `onPermission` 回调里返回 `false` 拒绝某次工具调用,但不会停止整个循环。
|