> 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

{% 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 密钥>"

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

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

### Action API 的组成部分

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

1. Actions
2. 对象
3. 角色
4. 背景故事

现在让我们详细讨论这些内容。我们在这里把它们列出来，但在进行设置时，你应该回到每个部分分别查看。

### 对象

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

下面我们给出两个示例，说明如何定义物体以及如何最好地进行定义。

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

# objects = [{"name": "莫吉托","description": "难得一次，是一杯无酒精的莫吉托。"},
#            {"name": "特基拉日出","description": "不是我个人最喜欢的。"},
#            {"name": "白俄罗斯","description": "那个家伙最喜欢的饮品。"},
#            {"name": "点唱机","description": "一台有很多歌曲的点唱机。"},
#            {"name": "新鲜切片橙子","description": "一些清爽带劲的橙子，让你精神一振。"},
#            {"name": "炸鱼薯条","description": "经典的炸鱼薯条。"},
#            {"name": "一些萨莫萨","description": "一种美味的印度小吃。"},
#            {"name": "书","description": "一本让你在享用餐点时打发时间的书。"},
#            ]

## 高级（更好的）定义
# 定义物体的更好方法是，在名称中也指定可以在其上执行哪些动作 
#。请记住，切勿在“name”或 
# “description”字段中使用 ;，因为它们会在 API 调用中被用作分隔符，并且
# 可能会导致不稳定的行为。
#
# 虽然这样定义物体可能更困难，但根据我们的经验 
# 它能大幅提升性能。"播放、提供、给予、叫出租车"
objects = [{"name": "莫吉托（可以：提供|不可以：播放、给予）","description": "难得一次，是一杯无酒精的莫吉托。"},
           {"name": "特基拉日出（可以：提供|不可以：播放、给予）","description": "不是我个人最喜欢的。"},
           {"name": "白俄罗斯（可以：提供|不可以：播放、给予）","description": "那个家伙最喜欢的饮品。"},
           {"name": "点唱机（可以：播放|不可以：提供、给予）","description": "一台有很多歌曲的点唱机。"},
           {"name": "新鲜切片橙子（可以：提供|不可以：播放、给予）","description": "一些清爽带劲的橙子，让你精神一振。"},
           {"name": "炸鱼薯条（可以：提供|不可以：播放、给予）","description": "经典的炸鱼薯条。"},
           {"name": "一些萨莫萨（可以：提供|不可以：播放、给予）","description": "一种美味的印度小吃。"},
           {"name": "书（可以：给予|不可以：播放、提供）","description": "一本让你在享用餐点时打发时间的书。"},
           ]
```

### 背景故事

重要的是要知道，背景故事也会影响 Action API 的表现。要有效生成动作，最重要的一点是在背景故事本身中加入一些关于物体、角色和动作的信息。（你也可以使用知识库来放入这些信息，但我们建议改用背景故事来完成）这里我们将给出一个示例。你可以看到我们如何说明场景中有哪些物体，以及关于它们的一些信息。如果可以的话，最好也在这里指定一些有关环境的信息。

关于角色本身的任何信息都可以放在知识库中。

```python
backstory = """一个酒保角色，能够帮助执行不同任务。 

它可以提供几种饮品：
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)

```

### Actions

Action 是此 API 的核心。要创建有效的动作，你需要确保这些动作能够普遍适用且简单。尽量不要把动作设得过于具体。例如，名为“Show”的动作会比“Demonstrate”更有效。同样，“Walks To”或“Runs To”也不如“Moves To”或“Go To”有效，因为后一组在某种意义上比前一组更“通用”。

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

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

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

### 角色

这很简单，只需提供场景中存在的角色即可。你可以添加两个以上的角色；例如，如果你在一家餐厅里和多人在一起，可以把他们都加在这里。

你应确保把角色的重要信息放在知识库或背景故事中。不要把任何真正重要的信息写在 bio 里。

```python
characters = [{"name": "用户", "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 dynamically by asking a question.

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

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

The question should be specific, self-contained, and written in natural language.
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.