# AI agent 须知

URL: https://docs.router.ezat.io/zh/agents

> 供 AI agent 在配置工具或代码使用 EZAT Router 时参考：必需的值、安全的配置流程和禁止事项清单。

## 何时阅读本页

如果你是一个 AI agent（Claude Code、Cursor、Codex、ChatGPT 或其他），正在为用户配置通过 EZAT Router 调用 AI 模型的工具、SDK 或代码，或者在排查这类配置的问题，请阅读本页。

## 必需的值

| 项目 | 值 |
| --- | --- |
| Anthropic 格式的 base URL | `https://api.router.ezat.io`（客户端会自己加上 `/v1/messages`：不要加 `/v1`） |
| OpenAI 格式的 base URL | `https://api.router.ezat.io/openai/v1` |
| 认证请求头 | `x-api-key: $EZAT_API_KEY` 或 `Authorization: Bearer $EZAT_API_KEY`，两种 API 都适用 |
| Key 格式 | `ezat_sk_` 加上 40 个字母和数字（共 48 个字符） |
| 保存 key 的变量 | `EZAT_API_KEY`，除非用户指定了其他变量 |
| 查询模型 | 用 key 调用 `GET https://api.router.ezat.io/v1/models`（或 `GET https://api.router.ezat.io/openai/v1/models`） |
| 模型 id | `author/model`，例如 `anthropic/claude-sonnet-5-5`。Anthropic 自己的模型名称是同一模型的别名。 |
| 含别名、限制和价格的模型目录（无需 key） | `GET https://api.router.ezat.io/api/models` |
| Messages 端点 | `POST https://api.router.ezat.io/v1/messages` |
| Chat Completions 端点 | `POST https://api.router.ezat.io/openai/v1/chat/completions` |
| 控制台（key、充值、用量） | `https://router.ezat.io/zh`：key 在 `https://router.ezat.io/zh/keys`，充值在 `https://router.ezat.io/zh/billing` |
| 支持 | support@ezat.io，请附上响应头 `request-id` |

可选的请求头，供你编写的代码使用：

| 请求头 | 作用 |
| --- | --- |
| `X-EZAT-Session: <any stable id>` | 让同一个对话的请求保持在同一份容量上，从而让提示缓存（prompt caching）持续生效。不设置时，EZAT Router 会按系统提示词和第一条消息给请求分组，这对大多数客户端已经足够。在兼容 OpenAI 的 API 上，`prompt_cache_key` 起同样的作用。 |
| `x-ezat-cache: off` | 仅限兼容 OpenAI 的 API：对本次请求关闭自动提示缓存。 |

