Sonzai Docs

API 参考

用于创建智能体并通过 REST API 与其交互的公共参考。 内部上下文组装、记忆管理和状态编排由平台管理，此处有意省略。

身份验证

所有 API 调用都需要使用项目 API 密钥进行 Bearer 身份验证。

Authorization: Bearer YOUR_PROJECT_API_KEY

REST API

用于智能体生命周期、实时智能体交互和主动投递的公共 HTTP 端点。 记忆、情绪、关系和上下文管理内部机制由平台处理。

仅限服务端。 该 API 不接受浏览器请求。对于 Web 应用，请通过后端代理。请参阅 集成指南。

智能体生命周期

POST/api/v1/agents

创建新智能体。返回带有平台生成的 UUID 的智能体。

参数

namestring智能体名称（必填）
personality_promptstring自定义系统提示（可选）
big5object大五人格评分：openness、conscientiousness、extraversion、agreeableness、neuroticism (0.0-1.0)
speech_patternsstring[]语言模式（可选）
true_interestsstring[]智能体兴趣（可选）
project_idstring分配智能体的项目 UUID（可选）
languagestringISO 语言代码，如 "en"（可选）

响应

{ "agent_id": "uuid", "name": "...", ... }

GET/api/v1/agents

列出智能体。通过 project_id 查询参数筛选。

参数

project_idstring按项目筛选（查询参数，可选）

响应

智能体对象数组

GET/api/v1/agents/{agentId}

通过 ID 获取智能体。

响应

包含人格、情绪、资料的智能体对象

对话

POST/api/v1/agents/{agentId}/chat

通过 SSE 流式传输与智能体对话。返回 Server-Sent Events。

参数

messagesCEChatMessage[]对话消息
user_idstring用户标识符

响应

聊天完成块的 SSE 流

主动通知

GET/api/v1/agents/{agentId}/notifications

列出待处理的主动消息。

参数

statusstring按状态筛选：pending | consumed（默认：pending，查询参数）
user_idstring按用户筛选（可选，查询参数）
limitint最大结果数（默认：50，最大：500，查询参数）

响应

主动消息列表，包含 message_id、agent_id、user_id、check_type、intent、generated_message、status、created_at

POST/api/v1/agents/{agentId}/notifications/{messageId}/consume

投递后将通知标记为已消费。

响应

确认

GET/api/v1/agents/{agentId}/notifications/history

列出所有状态的通知。

响应

完整通知历史

智能体生命周期（详细）

CreateAgent

创建具有人格配置的新智能体。生成人格提示、语言模式和情感倾向。

请求

user_idstring所有者用户标识符
agent_namestring智能体显示名称
genderstring"male"、"female" 或 "non_binary"
biostring智能体传记（可选）
avatar_urlstring头像图片 URL（可选）
big5CEBig5Scores大五人格评分 (0.0-1.0)
languagestring主要语言
equipped_outfitstring初始装扮 ID（可选）
skillsCESkillLevel[]初始技能等级（可选）
model_tierint32LLM 模型层级（可选）
project_idstring分配智能体的项目（可选）
agent_idstring调用方指定的 ID，用于确定性智能体（可选）
personality_promptstring自定义系统提示（可选）
generate_goalsbool创建后自动生成目标（可选）
provided_goalsstring[]直接存储这些目标（可选）
speech_patternsstring[]语言模式（可选）
true_interestsstring[]智能体兴趣（可选）
true_dislikesstring[]智能体不喜欢的（可选）
user_display_namestring所有者显示名称（可选）
generate_avatarbool创建时自动生成 AI 头像（默认：true，消耗 1 积分）。设为 false 可跳过。

响应

agent_id (UUID)、status ('completed' 或 'in_progress')

GetAgent

检索智能体当前状态，包括人格、情绪和资料。

请求

agent_idstring智能体 UUID

响应

Agent ID、name、bio、gender、avatar_url、Big5 scores、owner、created_at

UpdateAgent

更新智能体字段（名称、传记、头像、人格、兴趣、语言模式）。

请求

