# @agentskit/core 中文文档

规范地址：https://npmcn.com/package/%40agentskit/core/

版本：1\.15\.0
npm 元数据更新时间：2026-10-10T14:12:06.592Z
中文译文更新时间：2026-11-05T19:28:41.279Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/core
原文对照：https://npmcn.com/package/%40agentskit/core/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/core
源码仓库：https://github.com/AgentsKit-io/agentskit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.6 MB，153 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：0 个
- 首次发布：2026-04-05T21:52:09.764Z
- 最新版本发布：2026-10-10T14:12:06.266Z
- 近 30 天下载量：37669（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 36 个）

## 中文简介

可移动代理 Kit 运行时间用于聊天管弦乐,工具,内存和检索.

## 安装

```sh
npm install @agentskit/core
```

也可以使用：`pnpm add @agentskit/core`、`yarn add @agentskit/core`、`bun add @agentskit/core`

## README

# @ agentskit/ 核心

简介 : `major-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

每个 AgentsKit 软件包所基于的零依赖性基础——在10 KB gzip 预算下,边缘准备,在 JavaScript 运行的任何地方工作.

[![npm version](https://img.shields.io/npm/v/@agentskit/core?color=blue)](https://www.npmjs.com/package/@agentskit/core) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/core)](https://www.npmjs.com/package/@agentskit/core) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/core?label=bundle)](https://bundlejs.com/?q=@agentskit/core) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-stable-brightgreen)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `ai` • 妇女 `agents` • 妇女 `llm` • 妇女 `agentskit` • 妇女 `typescript` • 妇女 `orchestration` • 妇女 `streaming` • 妇女 `chat`

## 已核实的证据

-   软件包元数据和测试在 `packages/core/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/参考资料/packages/core](https://www.agentskit.io/docs/reference/packages/core)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

@agentskit/core是合同层:使适配器,工具,技能,内存,检索器和运行时间可以互换的微小而稳定的地基.

-   **探员Kit**:与本回购中的其他包一起作曲,从可互换的小零件来构建代理.
-   **书记官处**: 查找已使用此图层的即时代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 学习本层背后的生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/core) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 为什么是核心

-   **外部依赖性为零** ——无 npm bloat,无审计出乎意料;安装以毫秒为单位,并在Node,Deno,边缘运行时间,浏览器中工作
-   **释放整个生态系统的稳定契约** 6个ADR定位接口(`Adapter`, (中文(简体) ), `Tool`, (中文(简体) ), `Skill`, (中文(简体) ), `Memory`, (中文(简体) ), `Retriever`, (中文(简体) ), `Runtime`)使每个软件包可以互换
-   **包含聊天状态机器** —— 说 `createChatController` 处理流线、中止和消息历史,所以你从不执行循环
-   **不到10克贝克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克** ——在社区倡议中执行预算;你可以长期承诺的基础

## 安装

```bash
npm install @agentskit/core
```

## 快速实例

```ts
import { createChatController, createInMemoryMemory } from '@agentskit/core'
import { anthropic } from '@agentskit/adapters'

const controller = createChatController({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-6' }),
  memory: createInMemoryMemory(),
})

await controller.send('Hello!')
console.log(controller.getState().messages)
```

## 持久确认和内容部分

`controller.send` 接受字符串或 `ContentPart[]`; 部件保留在用户信件上 `content` 是他们的文本投影。 共享 `ChatReturn.send` 签名还接受部分;现有的字符串调用器仍然兼容。 结构 `ChatController` 执行必须提供所需的 `decide` 方法.

配置 `ChatConfig.decisionStore` 带对讲机 `ToolDecisionStore`,然后调用 `await controller.decide(toolCallId, 'approve')` 或者说 `await controller.decide(toolCallId, 'deny', reason)`。一个控制器在出现时使用它的活式对话,包括未保存的回合;否则它会加载已配置的聊天内存,保存后期的回合;所声称的快照只有在不存在当前对话时才是一种倒置. 它补补并坚持目标工具结果. 该模型仅针对目标助理消息中每个确认被决定时最新完成的助理消息恢复运行;工具结果按照调用顺序跟随他们的出处助理消息. 等待确认被保存到配置聊天存储器和决定库后,才能完成建议.

