PurrA for JavaScript and TypeScript

English | 简体中文

适用于 Node.js 22+ 的 ESM Agent 运行时。应用提供 ModelGateway，通过 purra 的公开导出 组合工具、上下文、规划和持久化能力。

1.0.0 开发状态

当前源码为尚未发布的 1.0.0 开发版。请安装版本一致的 Core 与集成本地产物；注册表命令不保证获取此开发版本。 持久化审批契约记录本版开发中的能力；Root 持久化审批恢复与宿主授权 MCP 写工具已具备确定性验证；真实 Provider、业务服务与下游验收仍需分别完成。 已有能力及 1.x 兼容承诺见1.0 支持说明。

0.x 升级要求见升级说明。

安装

npm install purra

运行 Agent

将配置好的模型网关传入 ask。OpenAI 和 Anthropic 适配包 提供各自原生 API 的网关。自定义网关需要声明模型能力，并确认每次请求实际应用的精确总生成上限。

import { Agent, type ModelGateway } from "purra";

async function ask(model: ModelGateway) {
  const agent = new Agent({ model });
  const run = await agent.submit({
    messages: [{ role: "user", content: "Hello" }],
  }, {
    budgets: { maxRunGenerationTokens: 8192 },
  });

  for await (const event of run.events()) {
    console.log(event.kind, event.payload);
  }
  return (await run.result).output;
}

submit() 返回 Run 句柄，提供已提交事件、取消和执行结果。调用 run.cancel() 请求取消。 只需要进程内结果时使用 invoke()；需要临时事件流、不需要持久化 Run 时使用 stream()。 本地网关与工具的完整代码见快速开始示例。

工具与检索

通过 new Agent({ model, tools }) 传入工具定义。每个工具声明输入 Schema 和副作用策略。 有副作用的工具需要幂等保障；confirm 工具还需要应用批准。

RetrieverTool 将应用实现的 Retriever 接入同一套工具系统。应用选择数据源和作用域， 并在读取前校验访问权限；模型只提供查询文本。注册方式见快速开始示例。

带工具的普通 Run 会额外调用一次不带工具的模型来生成公开回答。 设置调用次数、Token 和截止时间预算时，需要为这次调用预留额度。

规划

已有模型网关 model 时，可这样启用内置 Planner：

import { Agent, ModelWorkPlanner } from "purra";

const agent = new Agent({
  model,
  planning: { plannerFactory: tasks => new ModelWorkPlanner(tasks) },
});

Run 请求通过 planningMode 选择模式：

| 模式 | 行为 | | --- | --- | | auto | 默认模式。正常开始，在模型请求规划或工具要求规划时进入规划流程。 | | reactive | 通过模型与工具循环执行，不激活规划。 | | planned | 执行任务前先规划。 |

Planner 要求网关支持流式输出。订阅 Run 事件可逐片段接收 planning.delta，无需等待完整 JSON； planning.progress 保留完整进度记录的语义。原始预览可能包含无效计划片段，执行仍须通过校验，推理保持私有。 契约见计划输出，订阅与重放用法见规划示例。

预算与持久化

RunRequest.maxGenerationTokens 是用户对单次 Provider 调用全部生成 Token 的上限；当模型把 推理计入 generation 时，其中也包括推理 Token。maxRunGenerationTokens 限制 Run 累计生成量， 并且必须显式设置；null 表示不设有限 Token 上限。有限预算要求模型服务报告实际用量。

NewRunOptions.resultCapacityTargetTokens 是正式结果内容的可选工作流容量目标，不会降低 Provider 的生成额度；只有选定上下文窗口的物理容量可以收紧该额度。模型未报告推理用量时， Core 会保留“未知”状态，而不会把它记成 0。

内置仓储使用内存。需要持久化时，配置 SQLite 适配器 或实现仓储接口。恢复使用已提交的检查点，并要求还原原有模型与工具配置。 结果不确定的外部写入，需要先确认执行结果再重试。

使用子 Agent 时，通过 runRepository 和 agentTree.repository 传入同一组 Run 与 Run 树仓储。 子 Agent 的能力和预算受父级约束，详见架构说明。

更多

• 项目指南
• 示例
• 可选包
• MIT 许可证

长期公共接口约定见兼容承诺。

仅返回宿主结果

在 Agent 上设置 responsePresentation: "none"，可省略额外的公开回答呈现轮次。 默认 "model_live" 保持原行为。已有结果校验、工具权限和 Run 预算仍然生效。 此模式下 result.output、snapshot().finalOutput 是宿主私有结果，最终事件保持私有； 生命周期、工具和进度事件保留原可见性。临时 stream 不输出回答文本增量，最终结果事件 标记 visibility: "private"。呈现选择纳入 Run 配置身份，恢复时不能切换公开方式。