# @atlanai/sdk 中文文档

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

版本：0\.9\.0
npm 元数据更新时间：2026-11-11T07:21:47.805Z
中文译文更新时间：2026-11-14T16:24:36.937Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40atlanai/sdk
原文对照：https://npmcn.com/package/%40atlanai/sdk/?lang=original

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

- 包体积（解压后）：10.4 MB，2412 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：7 个
- 首次发布：2026-09-03T13:46:13.343Z
- 最新版本发布：2026-11-11T07:21:47.621Z
- 近 30 天下载量：1980（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

Atlan 代理网关管理 SDK

## 安装

```sh
npm install @atlanai/sdk
```

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

## README

# @atlanai/sdk (英语)

Atlan代理网关的TypeScript/JavaScript SDK:管理代理,技能, 和工作空间, 并选择跟踪您的代理.

## 安装

```bash
npm install @atlanai/sdk
```

## 快速启动

```typescript
import { AtlanClient } from "@atlanai/sdk";

const client = new AtlanClient({
  gatewayOrigin: "https://<your-gateway-host>",
  bearerToken: "<your-api-token>",
});

const agent = await client.agents.create({
  name: "support-triage",
  workspaceId: "workspace_01example",
});

const page = await client.agents.list({ limit: 10 });
console.log(`${page.items.length} agents`);
```

方法改为: `client.<resource>.<action>` —— 说 `client.agents.get(agentId)`, (中文(简体) ), `client.sessions.messages.create(sessionId, {...})`,等等。 (笑声) 每个公众 Agent Gateway 操作可以这样到达;不需要进入 直接生成客户端.

生成的API也被服务和标记所打入,包括他们的中间软件:

```typescript
const releases = client.raw.registry.apis.releases.withMiddleware({
  post: async ({ response }) => response,
});
const page = await releases.registryListReleases({ limit: 10 });
```

这些访问者保留生成的请求/答复类型。 动态字符串服务 在运行时发现服务的代码仍可查询.

