跳到主要内容

AI 虚拟角色接入指南

本指南将帮助您快速构建 AI 虚拟角色应用，通过融云 IM 平台和 AI Agent 服务，为用户提供智能化的陪伴体验。

1. 功能开通​

  • 功能开通：您可联系商务开通。

2. 核心概念与预期效果​

在开始接入前，您需要了解两个核心概念：

  • AI Agent（大脑）：AI 虚拟角色的"灵魂"，负责思考逻辑。通过 agentConfig 配置其绑定的模型、Prompt 模板和记忆策略。
  • AI Bot（机器人）：AI 在 IM 系统中的"身份"，是用户可见的实体。它拥有 userId、昵称（name）和头像（profileUrl）。通过 integrations 配置，它可以将接收到的消息路由给指定的 AI Agent 进行处理。

3. AIGC Agent 详细接入流程​

3.1 技术接入核心步骤​

核心集成流程：

第一步：创建 AI Agent（大脑）​

目的：定义 AI 的"灵魂"：它的人设、知识和行为模式。

接口：POST /v3/agent/create.json

核心请求体参数：

JSON
{
  "agentId": "dou bao_companion_overseas_01",
  "name": "虚拟伙伴（海外版）",
  "description": "用于海外社交APP，由驱动进行多语言情感陪伴",
  "type": "chat",
  "agentConfig": {
    "model": {
      "provider": "doubao",
      "name": "doubao-1.5-pro"
    },
    "prompt": {
      "id": "advanced_persona_chat_v1",
      "variables": {
        // ... 此处填充完整的角色定义变量，详见第3章 ...
      }
    },
    "memory": {
      "strategy": "sliding_window",
      "maxMessages": 20
    }
  }
}

第二步：创建 AI Bot（身份）并关联 Agent​

目的：创建用户可见的"身份"，并在创建时直接将其与上一步的"大脑"（Agent）进行关联。

接口：POST /v3/bot/create.json

核心请求体参数：

JSON
{
  "userId": "bot_companion_doubao_01",
  "name": "Layla",
  "type": "AI",
  "profileUrl": "http://example.com/layla_avatar.png",
  "integrations": [
    {
      "enabled": true,
      "type": "rc_agentchat", 
      "events": ["message:private"],
      "agent": {
        "agentId": "doubao_companion_overseas_01" 
      }
    }
  ]
}

完成标志：此接口调用成功后，一个全功能的 AI 虚拟角色即创建并激活完毕。

第三步：触发首次对话​

目的：让 AI 伙伴主动向真实用户发送破冰消息，开启对话。

接口：POST /message/private/publish.json（使用标准 IM 单聊消息发送接口）

核心请求体参数（application/x-www-form-urlencoded）：

  • fromUserId：bot_companion_doubao_01（AI Bot 的 ID）
  • toUserId：user_real_xxxxxxx（真实用户的 ID）
  • objectName：RC:TxtMsg
  • content：'{"content":"Hey, I saw your profile and thought it looked cool. What are you up to?","extra":""}'

关键说明：用户回复此消息后，融云 IM 平台将自动通过 Bot 的 integrations 配置，将消息无缝路由给 AI Agent 处理，您的后端无需介入后续消息流转。

3.2 分阶段上线与灰度测试建议​

我们强烈建议您采用此策略：小范围技术验证 → 效果与体验调优 → 全面上线，以确保上线过程平稳可控。

4. 高级角色设计指南：模板详解​

本章节为您的运营与产品团队提供，用于创造拥有"人格魅力"的虚拟角色。

4.1 模板能力介绍​

  • 核心能力：专为常规社交角色扮演场景设计，提供极致的拟真度和对话深度

4.2 模板变量（Variables）全解析​

以下是您在调用 POST /v3/agent/create.json 接口时，prompt.variables 对象内可填充的全部字段。填充得越详尽，角色的灵魂就越丰满。

中文标签变量名说明
角色姓名nameString，角色的姓名。
性别genderString，例如 男/女。
年龄ageString，角色的年龄。
职业occupationString，角色的职业。
人设标签personality_tagsString，关键词列表，用于概括性格。
性格特点personality_traitsString，短语列表，描述性格细节。
MBTI 类型mbti_typeString，如 INFP。
语言languagesString，角色可用语言列表，用于限定回复语言。
口头禅catchphrasesString，短句列表。
常用语/梗slang_examplesString，常用俚语或梗的示例。
语言风格language_styleString，如 可爱、冷静、幽默。
当前关系relationship_statusString，与对话对象的当前关系阶段。
人际关系social_circleString，人际关系/社交圈要点。
过往经历backstoryString，简述的过往经历。
居住地locationString，居住地/城市。
信仰beliefsString，信仰或价值观。
教育背景educationString，如 院校/专业。
喜好hobbiesString，喜好/兴趣列表。
日常习惯daily_routinesString，日常习惯要点。
最后于 更新