> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/convai-playground/character-customization/external-api/external-api-limitations.md).

# 外部 API 限制

适用于整个外部 API 的限制——支持的模型、Python 运行时、库、输入模式以及每个角色的上限。

无论你是在以下位置配置 External API，这些限制都适用： [Playground](/api-docs/zh/convai-playground/character-customization/external-api.md) 或通过 [API](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md).

## 支持的模型

只有当角色的模型能够调用工具时，External API 才会运行。这取决于你使用的路径：

| 路径                   | 支持的模型                                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Live API（WebRTC）** | OpenAI、Claude 和 Gemini。支持工具调用的热门开源模型——包括 Grok 和 DeepSeek 系列——在这里也可以使用。其他模型如果支持工具调用也可能可用；请查看 [models.dev](https://models.dev). |
| **gRPC**             | 仅限 OpenAI、Claude 和 Gemini 系列模型。                                                                                               |

如果模型不支持工具，角色仍会正常聊天——只是不会调用你的 External API 函数。

## 运行时

| 规则    | 详情                                                     |
| ----- | ------------------------------------------------------ |
| 语言    | 仅限 Python（`"language": "python"`)                      |
| 运行时   | Python 3.11                                            |
| 标准库   | 允许（`json`, `datetime`, `math`, `re`, `urllib`，以及其余标准库） |
| 第三方包  | **`requests` 仅限** 目前                                   |
| 源代码长度 | 最多 400 行                                               |
| 入口点   | 必须定义 `def handle_event(inputs):` （单个参数；名称固定）           |
| 返回值   | 可 JSON 序列化，通常是一个 `dict`                                |
| 状态    | 调用之间没有共享的可变状态——每次运行都是独立的                               |

标准库之外以及 `requests` 在运行时会失败。

## 输入说明

`input_description` 是一个 **JSON 字符串** （不是 API 请求体中的嵌套对象）。解析后，它必须看起来像：

```json
{
  "parameters": {
    "city": {
      "type": "string",
      "description": "Name of the city to look up"
    }
  },
  "required": ["city"]
}
```

| 规则                  | 详情                                                |
| ------------------- | ------------------------------------------------- |
| 顶级键                 | `parameters` 和 `required` 都是必需的                   |
| 参数名                 | `^[a-zA-Z_][a-zA-Z0-9_]*$`                        |
| 参数字段                | 每个参数都需要 `type` 和 `description`                    |
| 允许的类型               | `string`, `integer`, `boolean`, `object`, `array` |
| 下面的额外键 `parameters` | 不允许                                               |

保持描述具体。模型会根据这段文本填充参数，所以模糊的措辞会导致错误的调用。

## 角色限制

| 规则         | 详情                                                       |
| ---------- | -------------------------------------------------------- |
| 每个角色的启用函数数 | 最多 **128**                                               |
| 取消关联与删除    | `"status": "inactive"` 只会解除角色的关联；delete 会将该函数从账号及所有关联中移除 |

## 相关

* [External API（Playground）](/api-docs/zh/convai-playground/character-customization/external-api.md) —— UI 设置和示例
* [External API（API reference）](/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/external-api.md) —— 创建、列出、关联、取消关联、删除


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/convai-playground/character-customization/external-api/external-api-limitations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.