Characters

角色是用户在通话里交谈的对象：一张脸、一个声音，以及它怎么想、怎么做——它的指令、它知道什么、它能做什么。你在 AvatarGo 控制台里搭建一次，之后用它的 ID（ch_…）开会话。

角色由什么组成

角色在控制台的 Build 页面上搭建，每个标签设置其中一部分：

标签	设置什么
Avatar	脸——你上传的，或系统提供的——以及渲染它的 avatar model。
Card	名字、卡片上的一句话简介，以及用户说的语言（用于语音识别；不填则自动识别）。
Prompt	System prompt（它的指令）、通话开始时说的 First greeting，以及 Knowledge：它回答时可以检索的文档。
Voice	它说话用的声音。
LLM	生成回答的语言模型。
Tools	通话中它能做的事：结束通话、调用你的服务器、在你的页面里执行代码、检索知识库。
Advanced	通话怎么进行：语音识别、用户停下多久算说完、沉默多久挂断、一通电话最长多久。

设置旁边的试打通话让你边改边和它对话。

提示词。 你的 system prompt 会被一字不差地使用。在它之后，每通通话里 AvatarGo 还会加上自己的规则，并以这些规则为准：角色在语音通话里，所以只说话——不写「（微笑）」之类的舞台说明，不用 Markdown、列表或 emoji；它会被告知用户所在地的今天日期；还有任何角色都不能越过的界线。

知识库。 把文档——PDF、Word（.docx）、纯文本、Markdown、CSV 或 JSON——上传到知识库文件夹。通话中角色会检索它们，根据找到的内容回答。tool_call_* 事件会显示每次检索以及用到了哪些文档。

工具。 角色可以使用内置工具（比如结束通话），也可以使用你创建的工具：

Webhook——通话中 AvatarGo 调用你的 HTTPS 接口，把返回交给角色。
Client——由你的页面通过 JavaScript SDK 执行。见 Client tools。
Knowledge——检索你选定的知识库文件夹。

通话怎么进行（Advanced 标签）：

设置	默认值
End-of-speech sensitivity	Balanced	用户停下后角色等多久再回答：Eager 0.3–1.0 秒，Balanced 0.5–2.0 秒，Patient 0.8–3.5 秒。
End call after silence	60 秒	双方都沉默这么久，角色挂断（会话以 `idle_timeout` 结束）。
Max call length	2 小时	不会超过你的套餐允许的时长。你的服务器可以为单通会话设一个更短的。

草稿与发布

你在 Build 页面上的改动是草稿。控制台的试打通话用草稿；用你的 API key 创建的会话只用已发布的版本，所以用户永远不会遇到改到一半的角色。

Publish 把草稿变成已发布版本，从下一通通话起生效。正在进行的通话继续用它开始时的版本。
发布前会先拿你的提示词对照 AvatarGo 自己的规则。与规则冲突的指令——要求用 emoji 或舞台说明、让角色否认自己是 AI、让它索要一次性验证码——会挡住发布，控制台会列出每一句及原因。
Discard changes 丢弃草稿，回到已发布的版本。
Unpublish 让它停用：用它的 ID 开会话会被拒绝（409 character_not_published），直到你再次发布。只有试打通话能用它。

按 Build 页面顶部的 Copy character ID，复制你的服务器要发送的 ID。

预设

AvatarGo 提供一些现成的角色，覆盖常见用途。可以在控制台里试；想修改就复制一份——副本归你，可以编辑和发布。预设也可以直接用它的 ID 原样使用。

在会话里使用角色

你的服务器在创建会话时指定它（见 Quick start）：


body: JSON.stringify({ characterId: "ch_…" })

会话按角色的已发布版本说话：它的脸、avatar model、提示词、开场白、语言、声音、模型和最长时长。

要为某一通会话改动其中一部分，再发送 characterConfig：其中每个字段都会替换角色自己的，只对这通会话有效——比如带上用户名字的开场白。也可以不带 characterId，在 characterConfig 里写出整个角色，用于你不在控制台里保存的角色。无论哪种，它都留在 AvatarGo 这边：浏览器看不到。字段与角色的字段相同；见 API 参考里的 POST /v1/auth/session-token。

角色也可以用 API 创建、修改和发布：/v1/characters，同样分草稿和发布两步。