# @everruns/sdk 中文文档

规范地址：https://npmcn.com/package/%40everruns/sdk/

版本：0\.3\.1
npm 元数据更新时间：2026-10-11T22:04:58.549Z
中文译文更新时间：2026-11-14T01:33:04.747Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：238 kB，30 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：1 个
- 首次发布：2026-01-29T06:06:52.843Z
- 最新版本发布：2026-10-11T22:04:58.180Z
- 近 30 天下载量：2829（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

Everruns API 的脚本 SDK 类型

## 安装

```sh
npm install @everruns/sdk
```

也可以使用：`pnpm add @everruns/sdk`、`yarn add @everruns/sdk`、`bun add @everruns/sdk`

## README

# @everruns/ sdk (英语)

Everruns API 的 TypeScript SDK 版本.

## 安装

```bash
npm install @everruns/sdk
```

## 从代码调用您的代理

使用 `AgentClient` 从申请中调用一个代理。 它拿着密钥 (单位:千美元)`evr_ak_...`到达代理的会话,没有别的.

```typescript
import { AgentClient } from "@everruns/sdk";

// Reads EVERRUNS_AGENT_URL and EVERRUNS_AGENT_KEY
const agent = new AgentClient();
// or: new AgentClient({ agentUrl: "https://app.everruns.com/api/v1/channels/apichan_...", credential: "evr_ak_..." })

// One call: creates a session, sends the message, waits for the turn
console.log(await agent.run("What can you do?"));

// Act for one of your application's users (the key needs the `end_user` permission)
const alice = agent.forEndUser("customer-42");
console.log(await alice.run("Where is my order?"));

// For a browser or mobile app, never ship the key: mint a short-lived runtime token
const { access_token } = await alice.runtimeToken();
// ...then, in the browser:
const browser = new AgentClient({
  agentUrl: "https://app.everruns.com/api/v1/channels/apichan_...",
  credential: access_token,
});
```

用于更多的控制用途 `createSession`, (中文(简体) ), `sendMessage`, (中文(简体) ), `streamEvents`, (中文(简体) ), `listEvents`, (中文(简体) ), `getSession`, (中文(简体) ), `cancel`, (中文(简体) ), `answerQuestions` 财务报告和审定财务报表 `submitToolApprovals`。 。 。 .

以下管理客户`Everruns`,带有个人访问符号) 管理 Everruns : 代理,牵引,工作空间. 内容 `sessions.create` 财务报告和审定财务报表 `messages.create` 用于调用代理 `AgentClient` 换句话说.

## 管理快速启动

```typescript
import { Everruns } from "@everruns/sdk";

// Uses EVERRUNS_API_KEY and optional EVERRUNS_ORG_ID environment variables
const client = Everruns.fromEnv();

// Create an agent
const agent = await client.agents.create({
name: "Assistant",
systemPrompt: "You are a helpful assistant."
});

// Create a session
const session = await client.sessions.create({ agentId: agent.id });

// Send a message
await client.messages.create(session.id, "Hello!");

// Stream events
for await (const event of client.events.stream(session.id)) {
console.log(event.type, event.data);
}
```

## 特工哈内斯

每个特工都拥有一副吊带 设定为创建/更新 `harnessName` (首选)或 `harnessId` (相互排斥); 省略两者以默认为 org 的 `generic` 绳子。 由代理创建的会话运行在代理的操纵上.

```typescript
// Create an agent on a specific harness
const agent = await client.agents.create({
  name: "researcher",
  systemPrompt: "You do deep research.",
  harnessName: "deep-research",
});

// Agent-first session: runs on the agent's harness
const session = await client.sessions.create({ agentName: "researcher" });
```

## 调用模型( M)

发现并管理被带,浏览可用的模型以选择一个 `defaultModelId`。 。 。 .

```typescript
// Browse harnesses, then create one
const harnesses = await client.harnesses.list(); // or .search("research")
const harness = await client.harnesses.get(harnesses.data[0].id);
const custom = await client.harnesses.create({
  name: "my-harness",
  systemPrompt: "Base instructions for every session.",
});
const examples = await client.harnesses.listExamples();

// List models to pick a default for an agent
const models = await client.models.list();
```

## 初始文件

```typescript
const session = await client.sessions.create({
agentId: "agent_...",
initialFiles: [
{
path: "/workspace/README.md",
content: "# Demo Project\n",
encoding: "text",
isReadonly: true,
},
{
path: "/workspace/src/app.py",
content: 'print("hello")\n',
encoding: "text",
},
],
});
```