agent_idstring智能体 UUID
namestring新名称（可选）
biostring新传记（可选）
avatar_urlstring新头像 URL（可选）
big5CEBig5Scores更新的 Big5 评分（可选）
true_interestsstring[]更新的兴趣（可选）
true_dislikesstring[]更新的不喜欢的（可选）
speech_patternsstring[]更新的语言模式（可选）
personality_promptstring更新的系统提示（可选）

响应

success (bool)

DeleteAgent

永久删除智能体及所有关联数据（记忆、情绪、关系）。

请求

agent_idstring智能体 UUID

响应

success (bool)

RegenerateAvatar

为智能体生成或重新生成 AI 创建的头像。使用 LLM 根据人格数据创建图像提示，然后生成并上传图像。消耗 1 积分。除非禁用，头像在智能体创建时自动生成。

请求

agent_idstring智能体 UUID（URL 参数）
stylestring可选的风格提示（如 'watercolor anime'、'realistic portrait'）

响应

success (bool)、avatar_url (string)、prompt (string)、generation_time_ms (int64)

UpdateAgentPersonality

当您的产品有意更改智能体设计时，更新智能体的创作大五人格配置。

请求

agent_idstring智能体 UUID
big5CEBig5Scores更新的大五人格评分（含置信度）

响应

success (bool)

主动行为

ScheduleWakeup

安排智能体在延迟后主动联系用户。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
check_typestring检查类型：check_in、follow_up、mood_driven
intentstring智能体想要联系的原因
delay_hoursint32唤醒前的延迟小时数

响应

wakeup_id (string)、scheduled_at (Timestamp)

GetPendingWakeups

检索智能体待处理的唤醒事件。

请求

agent_idstring智能体 UUID

响应

PendingWakeup 列表 (wakeup_id、user_id、check_type、intent、scheduled_at)

流式对话

主要的公共对话 RPC。发送智能体、用户、应用上下文和消息历史； 平台自动处理上下文组装和状态更新。

StreamChat

流式传输智能体交互的 AI 响应，同时平台在后台处理内部记忆和状态更新。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
session_idstring唯一会话 ID
game_contextGameContext应用状态上下文
messagesCEChatMessage[]对话消息
continuation_tokenstring从上一个响应恢复（可选）
request_typestring"chat"、"guide" 或 "outing"
capabilitiesstring[]已解锁的能力（可选）
languagestringISO 语言代码（可选）
interaction_rolestring"owner" 或 "non_owner"
skill_levelsmap<string, int32>技能等级（可选）

响应

StreamChatEvent 流 (delta | message_boundary | complete | side_effects | error)

StreamChatEvent 是一个 oneof，包含以下事件类型：

StreamChatDelta (delta)
contentstringAI 的文本块
message_indexint32多消息响应中的索引
is_follow_upbool是否为后续消息
replacementbool如果为 true，则替换所有之前的内容
StreamChatComplete (complete)
full_contentstring完整响应文本
finish_reasonstring"stop"、"length" 或 "content_filter"
continuation_tokenstring用于继续对话的令牌
message_countint32响应中的消息数量
StreamChatError (error)
messagestring错误消息
codestring错误代码

AI 生成

平台管理的 AI 内容生成，用于传记、目标、人格、日记条目和图像。

GenerateBio

基于人格和上下文使用 AI 生成或重写智能体的传记。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
current_biostring用于重写的当前传记（可选）
stylestring风格：casual、formal、poetic 等（可选）

响应

bio (string)、tone (string)、confidence (double)

GenerateGoals

基于特质、兴趣和记忆为智能体生成人格驱动的目标。

请求

agent_idstring智能体 UUID
agent_namestring智能体显示名称
big5CEBig5ScoresBig5 评分
true_interestsstring[]智能体兴趣
true_dislikesstring[]智能体不喜欢的
speech_patternsstring[]语言模式
recent_memoriesCERecentMemory[]用于上下文的近期记忆
current_goalsCEGoalSummary[]现有目标以避免重复
max_goalsint32最大生成目标数
model_configCEModelConfigLLM 模型配置（可选）
custom_contextmap<string, string>应用特定上下文（可选）

响应

