> ## Documentation Index
> Fetch the complete documentation index at: https://steadyrenew.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 工具使用

> 把开放 API 作为 AI Agent 的工具使用，包括操作语义、确认规则和错误恢复建议。

# AI 工具使用

首次接入请先看[连接 Agent](/docs/zh-CN/user-guide/agent-setup)。设置页的 **复制给 Agent** 会带上当前网站地址、MCP 下载链接和 API 定义。

开放 API 可以暴露给 AI 助手作为工具使用。如果框架支持 JSON tool/function 定义，使用 [AI tool schema](/docs/api/ai-tools.json)。如果框架支持直接导入 OpenAPI，使用 [OpenAPI schema](/docs/api/openapi.yaml)。

## 推荐 Agent 策略

允许 AI 写入前，建议给助手这段规则：

```text theme={null}
你可以直接查询订阅。
创建、更新或删除订阅前，必须总结即将执行的变更并询问用户确认。
删除前，必须重复订阅名称和 id。
不要发送服务端管理字段：id、createdAt、updatedAt。下次续费日期使用 nextPaymentDate。
如果 API 返回 field、suggestedFix、allowedValues 或 writableFields，使用这些提示修正 payload。
```

## 工具选择

| 用户意图 | 工具 |
| - | - |
| “显示我的订阅” | `list_subscriptions` |
| “找到我的 Netflix 订阅” | `list_subscriptions`，再按名称或分类匹配 |
| “显示这个 id 的详情” | `get_subscription` |
| “添加 ChatGPT Plus” | 确认后调用 `create_subscription` |
| “把 Netflix 改成年付” | `list_subscriptions`，确认目标和变更后调用 `update_subscription` |
| “删除重复的 Netflix 记录” | `list_subscriptions`，确认名称和 id 后调用 `delete_subscription` |
| “提醒开了吗 / 提前 7 天提醒我” | `get_notification_settings` / 确认后 `update_notification_settings` |
| “这是我的 Bark URL，帮我配置” | 拒绝；引导到[续费提醒指南](/docs/zh-CN/user-guide/reminders) |

## 风险等级

| 风险 | 操作 | Agent 行为 |
| - | - | - |
| 低 | 查询列表、查询单条 | 用户要求时可直接执行 |
| 中 | 创建、更新 | 调用前确认计划写入内容 |
| 高 | 删除 | 调用前确认准确记录名称和 id |

公开 API 不支持通过 `status` 做软取消/暂停/恢复。如果用户说“取消订阅”，需要先确认：是删除本地追踪记录，还是要去外部服务真正取消订阅。

Bark URL、test push、时区和 locale 也不能通过公开 API 配置；引导用户到网页端设置与[续费提醒指南](/docs/zh-CN/user-guide/reminders)。

## 示例流程

用户：

```text theme={null}
把 Netflix 改成年付。
```

助手：

1. 调用 `list_subscriptions`。
2. 找到 Netflix 记录。
3. 询问确认：

```text theme={null}
我找到了 Netflix（33333333-3333-4333-8333-333333333333），当前为 monthly。我将把 period 改为 yearly，并保留当前的下次续费日期。确认执行吗？
```

4. 用户确认后，调用 `update_subscription`：

```json theme={null}
{
  "id": "33333333-3333-4333-8333-333333333333",
  "patch": {
    "period": "yearly"
  }
}
```

## 错误恢复

错误响应使用稳定结构：

```json theme={null}
{
  "error": {
    "code": "invalid_subscription",
    "message": "Invalid option",
    "field": "period",
    "suggestedFix": "Use one of the supported billing periods: monthly, yearly, custom.",
    "allowedValues": ["monthly", "yearly", "custom"]
  },
  "requestId": "request-..."
}
```

使用 `field` 和 `suggestedFix` 修正下一次请求。如果是写操作，并且修正后的 payload 改变了实际写入内容，需要重新向用户确认。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.