可运行实例 : [`examples/initial-files.ts`](https://npmcn.com/package/%40everruns/sdk/examples/initial-files.ts) 从此 repo 从本地运行 `npx tsx examples/initial-files.ts`。 。 。 .

## 代理版本

```typescript
const version = await client.agents.createVersion("agent_...", {
changeKind: "manual",
summary: "Baseline",
});

const versions = await client.agents.listVersions("agent_...");
const diff = await client.agents.diffVersions("agent_...", "agentver_1", version.id);
const fork = await client.agents.forkVersion("agent_...", version.id, {
name: "forked-agent",
});
const rollback = await client.agents.rollbackVersion("agent_...", version.id, {
saveVersion: true,
});
```

## 工作空间

工作区拥有各会场共享的文件.

```typescript
const workspace = await client.workspaces.create({ name: "team-docs" });

await client.workspaceFiles.create(
workspace.id,
"/notes/welcome.md",
"# Welcome\n",
{ encoding: "text" },
);
const file = await client.workspaceFiles.read(workspace.id, "/notes/welcome.md");
const files = await client.workspaceFiles.list(workspace.id, { recursive: true });
```

可运行实例 : [`examples/workspaces.ts`](https://npmcn.com/package/%40everruns/sdk/examples/workspaces.ts) 从此 repo 从本地运行 `npx tsx examples/workspaces.ts`。 。 。 .

## 回忆

记忆是长期,可搜索的知识库,供代理商使用.

```typescript
const memory = await client.memories.create({ name: "product-knowledge" });

await client.memories.createFile(memory.id, "/facts/product.md", {
content: "# Product\n",
encoding: "text",
});
const results = await client.memories.grepFiles(memory.id, "product");
await client.memories.sync(memory.id);
```

可运行实例 : [`examples/memories.ts`](https://npmcn.com/package/%40everruns/sdk/examples/memories.ts) 从此 repo 从本地运行 `npx tsx examples/memories.ts`。 。 。 .

## 认证

SDK使用个人访问令牌认证. 设定 `EVERRUNS_API_KEY` 环境变量或明确传递符号。 关于可进入多个组织的个人进入标志,设置 `EVERRUNS_ORG_ID` 或通过 `orgId` 明确:

```typescript
// From environment variable
const client = Everruns.fromEnv();
```

或者有明确的标志和组织:

```typescript
const client = new Everruns({
apiKey: "evr_pat_...",
orgId: "org_..."
});
```

## 变化原因

记下为什么做了改变. `withReason` 生成客户端发送 由它提出的每个 API 请求说明理由; 服务器将其保存在已更改的 实体的历史。 原客户端保持不变:

```typescript
await client.withReason("retire the unused agent").agents.delete("agent_123");

const scoped = client.withReason("rotate prompts for the Q3 launch");
await scoped.agents.delete("agent_456");
```

其原因出现在 `Everruns-Change-Reason` uTF-8 标题 百分之百的编码。 空白的原因不会发出信头。 服务器用 HTTP 400 来修剪原因并拒绝它( Name`invalid_change_reason`当它超过1000个字符,包含除新行和标签以外的控制字符,或者看起来它包含一个证书.

## 流动事件

SDK支持 SSE 流出自动重联:

```typescript
const stream = client.events.stream(session.id, {
exclude: ["output.message.delta"], // Filter out delta events
sinceId: "evt_..." // Resume from event ID
});

for await (const event of stream) {
switch (event.type) {
case "output.message.completed":
console.log("Message:", event.data);
break;
case "turn.completed":
console.log("Turn completed");
stream.abort(); // Stop streaming
break;
case "turn.failed":
console.error("Turn failed:", event.data);
break;
}
}
```

## 处理错误

```typescript
import { ApiError, AuthenticationError, RateLimitError } from "@everruns/sdk";

try {
await client.agents.get("invalid-id");
} catch (error) {
if (error instanceof AuthenticationError) {
console.error("Invalid personal access token");
} else if (error instanceof RateLimitError) {
console.log(`Retry after ${error.retryAfter} seconds`);
} else if (error instanceof ApiError) {
console.error(`API error ${error.statusCode}: ${error.message}`);
}
}
```

## 许可证

麻省理工学院

## 常见问题

### @everruns/sdk 是什么？

Everruns API 的脚本 SDK 类型

### 如何安装 @everruns/sdk？

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

### @everruns/sdk 支持 TypeScript 吗？

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

### @everruns/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @everruns/sdk 需要什么版本的 Node\.js？

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

### @everruns/sdk 可以商用吗？

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

### @everruns/sdk 的下载量有多少？

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

### @everruns/sdk 还在维护吗？

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