CEGeneratedGoal 列表 (type、title、description、priority、related_traits)、reasoning

GeneratePersonality

从模板和 Big5 评分生成语言模式和兴趣。

请求

template_idstring模板标识符
base_promptstring基础人格提示
big5CEBig5ScoresBig5 评分
agent_namestring智能体名称
genderstring智能体性别

响应

speech_patterns (string[])、true_interests (string[])、used_fallback (bool)

GenerateDiary

从对话消息和/或应用事件生成日记条目。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
datestringYYYY-MM-DD 格式的日期
agent_namestring智能体显示名称
languagestring生成内容的语言
messagesCEDiaryMessage[]对话消息 (role、content、time)
trigger_typestringdaily_summary、achievement、milestone、breakthrough
trigger_contextCEDiaryTriggerContext事件触发上下文（可选）
modelstringLLM 模型覆盖（可选）
temperaturedouble温度覆盖（可选）
timezonestring日期处理的时区（可选）

响应

user_id、date、diary (title、body_lines、tags)、generation_time_ms

GenerateImage

从文本提示生成图像并存储到云存储。

请求

promptstring图像生成提示
negative_promptstring负面提示（可选）
modelstring使用的模型（可选）
providerstring使用的提供商（可选）
output_bucketstring输出 GCS 存储桶（可选）
output_pathstring存储桶中的输出路径（可选）
cdn_domainstring公共 URL 的 CDN 域名（可选）

响应

success、image_id、gcs_uri、public_url、mime_type、generation_time_ms、error

语音与媒体

语音匹配、文本转语音、语音聊天和反思能力。

VoiceMatch

根据人格特质为智能体匹配合适的 TTS 语音。

请求

big5CEBig5Scores用于匹配的 Big5 评分
preferred_genderstring偏好的语音性别（可选）
agent_idstring智能体 UUID（如果不提供 big5 则自动查找）

响应

voice_id、voice_name、match_score、reasoning

TextToSpeech

使用 Google Gemini 语音进行文本转语音，具有情感上下文感知。

请求

textstring要转换的文本
voice_namestringGemini 语音名称
languagestring语言代码（可选）
emotional_contextCEEmotionalContext情感主题和语调（可选）

响应

audio (bytes)、content_type、voice_name

VoiceChat

单轮语音聊天：转录音频、生成 AI 响应、返回 TTS 音频。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
audiobytes原始音频数据
audio_formatstring音频格式 (opus、pcm、wav)
voice_namestringTTS 语音名称
continuation_tokenstring从上一轮恢复（可选）
languagestring语言代码（可选）
game_idstring应用标识符（可选）

响应

transcript、response (text)、audio (bytes)、content_type、continuation_token、side_effects_json

ListVoices

列出可用的 Gemini TTS 语音，可选按性别筛选。

请求

genderstring按性别筛选（可选）

响应

CEGeminiVoice 列表 (name、gender)

Reflect

生成关于能力解锁、里程碑或其他事件的 AI 反思。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
reflection_typestring"capability_unlock"、"milestone" 等
capabilitystring能力名称
capability_sourcestring能力来源
contextstring附加上下文字符串（可选）
new_capabilities_jsonbytes新能力 JSON（可选）
session_idstring用于自动构建上下文的会话 ID（可选）
interaction_rolestring"owner" 或 "non_owner"（默认："owner"）

响应

success (bool)、reflection (string)、side_effects_json (bytes)

流式语音聊天

具有服务端 VAD（语音活动检测）的双向流式语音聊天。 客户端持续流式传输音频块；服务器处理语音检测、转录、AI 响应和 TTS。

StreamVoiceChat

双向流式传输：客户端发送初始化 + 音频块，服务器返回转录和 TTS 音频。无需手动停止按钮。

请求

initVoiceChatInit第一条消息：会话初始化
audio_chunkVoiceAudioChunk后续消息：原始音频数据

响应

事件流：ready | vad | transcript | response_delta | audio | turn_complete | error

