2026/9/14 3:54:46
FEATURED · 精选文章 
Parlant 异步事件模型自定义客户端如何发送消息并长轮询接收回复【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant如果你在 Parlant 服务器上创建了 agent想不用官方 React 组件而是用自己的前端应用和它对话就会遇到一个和普通 LLM API 完全不同的问题调用发送消息接口时拿不到 agent 的回复。Parlant 的交互是异步的——客户消息只是被持久化并异步触发 agent 处理真正的回复会稍后以事件形式出现在会话时间线里。因此自定义客户端要做两件事用create_event发送客户消息再用list_events带min_offset长轮询把之后到达的回复、状态和工具事件持续拉回前端。本文以 Python 官方客户端 SDK 为主路径所有事实来自仓库内文档交互流程说明、会话概念文档 与 自定义前端文档。先理解模型事件、offset 与异步回复会话文档把 session 描述为一条时间线客户说话、agent 状态变化、工具调用结果都被捕获为事件每个事件有一个从 0 递增的offset。例如客户说Hello是事件 0系统发出状态事件是事件 1agent 的回复是事件 2以此类推。这个模型直接决定了客户端的收发方式交互流程文档分三点说明客户消息sourcecustomer请求把消息加入会话并异步触发 agent。返回的Created Event是已持久化的客户事件本身含其 ID 和 offset不包含 agent 的回复。AI Agent 消息sourceai_agent直接激活整个反应引擎。返回的也不是 agent 消息而是一个与最终 agent 消息共享同一Trace ID的状态事件文档指出大多数前端会忽略它主要用途是诊断。人工代理消息sourcehuman_agent由人代 AI agent 写入的预写消息返回的就是这条被持久化的消息。接收侧同理因为消息可能随时、由任意一方写入客户端必须持续等待新事件。Parlant 用带超时限制的长轮询端点实现这一点请求携带会话 ID 和一个最小 offset端点只在新消息到达时才返回。前端通常传入1 最后已知事件 offset并把这个请求循环执行每次约 60 秒超时后重新发起UI 就始终跟随会话的最新状态。每个事件还带trace_id用于把 AI 生成的消息与产生它的引擎触发、工具事件关联起来——比如前端可以检查一条消息关联的工具事件在消息下方做脚注展示。准备启动服务端并安装客户端按 安装文档Parlant 要求 Python 3.10 及以上pip install parlantParlant 默认使用 OpenAI 作为 NLP 提供方需要设置OPENAI_API_KEY然后用 SDK 启动服务器并创建一个 agent示例来自安装文档# main.py import asyncio import parlant.sdk as p async def main(): async with p.Server() as server: agent await server.create_agent( nameOtto Carmen, descriptionYou work at a car dealership, ) asyncio.run(main())export OPENAI_API_KEYYOUR_API_KEY python main.py服务端默认监听http://localhost:8800这也是后续客户端base_url使用的地址。客户端侧会话文档给出两种 SDK 安装方式pip install parlant-client # Python npm install parlant-client # TypeScript注意会话存储默认情况下 Parlant 不持久化 session会话保存在内存中服务器重启即丢失适合测试要持久化可在启动时指定session_storelocal保存到$PARLANT_HOME/sessions.json或传入 MongoDB 连接串见 会话文档。第 1 步初始化客户端并创建会话会话文档推荐使用异步客户端AsyncParlantClient可实时处理事件而不阻塞应用如果只是测试也可以用同步的ParlantClientAPI 相同from parlant.client import AsyncParlantClient # Change localhost to your servers address client AsyncParlantClient(base_urlhttp://localhost:8800)创建会话await client.sessions.create( agent_idAGENT_ID, # 要交互的 agent 的 ID customer_idCUSTOMER_ID, # 可选不传则使用 guest customer 的 ID titleSESSION_TITLE, # 可选会话也可以没有标题 )AGENT_ID替换为你在服务器端创建的 agent 的 ID返回对象中的会话 ID 就是后面所有事件操作的session_id。第 2 步发送客户消息发送消息的本质是在会话里创建一条kindmessage、sourcecustomer的事件event await client.sessions.create_event( session_idSESSION_ID, kindmessage, # 事件类型为 message sourcecustomer, # 消息来自客户 messageHello, I need help with my order., )SESSION_ID换成第 1 步创建的会话 ID。这里有两个容易踩的边界来自 API 实现该接口对应POST /{session_id}/events成功返回201和事件 DTO会话不存在返回404参数校验失败返回422。消息事件允许直接写入的 source 只有customer、human_agent、human_agent_on_behalf_of_ai_agent三种ai_agent走的是另一条触发引擎的路径且不能指定消息文本会由 agent 自动生成。返回的event就是被持久化的客户消息事件它的offset是你推进长轮询游标的关键。交互文档明确提醒这个 Created Event 不是 agent 的回复回复会稍后到达。第 3 步长轮询接收事件用list_events拉取新事件核心参数是min_offset和wait_for_datanew_events await client.sessions.list_events( session_idSESSION_ID, min_offsetEVENT_OFFSET, # 你最后一次收到或自己创建的事件的 offset wait_for_data60, # 最多等待 60 秒直到有新事件或超时 )语义在 API 实现的文档字符串中写得最精确wait_for_data0立即返回当前已存在的匹配事件wait_for_data0若已有匹配事件则立即返回否则等待新事件超时则抛504 Gateway Timeout。所以客户端的正常循环是发起请求 → 有新事件就处理并推进 offset → 超时后原样重新发起。文档给出的循环示意是Fetch new events →Timeout 或 New events→ 再次 FetchNormally, youd have this polling in a loop。offset 游标的推进方式以 自定义前端文档的 TypeScript 参考实现为准const events await this.client.sessions.listEvents(this.sessionId, { minOffset: this.lastOffset, waitForData: 30, // Wait up to 30 seconds for new events kinds: [message, status] // Only get message and status events }); for (const event of events) { await this.handleEvent(event); this.lastOffset Math.max(this.lastOffset, event.offset 1); }即每次处理完事件后把游标更新为max(游标, event.offset 1)list_events支持min_offset、source、kinds、trace_id等过滤参数见端点定义 sessions.py。文档建议把轮询放进循环并处理异常——参考实现在出错后等待 5 秒再重试而不是让整个监控崩溃。第 4 步判断并展示 agent 的回复拉回的事件需要按kind和source区分处理。Parlant 定义四类事件会话文档message参与者的消息statusagent 状态更新如thinking...、typing...tool工具调用结果custom你的应用自定义的事件用于向 agent 注入前端状态。识别 agent 回复的最小示例来自 会话文档agent_message next((m for m in new_events if m.kind message and m.source ai_agent), None) if agent_message: print(fAgent: {agent_message.data[message]})消息事件的数据结构文档示例{ id: EVENT_ID, kind: message, source: EVENT_SOURCE, offset: 0, trace_id: TRACE_ID, data: { message: MESSAGE, participant: { id: PARTICIPANT_ID, display_name: PARTICIPANT_DISPLAY_NAME }, draft: OPTIONAL_DRAFT } }其中data.draft是可选字段消息为 canned response 时出现。EVENT_ID、TRACE_ID等尖括号内容是文档模板的占位符实际值来自接口返回。status 事件固定sourceai_agentdata.status有六种取值适合做前端提示acknowledgedagent 已确认收到客户消息开始处理回复cancelledagent 中途取消了正在生成的回复通常是因为会话里又加入了新数据processingagent 正在评估会话准备生成回复typing评估结束正在生成消息readyagent 空闲可接收新事件erroragent 生成回复时遇到错误。因此一条完整可运行的最小主路径是创建会话 →create_event发消息 → 用offset1推进游标循环list_events→ 过滤kindmessage and sourceai_agent展示回复同时把 status 事件映射到 UI 的thinking/typing提示。限制与边界会话存储默认在内存服务器重启会话丢失需要持久化时按 会话文档配置session_storelocal或 MongoDB。长轮询超时是常态而非故障交互文档明确说每 60 秒左右超时并重新发起请求是这个循环的正常节奏API 层对超时返回504见 sessions.py客户端按上面循环方式续发即可。offset 从 0 开始事件按 offset 排序min_offset保证只拉取某点之后的事件避免重复抓取全部历史。trace_id 是关联线索状态事件、工具事件和最终消息事件通过同一 trace_id 串联前端可据此做消息级脚注自定义前端文档还给出原则始终展示来自 Parlant 事件的内容而不是乐观地先更新 UI。下一步可以对照 自定义前端文档 中的 TypeScript/JavaScript 参考实现补全会话管理、错误重试和完整 HTML 页面或阅读 交互流程文档 了解 human handoff 场景下人工代理事件的用法。【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Parlant 异步事件模型：自定义客户端如何发送消息并长轮询接收回复
Parlant 异步事件模型自定义客户端如何发送消息并长轮询接收回复【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant如果你在 Parlant 服务器上创建了 agent想不用官方 React 组件而是用自己的前端应用和它对话就会遇到一个和普通 LLM API 完全不同的问题调用发送消息接口时拿不到 agent 的回复。Parlant 的交互是异步的——客户消息只是被持久化并异步触发 agent 处理真正的回复会稍后以事件形式出现在会话时间线里。因此自定义客户端要做两件事用create_event发送客户消息再用list_events带min_offset长轮询把之后到达的回复、状态和工具事件持续拉回前端。本文以 Python 官方客户端 SDK 为主路径所有事实来自仓库内文档交互流程说明、会话概念文档 与 自定义前端文档。先理解模型事件、offset 与异步回复会话文档把 session 描述为一条时间线客户说话、agent 状态变化、工具调用结果都被捕获为事件每个事件有一个从 0 递增的offset。例如客户说Hello是事件 0系统发出状态事件是事件 1agent 的回复是事件 2以此类推。这个模型直接决定了客户端的收发方式交互流程文档分三点说明客户消息sourcecustomer请求把消息加入会话并异步触发 agent。返回的Created Event是已持久化的客户事件本身含其 ID 和 offset不包含 agent 的回复。AI Agent 消息sourceai_agent直接激活整个反应引擎。返回的也不是 agent 消息而是一个与最终 agent 消息共享同一Trace ID的状态事件文档指出大多数前端会忽略它主要用途是诊断。人工代理消息sourcehuman_agent由人代 AI agent 写入的预写消息返回的就是这条被持久化的消息。接收侧同理因为消息可能随时、由任意一方写入客户端必须持续等待新事件。Parlant 用带超时限制的长轮询端点实现这一点请求携带会话 ID 和一个最小 offset端点只在新消息到达时才返回。前端通常传入1 最后已知事件 offset并把这个请求循环执行每次约 60 秒超时后重新发起UI 就始终跟随会话的最新状态。每个事件还带trace_id用于把 AI 生成的消息与产生它的引擎触发、工具事件关联起来——比如前端可以检查一条消息关联的工具事件在消息下方做脚注展示。准备启动服务端并安装客户端按 安装文档Parlant 要求 Python 3.10 及以上pip install parlantParlant 默认使用 OpenAI 作为 NLP 提供方需要设置OPENAI_API_KEY然后用 SDK 启动服务器并创建一个 agent示例来自安装文档# main.py import asyncio import parlant.sdk as p async def main(): async with p.Server() as server: agent await server.create_agent( nameOtto Carmen, descriptionYou work at a car dealership, ) asyncio.run(main())export OPENAI_API_KEYYOUR_API_KEY python main.py服务端默认监听http://localhost:8800这也是后续客户端base_url使用的地址。客户端侧会话文档给出两种 SDK 安装方式pip install parlant-client # Python npm install parlant-client # TypeScript注意会话存储默认情况下 Parlant 不持久化 session会话保存在内存中服务器重启即丢失适合测试要持久化可在启动时指定session_storelocal保存到$PARLANT_HOME/sessions.json或传入 MongoDB 连接串见 会话文档。第 1 步初始化客户端并创建会话会话文档推荐使用异步客户端AsyncParlantClient可实时处理事件而不阻塞应用如果只是测试也可以用同步的ParlantClientAPI 相同from parlant.client import AsyncParlantClient # Change localhost to your servers address client AsyncParlantClient(base_urlhttp://localhost:8800)创建会话await client.sessions.create( agent_idAGENT_ID, # 要交互的 agent 的 ID customer_idCUSTOMER_ID, # 可选不传则使用 guest customer 的 ID titleSESSION_TITLE, # 可选会话也可以没有标题 )AGENT_ID替换为你在服务器端创建的 agent 的 ID返回对象中的会话 ID 就是后面所有事件操作的session_id。第 2 步发送客户消息发送消息的本质是在会话里创建一条kindmessage、sourcecustomer的事件event await client.sessions.create_event( session_idSESSION_ID, kindmessage, # 事件类型为 message sourcecustomer, # 消息来自客户 messageHello, I need help with my order., )SESSION_ID换成第 1 步创建的会话 ID。这里有两个容易踩的边界来自 API 实现该接口对应POST /{session_id}/events成功返回201和事件 DTO会话不存在返回404参数校验失败返回422。消息事件允许直接写入的 source 只有customer、human_agent、human_agent_on_behalf_of_ai_agent三种ai_agent走的是另一条触发引擎的路径且不能指定消息文本会由 agent 自动生成。返回的event就是被持久化的客户消息事件它的offset是你推进长轮询游标的关键。交互文档明确提醒这个 Created Event 不是 agent 的回复回复会稍后到达。第 3 步长轮询接收事件用list_events拉取新事件核心参数是min_offset和wait_for_datanew_events await client.sessions.list_events( session_idSESSION_ID, min_offsetEVENT_OFFSET, # 你最后一次收到或自己创建的事件的 offset wait_for_data60, # 最多等待 60 秒直到有新事件或超时 )语义在 API 实现的文档字符串中写得最精确wait_for_data0立即返回当前已存在的匹配事件wait_for_data0若已有匹配事件则立即返回否则等待新事件超时则抛504 Gateway Timeout。所以客户端的正常循环是发起请求 → 有新事件就处理并推进 offset → 超时后原样重新发起。文档给出的循环示意是Fetch new events →Timeout 或 New events→ 再次 FetchNormally, youd have this polling in a loop。offset 游标的推进方式以 自定义前端文档的 TypeScript 参考实现为准const events await this.client.sessions.listEvents(this.sessionId, { minOffset: this.lastOffset, waitForData: 30, // Wait up to 30 seconds for new events kinds: [message, status] // Only get message and status events }); for (const event of events) { await this.handleEvent(event); this.lastOffset Math.max(this.lastOffset, event.offset 1); }即每次处理完事件后把游标更新为max(游标, event.offset 1)list_events支持min_offset、source、kinds、trace_id等过滤参数见端点定义 sessions.py。文档建议把轮询放进循环并处理异常——参考实现在出错后等待 5 秒再重试而不是让整个监控崩溃。第 4 步判断并展示 agent 的回复拉回的事件需要按kind和source区分处理。Parlant 定义四类事件会话文档message参与者的消息statusagent 状态更新如thinking...、typing...tool工具调用结果custom你的应用自定义的事件用于向 agent 注入前端状态。识别 agent 回复的最小示例来自 会话文档agent_message next((m for m in new_events if m.kind message and m.source ai_agent), None) if agent_message: print(fAgent: {agent_message.data[message]})消息事件的数据结构文档示例{ id: EVENT_ID, kind: message, source: EVENT_SOURCE, offset: 0, trace_id: TRACE_ID, data: { message: MESSAGE, participant: { id: PARTICIPANT_ID, display_name: PARTICIPANT_DISPLAY_NAME }, draft: OPTIONAL_DRAFT } }其中data.draft是可选字段消息为 canned response 时出现。EVENT_ID、TRACE_ID等尖括号内容是文档模板的占位符实际值来自接口返回。status 事件固定sourceai_agentdata.status有六种取值适合做前端提示acknowledgedagent 已确认收到客户消息开始处理回复cancelledagent 中途取消了正在生成的回复通常是因为会话里又加入了新数据processingagent 正在评估会话准备生成回复typing评估结束正在生成消息readyagent 空闲可接收新事件erroragent 生成回复时遇到错误。因此一条完整可运行的最小主路径是创建会话 →create_event发消息 → 用offset1推进游标循环list_events→ 过滤kindmessage and sourceai_agent展示回复同时把 status 事件映射到 UI 的thinking/typing提示。限制与边界会话存储默认在内存服务器重启会话丢失需要持久化时按 会话文档配置session_storelocal或 MongoDB。长轮询超时是常态而非故障交互文档明确说每 60 秒左右超时并重新发起请求是这个循环的正常节奏API 层对超时返回504见 sessions.py客户端按上面循环方式续发即可。offset 从 0 开始事件按 offset 排序min_offset保证只拉取某点之后的事件避免重复抓取全部历史。trace_id 是关联线索状态事件、工具事件和最终消息事件通过同一 trace_id 串联前端可据此做消息级脚注自定义前端文档还给出原则始终展示来自 Parlant 事件的内容而不是乐观地先更新 UI。下一步可以对照 自定义前端文档 中的 TypeScript/JavaScript 参考实现补全会话管理、错误重试和完整 HTML 页面或阅读 交互流程文档 了解 human handoff 场景下人工代理事件的用法。【免费下载链接】parlantBuild reliable customer-facing AI agents with Parlant: an interaction control harness optimized for controlled, consistent, and predictable LLM interactions.项目地址: https://gitcode.com/GitHub_Trending/pa/parlant创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
