@atlanai/sdk (英语)

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

安装

npm install @atlanai/sdk

快速启动

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也被服务和标记所打入,包括他们的中间软件:

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

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

请求默认进行一次尝试。应用程序可以配置选入重试中间软件以有限度的尝试, 抖动、取消和 Retry-After 支助。见请求出错用于输入常见错误及其重试元数据.

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

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

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

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

运行 eval

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

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 如果设置了空分数预期.

计分器返回值

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

() => 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 必须是同步函数返回布尔.

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

直接控制电子寿命周期

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

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。帮助者将解析的数据集版本和上下文标出表现在不可改变的实验配置中。当另一把绳子拥有时使用它执行、结果上传和定稿.

追踪

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路径:

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

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

见评估与追踪框架设置, 上下文显示、无服务器冲出和测试的集成矩阵.

克劳德探员SDK

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

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 (英语) 工人工作方式不同;见运行时间。仅 2xx 答复是读取的,答复机构从未读取过,而且跨度已经是一个值载具被保存。数值需要LLM跨度才能降落在: llm 宽度本身,一个提供器件的跨度,或者AI SDK的 doGenerate 编号 : doStream 间距.

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

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

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

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

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

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数字 :

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 有预装:

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

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

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

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

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的工人没有经过测试.

版本	发布日期	距今
`0.9.0`latest	2026/11/11	3 天前
`0.9.0-beta.1`beta	2026/11/02	12 天前
`0.8.2`	2026/10/22	23 天前
`0.8.0`	2026/10/20	25 天前
`0.8.0-beta.2`	2026/10/20	25 天前
`0.6.0`	2026/10/15	30 天前

@atlanai/sdk

@atlanai/sdk (英语)

安装

快速启动

运行 eval

计分器返回值

运行数据集的一部分

直接控制电子寿命周期

追踪

克劳德探员SDK

LITELM 部署 ID

错误

运行时间

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

版本与发布记录

关于 @atlanai/sdk 的常见问题

@atlanai/sdk 是什么？

如何安装 @atlanai/sdk？

@atlanai/sdk 支持 TypeScript 吗？

@atlanai/sdk 支持 ESM 还是 CommonJS？

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

@atlanai/sdk 可以商用吗？

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

@atlanai/sdk 还在维护吗？