请求默认进行一次尝试。 应用程序可以配置 [选入重试中间软件](https://npmcn.com/package/%40atlanai/docs/typescript-retries.md) 以有限度的尝试, 抖动、取消和 `Retry-After` 支助。 见 [请求出错](https://npmcn.com/package/%40atlanai/docs/typescript-errors.md) 用于输入常见错误及其重试元数据.

`timeoutMs` 限制每个管理操作,包括信使查询、重试、, 和成功/错误的身体解码。 通过 a `signal` 通过生成的 API 请求 取消一个呼叫 . `Raw` 方法保留最后期限,同时保留其身体 打开: 消耗响应或取消 `response.raw.body` 当完成.

通过默认的工作空间一次, 而不是在每次呼叫中重复 :

```typescript
const client = new AtlanClient({ gatewayOrigin, bearerToken, workspace: "workspace_01example" });
```

默认还提供资源所需的工作空间查询参数 方法,既适用于立场参数,也适用于明确的选项对象。 明确 工作空间值胜出; 没有默认, 需要的工作空间参数仍然保留 运行时需要.

## 运行 eval

`Eval()` 执行任务和计分器,创建登记实验,发射 每例1个跟踪,上传跟踪链接结果,并完成运行. 书记官处 在最后敲定期间,获得持久的分数摘要:

```typescript
import { Eval } from "@atlanai/sdk";

const result = await Eval("Anthropic Evaluation", {
  data: () => [
    { input: "What is 2+2?", expected: "4" },
    { input: "What is the capital of France?", expected: "Paris" },
  ],
  task: async (input) => callModel(input),
  scores: [{
    name: "accuracy",
    scorer: ({ output, expected }) => output === expected ? 1 : 0,
  }],
}, { subjectKind: "agent", subjectId: "agent_01example" });

console.log(result.experimentId);
```

`subjectKind` 财务报告和审定财务报表 `subjectId` 连接运行到它测试的代理, 即 evals UI如何找到它;代理标识(`agent_...`这是 `id` 那个 `client.agents.list()` 返回。 运行一个既无, 仍然保存, 但列表 在没有代理的情况下 `Eval()` 以创造人的时候盟誓.

设定 `ATLAN_API_KEY` 财务报告和审定财务报表 `ATLAN_WORKSPACE_ID`内置替换 `data` 与 `dataset: "dataset_..."` 或一个准确的登记数据集名称。 跑者拒绝 当跟踪被禁用时继续,因为微量的 eval 行会打破 证据链。 冲洗后,它读出每个案件 追溯到 实验过滤器在上传结果之前; 缺失的跟踪标记 实验失败 。 登记册数据集大小写传递到数据集的值 `inputKey` (默认) `question`)到任务并解开一键 `{ value: ... }` 预期值。 一次毫无可用分数的跑步 最终确定并被拒绝;通过 `requireScores: false` 如果设置了空分数 预期.

### 计分器返回值

得分者还取一分. 计分员自己的名字是度量名,除非 值带有一个值.

```typescript
() => 0.8                                        // a number (true counts as 1, false as 0)
() => null                                       // abstain: recorded, but not averaged
() => ({ score: 1, name: "exact", metadata: { why: "match" } })
() => [{ score: 1, name: "a" }, { score: 0, name: "b" }]   // a list of { score, ... } objects
```

名单持有 `{ score, name?, metadata? }` 物体,不是空数。 一个平地 对象需要一个 `score` 键.

默认是投球的计分员将整个案例标为出错. 过 `{ scorerErrors: "score" }` 在将失败保留到该计分器的选项中: 其衡量标准记录为: `null`。信息存储在案件结果上(以及 `sourceMetadata.atlan_eval.scorer_errors` 和那个案子 除非计分员产生一个数字,否则将保持成功。 只有一个例外 计分器计数:不支持的返回值、重复或相撞分数 名称,或注册失败仍然错误.

### 运行数据集的一部分

`recordIds`, (中文(简体) ), `where` 财务报告和审定财务报表 `limit` 运行书记官处数据集的子集。 运行 保留与数据集的链接,因此每个结果都保留其 `datasetRecordId` 财务报告和审定财务报表 运行可以和记录中同一数据集的完整运行进行比较 运行。 实验的冰冻快照和简历 必须通过相同的选择者. `where` 必须是同步函数 返回布尔.

```typescript
await Eval("Support smoke", {
  dataset: "support-daily-tasks",
  task,
  scores,
}, {
  where: (item) => (item.tags ?? []).includes("billing"),
  limit: 10,
});
```

## 直接控制电子寿命周期

用文物标识或确切名称解决已存在的数据集,然后创建 在另一个跑者发出任何痕迹之前进行登记试验:

```typescript
import { createContextManifest, startExperiment } from "@atlanai/sdk";
import { propagateAttributes } from "@atlanai/sdk/tracing";

const contextManifest = await createContextManifest([{
  kind: "file",
  name: "CLAUDE.md",
  version: "git:0123456789abcdef0123456789abcdef01234567",
  digest: `sha256:${"0".repeat(64)}`,
}]);

const run = await startExperiment(
  client,
  "conversational-studio-daily", // exact name, or dataset_... ID
  { name: "candidate-run", config: { model: "example-model" } },
  { contextManifest },
);

await propagateAttributes(run.traceOptions, () => existingRunner());
```

`run.experiment` 是生成的创建响应 `run.id` 这是它的 `experimentId`。帮助者将解析的数据集版本和上下文标出 表现在不可改变的实验配置中。 当另一把绳子拥有时使用它 执行、结果上传和定稿.

## 追踪

```typescript
import { initLogger, wrapTraced } from "@atlanai/sdk/tracing";

const logger = initLogger({ projectName: "support-agent" });
const handleRequest = wrapTraced(async (input: string) => callModel(input));

await logger.traced(async (span) => {
  const output = await handleRequest("hello");
  span.log({ input: "hello", output });
}, { name: "handle-request", type: "task" });

await logger.flush();
```

追踪有自己的API密钥和生命周期. 它不重复管理 客户的运输。 它作为单独的子道而航行 (单位:千美元)`@atlanai/sdk/tracing`)所以导入它不会把 OpenTeleometry 拖入一个 仅管理捆绑。 npm 仍然安装 OpenTeleometry 依赖性 软件包,因为 npm 无法将依赖性作为导入条件 子路径; 将追踪拆分为第二个包将交易安装大小 用于第二版并发布生命周期.

Vercel AI SDK v3-v6使用其原生的OpenTelection路径:

```typescript
import * as ai from "ai";
import { initLogger, wrapAISDK } from "@atlanai/sdk/tracing";

initLogger({ projectName: "support-agent" });
const { generateText, streamText } = wrapAISDK(ai);
```

见 [评估与追踪](https://npmcn.com/package/%40atlanai/docs/evals-and-tracing.md) 框架设置, 上下文显示、无服务器冲出和测试的集成矩阵.

### 克劳德探员SDK

Claude探员SDK是用密码包起来的 而不是在 `instrument`页:1 软件包仅限无害环境管理,因此没有 `init()` 要补丁.

```typescript
import * as sdk from "@anthropic-ai/claude-agent-sdk";
import { getClient, init, wrapClaudeAgentSDK } from "@atlanai/sdk/tracing";

init({ serviceName: "support-agent" });
const { query } = wrapClaudeAgentSDK(sdk); // same exports as the SDK, traced

for await (const message of query({ prompt: "hello" })) {
  // unchanged
}
await getClient().flush();
```

每个 `query()` 呼叫变成一个 `invoke_agent` 用一个 `chat` 每个模型的跨度 转来转去 `execute_tool` 每个工具呼叫间距。 命名 `claude-agent-sdk` 内 `instrument` 打印此提示并报告一次 `manual` 内 `init(...).instrumentation`。 。 。 .

### LITELM 部署 ID

一个 LiteLLM 代理用户名 `x-litellm-model-id` 响应头。 之后 `init()` 或者说 `initLogger()`和SDK一样 记录该值为 `atlan.model.ref` 在呼叫的LLM跨度,和 `x-litellm-call-id` 作为 `atlan.model.call_id`所以Atlan可以给电话定价 部署。 没有客户端代码更改 。 Atlan模型网关读取方式相同: `x-gateway-model-deployment` (LiteLLM部署它计费),或者其他 `x-gateway-model-id` (它的模范行),变成 `atlan.model.ref`,以及 `x-gateway-model-name` 替换 `gen_ai.response.model` 当该跨度导出时。 网关 `x-gateway-model-price` (价格它解决呼叫) 变成 `atlan.model.price`,所以请 追踪会像Model Gateway的用途那样花费呼叫费. `atlan.model.gateway.type` 命名路由器( r)`atlan-model-gateway` 或者说 `litellm`) (中文(简体) ).

这是默认的。 在节点上,SDK订阅了undici的诊断频道 并且没有补丁,所以客户端在之前构建 `init()` 被覆盖。 只有 内置 `fetch` (unidici)观察到:客户在 `node-fetch`, (中文(简体) ), `axios` 或者说 `node:http` 需求 `litellmFetch()` 或者说 `recordModelRef()`. Bun, Deno和Cloudflare (英语) 工人工作方式不同;见 [运行时间](https://npmcn.com/package/%40atlanai/sdk/#readme-runtimes)。仅 2xx 答复是读取的,答复机构从未读取过,而且跨度已经是一个值 载具被保存。 数值需要LLM跨度才能降落在: `llm` 宽度 本身,一个提供器件的跨度,或者AI SDK的 `doGenerate` 编号 : `doStream` 间距.

把它关掉 `init({ captureModelRef: false })` 或者说 `ATLAN_CAPTURE_MODEL_REF=false`。关闭表示没有安装钩子;它没有 删除早先的钩子 `init()` 安装在相同的进程.

钩子看不见的呼叫,通过 `litellmFetch()` 作为客户的 `fetch`。 包装 `globalThis.fetch` 仅供客户使用:

```typescript
import OpenAI from "openai";
import { litellmFetch } from "@atlanai/sdk/tracing";

const openai = new OpenAI({ baseURL: litellmUrl, fetch: litellmFetch() });
```

或者在LLM范围内记录你的价值. `recordModelRef` 写到 活动 LLM 跨度, 除非您通过 `span`返回 `true` 当它写了什么 从不掷出 :

```typescript
import {
  LITELLM_CALL_ID_HEADER,
  LITELLM_MODEL_ID_HEADER,
  recordModelRef,
} from "@atlanai/sdk/tracing";

if (response.ok) {
  recordModelRef(response.headers.get(LITELLM_MODEL_ID_HEADER), {
    callId: response.headers.get(LITELLM_CALL_ID_HEADER),
  });
}
```

一个没有LLM横跨的电话 根本没有记录.

## 错误

每个非-2xx的答复都以 `AtlanAPIError`,与 `.status`, (中文(简体) ), `.code`, (中文(简体) ), (如果网关包括一个) `.traceId`. 在作出任何答复之前未能采取行动 改为 `AtlanAPIError` 与 `status === 0`数字 :

```typescript
import { AtlanAPIError } from "@atlanai/sdk";

try {
  await client.agents.get("agent_does_not_exist");
} catch (error) {
  if (error instanceof AtlanAPIError) {
    console.log(error.status, error.code);
  }
}
```

## 运行时间

节点20. 跟踪子路径被写入为也在非节点运行时运行 像Cloudflare工人——通过配置到 `init()` 很明显 而不是依赖环境变量,因为工人没有环境 环境.

### Bun、Deno和工人的LiteLLM部署编号

Bun, Deno和Cloudflare工人从不发表undici的诊断事件,所以 那边 `init()` 包装 `globalThis.fetch` 换句话说 这个 `openai` 财务报告和审定财务报表 `@anthropic-ai/sdk` 客户留着 `fetch` 当他们被建造的时候, 所以,一个客户端 之前建立 `init()` 被默默地错过。 打电话 `init()` 在任何时间之前 客户端已构建 。 在它无法识别的运行时间, SDK 安装什么也没有.

Bun 有预装:

```bash
bun --preload ./atlan-init.ts ./app.ts
```

Deno,以init模块作为第一个导入:

```typescript
import "./atlan-init.ts"; // calls init() before anything below runs
import OpenAI from "openai";
```

工人,客户建在操作员之后 `init()`数字 :

```typescript
import OpenAI from "openai";
import { init } from "@atlanai/sdk/tracing";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    init({ serviceName: "edge-agent", apiKey: env.ATLAN_API_KEY, workspaceId: env.ATLAN_WORKSPACE_ID });
    const openai = new OpenAI({ apiKey: env.LITELLM_API_KEY, baseURL: env.LITELLM_URL });
    // ...
  },
};
```

当客户必须存在之前 `init()`,给它 `litellmFetch()` 换句话说. 没有Async LocalStorage和Vercel Edge的工人没有经过测试.

## 常见问题

### @atlanai/sdk 是什么？

Atlan 代理网关管理 SDK

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

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

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

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

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

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

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

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

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

@atlanai/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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