> 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/api-can-kao/core-api-reference/character-crafting-apis/action-api.md).

# 动作 API

参考面向现有客户端保留的基于字符串的 Action API 工作流，并查找面向新集成的 Agentic Actions 和 Live API 替代方案。

本页保留基于字符串的 Action API 工作流，供现有客户端调用 `POST /character/getResponse`.

{% hint style="warning" %}
**自 2026 年 8 月 26 日起，新动作集成已弃用。** 使用 [代理式动作](/api-docs/zh/convai-playground/character-customization/agentic-actions.md) 用于编写角色契约，然后使用 [连接 API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md) 或当前的 SDK 来声明并接收结构化动作。现有客户端在迁移期间可以继续使用本页。
{% endhint %}

{% hint style="danger" %}
此 API 仅适用于专业版及以上计划。
{% endhint %}

如果对话能够推动你角色的行为并赋予其操控环境的能力，它们就会变得更有吸引力。Action API 通过允许你定义角色可以执行的各种动作来实现这一点。这些动作通常与环境中可用的对象相关联。

要充分使用 Action API，需要先理解几件事，才能把它的作用发挥到最大。这里我们说明一些原则，指导你如何编写这些内容。

本教程将使用代码示例和注释来展示如何有效使用 Action API。

### 设置

要顺利跟着本教程操作，需要先完成以下设置。只要创建一个 Colab 笔记本，不安装任何软件包，也足以跟着进行。

```python
# 导入几个库
import base64
import json
import requests

# 在这里使用你的角色 ID
CHAR_ID = "<你的角色 ID>"

# 你应该在这里设置你的 Convai API 密钥
CONVAI_KEY = "<你的 convai api key>"

# 这是将生成动作和响应的 URL
action_url = "https://api.convai.com/character/getResponse"

# 用于更新背景故事的 URL
url = "https://api.convai.com/character/update"
```

### Action API 的组成部分

在环境中生成动作所需的基本构成如下。

1. 操作
2. 对象
3. Characters
4. 背景故事

现在让我们详细讨论这些内容。我们在这里把它们列出来，但在配置时你应该回到各个部分逐一查看。

### 对象

同动作一样，关于对象也有一些细节是用户需要了解的。如果你有多个相似对象，最好给它们编号。例如，不要写“5 把椅子”，而应该写“椅子#1”“椅子#2”等。如果你需要角色给你带来某个特定对象，也应该明确提出，例如“给我带 3 号椅子”。你还可以提到能与该对象交互的动作，以提高效果。

下面我们提供两个定义对象的示例，并说明如何更好地定义它们。

```python
## 基本定义
# 定义动作最简单的方式如下，使用 convert()
# 函数，我们可以直接将其转换为 API 所需的形式， 
# API 参考将说明如何进行 API 调用。

# objects = [{"name": "莫吉托","description": "难得一次，是一杯无酒精莫吉托。"},
#            {"name": "龙舌兰日出","description": "不是我个人最喜欢的。"},
#            {"name": "白俄罗斯","description": "The Dude 最喜欢的饮料。"},
#            {"name": "点唱机","description": "一台有很多歌曲的点唱机。"},
#            {"name": "新鲜切片橙子","description": "一些清新的橙子，帮你提提神。"},
#            {"name": "炸鱼薯条","description": "经典的炸鱼薯条。"},
#            {"name": "一些咖喱角","description": "美味的印度小吃。"},
#            {"name": "书","description": "一本让你在享用餐点时打发时间的书。"},
#            ]

## 高级（且更优）的定义
# 更好的对象定义方式，是同时说明这些对象可以被执行哪些 
# 动作。请记住，不要在 "name" 或 
# "description" 字段中使用 ;，因为它们会被用作 API 调用中的分隔符，
# 并可能导致不稳定的行为。
#
# 虽然这样定义对象可能更困难，但根据我们的经验， 
# 它会大大提升性能。“播放、提供、给予、叫出租车”
objects = [{"name": "莫吉托（可执行：提供｜不可执行：播放、给予）","description": "难得一次，是一杯无酒精莫吉托。"},
           {"name": "龙舌兰日出（可执行：提供｜不可执行：播放、给予）","description": "不是我个人最喜欢的。"},
           {"name": "白俄罗斯（可执行：提供｜不可执行：播放、给予）","description": "The Dude 最喜欢的饮料。"},
           {"name": "点唱机（可执行：播放｜不可执行：提供、给予）","description": "一台有很多歌曲的点唱机。"},
           {"name": "新鲜切片橙子（可执行：提供｜不可执行：播放、给予）","description": "一些清新的橙子，帮你提提神。"},
           {"name": "炸鱼薯条（可执行：提供｜不可执行：播放、给予）","description": "经典的炸鱼薯条。"},
           {"name": "一些咖喱角（可执行：提供｜不可执行：播放、给予）","description": "美味的印度小吃。"},
           {"name": "书（可执行：给予｜不可执行：播放、提供）","description": "一本让你在享用餐点时打发时间的书。"},
           ]
```

