> 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. Objects
3. 角色
4. 背景故事

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

### Objects

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

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

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

# objects = [{"name": "Mojito","description": "For once, a VIRGIN Mojito."},
#            {"name": "Tequilla Sunrise","description": "Not my personal favourite."},
#            {"name": "White Russian","description": "The Dude's favourite drink."},
#            {"name": "A Jukebox","description": "A jukebox with lots of songs."},
#            {"name": "Freshly sliced oranges","description": "Some zesty oranges to freshen you up."},
#            {"name": "Fish and Chips","description": "Good old fish n' chips."},
#            {"name": "Some Samosas","description": "A tasty Indian snack."},
#            {"name": "Book","description": "A book to pass your time as you enjoy your meal."},
#            ]

## 高级（更好）的定义
# 定义对象的更好方法，是在名称中同时指定可以 
# 对其执行的动作。请记住，不要在 "name" 或 
# "description" 字段中使用 ;，因为它们会在 API 调用中被用作分隔符，
# 并可能导致不稳定的行为。
#
# 虽然这样定义对象可能更困难，但根据我们的经验， 
# 它能显著提升性能。"Play, Serve, Give, Call Cab"
objects = [{"name": "Mojito (可执行: Served|不可执行: Played, Given)","description": "For once, a VIRGIN Mojito."},
           {"name": "Tequilla Sunrise (可执行: Served|不可执行: Played, Given)","description": "Not my personal favourite."},
           {"name": "White Russian (可执行: Served|不可执行: Played, Given)","description": "The Dude's favourite drink."},
           {"name": "A Jukebox (可执行: Played|不可执行: Served, Given)","description": "A jukebox with lots of songs."},
           {"name": "Freshly sliced oranges (可执行: Served|不可执行: Played, Given)","description": "Some zesty oranges to freshen you up."},
           {"name": "Fish and Chips (可执行: Served|不可执行: Played, Given)","description": "Good old fish n' chips."},
           {"name": "Some Samosas (可执行: Served|不可执行: Played, Given)","description": "A tasty Indian snack."},
           {"name": "Book (可执行: Given|不可执行: Played, Served)","description": "A book to pass your time as you enjoy your meal."},
           ]
```

### 背景故事

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

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

```python
backstory = """一个可以帮助执行不同任务的酒保角色。 

它可以提供几种饮品：
1. Mojito
2. Tequilla Sunrise
3. White Russian

周围还有一些对象；它们是：
1. 一个点唱机
2. 一碗花生
3. 新鲜切片的橙子
4. Fish and Chips
5. 一些萨莫萨三角饺
6. 书

这个角色可以对上述对象执行几种动作。 
角色可以同意或不同意执行用户要求的任务。 
同样地，如果被要求对其他对象做某些事情，只有在 
可用动作能够作用于可用对象时，角色才可以执行。角色还可以执行 Call Cab
动作，如果被要求的话。"""

# 顺带一提，如果你想
# 修改内容并自行尝试，我们也提供了更新背景故事的代码。
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 的核心。要创建有效的动作，你需要确保这些动作具有通用性且简单。尽量不要让动作过于具体。例如，一个名为“Show”的动作会比“Demonstrate”更有效。类似地，“Walks To”或“Runs To”会比“Moves To”或“Go To”效果更差，因为第二组在某种意义上比第一组更“通用”。

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

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

```python
actions = "Play, Serve, Give, Call Cab"
```

### 角色

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

你应确保将关于角色的重要信息包含在知识库或背景故事中。不要把真正重要的信息放在 bio 里。

```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": "当然！你想要什么？我这里有 Mojito、Tequilla Sunrise 和 White Russian。",
#     "response": "当然！你想要什么？我这里有 Mojito、Tequilla Sunrise 和 White Russian。",
#     "actionSequence": " \nServe Mojito\n Serve Tequilla Sunrise\n Serve White Russian"
# }
```


---

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