VoiceChatInit
agent_idstring智能体 UUID
user_idstring用户标识符
audio_formatstring"opus"、"pcm"、"wav"（默认："opus"）
sample_rateint32采样率（Hz）（opus 默认：48000）
voice_namestringTTS 语音名称
languagestring语言代码（默认："en"）
game_idstring应用标识符
continuation_tokenstring从上一个会话恢复（可选）
VoiceAudioChunk
audiobytes原始音频数据（如 Opus 帧）
end_of_speechbool可选的客户端 VAD 提示

服务器响应事件：

VoiceStreamReady
session_idstring分配的会话 ID
VoiceStreamVAD
speakingbooltrue = 语音开始，false = 语音结束
VoiceStreamTranscript
textstring转录文本
is_finalbooltrue = 此次话语的最终转录
VoiceStreamAudio
audiobytes音频数据块
content_typestring如 "audio/opus"、"audio/wav"
VoiceStreamTurnComplete
continuation_tokenstring用于继续会话的令牌
side_effects_jsonbytesJSON 序列化的 AgentSideEffects（可选）
VoiceStreamError
messagestring错误消息
codestring"vad_error"、"stt_error"、"llm_error"、"tts_error"
fatalbool如果为 true，应关闭会话

分析与搜索

AI 驱动的对话分析、摘要和基于搜索。

AnalyzeConversation

分析对话以提取副作用（人格变化、习惯、记忆等）。

请求

agent_idstring智能体 UUID
agent_namestring智能体显示名称
user_idstring用户标识符
messagesCEAnalyzeConversationMessage[]要分析的消息 (role、content)
is_finalbool是否为最后一批消息

响应

success、side_effects_json (bytes)、summary、latency_ms

SummarizeConversation

生成带主题提取的对话简洁摘要。

请求

messagesCESummarizeConversationMessage[]消息 (role、content、time)
agent_namestring智能体名称
user_namestring用户显示名称
max_summary_lengthint32最大摘要长度（字符数）

响应

summary (string)、topics (string[])、message_count (int)

GenerateSearchQuery

从主题和类别生成优化的搜索查询，用于网络搜索。

请求

topicstring要搜索的主题
categorystring上下文类别

响应

query (string)、context (string)

GroundedSearch

使用多个查询执行基于事实的网络搜索，返回带来源的摘要结果。

请求

queriesstring[]搜索查询
contextstring搜索相关性上下文
agent_namestring用于响应框架的智能体名称

响应

CEGroundedSearchResult 列表 (query、summary、sources with title/url/snippet)

多智能体对话

智能体之间的对话，用于外出、对话和多智能体场景。

AgentDialogue

在多智能体对话上下文中生成智能体响应（如智能体之间的外出）。

请求

agent_idstring智能体 UUID（响应方智能体）
user_idstring用户标识符
messagesCEChatMessage[]对话消息
request_typestring"outing"、"dialogue" 等
scene_guidancestring场景特定提示引导
tool_config_jsonbytes工具配置 JSON（可选）
session_idstring用于自动构建上下文的会话 ID（可选）
interaction_rolestring"owner" 或 "non_owner"（默认："owner"）

响应

response (string)、side_effects_json (bytes)

应用事件

通知平台重要的应用事件。平台可能生成日记条目、更新目标或采取其他 AI 操作。 当日记创建时触发 OnDiaryGenerated webhook。

TriggerGameEvent

接受应用事件（成就、里程碑、突破、完成）并触发 AI 内容生成。

请求

agent_idstring智能体 UUID
user_idstring用户标识符
event_typestring"achievement"、"milestone"、"breakthrough"、"level_up"
event_descriptionstring供 AI 使用的人类可读上下文
metadatamap<string, string>附加上下文（achievement_id、level 等）
languagestring生成内容的语言（默认："en"）

响应

accepted (bool)、event_id (string)

知识库

项目范围的知识图谱。上传文档或通过 API 推送结构化数据—— 平台提取实体、构建图谱，并为智能体提供 knowledge_search 工具在对话中查询。

文档

POST/projects/{projectId}/knowledge/documents

上传文档（带 'file' 字段的 multipart/form-data，最大 50 MB）。返回 202 及 document_id 并触发异步提取。

参数

filemultipart文档文件

响应

document_id、file_name、file_size、checksum、status、gcs_path

