# @amigo-ai/sdk 中文文档

规范地址：https://npmcn.com/package/%40amigo-ai/sdk/

版本：2\.1\.0
npm 元数据更新时间：2026-09-08T02:32:44.491Z
中文译文更新时间：2026-11-06T12:14:03.296Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：8.9 MB，27 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：1 个
- 首次发布：2025-08-07T20:17:45.737Z
- 最新版本发布：2026-09-08T02:32:44.140Z
- 近 30 天下载量：3244（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：115（近 12 个月 61 个）

## 中文简介

在 api.amigo.ai 的 Classic Amigo API 的官方类型脚本 SDK

## 安装

```sh
npm install @amigo-ai/sdk
```

也可以使用：`pnpm add @amigo-ai/sdk`、`yarn add @amigo-ai/sdk`、`bun add @amigo-ai/sdk`

## README

![Amigo banner](https://npmcn.com/package/%40amigo-ai/sdk/assets/readme/amigo-banner.png)

# @ amigo-ai/ sdk

(原始内容存档于2018-10-21). Official TypeScript SDK for the Classic Amigo API.

[产品文档](https://docs.amigo.ai/) • 妇女 [开发者指南](https://docs.amigo.ai/developer-guide/classic-api/sdks) • 妇女 [API 参考](https://amigo-ai.github.io/amigo-typescript-sdk/) • 妇女 [实例](https://github.com/amigo-ai/amigo-typescript-sdk/tree/main/examples) • 妇女 [更改日志](https://github.com/amigo-ai/amigo-typescript-sdk/blob/main/CHANGELOG.md)

[![npm version](https://img.shields.io/npm/v/%40amigo-ai%2Fsdk?logo=npm)](https://www.npmjs.com/package/@amigo-ai/sdk) [![CI](https://github.com/amigo-ai/amigo-typescript-sdk/actions/workflows/test.yml/badge.svg)](https://github.com/amigo-ai/amigo-typescript-sdk/actions/workflows/test.yml) [![codecov](https://codecov.io/gh/amigo-ai/amigo-typescript-sdk/graph/badge.svg?token=PQU5JBU941)](https://codecov.io/gh/amigo-ai/amigo-typescript-sdk) [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

从承诺的 Classic OpenAPI快照中打入,被作为无害环境管理和普通JS 发运,并被现有的 org 范围集成在最初的 Amigo 后端上使用 `api.amigo.ai`。 。 。 .

## 经典后端上下文

`@amigo-ai/sdk` 瞄准原始的 org 镜像后端。 现有的部署仍然使用这个表面来进行对话,服务,组织,用户,代理,上下文图,webhoks,和流出的事件.

![Classic text session flow](https://npmcn.com/package/%40amigo-ai/sdk/assets/readme/classic-session-flow.svg)

## 产品状况

`@amigo-ai/sdk` 保留经典 API 支持的 TypeScript 客户端 .

平台API是新的工作空间范围能力首先落地的地方,但经典API并没有被突然关闭. Amigo会发布一条迁移路径,兼容性说明,并在要求客户移动生产工作量之前更新指导.

## 选择右侧 SDK

| 如果你需要的话 | 从这里开始 |
| --- | --- |
| 现有整形整合 `api.amigo.ai` | `@amigo-ai/sdk` |
| 新的工作空间范围整合 `api.platform.amigo.ai` | [`@amigo-ai/platform-sdk`](https://github.com/amigo-ai/amigo-platform-typescript-sdk) |

## 文档

| 需求 | 最佳切入点 |
| --- | --- |
| 产品概况和部署背景 | [(原始内容存档于2017-10-21). docs.amigo.ai](https://docs.amigo.ai/) |
| 综合指导和开发者 | [开发者指南](https://docs.amigo.ai/developer-guide/classic-api/sdks) |
| 生成 API 引用 | [amigo-ai.github.io/amigo-typescript-sdk 存档副本](https://amigo-ai.github.io/amigo-typescript-sdk/) |
| 可运行示例 | [实例/](https://github.com/amigo-ai/amigo-typescript-sdk/tree/main/examples) |
| 发布历史 | [变动情况](https://github.com/amigo-ai/amigo-typescript-sdk/blob/main/CHANGELOG.md) |

文件网站仍然是主要参考。 Repo-local 示例保持与已发运的包表面相近,并在 CI 中验证.

## 安装

```bash
npm install @amigo-ai/sdk
```

在提出请求之前,获取经典组织证书和一个有权阅读目标资源的用户. 将 API 密钥保存在服务器侧环境变量或密管中. 下面的例子读取了对话数据;它们要求进入现有的组织.

2.0.0生成的模型变化,请审查 [当前 SDK 升级指导](https://docs.amigo.ai/api-reference/change-logs/sdk-ecosystem#september-2026-compatibility-releases) ,并在选择版本时重新检查软件包注册.

## 快速启动

```typescript
import { AmigoClient } from '@amigo-ai/sdk'

const client = new AmigoClient({
  apiKey: 'your-api-key',
  apiKeyId: 'your-api-key-id',
  userId: 'user-id',
  orgId: 'your-organization-id',
})

const conversations = await client.conversations.getConversations({
  limit: 10,
  sort_by: ['-created_at'],
})

console.log(conversations.conversations.map(conversation => conversation.id))
```

## 配置

| 选项 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `apiKey` | `string` | 对 | Amigo 仪表盘上的 API 密钥 |
| `apiKeyId` | `string` | 对 | API 密钥标识配对 `apiKey` |
| `userId` | `string` | 对 | 请求所代表的用户代号 |
| `orgId` | `string` | 对 | 经典 API 的组织代号 |
| `baseUrl` | `string` | 没有 | 覆盖 API 基础 URL 。 默认为 `https://api.amigo.ai` |
| `retry` | `RetryOptions` | 没有 | 对瞬态 HTTP 故障重试策略覆盖 |

### 运行时间要求

SDK 支持节点 `18+` 并且通过CI中的活性节点释放测试. 它依赖于网络标准原始人,例如: `fetch`, (中文(简体) ), `AbortController`, (中文(简体) ), `URL`,以及 `TextEncoder`。 。 。 .

## 生成类型

软件包再导出生成的 OpenAPI 类型, 因此应用程序代码可以直接对应于 API 合同键入 :

```typescript
import type { components, operations, paths } from '@amigo-ai/sdk'

type Conversation = components['schemas']['ConversationInstance']
type GetConversationsQuery = operations['get-conversations']['parameters']['query']
```

公共建筑产生于承诺 [`specs/openapi-baseline.json`](https://npmcn.com/package/%40amigo-ai/sdk/specs/openapi-baseline.json) 在这种重播中快照,所以类型输出在机器和CI运行中仍然具有决定性. 当你需要刷新快照,运行:

```bash
npm run openapi:sync
```

## 检索

HTTP 客户端在合理默认情况下重试瞬态失败 :

-   最大尝试 : `3`
-   后退基数 : `250ms` 完全紧张
-   每次尝试的最大延迟 : `30s`
-   状态 : `408`, (中文(简体) ), `429`, (中文(简体) ), `500`, (中文(简体) ), `502`, (中文(简体) ), `503`, (中文(简体) ), `504`
-   方法: `GET`附加时 `POST` 打开 `429` 何时 `Retry-After` 当前

## 处理错误

```typescript
import { AmigoClient, AuthenticationError, NetworkError } from '@amigo-ai/sdk'

try {
  const client = new AmigoClient({
    apiKey: 'your-api-key',
    apiKeyId: 'your-api-key-id',
    userId: 'user-id',
    orgId: 'your-organization-id',
  })

  await client.organizations.getOrganization()
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Authentication failed:', error.message)
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}
```

## 支助

使用 [问题跟踪器](https://github.com/amigo-ai/amigo-typescript-sdk/issues) 用于错误和特性请求。 关于负责任的披露,见 [警卫](https://github.com/amigo-ai/amigo-typescript-sdk/blob/main/SECURITY.md)。 。 。 .

## 常见问题

### @amigo-ai/sdk 是什么？

在 api\.amigo\.ai 的 Classic Amigo API 的官方类型脚本 SDK

### 如何安装 @amigo-ai/sdk？

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

### @amigo-ai/sdk 支持 TypeScript 吗？

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

### @amigo-ai/sdk 支持 ESM 还是 CommonJS？

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

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

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

### @amigo-ai/sdk 可以商用吗？

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

### @amigo-ai/sdk 的下载量有多少？

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

### @amigo-ai/sdk 还在维护吗？

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