# @agentium/core 中文文档

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

版本：4\.11\.0
npm 元数据更新时间：2026-10-23T22:18:42.391Z
中文译文更新时间：2026-11-06T18:15:27.349Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentium/core
原文对照：https://npmcn.com/package/%40agentium/core/?lang=original
项目主页：https://agentium.in/
源码仓库：https://github.com/agentiumOS/agentium

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

- 包体积（解压后）：4.4 MB，971 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^22\.18\.0 \|\| ^24\.11\.0
- 运行依赖：2 个
- peer 依赖：pg ^8\.0\.0，ollama ^0\.5\.0 \|\| ^0\.6\.0，openai ^4\.0\.0 \|\| ^5\.0\.0 \|\| ^6\.0\.0 \|\| ^7\.0\.0，stripe \>=14\.0\.0，ioredis \>=5\.0\.0，mongodb ^6\.0\.0，cohere-ai \>=7\.0\.0，dockerode \>=4\.0\.0，pdf-parse ^2\.4\.5，discord\.js \>=14\.0\.0，googleapis \>=100\.0\.0，@a2a-js/sdk ^1\.3\.0，@daytona/sdk ~0\.220\.0，neo4j-driver \>=5\.0\.0，@google/genai \>=0\.10\.0 \<3，gpt-tokenizer \>=3\.0\.0，better-sqlite3 ^11\.0\.0，@typesafe-ai/sdk \>=0\.6\.0，@anthropic-ai/sdk \>=0\.30\.0 \<1，@aws-sdk/client-s3 \>=3\.0\.0，@e2b/code-interpreter ~2\.8\.0，@qdrant/js-client-rest ^1\.0\.0，@huggingface/transformers ^4\.3\.0，@modelcontextprotocol/sdk ^1\.27\.1，@modelcontextprotocol/client ^2\.3\.0，@perplexity-ai/perplexity\_ai \>=0\.20\.0，@aws-sdk/s3-request-presigner \>=3\.0\.0
- 首次发布：2026-05-22T13:04:25.721Z
- 最新版本发布：2026-10-23T22:18:42.193Z
- 近 30 天下载量：2497（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

以工具、内存和多模式支持构建人工智能代理的核心框架

## 安装

```sh
npm install @agentium/core
```

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

## README

# @ agentium/ 核心

以工具,内存,多模型支持等方式构建AI代理的核心框架等.

## 安装

```bash
npm install @agentium/core
```

## 快速启动

```typescript
import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-4o"),
  instructions: "You are a helpful assistant.",
});

const result = await agent.run("Hello!");
console.log(result.text);
```

## 特征

