接口定义
本接口
append_event()用于向指定会话(Session)中添加新的对话事件。该接口支持两种会话模式,适用于不同的业务场景:会话模式 | 说明 | 典型场景 |
单用户会话 | 会话仅涉及一个用户与系统的交互,用户身份在会话级别统一指定 | 智能客服、个人助手、一对一咨询 |
多用户群聊 | 会话包含多个用户的发言,每条消息需单独标识发送者身份 | 群组讨论、多人协作、会议记录 |
def append_event(self,session_id: str,messages: list,actor_id: Optional[str] = None,) -> Dict[str, Any]:
使用示例
单一用户与系统(或 AI 助手)之间的交互会话,会话中仅存在一个用户身份。
import jsonevent = client.append_event(session_id="session-1c54d41a********",actor_id="tourist-sdk-test",messages=[{"role": "user","content": "嗨,帮我规划一个下周去杭州的3天行程。","timestamp": "2025-12-01T10:00:05Z"},{"role": "assistant","content": "好的,已为您推荐杭州三日行程。第一天,我们聚焦西湖经典。清晨从断桥残雪出发,漫步白堤,感受水墨画般的湖光山色。随后乘船登岛探访三潭印月,下午登雷峰塔俯瞰全景,傍晚在曲院风荷赏夕阳,晚上则去河坊街夜市品尝地道小吃。\\n\\n第三天,探索湿地与运河文化。上午在西溪湿地乘坐摇橹船,听船娘小调,感受水乡慢生活;下午逛一逛桥西历史街区和文艺的小河直街,参观工艺美术博物馆,在咖啡馆小憩后即可轻松结束旅程,准备返程。\\n\\n第二天,体验禅意与宋韵。上午前往灵隐寺景区祈福,在法喜寺的黄墙拍照打卡;下午沉浸于宋城,体验AR剧本杀并观看《宋城千古情》演出;如果傍晚还有精力,可以去九溪烟树享受清凉的溪水。","timestamp": "2025-12-01T10:01:05Z"},{"role": "user","content": "我喜欢人少、安静的地方,对美食特别感兴趣。","timestamp": "2025-12-01T10:05:05Z"},{"role": "assistant","content": "基于您喜欢安静和美食的偏好,我为您优化了行程,避开了团队游客扎堆的景点,专注于幽静的体验和地道的风味。\\n\\n第一天:避世西湖\\n清晨漫步杨公堤与茅家埠,享受静谧湖景。午餐在老字号「奎元馆」吃虾爆鳝面。下午乘船访三潭印月,傍晚在湖边茶社小坐。晚餐去本地人爱的胜利河美食街尝地道风味。\\n\\n第二天:禅意之路\\n一早探灵隐寺,然后沿幽静天竺路步行至法喜寺。午餐在「知竹」吃素面。下午深入云栖竹径看竹海。晚餐用「新丰小吃」的喉口馒头等市井味道收尾。\\n\\n第三天:水乡慢生活\\n全天在西溪湿地坐摇橹船,深入芦苇荡享受宁静。午后往文艺的小河直街,在运河畔的咖啡馆小坐休憩,结束旅程。","timestamp": "2025-12-01T10:06:05Z"},{"role": "user","content": "太好了,酒店要带健身房,另外我对花生严重过敏,预订餐厅时请务必注意。","timestamp": "2025-12-01T10:08:05Z"},{"role": "assistant","content": "好的,已完全了解您的需求(偏好安静人少、喜爱美食、酒店需带健身房、对花生严重过敏)。为您精选的酒店(带健身房):\\n\\n西湖庐驿精品酒店:位于西湖区,设计静谧,配备健身房,且远离闹市,符合您对安静的需求。\\n\\n杭州西溪紫金港希尔顿逸林酒店:靠近西溪湿地,设施完善,健身房专业,适合在第三天安排湿地行程时入住。","timestamp": "2025-12-01T10:10:05Z"},{"role": "user","content": "完美!哦对了,我女朋友更喜欢现代艺术,有什么地方可以推荐吗?","timestamp": "2025-12-01T10:12:05Z"},{"role": "assistant","content": "收到!考虑到您女朋友的喜好。这是为您和您女友定制的杭州三日行程:\\n\\n第一天:上午游茅家埠、杨公堤;下午观天目里美术馆现代展览。晚餐于胜利河美食街 品尝安全地道的本帮菜。\\n\\n第二天:上午早访灵隐寺,漫步幽静天竺路。下午重点参观 浙江省博物馆之江馆 重磅国际艺术大展。晚餐体验本地 新丰小吃(已规避风险)。\\n\\n第三天:上午于 西溪湿地乘摇橹船。下午在小河直街 咖啡馆悠闲小憩,结束旅程。","timestamp": "2025-12-01T10:13:05Z"}],)print(json.dumps(event, ensure_ascii=False))
多个用户在同一会话中进行群聊,每条消息需明确标识其发送者身份。
import jsonevent = client.append_event(session_id="session-1c54d41a********",messages=[{"role": "user","actor_id": "tourist-first-timer-01","content": "[游客小李] 第一次去杭州,西湖一天能逛完吗?","timestamp": "2025-01-20T08:00:00Z"},{"role": "user","actor_id": "hangzhou-local-resident","content": "[杭州本地人] 西湖很大,建议租辆共享单车环湖骑行,半天能走完主要景点","timestamp": "2025-01-20T08:03:00Z"},{"role": "user","actor_id": "travel-enthusiast-02","content": "[旅游达人梦梦] 苏堤和白堤必去,断桥最好早上7点前到,不然全是人","timestamp": "2025-01-20T08:05:00Z"},{"role": "user","actor_id": "tourist-first-timer-01","content": "[游客小李] 雷峰塔值得上去吗?门票多少钱?","timestamp": "2025-01-20T08:08:00ZZ"},{"role": "assistant","actor_id": "tourist-first-timer-01","content": "雷峰塔门票40元,登塔可俯瞰西湖全景,傍晚时分夕照雷峰是西湖十景之一,推荐游览","timestamp": "2025-01-20T08:09:00Z"}],)print(json.dumps(event, ensure_ascii=False))
入参描述
参数 | 是否必选 | 参数含义 | 配置方法及要求 |
actor_id | 是 | 在单用户会话场景中,actor_id 作为请求级参数传入,用于指定当前会话所属用户的唯一标识。 | 单用户会话:必须在此处传入 actor_id,用于标识会话归属的用户。 数据类型:String。 长度限制:[1,128]。 字符规则:任意字符。 多用户群聊:无需填写此参数,需在 messages 消息体内为每条消息单独配置 actor_id。 说明: 单用户会话时必填,用于标识会话归属用户;多用户群聊时无需填写,改为在 messages 消息体内逐条配置。两处参数互斥,必须二选一。 |
session_id | 是 | 指定追加 Event 的 Session ID。 | 新建会话:直接传入自定义字符串(1-128 个字符)即可,系统将自动创建会话。 追加到已有会话:传入已有的会话 ID。获取方式,请参见 查询 Session。 |
messages | 是 | 以 JSON 格式配置消息体。每个消息对象必须包含三个关键字段:role、content 和 timestamp,支持自定义字段。
| (必须)role:指定用户角色。可选值如下所示: user:表示最终用户。 assistant:AI 助手。 tool:被调用的工具或函数。 |
| | | (可选)actor_id:在多用户群聊场景中,actor_id 需写入 messages 消息体内,与每条 Event 绑定,用于标识该消息的发送者。 数据类型:String。 长度限制:[1,128]。 字符规则:任意字符。 说明: 多用户群聊时必填,用于标识消息发送者;单用户会话时无需填写,改为在请求级传入 actor_id。两处参数互斥,必须二选一。 |
| | | (必选)content:对应角色发出的文本内容或数据。 |
| | | (必选)timestamp:记录消息产生的时间。使用 ISO 8601 格式 `YYYY-MM-DDTHH:MM:SSZ`。 |
出参描述
执行成功,输出如下信息。
{"event_ids": ["event-6deb0d74********","event-0811d41c********","event-4d48e3ac********","event-724c5fe6********","event-2855d62a********","event-63fb98fa********","event-1ce29851********","event-b99185bd********"],"total_count": 8}
参数名 | 参数含义 |
event_id | 生成的事件 ID 列表。 |
total_count | 创建的事件总数。 |