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_endmessage.usagetoken统计
message.stopReason判断后续行为
message.content完整内容

stopReason 含义#

type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
含义后续行为
stop正常完成对话结束
length达到maxTokens内容截断
toolUse需要执行工具Agent将执行工具
errorAPI错误查看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_starttoolName, args显示”正在执行…“
tool_execution_endresult, 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-核心使用场景/
作者
AltumSisy
发布于
2026-05-25
许可协议
CC BY-NC-SA 4.0
Profile Image of the Author
AltumSisy
Hello, I'm AltumSisy.
公告
欢迎来到我的博客!这是一则示例公告。
音乐
封面

音乐

暂未播放

0:00 0:00
暂无歌词
分类
标签
站点统计
文章
32
分类
3
标签
25
总字数
68,347
运行时长
0
最后活动
0 天前

文章目录