商店执行插入 - 如果缺席 `putPending`, (中文(简体) ), `get`原子 `claim` (待) 索赔,只将快照还给胜者) `settle` (维持相应的索赔最终结果). 存储记录必须活过进程重启,每个工具调用的方法必须可线性化. 书写之后同步读取的不是原子主张:使用数据库有条件的更新/交易或等同的比较和分页,包括跨进程. 使用申请授权的对话范围. 数据库索赔可以使用 `UPDATE ... WHERE status = 'pending' RETURNING ...`;核心船舶没有执行数据库.

同样的决定甚至在声称时也是一意孤行的:它们返回记录的结果,或者在执行时的原调,而不再引用工具或模型. 流式确认在 `onToolCall`。重启后,流化决定需要当前 `ChatMemory`:到达快照是不可改变的,可能会省略后期的来电;没有目前的谈话, `AK_CONFIG_INVALID` 拒绝一个不完整的流出快照后, 才会声称 。 活控制器不需要内存.

同上,只比较裁决的不合理性;一再拒绝和不同的理由保留了最初的理由和结果。 同决定终端重放返回记录 `ToolCall` 不引用工具或模型。 未知的ID 提升 `AK_ACTION_NOT_FOUND`;冲突的决定或不再待决的目标引起 `AK_ACTION_ALREADY_DECIDED`。工具失败是终端,并输入模型;重试需要新的建议ID。 索赔后的空难为应用程序调节留下了不确定的记录,从不自动重复试验副作用。 在对话中将不同的电话序列化,以保护笔录.

