# 智能体 API

> 用你自己的代码运行 Waslo 智能体：一个 REST 端点负责回复，另有知识库、商品目录、记忆与日历——无需控制台。

Source: https://waslo.io/zh-CN/docs/agent-api · Last updated: 2026-10-12

智能体应答引擎能做的一切，你的代码也能做——包括它的知识库、记忆、商品目录、日历、配置与用量。智能体 API 对外提供的，正是在 WhatsApp 与 Instagram 上回复的同一个引擎——同一套知识库、同样的按客户记忆、同样的日历与目录工具——以一个可从你自己产品调用的 REST API 呈现。

完整参考与密钥管理见[开发者门户](/developers)。

## 什么时候用

- 你已经有 App 或网站，希望 Waslo 在其中回复，而不是在某个渠道上。
- 你是代理商，想以自己的品牌为客户运行这个智能体。
- 你只想单独用分类、记忆或知识库检索，不需要消息层。

如果你只是想在 WhatsApp 或 Instagram 上有个智能体，那不需要这个——去[集成](/docs/connecting-channels)里连接渠道即可。

## 一次调用

发送一条消息和一个用户 ID，返回的回复已经应用了记忆、知识库引用与工具动作。

```bash
curl https://api.waslo.io/v1/agent/reply \
  -H "Authorization: Bearer wsk_live_..." \
  -d '{
    "message": "Do you have a morning slot Thursday?",
    "userId": "customer_8842",
    "tools": ["calendar"]
  }'
```

`userId` 由你决定，它是智能体在多次调用之间记住同一个人的依据。沿用它对话就继续，换掉它就重新开始。

## API 还覆盖什么

| 领域 | 你可以做什么 |
| --- | --- |
| 回复 | 文本、媒体（图片、音频、视频、PDF）与语音输出 |
| 分类 | 单独把一条消息评为 HOT / WARM / COLD |
| 记忆 | 读取或删除智能体对某位用户的记忆 |
| 知识库 | 上传、列出与删除文档——与控制台共用 |
| 商品目录 | 对商品的完整增删改查——与控制台共用 |
| 日历 | 无需打开控制台即可连接 Google Calendar 或 Cal.com |
| 配置 | 按请求或长期设置系统提示词与行为 |
| 用量 | 已消耗额度、当前余额、支出上限 |

你通过 API 上传的一切都会出现在控制台，你在控制台添加的一切 API 也看得到。这是同一个工作区，不是两个。

## API 密钥

密钥在[开发者门户](/developers)创建，且**只显示一次**——它以哈希形式存储，我们无法替你找回。每个密钥带有权限范围——`agent`、`memory`、`kb`、`catalog`、`config`、`usage` 和 `tenants`（`tenants` 仅限 White-label 密钥）——只能做其权限允许的事。每个组织最多可保留 10 个有效密钥，可随时吊销。

请把密钥当作密码：仅限服务端，绝不要放进浏览器打包产物或移动应用。

## 额度与限流

**API 在所有套餐下都按额度计费**——它与渠道订阅是两个产品，因此 Growth 订阅并不会让 API 调用免费。费率高于渠道回复，因为每次调用承担的工作更多：

| 事件 | 额度 |
| --- | --- |
| 文本回复 | 2 |
| 调用了工具的回复 | 3 |
| 读取了媒体（图片、音频、视频或 PDF）的回复 | 5 |
| 语音输出 | +2 |
| 分类 | 1 |

开发者套餐决定你的限流额度，并在你购买之外每月额外赠送一部分额度。没有套餐时，将回落到默认的每分钟与每日限制。你还可以设置每月支出上限，避免失控的循环耗尽余额——达到上限后请求会以 `spend_cap_reached` 被拒绝。

## 错误

所有错误都以同一种信封返回，并带有一个 `request_id`，联系支持时值得一并提供。

| 状态码 | 含义 |
| --- | --- |
| 400 | 请求体未通过校验 |
| 401 | 缺少或无效的 API 密钥 |
| 402 | 额度不足，或已达支出上限 |
| 403 | 密钥的权限范围不包含此端点 |
| 413 | 请求体过大 |
| 429 | 触发限流——请在响应头给出的间隔后重试 |

在回复请求上带 `Idempotency-Key` 头：24 小时内的重复调用会返回原始响应，而不会重复扣费。

## 你的 API 用户不会进入运营收件箱

通过 API 产生的会话属于你 App 的用户，而不属于盯着 Waslo 收件箱的那个人——因此它们默认在「客户」和「收件箱」中隐藏。想看时加上 `?includeApi=true`。

## 白标

租户仅存在于 White-label 套餐。在该套餐下，主密钥可以创建彼此隔离的租户工作区，每个都有自己的密钥、知识库与商品目录。母账户支付全部用量，并获得按租户计量的数据用于二次计费；租户永远看不到母账户余额。租户按设计没有控制台权限——API 就是他们的全部界面，包括[连接日历](/docs/integrations)。

## 下一步

- [开发者门户](/developers)——创建密钥、阅读完整参考、选择套餐
- [知识库](/docs/knowledge-base)——智能体作答前会读什么
- [商品目录](/docs/product-catalog)——它能从哪里成交
- [为什么这样回答](/docs/why-this-reply)——每个答案背后的推理轨迹

## 主题

当你的组织定义了主题标签（2–8 个）后，`POST /v1/agent/reply` 与 `POST /v1/agent/classify` 会包含 `topic` 字段，`GET/PUT /v1/config` 可读写 `topicLabels`——完全 headless，包括 white-label。参见[主题与团队路由](/docs/team-routing)。

`GET/PUT /v1/config` 还可读写 `replyLanguage`：`"auto"` 用每位终端用户的语言回复；语言代码（`"es"`、`"ar"`、`"zh-Hans"`…）始终用该语言回复；`null` 沿用组织在控制台中的设置（未固定语言时即终端用户的语言）。
