理解命名空间
每个事件都带"身份证"，告诉你它是谁发的
启用 subgraphs 后，每个事件都包含一个命名空间（namespace），用于标识是哪个 Agent 生成了该事件。命名空间是由节点名称和任务 ID 组成的路径。
卸甲："身份证"只是一个比喻。实际上，每个事件附带的是一个名为 namespace 的字符串数组。通过检查数组内容来判断来源——空数组 [] 表示主 Agent，包含 tools: 前缀的段表示来自子代理。它就是一条路由标识，跟身份证没有关系。
| 命名空间 | 来源 |
|---|---|
()（空数组） | 主 Agent 的事件 |
("tools:abc123",) | 主 Agent 的 task 工具调用 abc123 派生的 Subagent |
("tools:abc123", "model_request:def456") | Subagent 内部的模型请求节点 |
for await (const [namespace, chunk] of await agent.stream(
{ messages: [{ role: "user", content: "Plan my vacation" }] },
{ streamMode: "updates", subgraphs: true }
)) {
// 检查 namespace 中是否含 "tools:" 前缀的段
const isSubagent = namespace.some(
(segment) => segment.startsWith("tools:")
);
if (isSubagent) {
// 从命名空间中提取工具调用 ID（如 "tools:call_abc123" 中的 "call_abc123"）
const toolCallId = namespace
.find((s) => s.startsWith("tools:"))
?.split(":")[1];
console.log(`Subagent ${toolCallId}:`, chunk);
} else {
console.log("Main agent:", chunk);
}
}
常见误区：命名空间不是字符串，是一个字符串数组。
namespace.length === 0 表示主 Agent，namespace[0].startsWith("tools:") 表示 Subagent。不要拿整个数组做字符串匹配。
Subagent 生命周期
监控 Subagent 的启动、运行、完成三个阶段
这是一个常见的实战模式——用 updates 模式追踪 Subagent 从创建到完成的完整生命周期：
阶段 1：启动
主 Agent 的 model_request 包含 task 工具调用
阶段 2：运行
收到 tools:UUID 命名空间的事件
阶段 3：完成
主 Agent 的 tools 节点返回 tool 消息
const activeSubagents = new Map();
for await (const [namespace, chunk] of await agent.stream(
{ messages: [
{ role: "user", content: "Research the latest AI safety developments" },
]},
{ streamMode: "updates", subgraphs: true },
)) {
for (const [nodeName, data] of Object.entries(chunk)) {
// 阶段 1：检测 Subagent 启动
// 主 Agent 的 model_request 节点中包含 task 工具调用时，说明子代理即将启动
if (namespace.length === 0 && nodeName === "model_request") {
for (const msg of data.messages ?? []) {
for (const tc of msg.tool_calls ?? []) {
if (tc.name === "task") {
// 记录子代理信息，状态为 pending
activeSubagents.set(tc.id, {
type: tc.args?.subagent_type, // 子代理类型名称
description: tc.args?.description?.slice(0, 80), // 任务描述
status: "pending", // 初始状态
});
console.log(
`[lifecycle] PENDING → "${tc.args?.subagent_type}" (${tc.id})`
);
}
}
}
}
// 阶段 2：检测 Subagent 运行中
// 收到 tools:UUID 命名空间的事件说明子代理已开始执行
if (namespace.length > 0 && namespace[0].startsWith("tools:")) {
const pregelId = namespace[0].split(":")[1];
// 注意：pregel 运行时 ID 与 tool_call_id 不同，无法直接关联
// 因此将所有 pending 状态的子代理标记为 running
for (const [id, sub] of activeSubagents) {
if (sub.status === "pending") {
sub.status = "running";
console.log(`[lifecycle] RUNNING → subagent "${sub.type}" (pregel: ${pregelId})`);
break;
}
}
}
// 阶段 3：检测 Subagent 完成
// 主 Agent 的 tools 节点返回 tool 类型消息，说明子代理执行完毕
if (namespace.length === 0 && nodeName === "tools") {
for (const msg of data.messages ?? []) {
if (msg.type === "tool") {
// 通过 tool_call_id 匹配之前记录的子代理
const sub = activeSubagents.get(msg.tool_call_id);
if (sub) {
sub.status = "complete";
console.log(
`[lifecycle] COMPLETE → subagent "${sub.type}" (${msg.tool_call_id})`,
);
console.log(
` Result preview: ${String(msg.content).slice(0, 120)}...`,
);
}
}
}
}
}
}
// 打印最终状态
console.log("\n--- Final subagent states ---");
for (const [id, sub] of activeSubagents) {
console.log(` ${sub.type}: ${sub.status}`);
}