GET/projects/{projectId}/knowledge/documents

列出文档。查询参数：limit（默认 50，最大 200）。

响应

documents[]、total

GET/projects/{projectId}/knowledge/documents/{docId}

获取单个文档。

响应

KBDocument 对象

DELETE/projects/{projectId}/knowledge/documents/{docId}

删除文档。

响应

204 No Content

事实与图谱

POST/projects/{projectId}/knowledge/facts

向知识图谱插入实体和关系。与现有节点进行解析，创建/更新并保存版本历史。

参数

sourcestring来源标识符（默认：'api'）
facts[]array实体：entity_type、label、properties
relationships[]array边：from_label、to_label、edge_type

响应

processed、created、updated、details[]

GET/projects/{projectId}/knowledge/nodes

列出知识图谱节点。查询参数：type（筛选）、limit（默认 100，最大 500）。

响应

nodes[]、total

GET/projects/{projectId}/knowledge/nodes/{nodeId}

获取节点及连接的边。查询参数：history=true 获取版本历史。

响应

node、outgoing[]、incoming[]、history[]

DELETE/projects/{projectId}/knowledge/nodes/{nodeId}

软删除节点（设置 is_active=false）。

响应

204 No Content

GET/projects/{projectId}/knowledge/nodes/{nodeId}/history

获取节点版本历史。查询参数：limit（默认 50，最大 200）。

响应

history[]、total

搜索

GET/projects/{projectId}/knowledge/search

带图谱遍历的全文搜索。查询参数：q（必填）、limit、history、type、filters (JSON)。

参数

qstring搜索查询（必填）
limitint最大结果数（默认 20，最大 100）
typestring逗号分隔的实体类型筛选
filtersJSON string属性筛选对象
historybool包含版本历史

响应

query、results[]（含相关节点）、total

架构

POST/projects/{projectId}/knowledge/schemas

创建带字段和可选相似度配置的实体类型架构。

参数

entity_typestring实体类型名称（必填）
fields[]array字段定义：name、type、required
descriptionstring架构描述
similarity_configobjectmatch_fields[]、threshold

响应

KBEntitySchema 对象

GET/projects/{projectId}/knowledge/schemas

列出项目的实体架构。

响应

schemas[]、total

PUT/projects/{projectId}/knowledge/schemas/{schemaId}

更新实体架构。

参数

entity_typestring更新的实体类型名称
fields[]array更新的字段定义

响应

KBEntitySchema 对象

DELETE/projects/{projectId}/knowledge/schemas/{schemaId}

删除实体架构。

响应

204 No Content

统计

GET/projects/{projectId}/knowledge/stats

获取知识库统计信息（文档数量、节点数量、边数量、提取 token 数）。

响应

documents {total、indexed、pending、failed}、nodes {total、active}、edges、extraction_tokens

分析

POST/projects/{projectId}/knowledge/analytics/rules

创建分析规则（推荐或趋势）。

参数

rule_typestring'recommendation' 或 'trend'
namestring规则名称
configobject规则配置
enabledbool规则是否激活

响应

KBAnalyticsRule 对象

GET/projects/{projectId}/knowledge/analytics/recommendations

获取推荐。查询参数：rule_id、source_id（均为必填）、limit。

响应

recommendations[]、total

GET/projects/{projectId}/knowledge/analytics/trends

获取趋势聚合。查询参数：node_id（必填）。

响应

trends[]、total

POST/projects/{projectId}/knowledge/analytics/feedback

记录推荐反馈（展示/转化）。

参数

source_node_idstring来源节点 ID
target_node_idstring目标节点 ID
rule_idstring分析规则 ID
convertedbool用户是否转化
score_at_timefloat推荐展示时的评分

响应

status: 'recorded'

用户引导

预加载用户元数据和内容，使 AI 智能体从首次对话起就"了解"用户。 元数据（姓名、公司、职位）成为即时事实；内容块（文本、聊天记录） 通过 LLM 提取异步处理。

引导用户

POST/agents/{agentId}/users/{userId}/prime

使用元数据和内容引导用户。返回 202 及任务 ID；内容的 LLM 提取异步运行。

