From 710e20a6ab5f7a329c30b26d3ee6543005679358 Mon Sep 17 00:00:00 2001 From: j-zhangyiyuan Date: Fri, 24 Jul 2026 11:11:42 +0800 Subject: [PATCH 1/2] docs: document complete sub-agent event data fields The event table for sub-agent lifecycle events was missing several fields that are available in the typed event interfaces: - subagent.started: add \model?\ - subagent.completed: add \model?\, \durationMs?\, \ otalTokens?\, \ otalToolCalls?\ - subagent.failed: add \model?\, \durationMs?\, \ otalTokens?\, \ otalToolCalls?\ Also update the Node.js code example to demonstrate accessing the performance metrics (duration, tokens, tool calls) from completed/failed events. --- docs/features/custom-agents.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/features/custom-agents.md b/docs/features/custom-agents.md index 0cb68b944..13912ddd3 100644 --- a/docs/features/custom-agents.md +++ b/docs/features/custom-agents.md @@ -445,9 +445,9 @@ Sub-agent-originated session events share the parent session stream and include | Event | Emitted when | Data | |-------|-------------|------| | `subagent.selected` | Runtime selects an agent for the task | `agentName`, `agentDisplayName`, `tools` | -| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription` | -| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName` | -| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error` | +| `subagent.started` | Sub-agent begins execution | `toolCallId`, `agentName`, `agentDisplayName`, `agentDescription`, `model?` | +| `subagent.completed` | Sub-agent finishes successfully | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` | +| `subagent.failed` | Sub-agent encounters an error | `toolCallId`, `agentName`, `agentDisplayName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` | | `subagent.deselected` | Runtime switches away from the sub-agent |—| ### Subscribing to events @@ -466,11 +466,15 @@ session.on((event) => { case "subagent.completed": console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`); + if (event.data.durationMs) console.log(` Duration: ${event.data.durationMs}ms`); + if (event.data.totalTokens) console.log(` Tokens: ${event.data.totalTokens}`); + if (event.data.totalToolCalls) console.log(` Tool calls: ${event.data.totalToolCalls}`); break; case "subagent.failed": console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`); console.log(` Error: ${event.data.error}`); + if (event.data.durationMs) console.log(` Duration: ${event.data.durationMs}ms`); break; case "subagent.selected": From 7dc169a30df419ad834ffd5ce8e37c9041ee9559 Mon Sep 17 00:00:00 2001 From: Steve Sanderson <1101362+SteveSandersonMS@users.noreply.github.com> Date: Tue, 28 Jul 2026 10:17:15 +0000 Subject: [PATCH 2/2] docs: complete subagent event references Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/features/custom-agents.md | 8 ++++---- docs/features/streaming-events.md | 15 ++++++++++++--- 2 files changed, 16 insertions(+), 7 deletions(-) diff --git a/docs/features/custom-agents.md b/docs/features/custom-agents.md index 13912ddd3..cc643c650 100644 --- a/docs/features/custom-agents.md +++ b/docs/features/custom-agents.md @@ -466,15 +466,15 @@ session.on((event) => { case "subagent.completed": console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`); - if (event.data.durationMs) console.log(` Duration: ${event.data.durationMs}ms`); - if (event.data.totalTokens) console.log(` Tokens: ${event.data.totalTokens}`); - if (event.data.totalToolCalls) console.log(` Tool calls: ${event.data.totalToolCalls}`); + if (event.data.durationMs !== undefined) console.log(` Duration: ${event.data.durationMs}ms`); + if (event.data.totalTokens !== undefined) console.log(` Tokens: ${event.data.totalTokens}`); + if (event.data.totalToolCalls !== undefined) console.log(` Tool calls: ${event.data.totalToolCalls}`); break; case "subagent.failed": console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`); console.log(` Error: ${event.data.error}`); - if (event.data.durationMs) console.log(` Duration: ${event.data.durationMs}ms`); + if (event.data.durationMs !== undefined) console.log(` Duration: ${event.data.durationMs}ms`); break; case "subagent.selected": diff --git a/docs/features/streaming-events.md b/docs/features/streaming-events.md index f359dd606..6ad723e0a 100644 --- a/docs/features/streaming-events.md +++ b/docs/features/streaming-events.md @@ -733,6 +733,7 @@ A custom agent was invoked as a sub-agent. | `agentName` | `string` | ✅ | Internal name of the sub-agent | | `agentDisplayName` | `string` | ✅ | Human-readable display name | | `agentDescription` | `string` | ✅ | Description of what the sub-agent does | +| `model` | `string` | | Model the sub-agent will run with, when known at start | ### `subagent.completed` @@ -743,6 +744,10 @@ A sub-agent finished successfully. | `toolCallId` | `string` | ✅ | Matches the corresponding `subagent.started` | | `agentName` | `string` | ✅ | Internal name | | `agentDisplayName` | `string` | ✅ | Display name | +| `model` | `string` | | Model used by the sub-agent | +| `durationMs` | `number` | | Wall-clock execution duration in milliseconds | +| `totalTokens` | `number` | | Total input and output tokens consumed | +| `totalToolCalls` | `number` | | Total tool calls made | ### `subagent.failed` @@ -754,6 +759,10 @@ A sub-agent encountered an error. | `agentName` | `string` | ✅ | Internal name | | `agentDisplayName` | `string` | ✅ | Display name | | `error` | `string` | ✅ | Error message | +| `model` | `string` | | Model selected for the sub-agent, when known | +| `durationMs` | `number` | | Wall-clock execution duration in milliseconds | +| `totalTokens` | `number` | | Total input and output tokens consumed before failure | +| `totalToolCalls` | `number` | | Total tool calls made before failure | ### `subagent.selected` @@ -958,9 +967,9 @@ This table lists key `data` payload fields. Common envelope fields are documente | `user_input.completed` | ✅ | User Input | `requestId` | | `elicitation.requested` | ✅ | User Input | `requestId`, `message`, `requestedSchema` | | `elicitation.completed` | ✅ | User Input | `requestId` | -| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` | -| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName` | -| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error` | +| `subagent.started` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?` | +| `subagent.completed` | | Sub-Agent | `toolCallId`, `agentName`, `agentDisplayName`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` | +| `subagent.failed` | | Sub-Agent | `toolCallId`, `agentName`, `error`, `model?`, `durationMs?`, `totalTokens?`, `totalToolCalls?` | | `subagent.selected` | | Sub-Agent | `agentName`, `agentDisplayName`, `tools` | | `subagent.deselected` | | Sub-Agent | *(empty)* | | `skill.invoked` | | Skill | `name`, `path`, `content`, `allowedTools?` |