为了一个卡住 `claimed` 记录,操作员必须检查 `get(id)` 和域行刑证据, 停止原始工人, 并末期 `settle` 将索赔与经证明的结果或明确的不确定失败相匹配。 绝不删除或重置索赔待决。 在当前聊天内存中调试目标调用,然后明确继续使用新用户转接;任何经授权的重试都需要新的建议ID. 参见业务回收程序 [IDR 0042 (英语)](https://npmcn.com/package/docs/architecture/adrs/0042-durable-tool-decisions.md)。 。 。 .

`approve` 财务报告和审定财务报表 `deny` 已贬值。 有一家决定店 他们委托给 `decide` 并分享它的原子要求和打字错误;没有商店,它们保留了生成本地行为。 见 [IDR 0042 (英语)](https://npmcn.com/package/docs/architecture/adrs/0042-durable-tool-decisions.md)。 。 。 .

## 特征

-   `createChatController` ——有中止支持的流能聊天状态机;在成功转会后会保存内存,在失败或中止转会后永远不会保存. 背景记忆和技能激活失败通过 `onError`。 。 。 .
-   `createInMemoryMemory` — 原型化的零配置进程内存
-   `createLocalStorageMemory` – 浏览器/演示持续;存储的数据格式不当 `MemoryError` 而不是默默地成为空虚的历史
-   `createStaticRetriever` - 用于演示和倒置的确定符号重叠检索 `@agentskit/rag` 用于语义制作检索
-   `parseToolArgs` 键入 JSON 参数分析,用于需要故障闭塞验证的适配器; `safeParseArgs` 保留相容性帮助
-   `createId(prefix)` 前缀外加密码随机UUID; `generateId(prefix)` 保留用于信件和呼叫的相容性帮助
-   每个合同的脚本类型 : `ToolDefinition`, (中文(简体) ), `SkillDefinition`, (中文(简体) ), `AgentEvent`, (中文(简体) ), `Adapter`, (中文(简体) ), `ChatMemory`, (中文(简体) ), `Retriever`, (中文(简体) ), `ChatController`
-   事件发射器 `AgentEvent` 串流 – 随附的可观察钩
-   `AgentEvent.correlation` 是一个可选、提供者中立的身份信封: `operationId` 跨越边界稳定 `runId`, (中文(简体) ), `sessionId`, (中文(简体) ), `turnId`, (中文(简体) ), `actionId`,以及 `traceId` 保留本地含义
-   双 CJS/ ESM 输出, 严格类型脚本, 不 `any`
-   静电源护卫规则可从 `@agentskit/core/rules` 作为 `CORE_RULES`;它们用于工具,而非核心运行时间所导入.

## 处理错误

探员 装船a **教学错误系统** 由 Rust 编译器所启发. 每个错误都包含一个 `code`页:1 `hint` 给固定,和一个 `docsUrl` 不再含糊不清 `"Something went wrong"` 留言.

```ts
import {
  AgentsKitError,
  AdapterError,
  ToolError,
  MemoryError,
  ConfigError,
  ErrorCodes,
} from '@agentskit/core'

try {
  await runtime.run(task)
} catch (err) {
  if (err instanceof ToolError) {
    // err.code     → 'AK_TOOL_EXEC_FAILED'
    // err.hint     → actionable suggestion
    // err.docsUrl  → https://www.agentskit.io/docs/agents/tools
    console.error(err.toString())
    // error[AK_TOOL_EXEC_FAILED]: ...
    //   --> Hint: ...
    //   --> Docs: https://www.agentskit.io/docs/agents/tools
  }
}
```

可用错误代码( 通过 `ErrorCodes`:

| 代码 | 被丢弃 |
| --- | --- |
| `AK_ADAPTER_MISSING` | 未向控制器提供适配器 |
| `AK_ADAPTER_STREAM_FAILED` | 给提供者的串流呼叫失败 |
| `AK_TOOL_NOT_FOUND` | 请求的工具名称没有注册 |
| `AK_TOOL_EXEC_FAILED` | `execute()` 掷出 |
| `AK_TOOL_PEER_MISSING` | 未安装可选工具对等依赖 |
| `AK_TOOL_INVALID_INPUT` | 工具参数或建议无效 |
| `AK_TOOL_QUOTA_EXCEEDED` | 工具执行超过其配置的配额 |
| `AK_TOOL_FORBIDDEN` | 策略拒绝工具执行 |
| `AK_MEMORY_LOAD_FAILED` | 内存. load () 失败 |
| `AK_MEMORY_SAVE_FAILED` | 内存. save () 失败 |
| `AK_MEMORY_CLEAR_FAILED` | 内存. clear () 失败 |
| `AK_MEMORY_DESERIALIZE_FAILED` | 持续状态腐败 |
| `AK_MEMORY_PEER_MISSING` | 未安装可选内存后端 |
| `AK_MEMORY_REMOTE_HTTP` | 远程内存请求失败 |
| `AK_CONFIG_INVALID` | 缺少必要的配置或类型错误 |
| `AK_RUNTIME_INVALID_INPUT` | 运行时间输入无效 |
| `AK_RUNTIME_STEP_FAILED` | 运行时间步骤失败 |
| `AK_RUNTIME_DELEGATE_FAILED` | 代理执行失败 |
| `AK_SANDBOX_DENIED` | 沙盒政策拒绝执行 |
| `AK_SANDBOX_INVALID_TOOL` | 工具对沙盒无效 |
| `AK_SANDBOX_PEER_MISSING` | 未安装可选沙盒后端 |
| `AK_SANDBOX_BACKEND_FAILED` | 沙盒后端失败 |
| `AK_SKILL_INVALID` | 技能定义无效 |
| `AK_SKILL_DUPLICATE` | 技能身份被复制 |

## 类型安全工具 `defineTool`

`defineTool` 推断类型脚本类型 `execute`是因为 `args` 参数出自JSON Schema——没有手工铸造.

```ts
import { defineTool } from '@agentskit/core'

const greet = defineTool({
  name: 'greet',
  schema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  } as const,   // as const is required for inference
  execute(args) {
    // args.name → string  (inferred, not cast)
    return `Hello, ${args.name}!`
  },
})
```

使用 `InferSchemaType<typeof schema>` 引用代码库中其他部分的推断类型.

## 亚波斯出口(树干,零干重)

| 子路径 | 目的 |
| --- | --- |
| `@agentskit/core/agent-schema` | 声明YAML/JSON代理定义+验证符 |
| `@agentskit/core/prompt-experiments` | A/B 有 PostHog / GrowthBook / 自定义旗下提供者的提示 |
| `@agentskit/core/auto-summarize` | `ChatMemory` 折叠旧的包装会变成摘要 |
| `@agentskit/core/hitl` | 核准大门+ `ApprovalStore` |
| `@agentskit/core/security` | PII和秘密编辑+注射检测器+限速器 |
| `@agentskit/core/fuzzy-match` | 确定 Jaro- Winkler 匹配 KYC、 制裁、 调试和实体解析 |
| `@agentskit/core/finding` | 光学 `Finding` 编号 : `Severity` 用于审查和遵守结果的形状 |
| `@agentskit/core/compose-tool` | 链入一个宏工具的 N 工具 |
| `@agentskit/core/self-debug` | 用 LLM 修正参数重试失败的工具 |
| `@agentskit/core/generative-ui` | 已打入UI元素树 + 代码 / 标记下 / html / 图表文物 |
| `@agentskit/core/a2a` | 代理对代理协议规格(JSON-RPC,任何运输) |
| `@agentskit/core/manifest` | Skill + 工具显示格式( MCP 兼容) |
| `@agentskit/core/eval-format` | 便携式 eval 数据集 + 运行结果 JSON |
| `@agentskit/core/memory-validation` | 未经信任的序列式内存记录的验证 |
| `@agentskit/core/tool-proposal` | 通过控制器授权为已验证的建议书路由提供公共帮助 |
| `@agentskit/core/hash` | RFC 8785 Canonic JSON和SHA-256助手 |

见 [代理人核心指南](https://www.agentskit.io/docs/for-agents/core) 整个合同.

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 适应器](https://www.npmjs.com/package/@agentskit/adapters) | LLM 聊天+ 嵌入提供者、 路由器、 综艺、 倒置 |
| [@ agentskit/ 运行时间](https://www.npmjs.com/package/@agentskit/runtime) | `createRuntime`, (中文(简体) ), `speculate`、地形、耐用处决、背景代理 |
| [@ agentskit/ 反应](https://www.npmjs.com/package/@agentskit/react) | `useChat`无头聊天组件 |
| [@ agentskit/ veue (帮助)](https://www.npmjs.com/package/@agentskit/vue) • 妇女 [丝绒](https://www.npmjs.com/package/@agentskit/svelte) • 妇女 [固态](https://www.npmjs.com/package/@agentskit/solid) • 妇女 [反应-内在](https://www.npmjs.com/package/@agentskit/react-native) • 妇女 [角线](https://www.npmjs.com/package/@agentskit/angular) | 一样 `ChatReturn` 合同,每个框架一个包 |
| [@ agentskit/ 工具](https://www.npmjs.com/package/@agentskit/tools) | 内建工具,20+集成,MCP桥 |
| [@ agentskit/ 记忆](https://www.npmjs.com/package/@agentskit/memory) | 聊天+矢量+分级+加密+图表存储 |
| [@ agentskit/ 擦伤](https://www.npmjs.com/package/@agentskit/rag) | 插座和游戏 RAG + 后排 + 加载器 |
| [@ agentskit/ 技能](https://www.npmjs.com/package/@agentskit/skills) | 预备人员+市场 |
| [@ agentskit/ 可观察性](https://www.npmjs.com/package/@agentskit/observability) | 追踪、审计记录、费用保障、支架 |
| [@ agentskit/ sandbox (英语)](https://www.npmjs.com/package/@agentskit/sandbox) | 安全代码执行+强制沙盒政策 |
| [@ agentskit/ eval (英语)](https://www.npmjs.com/package/@agentskit/eval) | Eval套房,定型重播,快照,CI记者 |
| [@ agentskit/ cli (英语)](https://www.npmjs.com/package/@agentskit/cli) | `agentskit init / chat / run / ai / dev / doctor` |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **稳定** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/core`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @agentskit/core 是什么？

可移动代理 Kit 运行时间用于聊天管弦乐,工具,内存和检索\.

### 如何安装 @agentskit/core？

在项目目录运行 npm install @agentskit/core，或使用 pnpm add / yarn add / bun add。

### @agentskit/core 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @agentskit/core 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @agentskit/core 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @agentskit/core 可以商用吗？

@agentskit/core 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @agentskit/core 的下载量有多少？

根据 npm 官方下载统计，@agentskit/core 在 2026/10/05 – 2026/11/03 这 30 天内被下载 37,669 次，日均约 1,256 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @agentskit/core 还在维护吗？

最新版本 1\.15\.0 发布于 2026/10/10（26 天前）；至今共发布 36 个版本，其中过去 12 个月发布了 36 个；首次发布于 2026/04/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。