docs: document sub-agent event attribution#1878
Open
loganrosen wants to merge 10 commits into
Open
Conversation
Document envelope-level agentId in streaming events and clarify parent-agent rendering guidance. Mark parentToolCallId as deprecated for sub-agent attribution. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the documentation to clarify how sub-agent attribution works in streamed session events, centering on the envelope-level agentId and guidance for rendering only the parent agent’s chat output while routing sub-agent activity elsewhere.
Changes:
- Documented envelope-level
agentIdin the streaming event envelope and added renderer guidance to ignore sub-agent assistant events in the main chat UI. - Marked payload-level
parentToolCallIdas deprecated for sub-agent attribution across relevant event payload tables. - Noted in custom agents docs that sub-agent events share the parent session stream and can be separated via the envelope.
Show a summary per file
| File | Description |
|---|---|
| docs/features/streaming-events.md | Adds agentId to the event envelope docs, introduces “render only the parent agent” guidance, and deprecates parentToolCallId for attribution. |
| docs/features/custom-agents.md | Adds a clarification that sub-agent events share the parent stream and can be separated using envelope-level agentId. |
Review details
- Files reviewed: 2/2 changed files
- Comments generated: 1
- Review effort level: Low
Add a hidden validation-only Python block for the parent-agent streaming example so docs validation has a typed session placeholder while keeping the visible snippet concise. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Use a typed CopilotSession helper in the hidden validation snippet instead of typing the session as Any. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Use the docs pipeline's supported TypeScript summary label for the new streaming-events tabbed example. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Keep the quick-reference table note focused on payload fields rather than repeating sub-agent attribution guidance. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Use a single visible Python snippet for parent-response filtering instead of a hidden validation block plus duplicate visible example. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
stephentoub
reviewed
Jul 14, 2026
| print(event.data.delta_content, end="", flush=True) | ||
|
|
||
| session.on(handle) | ||
| ``` |
Collaborator
There was a problem hiding this comment.
Why is this showing code for only two of the six languages?
Contributor
Author
There was a problem hiding this comment.
Fixed by adding equivalent examples for all six SDK languages. Java was the blocker because generated session events did not expose the envelope-level agentId; this now updates Java codegen/generated SessionEvent and adds deserialization coverage, so the docs can show the same filter everywhere.
Remove the two-language parent-response snippet so the streaming events guide does not present uneven language coverage. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add the generated Java session event envelope field for sub-agent attribution and restore equivalent parent-response streaming examples across all SDK languages. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: f1fa1c7f-9fdc-4cd4-9279-586191a6a646
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR documents envelope-level
agentIdas the canonical way to attribute session events to sub-agent instances. The streaming events guide now explains how root/main-agent and session-level events omitagentId, while sub-agent-originated events include it, and shows parent-response filtering consistently across TypeScript, Python, Go, .NET, Java, and Rust.To keep the Java SDK aligned with the documented contract, this also updates Java session event codegen so generated
SessionEventexposesagentId, then adds deserialization coverage for that envelope field. Payload-levelparentToolCallIdremains documented as deprecated rather than removed.Validation
cd java && mvn generate-sources -Pcodegencd java && mvn spotless:apply && mvn test -Dtest=SessionEventDeserializationTestPATH="$PWD/python/.venv/bin:$PATH" just validate-docs-check