### 背景故事

重要的是要知道，背景故事也会影响 Action API 的表现。要让动作生成更有效，最重要的一点是把对象、角色和动作的部分信息直接写进背景故事里。（你也可以把这些信息放进知识库，但我们更建议用背景故事来完成）下面我们会给出一个示例，展示如何这样做。你可以看到我们是如何说明场景中有哪些对象，以及它们的一些信息。如果可以的话，在这里补充一些环境信息也会很好。

有关角色本身的任何信息都可以放入知识库。

```python
backstory = """一个酒保角色，可以帮助执行不同任务。\n它可以提供几种饮料：\n1. 莫吉托\n2. 龙舌兰日出\n3. 白俄罗斯\n\n它周围还有一些物品；它们是：\n1. 点唱机\n2. 一碗花生\n3. 新鲜切片橙子\n4. 炸鱼薯条\n5. 一些咖喱角\n6. 书\n\n这个角色可以对上面列出的物品执行一些动作。\n角色可以同意或拒绝执行用户要求的任务。\n同样，如果被要求对其他物品做某事，角色只有在\n可用动作能够作用于可用物品时才能执行。若有请求，角色还可以执行“叫出租车”\n动作。""" 

它可以提供几种饮料：
1. 莫吉托
2. 龙舌兰日出
3. 白俄罗斯

它周围还有一些物品；它们是：
1. 点唱机
2. 一碗花生
3. 新鲜切片橙子
4. 炸鱼薯条
5. 一些咖喱角
6. 书

这个角色可以对上面列出的物品执行一些动作。 
角色可以同意或拒绝执行用户要求的任务。 
同样，如果被要求对其他物品做某事，角色只有在 
可用动作能够作用于可用物品时才能执行。若有请求，角色还可以执行“叫出租车”
动作。"""

# 顺带一提，如果你想修改内容并自行尝试，我们也提供了更新背景故事的代码。
# 更改一下试试看。
payload = json.dumps({
  "charID": CHAR_ID,
  "backstory": backstory,
})
headers = {
  'CONVAI-API-KEY': CONVAI_KEY,
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

```

### 操作

动作是此 API 的核心。要创建有效的动作，你需要确保这些动作足够通用且简单。尽量不要把动作设定得过于具体。例如，叫作“展示”的动作会比“演示”更有效。同样，“走向”或“跑向”也不如“移动到”或“前往”更有效，因为后者在某种意义上比前者更“通用”。

在定义动作时，你还应该保持大小写风格一致。如果你采用小写，那么所有动作都写成小写，依此类推。为了获得最佳效果，动作也必须符合角色背景语境。

动作可以通过 API 调用发送，也可以在 Playground UI 中设置。这里我们演示 API 调用版本。如果你想用 UI 来设置，请前往 <https://convai.com/pipeline/dashboard/character> 并点击 Actions 按钮，添加你的动作，最后点击 `Update` 按钮。

```python
actions = "播放、提供、给予、叫出租车"
```

### Characters

提供场景中的角色。你可以添加两个以上的角色；例如，如果你在一家有多个人的餐厅里，也可以把他们都添加到这里。

你应确保把有关角色的重要信息包含在知识库或背景故事中。不要把简介用于任何真正重要的信息。

```python
characters = [{"name": "User", "bio": "这是使用 Action API 的人。"},
              {"name": "Action-API-Doc-Bot", "bio": "帮助在 Convai 这里创建文档。"},]
```

### API 参考

现在我们可以用 API 参考以及调用 Action API 的各种方式来完成本教程了。

```python
userText = input("请输入你的命令：")

payload={'userText': userText,
  'charID': CHAR_ID,
  'sessionID': '-1',
  'voiceResponse': 'false',
  'actions': actions,
  'classification':'multistep', 
  'objects': json.dumps(objects),
  'characters': json.dumps(characters),
  }

files = []

headers = {
  'CONVAI-API-KEY': CONVAI_KEY 
}

response = requests.request("POST", action_url, headers=headers, data=payload, files=files)

response = json.loads(response.text)

print(json.dumps(response, indent=4))

# 响应体
# {
#     "userQuery": "你能给我一杯饮料吗？",
#     "charID": "17e9cbde-abcd-11ed-9d60-42010a80000d",
#     "sessionID": "4ba18da3db1627953bf04f3a4021779f",
#     "text": "当然！你想要什么？我这里有莫吉托、龙舌兰日出和白俄罗斯可供选择。",
#     "response": "当然！你想要什么？我这里有莫吉托、龙舌兰日出和白俄罗斯可供选择。",
#     "actionSequence": " \n提供莫吉托\n 提供龙舌兰日出\n 提供白俄罗斯"
# }
```


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/action-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.