参数

display_namestring用户显示名称
metadataobjectcompany、title、email、phone、custom (map)
content[]array内容块：type ('text'、'chat_transcript')、body
sourcestring来源标识符（如 'crm'、'linkedin'）

响应

job_id、status ('queued')、facts_created

GET/agents/{agentId}/users/{userId}/prime/{jobId}

获取引导任务的状态。

响应

ImportJob 对象 (job_id、status、facts_created、error_message 等)

内容

POST/agents/{agentId}/users/{userId}/content

添加用于异步 LLM 提取的内容块（如引导后追加聊天记录）。

参数

content[]array内容块：type、body
sourcestring来源标识符

响应

job_id、status ('queued')

元数据

GET/agents/{agentId}/users/{userId}/metadata

获取用户的引导元数据。

响应

UserPrimingMetadata 对象

PATCH/agents/{agentId}/users/{userId}/metadata

部分更新引导元数据。更新字段会自动生成新事实。

参数

display_namestring更新的名称
companystring更新的公司
titlestring更新的职位
emailstring更新的邮箱
phonestring更新的电话
custommap自定义键值对（合并）

响应

metadata（已更新）、facts_created

批量导入

POST/agents/{agentId}/users/import

在单个请求中导入多个用户及其元数据和内容。元数据事实同步创建；内容提取异步运行。

参数

users[]array{user_id、display_name、metadata、content[]} 数组
sourcestring来源标识符

响应

job_id、status ('queued')、total_users、facts_created

GET/agents/{agentId}/users/import/{jobId}

获取批量导入任务的状态。

响应

ImportJob 对象

GET/agents/{agentId}/users/imports

列出智能体最近的导入任务。查询参数：limit（默认 20）。

响应

jobs[]、count

共享类型

GameContext
custom_fieldsmap<string, string>传递到提示的任意应用特定键值对
game_state_jsonbytes可选的结构化状态 JSON（透传到提示）
CEBig5Scores
opennessdouble经验开放性 (0.0-1.0)
conscientiousnessdouble组织性和纪律性 (0.0-1.0)
extraversiondouble社交能量和热情 (0.0-1.0)
agreeablenessdouble温暖和合作性 (0.0-1.0)
neuroticismdouble情绪敏感性 (0.0-1.0)
confidencedouble评估置信度 (0.0-1.0)
MoodState
valencedouble愉悦/不悦光谱 (0-100)
arousaldouble激活/能量水平 (0-100)
tensiondouble压力/平静状态 (0-100)
affiliationdouble社交温暖/亲密度 (0-100)
CEChatMessage
rolestring"user" 或 "assistant"
contentstring消息文本
timestampTimestamp消息发送时间
MemoryCandidate
contentstring记忆内容文本
fact_typestringpreference、commitment、fact、experience、correction
importancedouble重要性评分 (0.0-1.0)
entitiesstring[]相关实体
Habit
namestring习惯名称
categorystring习惯类别
strengthdouble当前强度 (0.0-1.0)
last_observedTimestamp最后观察时间
is_formedbool习惯是否已完全形成
CEGoal
idstring目标标识符
descriptionstring目标描述
statusstring"active"、"completed"、"abandoned"
prioritystring优先级
related_traitsstring[]相关人格特质
created_atTimestamp目标创建时间
Interest
topicstring兴趣主题
categorystring兴趣类别
confidencedouble检测置信度 (0.0-1.0)
discovered_atTimestamp兴趣发现时间
research_statusstring"pending" 或 "researched"
CEModelConfig
providerstringLLM 提供商名称
modelstring模型标识符
temperaturedouble采样温度
max_tokensint32最大生成 token 数
ProactiveMessage
message_idstring唯一消息标识符
agent_idstring生成消息的智能体
user_idstring目标用户
wakeup_idstring关联的唤醒事件
check_typestring检查类型 (check_in、follow_up、mood_driven)
intentstring智能体想要联系的原因
generated_messagestring实际消息文本
statusstringpending、consumed、expired、failed_generation
created_atTimestamp生成时间
← 集成指南MCP 集成→