-   **多模式** — OpenAI, Anthropic, Google, Ollama, Vertex AI (英语)
-   **工具** ——用Zod schemas,沙箱执行,审批工作流程,严格模式定义工具
-   **30+内置工具包** ——计算器 GitHub, Slack, Jira, Notion, SQL等. 从 `@agentium/core/toolkits` (或 `@agentium/core/toolkits/github`这样 `import { Agent }` 并没有拉动每一个整合. `toolkitCatalog` 住在同一个入口.
-   **自动发现** - 代理人、团队和工作流程自动登记为全球 `Registry`; 运输层动态地发现它们
-   **内存** ——具有摘要,用户事实,实体内存的统一内存系统
-   **团队和工作流程** ——多方代理协调与交割
-   **流线** ——一等流支支持
-   **护栏** - 投入/产出验证
-   **费用追踪** 预算支出和成本监测
-   **语义缓存** - 基于病媒的反应缓冲

## 代理和支配所有权

`new Agent(...)` 配置核心代理执行:模型,工具,消息和明确要求的服务. 可选 [`@agentium/harness`](https://npmcn.com/package/%40agentium/harness/README.md) 软件包拥有定义、能力、组成、运行时间、控制器、上下文/完成政策、驱动程序及其资源生命周期。 核心不依赖这个包.

使用 `HarnessRuntime({ definition, driver: agentDriver(config), ... })` 或者通过一个已经配置好的特工来借钱 特定代理定义默认仅适用于配置表. 核心的中立性 `ExecutionServices` 港口供应模式/工具操作、授权、取消和自有工作;其中没有说明、控制器或清单。 应用程序调用者通常让司机提供该端口.

`Agent.deep()`, (中文(简体) ), `AgentConfig.harness`, (中文(简体) ), `harnessOptions`, (中文(简体) ), `replaceTools` 财务报告和审定财务报表 `harnessDescription` 在4.0.0中被删除。 明确的工作空间配置要求 `{path, mode: "read" | "write"}`。普通代理选项仍然可用 [移徙指南](https://npmcn.com/package/%40agentium/harness/README.md) 显示已删除的深预设行为作为明确的选择。 存储的对话阅读器和公用Zod 3工具计划仍然得到支持.

借款的审批调度员在代理关闭时保持营业. `Agent.close({closeStorage:false})` 释放 代理拥有的资源,同时将一个供应的存储客户端留给了它的宿主;被支配拥有的代理驱动程序使用这个模式. 普通类 `close()` 仍然关闭已配置的内存存储, 在自有内存工作结算后 。 它拒绝繁忙的代理 而不是取消被承认的工作 并等待最多30秒的内存 默认。 超时或被取消的排水管会让存储打开并运行入室关闭;一旦工作结束就重新试闭. 见 [可靠性指南](https://github.com/agentiumOS/agentium/blob/main/packages/harness/DEPENDABILITY.md) 用于键入错误、取消和三个收养路径.

对于新的共享商店, 配置清晰 `tuple-v1` 范围/ Redis 密钥编码。 现有持久储存保留遗留的缺省,需要迁移宿主;见 [存储身份和迁移](https://npmcn.com/package/%40agentium/core/src/storage/README.md)。工作流程严格结合,失败政策和版本约束的续作在 [工作流程合同](https://npmcn.com/package/%40agentium/core/src/workflow/README.md)。 。 。 .

## 执行政策和核准

`AgentConfig.executionPolicy` 是 Zod 验证调用上的一个强制主机边界 。 内容 `decide(call, ctx)` 返回时 `{ action: "allow" | "ask" | "deny", reason?: string }`继承的政策和执行者的地方政策都适用;一个工具不能推翻否定。 授权也在缓存命中和结果转换前运行.

```typescript
const agent = new Agent({
  name: "workspace-assistant",
  model: openai("gpt-4o"),
  workspace: { path: "./project", mode: "read" },
  approval: { policy: "none" }, // Dispatcher for explicit tool/policy requests.
  executionPolicy: {
    decide: (call) => ({ action: call.toolName.startsWith("fs_") ? "allow" : "ask" }),
    resolveEffect: (call) =>
      ["fs_read_file", "fs_list_directory", "fs_file_info"].includes(call.toolName) ? "read" : "unknown",
  },
});
await agent.run("Inspect the project", { sessionId: "review", runMode: "plan" });
```

使用主机拥有的效果解析器;模型参数和MCP说明不是分类权限. 不可改变 `runMode: "plan"` 许可证分类读取,否认书面/执行/外部效果,并需要批准未知效果。 它不会在工具内任意使用沙盒 JavaScript 。 分类工具的整个执行过程,包括其结果变压器.

明确 `requiresApproval: true` (或真正的上游),或政策 `ask`,但当没有配置批准服务时,现在无法关闭。 遗产 `requiresApproval: false` 仍然将一个工具排除在遗留的核准政策之外 `executionPolicy` 强制规则。 核准观察员或执行前钩所改变的论点必须通过新的援引再次授权.

马厩 `agent.approvalManager` 外观到达待运行,流和动态添加的工具请求. 使用 `approve(requestId)`, (中文(简体) ), `deny(requestId)`,以及 `listPending({ tenantId, userId, sessionId, runId })`; 范围字段是可选过滤器。 申请在登记前 `tool.approval.request` 火,所以同步的决定是有效的。 未过滤访问是给信任的主机的 。 单独需要托管所有权授权;参见运输RADEME. 取消和代理关闭未决请求.

`VoiceAgent` 接受 `approval`, (中文(简体) ), `approvalManager`,以及 `executionPolicy`;技能工具使用相同的调度器. `connect` 接受 `tenantId`, (中文(简体) ), `signal`,以及 `runMode`。待决工具在中断、取消或会话关闭时被撤销。 此边界覆盖了本地工具Defs;提供商-本地MCP/工具在其外.

工作空间路径需要明确 `{ path, mode: "read" | "write" }` 配置 。 使用读取模式来省略工作空间写工具 。 canonical checks 拒绝外部/正在连接的连锁,包括连接父母的新路径;内部链接工作. 覆盖使用同名目录的临时文件并重命名 。 附录不是交易式的,而Cononical路径检查并不能防止敌对的并发文件系统替换. 这些保证适用于文件系统工具包,而不是 shell 命令或任意自定义工具.

## 明确的工作空间执行和云沙箱

`SandboxAgent({backend: "unix-local"})` 在拥有的临时工作空间中执行主机上信任的程序。 这不是安全边界。 未执行 `"docker"` 选择器和 `dockerImage` 选项被删除; Stale JavaScript Docker 配置在文件系统或进程 I/O 之前拒绝。使用 `backend: "remote"` 带有用于远程执行的已配置的云适配器。 本地文件帮助者验证路径和已存在的祖先,但不能限制任意的 shell 代码或防御敌对的并发文件系统替换.

本地执行通过解释器参数通过代码,限制所捕获的输出,支持取消,并等待其进程组所继承的输出管结算. 只有路径, 明确 `inheritEnv` 名称、工作空间变量和每个呼叫变量进入儿童环境。 打电话 `start()` 使用前和 `close()` 释放自有的工作空间。 见 [沙盒合同和移民指南](https://npmcn.com/package/%40agentium/core/src/sandbox/README.md) 用于快照、远程所有权、取消限额和精确的SDK验证.

E2B 使用可选 `@e2b/code-interpreter ~2.8.0`;代托纳使用可选 `@daytona/sdk ~0.220.0`。旧的猜测 `@e2b/sdk` 财务报告和审定财务报表 `@daytonaio/sdk` 路径不再被装入 。 SDKs初用后加载. 当前适配器通过已安装的SDK和本地响应进行验证;活账户执行需要单独的操作员授权和清理验证.

## 提供者的延续和历史

答复助理信息带有版本 `providerExtras.responsesReplay` 包含命令输出项和端点/模型所有权的信封。 不透明推理仍与显示文本相分离. 通过持续的内存和倒置会话生成并流保留工具调用,匹配结果,以及非工具推理. `RunOutput.text` 显示输出; `RunOutput.messages` 和存储的会话信息是犬科记录,包括反射修正. 请求收缩不会覆盖该笔录.

仅保存文本的会话仍然可以读取;缺失的历史推理无法重建. 存储 v3.2.0 `responsesReasoning` 仅为 OpenAI 正式终点接受。 新的信封拒绝不相容的端点/模型,响应续作不能默默地降级为Chat补全. 切换提供者需要一个新的会话或由主机执行明确的转换; Anthropic/Gemini适配器拒绝外国不透明续作.

只有在第一个公共溪流块之前才允许回落。 文字,思维,工具开始,完成元数据,每个都承诺尝试. 承诺后的错误传播而不附加另一个提供者的输出 。 初始参数片段被保留;格式错误,被中断,或未完成的工具流执行不了不完整的工具.

Concession保留了所有工具回合和供应商外加的全用户回合. 最新转折保持不变;一个不可分割的转折超过压缩器预算 `ContextCompactionError`. 摘要是历史的助手数据,从来不是常备系统指令. 会议 `maxMessages`/历史极限是整个转弯的软极限:最新的转弯可以超过. 模型输入令牌修剪可以掉出整个更古老的转折,但不能分割出其工具交换.

后退固定装置覆盖被命令的回放生成/流回放,官方和自定义的端点所有权,遗留外加,初始的Chat补全参数,Anthropic/Gemini回放,实际的双回转代理持续,和剪切/摘要/hybrid收缩. 测试使用合成SDK形状的响应,而不是现场提供者证书;测试不认证每个模型或相容的终点. 现有单位 `providerOptions` 继续支持.

## 文档

完整文件时间 [参考文献. agentium.in](https://docs.agentium.in/)

## 社区

加入对话 [解析器](https://discord.gg/T86SJshP)。 。 。 .

## 许可证

麻省理工学院

### 递增会话快照

`IncrementalSessionManager` 读取遗留数组快照并写入 `{ messages, nextSeq }` 示意图. 序列水印防止了如果松开的条目清理失败而重复播放,会话扫描将共享前缀的ID隔离出. 在与更古老的 Agentium 版本共享此存储之前, 更新每个读者/ 作者; 更古老的版本无法读取新的快照形状 。 操作序列化在一个管理器实例中;共享多进程存储仍然需要主机协调,在部分存储失败后一个被拒绝的附件可能一直存在数据.

### 经核实的本地重排

可选的跨编码器加载器被用变形器进行.js **4.3.0 (单位:千美元)**,节点CPU推论,预装 `Xenova/ms-marco-MiniLM-L-6-v2` 修订文物 `a09144355adeed5f58c8ed011d209bf8ee5a1fec`, (中文(简体) ), **数字 8** ONNX精度. 集成测试验证关联性命令和缺失艺术故障. 它是一种相容性固定,而不是跨语言/域或GPU设备的基准.

已安装了可选的 SDK 并可以兼容的重量 :

```sh
AGENTIUM_TRANSFORMERS_MODEL=/absolute/path/to/model \
AGENTIUM_TRANSFORMERS_DTYPE=q8 \
npx vitest run packages/core/src/rerank/__tests__/cross-encoder-reranker.test.ts
```

默认测试跳过此门 。 推论保留 `localFilesOnly: true`;测试不下载模型. 选择与预装的 ONNX 文件名相匹配的精确度( S)`fp32` 是未指定精确度时的固定默认值。 习惯 `pipelineFactory` 拥有替代设备/艺术行为;这些设备需要自己的认证.

### 渐进快照推出

新的递增会话读者既接受遗留信件阵列,也接受 `{messages,nextSeq}` 示意图. 后者防止在写出快照后清理失败时重复播放. 升级 **所有读者** 在允许新的快照写器之前,在修改持续格式之前保留存储备份。 要回滚,排出写作员,并恢复从备份中组合起来的旧读取相容的快照/ Lose-message;不要简单地取出 `messages` 并留下重叠的条目.

运行 `npx vitest run packages/core/src/session/__tests__/incremental-session.test.ts` 包括遗产、水印和清理失败 这不为通用会话/admin商店提供跨进程锁定:主机必须串行写作机或选择一个CAS能力适配器. 范围存储取名空间和由经认证的租户/演员保留,包括本地语音记忆. 持久任务存储是一个单独的选入API,不会改变通用会话-存储的货币语义.

### 可选资源、移交、呼叫和恢复

-   调用 MCP 上下文 [`mcpResources`](https://npmcn.com/package/%40agentium/harness/README.md#approved-mcp-resources),明确URI/MIME赠款和主机授权.
-   [`Agent.stream` 移交](https://npmcn.com/package/%40agentium/core/src/handoff/README.md) 懒散地跟踪目标代理商,同时保留有条不紊的信息、确定的工具结果、政策和取消。 控制在操纵下的暗中代理交接仍然受到注意;行刑司机在拥有会议和能力时必须拥有自己的代表团.
-   [`@agentium/core/telephony`](https://npmcn.com/package/%40agentium/core/src/telephony/README.md) 供货商中性呼叫意图和可选的Twilio、Telnyx、Exotel、SignalWire、Vonage和LiveKit SIP适配器。 HTTP提供商使用取取端口;LiveKit使用结构主机SDK客户端. 不需要电话 SDK来导入核心 .
-   [现场复原](https://npmcn.com/package/%40agentium/core/src/voice/README.md) 选择进入。 双子座使用安全会话控件;OpenAI支持一个明确的空会话倒置. 不确定的工具效应需要调节. 恢复从不重放输入,工具动作或语音.

### Zod 3和 Zod 4 计划

`defineTool`, (中文(简体) ), `defineAsyncTool`, (中文(简体) ), `ToolDef.parameters` 财务报告和审定财务报表 `AgentConfig.structuredOutput` 接受独立的Zod 3,目前的Zod 4 Classic和Zod 4 Mini. 辩证推论和运行时间验证得到保留. 内用Zod 4.6并稳定 `zod/v3` 用于现有内部计划; 应用程序可以保持自己的Zod 3依赖性.

使用 `parseSchema(schema, value)`, (中文(简体) ), `safeParseSchema(schema, value)` 财务报告和审定财务报表 `schemaShape(tool.parameters)` 当检查任意的公共计划。 拓宽 `ToolDef.parameters` 结合包括Mini的核心合同,所以消费者应该取代直接 `.parameters.safeParse()` 或者说 `.parameters.shape` 使用这些帮助. `convertJsonSchema` 保留输入形状转换,并报告运行时间仅限转换/精炼;JSON Schema无法执行可执行验证功能. 成套装置核实无害环境管理/共同JS消费者中的实际Zod 3.25.76和4.6.5.

## OpenAI 决定(4.1+)

安装 `openai@^7.30.0` 设置 `OPENAI_API_KEY`启用 `openaiDecisions()` 用于打入的分类、条件概率和分数.

```typescript
import { Agent, openaiDecisions } from "@agentium/core";

const agent = new Agent({ name: "triage", model: openaiDecisions() });
try {
  const result = await agent.run("I was charged twice.", {
    questions: [{ type: "predicate", name: "billing", instructions: "Does this concern billing?" }],
  });
  console.log(result.decisions);
} finally {
  await agent.close();
}
```

默认模式是 `gpt-6-luna`。运行的问题数组取代了构造器默认值。 答案可以包括个别拒绝;分数可以是分数. `stream()` 发射完成 JSON ,然后是包含 `decisions`. 对话角色和组合函数调用历史作为证据保留。 用户信息接受文本和内含或主机图像. 多达400个问题可以包括文本和图像指示;完整的请求最多可以包含128个图像. 工具定义,任意输出计划,聊天采样选项,语义缓存仍然不支持.

本地输入的API在4.11.0. 现有代理电话仍在使用 `ChatMessage`; 构造 `OpenAIDecisionsProvider` 和使用情况 `evaluate()` 为结构化的JSON或自定义工具历史. 登记册支持 `openaiDecisions()` 工厂保留其通用 `ModelProvider` 返回类型.

```typescript
import { OpenAIDecisionsProvider, type DecisionInputItem } from "@agentium/core";

const provider = new OpenAIDecisionsProvider("gpt-6-luna", {
  questions: [{ type: "predicate", name: "duplicate", instructions: "Are there duplicate charges?" }],
});
const input: DecisionInputItem[] = [{
  role: "user",
  content: [{ type: "input_json", data: { charges: [49, 49] } }],
}];
const result = await provider.evaluate(input);
console.log(result.decisions);
```

原生的JSON接受对象或对象阵列,内部有有限的JSON值. 无效的角色,不支持的介质,循环数据,和无法匹配的工具输出在传输前失败. 适配器使用文档中的通用请求方法 `openai@7.30.0`因此不需要SDK升级。 构造器缓存默认值和每次调用 `promptCacheKey` 编号 : `promptCacheOptions: { mode: "explicit" }` 控制快速缓存。 无标记部件的清晰模式会禁用缓存;语义缓存仍然分开. 直接提供者调用回用,但不创建代理会计尝试.

决定使用量记录在自己的API和实际计费上。 区域、背景和账户条件必须与目录规则相匹配;缺失的条件仍然没有价格。 见 [决定指南](https://docs.agentium.in/models/openai-decisions)。 。 。 .

## 双子座( 4. 11+)

使用 `google("gemini-4-argon")` 与 `@google/genai@2.27.0` 或以后用于现有的单请求生成和流出路径。 作出合理努力 `low`, (中文(简体) ), `medium`,以及 `high` 映射到提供者的水平; `xhigh` 财务报告和审定财务报表 `max` 使用情况 `HIGH`. 保留提供者默认的 Omit 推理。 Argon拒绝残疾推理, `none` 编号 : `minimal`,以符号为基础的思维预算,明确的缓存内容资源,以及超过65,536个产出限额. 较小的呼叫器限制和超时被保留. 为Argon省略了抽样值.

长解码续作在此适配器中未被执行. 如果 Google 返回续作标记, 调用失败 `ModelUsageError` 使用现有方法,而不是报告已完成的答复或发出另一项请求。 在该错误为临时错误之前已流出文本 。 原生的函数调用ID,思想签名,和返回的模型身份在工具历史和核算中幸存. 现有的双子座2.5和3控制保持他们的行为.

## 使用和成本核算

成本核算留在 `@agentium/core`启用一次 `cost: true`. 核心记录可观察到的提供者呼叫、辅助模型工作、复试和倒叶。 父摘要不添加其他收费 .

```typescript
import { Agent, openai } from "@agentium/core";

const agent = new Agent({
  name: "assistant",
  model: openai("gpt-6.1-sol"),
  cost: true,
});
const result = await agent.run("Summarize this request");
console.log(result.costs); // Snapshot for this run and its child work.
await agent.close(); // Drain owned accounting when the application stops using this agent.
```

没有每个运行的冲出或查询步骤 . `result.costs.status === "available"` 表示分类账被读取. 这并不意味着每个收费都有价格. `total` 当所有需要的电荷已知时为小数字符串,并且 `null` 当用法、费率或计费条件缺失时. `knownSubtotal` 包含定价部分。 读取失败返回 `status: "unavailable"` 两个数额 `null`输出 `accounting.error`。模型结果保存.

报告包括: `asOf` 财务报告和审定财务报表 `finality`;正在进行的儿童工作可以暂时留下一个快照。 最后的代理流结束 也包括 `costs`。取消事件包括可用的快照. `Team` 财务报告和审定财务报表 `Workflow` 支持同样的 `cost` 选项。 默认情况下,除非父母运行提供,否则会计将被禁用. `cost: false` 不绕过父母的预算.

使用 `cost: { catalog, budget, store }` 以配置会计,或通过已有的 `costTracker` 共享一个分类账。 一次配置一个选项 。 代理人近距离排出其拥有的跟踪器;它不冲出或关闭所借的跟踪器或关闭呼叫器拥有的商店. 默认商店是本地记忆. `SqliteUsageStore(path)` 财务报告和审定财务报表 `PostgresUsageStore(connectionString)` 支持持久存储并需要可选 `better-sqlite3` 或者说 `pg` 软件包。 高级报告和原始证据通过 `CostTracker.queryCosts()` 财务报告和审定财务报表 `queryUsage()`。 。 。 .

`billingContext` 代理主型号呼叫的可靠帐号 例如,使用 `billingContext: { actualServiceTier: "standard", region: "global" }` 只有这些符合账户合同。 它不改变提供者的请求或选择服务级别。 响应事实覆盖已配置的默认 。 失踪的事实没有价格.

### 输入、输出和缓存符号

分类输入包括普通输入,缓存读取,和缓存写取. 输出包括推理符. 理性是产出的一个细节;不要再加. 原始供应商的使用与正常数量分开保留.

下列费率为: **合成试验率**,单位:百万令牌:

| 充电 | 键 | 费率 | 费用 |
| --- | --- | --- | --: |
| 普通输入 | 1 000个 | 10个 | 0.010 (简体中文) |
| 快取已读取 | 12 000个 | 1个 | 0.012 (简体中文) |
| 快取写入 | 2 000个 | 12.5 (中文(简体) ) | 0.025号 |
| 产出,包括100个推理符号 | 500个 | 第50条 | 0.025号 |
| 共计 | 15 500美元 |  | 0.072 (单位:千美元) |

如果写率少了, `total` 实值 `null` 财务报告和审定财务报表 `knownSubtotal` 实值 `"0.047"`。缓存- write TTL 分区写出符;总数及其桶不能同时收费。 缺少的模式/缓存相交点也一直不明.

### 价格规则和预算

提供版本 `PricingCatalog` (c) 确定利率或适用账户合同。 规则与实际提供者,计费者,模型,API,日期相匹配,并需要计费维度. 他们可以定价符号,请求,图像,人物,持续时间,以及定制单位. 固定收费,上下文带,缓存TTL,明确调整,计费组四舍五入使用相同的充电引擎. 每笔收费都保留其规则和速率快照.

单独存储请求和返回的服务级别 。 使用返回的等级来记录快降级。 Pro模式并不意味着通用乘数;其报告的用法计算一次. 缺失的计费条件会产生出价不高的物品.

```typescript
import { CostTracker } from "@agentium/core";

const costs = new CostTracker({
  budget: {
    mode: "threshold",
    onExceeded: "warn",
    onUnknown: "warn",
    limits: [{
      scope: "session", amount: "2", currency: "USD",
      period: { start: "2026-10-01T00:00:00Z", end: "2026-11-01T00:00:00Z" },
    }],
  },
});
```

阈值检查在接受的工作运行时可以超标. 警告模式继续 。 零限为正限. 保留模式需要一个原子核算库和一个保守约束。 它不能担保供应商发票。 没有可靠运输证据的SDK重试贴有标签 `opaque`。失败、取消或错误的反应仍然可以使用;核心保留了这种证据.

流用在运输关闭前被保存. 已更改的累积快照取代了以前的快取. 自定义适配器可以用 `usageObservation: { kind: "delta", id, sequence }`; 使用稳定事件ID和序列,所以重放三角洲计数一次. 观察暂时停留,直到运输结束。 预算检查是在每次新的使用情况观察之后进行的. `Team` 财务报告和审定财务报表 `Workflow` 将会计范围扩大到童工.

成功提供者调用发送后会计写出失败 `accounting.error`它不重试提供者. `flush()` 以原始身份重写会计笔记. `usage.recorded`, (中文(简体) ), `cost.assessed`,以及 `budget.checked` 暴露犬科状态. 遗产 `cost.tracked` 事件仍然是替换运行总计。 不将其值添加到 `cost.assessed` 金额.

遗产同步 `checkBudget(runId)`, (中文(简体) ), `checkInProgressBudget`, (中文(简体) ), `isBudgetExceeded` 财务报告和审定财务报表 `estimateRemaining` 拒绝 `IncompleteCostError` 在采用犬科会计之后,包括观察用途完成之后。 当地展出窗口遭拆迁时, 使用同步的条块预算检查和 `queryCosts()` 长期会计决策.

### 支付聊天以外的业务

使用 `meteredOperation` 用于自定义付费工具或适配器。 供应a `BillingContext`,抓取一个 `NormalizedUsage` 在输出解析之前,返回通常的应用结果。 供应 `accounting: { tracker, tenantId, runId, ... }` 明确在特工行动之外 在跑道内,Aync上下文携带了范围. 工具的过期时间或文本长度无法确定其账单.

| 内建路径 | 获取的证据 | 当前限制 |
| --- | --- | --- |
| OpenAI 嵌入 | 提供者输入令牌 | SDK 重试不透明; 自定义网关需要收费 |
| 谷歌嵌入 | 供应商使用元数据 | 多式联运数量仍为部分数量 |
| 重新排队 | 计费搜索单位 | SDK 重试不透明 |
| Jina和Voyage重新排队 | HTTP 尝试中提供方令牌 | 用户缺失情况不详 |
| OpenAI 图像 | 返回图像计数、 原始符号使用、 大小、 质量 | 图像/托盘计费仍为部分 |
| OpenAI 实时 | 响应ID、状态、原始缓存和模式使用 | 模式价格和自动周转预算仍为部分 |
| 谷歌实况 | Raw Live 使用元数据 | 模式和事件汇总仍为部分 |
| 语音适配器 | 可用字符或持续时间测量 | 供应商开单合同仍为部分 |
| 文件复制和语音管道 | Raw STT 使用,模型使用,测量 TTS 字符 | 语音定价合同仍为部分 |
| 其他付费工具包 | 明显未达到 | 使用带有计费证据的自定义操作 |

`BUILTIN_ACCOUNTING_CAPABILITIES` 列出单个工具包的覆盖范围。 本地嵌入,本地重排,和计算工作并不意味着应用程序基础设施是免费的. 未来供货商字段或无凭证的账户合同没有保证适配器的准确定价.

### 从旧追踪器迁移

使用 `recordUsage`, (中文(简体) ), `queryUsage`, (中文(简体) ), `queryCosts`,以及 `flush` 用于犬科会计. `track()` 财务报告和审定财务报表 `getSummary()` 继续同步兼容 API。 它们不是持久的分类账查询。 遗产平面符号数据需要明确的包容性使用合同;不完整的遗产定价会引起打字错误。 配置 `legacyUsageSemantics: "inclusive"` 仅当输入/缓存/输出定义为已知时。 删除缺失价格意味着零的假设,或者必须在产出中添加推理.

## 公共传播(4.6)

`RunOutput.publicMessages` 分离 `commentary`, (中文(简体) ), `final`,以及 `reasoning_summary` 带有稳定身份证明的物品。 这个 `run.message` 事件Bus 有效载荷 包含 `{ runId, messageEvent }`;其事件是: `message.started`, (中文(简体) ), `message.delta`, (中文(简体) ), `message.completed`,以及 `message.failed`. 待流 选项不是最后答案。 对于生命周期块在内 `Agent.stream()`选择 输入 `{ publicMessageEvents: true }`。最后的完成块将保持使用和 成本核算。 现有的文本和思维渠道仍然兼容.

使用 `getCommunicationCapabilities(provider)` 检查原生/受孕阶段 以及支持/不支持/有条件的简要支持。 仅使用公开摘要 文档提供者摘要字段; 原始思维和不透明提供者 不显示摘要。 见 [对话运行向导](https://npmcn.com/package/%40agentium/harness/CONVERSATIONAL-RUNS.md) 用于现场提问,引导, 和完成的工具轮式收缩 通过绳索.

### 主机控制型号请求

OpenAI 和 Anthropic 构造器以及 `openai()`编号 :`anthropic()` 工厂接受 `maxRetries` (Agentium,默认 2), `sdkMaxRetries` ( 保留 SDK 默认), `timeoutMs` (SDK 请求超时),和 `callTimeoutMs` (整个逻辑 电话,包括重试等待和溪流消耗)。 要让主机自己重试 :

```ts
import { openai } from "@agentium/core";

const model = openai("your-model", {
  apiKey: process.env.OPENAI_API_KEY,
  maxRetries: 0,
  sdkMaxRetries: 0,
  timeoutMs: 30_000,
  callTimeoutMs: 90_000,
  endpoint: "responses",
  fallback: "error",
});
const response = await model.generate([{ role: "user", content: "Hello" }], {
  signal: controller.signal,
  deadline: Date.now() + 60_000,
  maxTokens: 2_000,
});
```

最早的呼叫者取消、施工/呼叫暂停或绝对截止日期 赢了 调用器中止原因被保留; 逻辑期限丢弃 `ModelDeadlineError`. SDK 请求超时可以重试,而逻辑 最后期限/取消为终端。 等待的听众和计时者被释放. 流流只在 SDK 请求建立时重试, 流后从不重试 迭接开始, 即使只有提供者元数据到达 。 SDK 超时细节 是 SDK 版本依赖的; 使用逻辑的截止日期绑定全流 .

还有一个代理级重试包 调用控制代理现在默认 包装为零; 明确 `Agent({ retry: { maxRetries: ... } })` 选择 中。独立代理保存其先前的默认值,所以设置 `retry: { maxRetries: 0 }` 在那里,当主机有 重试。 型号 `maxRetries` 财务报告和审定财务报表 `sdkMaxRetries` 继续脱离代理设置.

会计将逻辑操作与其观察到的SDK引用区分开来. `attemptVisibility` 实值 `physical` 仅使用 `sdkMaxRetries: 0`;否则 `opaque`. SDK-内部重试不能被 Agentium 准确计算. 节奏 模型调用预算和模型遥测计数逻辑调用,而不是HTTP尝试. `ModelUsageError` 暴露于未能恢复正常状态或 完成验证; 利用保留调节这些证据.

`OpenAIConfig.endpoint` 接受 `auto` (违约), `responses` (必需),或 `chat_completions`。 。 。 . `fallback` 接受 `compatible` (违约)或 `error`。 。 。 . 如果 Chat 补全会禁用, 无法获取的响应结束点现在失败 推理, 丢失提供者重放, 或放弃只响应推理/ 缓存选项 . 要求回应永远不会退缩。 明确聊天完成也验证 运输前的相容性。 这故意取代先前的沉默 在一些模型/工具组合上推理降级.

`ModelCapabilities` 是由主机提供的接口,独立于任何登记册: `contextWindow`, (中文(简体) ), `maxOutputTokens`, (中文(简体) ), `tools`, (中文(简体) ), `reasoningEfforts`, (中文(简体) ), `reasoningModes`, (中文(简体) ), 财务报告和审定财务报表 `historyEviction`供应 `capabilities` 改为适配器或可选 `unknownCapabilities: "error"`;默认允许未知字段。 严格模式 要求上下文/产出对明确要求的特征限制事实和事实. 已知输出限制也省略了适配器输出默认值. `validateModelRequest()` 曝光其他适配器相同的飞行前检查. 配置的不相容性在运输前失败 。 背景大小是一个估计 除非主办方提供权威的表示器/捆绑;提供方执行 是权威的。 能力不会改变提供者端点的语义.

## 常见问题

### @agentium/core 是什么？

以工具、内存和多模式支持构建人工智能代理的核心框架

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

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

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

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

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

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

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

package\.json 的 engines 字段要求 Node\.js ^22\.18\.0 \|\| ^24\.11\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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