@coval/ sdk (英语)

输入的脚本客户端 科瓦尔 评估平台API.

这个SDK大部分是 生成 从 Coval 的公开 OpenAPI 规格( 同样的力量 文件.coval.dev/参考) (中文(简体) ). 一个小的手写图层会添加认证, 带有后退的重试, pagination 迭代,和打出错误,所以生成的客户端是 ergonotic for 生产用途.

安装

npm install @coval/sdk

需要节点18+.

快开始

import { CovalClient } from '@coval/sdk';

const coval = new CovalClient({ apiKey: process.env.COVAL_API_KEY! });

// List agents
const { agents } = await coval.agents.listAgents({ pageSize: 25 });

// Submit a production conversation for evaluation
await coval.conversations.submitConversation({
  covalConversationsAPISubmitConversationRequest: {
    agent_id: 'my-agent-id',
    external_conversation_id: 'call-2026-05-11-abc',
    occurred_at: new Date(),
    transcript: [
      { role: 'agent', content: 'Hi, thanks for calling.' },
      { role: 'user', content: "I'd like to update my account." },
    ],
  },
});

包装纸加上什么

奥特 - x-api-key (减)

Coval的网关对API-键头头的大小写敏感. 大写 X-API-Key 返回时 Missing API Key编辑 CovalClient 总是发送 小写 x-api-key,所以你不用考虑.

以指数回转进行回转

给天花板 GET, (中文(简体) ), HEAD,以及 OPTIONS 请求,客户端重试 自动打开 408, (中文(简体) ), 429,以及 5xx 回应,加上网络错误. 默认:3次尝试,200ms碱性延迟与焦急,5s盖. Retry-After 信头(包括秒和HTTP-date)均被尊重. 更改请求不是 重审,除非你明确添加他们的方法 retryableMethods。 。 。 .

const coval = new CovalClient({
  apiKey: process.env.COVAL_API_KEY!,
  retry: { maxAttempts: 5, baseDelayMs: 500, maxDelayMs: 10_000 },
});

// Disable retries entirely:
const coval2 = new CovalClient({ apiKey, retry: false });

输入错误

每个非-2xxHTTP响应都变成一个 CovalApiError 复试后为 筋疲力尽了 网络失败变成 CovalNetworkError。两者都延伸 Error, (中文(简体) ), 这么平淡 try/catch 工作时.

import { CovalApiError } from '@coval/sdk';

try {
  await coval.agents.getAgent({ agentId: 'unknown' });
} catch (err) {
  if (err instanceof CovalApiError) {
    console.error(err.status, err.code, err.message, err.requestId);
  }
}

延展器

列表端点返回一页加一页 next_page_token编辑 paginate 帮助者将它变成一个同步执行器,这样你就不用管理符号了.

import { paginate, collectAll } from '@coval/sdk';

for await (const agent of paginate({
  fetchPage: (pageToken) => coval.agents.listAgents({ pageToken, pageSize: 50 }),
  items: (page) => page.agents,
  nextToken: (page) => page.next_page_token,
})) {
  console.log(agent.id, agent.display_name);
}

// Or collect everything into an array:
const all = await collectAll({
  fetchPage: (pageToken) => coval.simulations.listSimulations({ pageToken }),
  items: (p) => p.simulations,
  nextToken: (p) => p.next_page_token,
});

断断续续的故障诊断

在途中死亡的请求从未到达API,所以没有 服务器侧跟踪它。 客户端保留直播计数器:

coval.stats;
// { calls: 12, requests: 14, retries: 2, networkErrors: 1 }

calls 是逻辑 API 调用, requests 计数 fetch 包括 重复,以及 networkErrors 在没有回复的情况下计算失败 都说吧 在报告零星超时时包括这些内容。 每次重试的行和 每一次过境故障 :

const coval = new CovalClient({ apiKey, onDebug: console.debug });

连接再使用

在节点上,客户端使用全局 fetch (unidici),闲置期满 大约4秒后保持动态连接。 这一点很重要: 网络路径默默地不关闭闲置连接并重用 将请求拖到超时, 因为它从未到达服务器 .

在该窗口内提出的要求仍然可以重新使用集合连接。 狦 不经常地提交,或者你看见没有解释的暂停,你应当明白地传达: 调度器 :

import { Agent, fetch as undiciFetch } from 'undici';

const coval = new CovalClient({
  apiKey,
  fetch: ((input, init) =>
    undiciFetch(input as never, { ...init, dispatcher: new Agent({ keepAliveTimeout: 1_000 }) })) as typeof fetch,
});

Python SDK 直接暴露出与 max_idle_seconds。 。 。 .

自定义

覆盖基础 URL( stage,自主机)

const coval = new CovalClient({
  apiKey,
  baseUrl: 'https://staging.api.coval.dev/v1',
});

插入自定义中间软件

const coval = new CovalClient({
  apiKey,
  middleware: [
    {
      async pre({ url, init }) {
        console.log('→', init.method, url);
        return undefined;
      },
    },
  ],
});

覆盖取取取( 例如, 无保留- 保留)

import { fetch as undiciFetch } from 'undici';

const coval = new CovalClient({ apiKey, fetch: undiciFetch });

实例

可在这回购中运行。 设定 COVAL_API_KEY (和 COVAL_AGENT_ID 联 合 国 并运行 :

npm run example:list-agents
npm run example:submit-conversation

版本

生成的地表跟踪了基本的Coval API. 光谱改变 打破生成的客户端递增 小声 版本。 手写 折断公共类型Script API的包装更改也会递增 小声 版本。 错误修正增量 补丁 版本.

重新生成

如果您想要在当地重生客户端 :

# From the repo root, with the docs repo checked out as a sibling:
node scripts/bundle-spec.mjs
bash scripts/generate-sdks.sh

见 捐款 供当地一代人使用 发布指南 用于预定的再生设置.

许可证

麻省理工学院.