见[提示缓存](https://docs.router.ezat.io/zh/guides/prompt-caching.md)。

## 安全的配置流程

1. **在看不到 key 的前提下找到它**。询问用户哪个环境变量保存了他们的 EZAT Router key；建议使用 `EZAT_API_KEY`。不要让用户把 key 粘贴到对话里。如果用户还没有 key，告诉他们在 `https://router.ezat.io/zh/keys` 创建一个，并在他们自己的终端中 export。
2. **确认已经设置，但不打印它**。只打印长度和前缀：

   ```bash
   printf 'length %s, prefix %s\n' "${#EZAT_API_KEY}" "${EZAT_API_KEY:0:8}"
   ```

   预期输出 `length 48, prefix ezat_sk_`。长度不对，通常是因为有引号、空格，或者复制不完整。
3. **验证 key**，用一个不花钱的请求：

   ```bash tab="curl" test
   curl --fail-with-body -sS -o /dev/null -w '%{http_code}\n' https://api.router.ezat.io/v1/models \
     -H "x-api-key: $EZAT_API_KEY"
   ```

   `200` 表示 key 可用。`401` 表示 key 缺失、输错、已过期或已被吊销：停下来告诉用户。
4. **选择模型**。使用用户要求的模型，或者从 `GET https://api.router.ezat.io/v1/models` 中选一个。不要依赖你记忆中或本页上的列表。
5. **发送一个极小的请求**，`max_tokens` 设得小一些：

   ```bash tab="curl" test
   curl --fail-with-body -sS https://api.router.ezat.io/v1/messages \
     -H "x-api-key: $EZAT_API_KEY" \
     -H "anthropic-version: 2023-06-01" \
     -H "content-type: application/json" \
     -d '{"model": "anthropic/claude-sonnet-5-5", "max_tokens": 16, "messages": [{"role": "user", "content": "Reply with OK."}]}'
   ```

   如果返回 `402`，说明组织没有余额，或者 key 达到了消费上限：告诉用户到 `https://router.ezat.io/zh/billing` 充值（或者换一个 key），然后停止。
6. **配置工具**。使用工具所用的格式：
   - Claude Code 和 Anthropic SDK：base URL 为 `https://api.router.ezat.io`。Claude Code 使用 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_AUTH_TOKEN`（[Claude Code](https://docs.router.ezat.io/zh/tools/claude-code.md)）。
   - OpenAI SDK 和 OpenAI 格式的工具：base URL 为 `https://api.router.ezat.io/openai/v1`（[OpenAI 格式的工具](https://docs.router.ezat.io/zh/tools/openai-tools.md)）。
   - 你自己的代码：在服务器端，于运行时从环境变量读取 key。

   只把 key 放在用户级或不受版本控制的配置中。修改用户没有提到的全局配置文件之前，先征得同意。
7. **在工具内验证**。通过工具本身发送一个请求。在 Claude Code 中，`/status` 会显示 base URL 和正在使用的凭据。
8. **出错时按错误类型处理**。对 `429`、`500` 和 `529`（OpenAI 格式中为 `503`）按退避策略重试；如果有 `retry-after` 响应头，至少等待其中的秒数。非流式请求返回 `504`，表示模型耗时太长：改用流式输出重新发送。不要重试 `400`、`401`、`402`、`403`、`404` 或 `413`：先解决原因。见[错误](https://docs.router.ezat.io/zh/reference/errors.md)和[故障排查](https://docs.router.ezat.io/zh/troubleshooting.md)。

## 禁止事项

- 不要让用户把 key 粘贴到对话里，也不要打印、echo 或记录 key，哪怕只是 `ezat_sk_` 前缀之外的一部分。
- 不要把 key 写进会提交的文件：源代码、受版本控制的 `.env`、项目的 `.claude/settings.json`、仓库里的 CI 配置。
- 不要把 key 放进前端、浏览器或移动应用的代码，也不要放进 URL 或查询字符串。
- 不要在 `https://api.router.ezat.io` 后面加 `/v1`，也不要把 `https://api.router.ezat.io` 交给 OpenAI 客户端：它需要的是 `https://api.router.ezat.io/openai/v1`。
- 不要写死价格或模型列表。需要时读取 `GET https://api.router.ezat.io/v1/models`、[模型](https://docs.router.ezat.io/zh/models.md)和[价格](https://docs.router.ezat.io/zh/pricing.md)。
- 不要替用户注册、付款、充值，或者创建、吊销 key。这些由用户在控制台中完成。
- 不要在未询问的情况下覆盖用户用于其他工作的现有 Anthropic 或 OpenAI 配置。只修改任务需要的部分。
- 不要循环重试 `402`，也不要只为了测试配置而发送大请求或长请求。
- 不要依赖 Message Batches、Files API、在 Anthropic 侧运行的服务端工具（网页搜索、代码执行）或 MCP connector：EZAT Router 不提供这些功能。

## 机器可读的文档

| 文件 | 内容 |
| --- | --- |
| `https://docs.router.ezat.io/llms.txt` | 索引：先列出关键值，再列出每个页面及一行描述 |
| `https://docs.router.ezat.io/llms-full.txt` | 所有页面合成的一个 Markdown 文件，已填入实时的模型表和价格表 |
| `https://docs.router.ezat.io/<page>.md` | 单个页面的 Markdown，例如 `https://docs.router.ezat.io/quickstart.md`。发送 `Accept: text/markdown` 时，页面 URL 本身也会返回 Markdown。 |
| `https://docs.router.ezat.io/openapi.yaml` | 公开的 API 规范（OpenAPI 3） |
| `https://docs.router.ezat.io/skill/ezat-router.zip` | `ezat-router` agent 技能。见 [Agent 技能](https://docs.router.ezat.io/zh/agents/skill.md)。 |

只读取你需要的页面。价格和模型列表会变化；需要时再获取，不要保留一份副本。