AgentEvent 核心使用场景
945 字
5 分钟
AgentEvent 核心使用场景
AgentEvent 核心使用场景
AgentEvent 有 7 种类型,AssistantMessageEvent 有 13 种类型。 但 90% 的开发场景只需要关注四个核心:
流式输出:实时显示文本 状态获取:token用量、stopReason 工具处理:执行状态、结果获取 错误处理:API错误、工具失败
理解这四个场景,其他都是特殊需求的扩展。
场景一:流式输出
最常用、最高频的场景:实时显示 AI 的文本回复。
核心事件
| 事件 | 层级 | 用途 |
|---|---|---|
| message_update | 高层 | 包装层,携带底层事件 |
| text_delta | 底层 | 实际的文本增量 |
代码模板
agent.subscribe((event) => { if (event.type !== "message_update") return;
const e = event.assistantMessageEvent;
switch (e.type) { case "text_delta": process.stdout.write(e.delta); // 文本增量(必用) break;
case "toolcall_delta": // 可选:显示参数生成过程 console.log("[参数]", e.delta); break;
case "thinking_delta": // 可选:显示思考过程 console.log("[思考]", e.delta); break; }});触发频率:每秒多次(最高频事件)。
场景二:状态获取
获取 token 用量、stopReason、完整内容。
核心事件
| 事件 | 核心字段 | 用途 |
|---|---|---|
| message_end | message.usage | token统计 |
| message.stopReason | 判断后续行为 | |
| message.content | 完整内容 |
stopReason 含义
type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";| 值 | 含义 | 后续行为 |
|---|---|---|
| stop | 正常完成 | 对话结束 |
| length | 达到maxTokens | 内容截断 |
| toolUse | 需要执行工具 | Agent将执行工具 |
| error | API错误 | 查看errorMessage |
| aborted | 用户中止 | 用户主动取消 |
代码模板
agent.subscribe((event) => { if (event.type !== "message_end") return;
const msg = event.message; if (msg.role !== "assistant") return;
// Token用量 console.log("Input:", msg.usage.input); console.log("Output:", msg.usage.output); console.log("Total:", msg.usage.totalTokens);
// 判断后续行为 switch (msg.stopReason) { case "stop": console.log("对话完成"); break; case "toolUse": console.log("即将执行工具"); break; case "error": console.log("错误:", msg.errorMessage); break; }});触发频率:每条消息一次(低频)。
场景三:工具处理
监控工具执行状态,获取执行结果。
核心事件
| 事件 | 核心字段 | 用途 |
|---|---|---|
| tool_execution_start | toolName, args | 显示”正在执行…“ |
| tool_execution_end | result, isError | 获取结果或错误 |
代码模板
agent.subscribe((event) => { // 开始执行 if (event.type === "tool_execution_start") { console.log(`[执行] ${event.toolName}`); console.log(`[参数]`, event.args); }
// 执行完成 if (event.type === "tool_execution_end") { if (event.isError) { console.error(`[失败] ${event.toolName}`); console.error(`[错误]`, event.result); } else { console.log(`[完成] ${event.toolName}`); console.log(`[结果]`, event.result); } }});触发频率:每次工具调用一次(中频)。
场景四:错误处理
处理 API 错误、工具失败、用户中止。
错误来源层级
| 错误来源 | 事件/字段 | 处理方式 |
|---|---|---|
| API错误 | message_update + error | 底层流错误 |
| 消息错误 | message_end + stopReason/errorMessage | 消息状态错误 |
| 工具错误 | tool_execution_end + isError | 工具执行错误 |
代码模板
agent.subscribe((event) => { // 1. API流式错误(最高优先级) if (event.type === "message_update") { const e = event.assistantMessageEvent;
if (e.type === "error") { if (e.reason === "aborted") { console.log("[用户中止]"); } else { console.error("[API错误]", e.error.errorMessage); } return; // 错误后不再处理 } }
// 2. 消息完成时检查错误状态 if (event.type === "message_end") { const msg = event.message; if (msg.role === "assistant") { if (msg.stopReason === "error") { console.error("[消息错误]", msg.errorMessage); } if (msg.stopReason === "aborted") { console.log("[请求中止]"); } } }
// 3. 工具执行错误 if (event.type === "tool_execution_end") { if (event.isError) { console.error(`[工具失败] ${event.toolName}`); } }});触发频率:错误时触发(低频但重要)。
完整订阅示例
将四个场景整合:
agent.subscribe((event) => { switch (event.type) { // 流式输出 case "message_update": const e = event.assistantMessageEvent; if (e.type === "text_delta") { process.stdout.write(e.delta); } if (e.type === "error") { console.error("[API错误]", e.error.errorMessage); } break;
// 状态获取 case "message_end": const msg = event.message; if (msg.role === "assistant") { console.log(`[Token] ${msg.usage.totalTokens}`); console.log(`[Reason] ${msg.stopReason}`); } break;
// 工具处理 case "tool_execution_start": console.log(`[执行工具] ${event.toolName}`); break;
case "tool_execution_end": console.log(`[工具完成] ${event.toolName}`); if (event.isError) console.error("[工具失败]"); break;
// 本轮结束 case "turn_end": console.log("[本轮结束]"); break; }});使用原则
90% 场景只需要关注:
- message_update(流式输出)
- message_end(状态获取)
- tool_execution_*(工具处理)
- error 处理(错误分支)
特殊需求才需要深入:
- 参数预览 → toolcall_delta
- 思考过程 → thinking_delta
- 完整历史 → agent_end.messages
支持与分享
如果这篇文章对你有帮助,欢迎分享给更多人或赞助支持!
AgentEvent 核心使用场景
https://firefly.cuteleaf.cn/posts/learn-pi/event&message/03-核心使用场景/ 相关文章 智能推荐
1
AgentEvent 类型系统详解
pi 深入理解 AgentEvent 的7种业务事件和 AssistantMessageEvent 的13种技术事件
2
AgentEvent 系统分层设计理念
pi 理解 pi-agent-core 和 pi-ai 的分层设计,掌握 AgentEvent 与 AssistantMessageEvent 的职责边界
3
AbortController 与 terminate 设计原理
pi 深入理解两种中断机制的设计原理:AbortController的预先注册模式与terminate的返回值携带模式
4
Message 与 Tool 的时序关系
pi 理解工具调用的两阶段设计:LLM生成参数与Agent执行工具的时序边界与协作方式
5
message_update 事件深入
pi 理解 message_update 如何连接高层 AgentEvent 和底层 AssistantMessageEvent,掌握两个关联字段的使用
随机文章 随机推荐