Review and update ADK-TS events section documentation#707
Merged
Timonwa merged 3 commits intoMay 26, 2026
Conversation
Rewrites all pages in the events section against the actual source in packages/adk/src/events/ to fix inaccuracies, add missing fields, and bring content in line with the artifacts section standard. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request refactors and streamlines the event system documentation under apps/docs/content/docs/framework/events/. It replaces theoretical architectural patterns with practical, API-grounded examples (such as multi-turn chat loops, tool activity indicators, and streaming utilities like textStreamFrom). One review comment suggests removing unnecessary any type casting on event when accessing errorCode and errorMessage in working-with-events.mdx to maintain type safety.
Comment on lines
+167
to
+170
| if ((event as any).errorCode) { | ||
| console.error( | ||
| `Error ${(event as any).errorCode}: ${(event as any).errorMessage}`, | ||
| ); |
Contributor
There was a problem hiding this comment.
Since Event inherits errorCode and errorMessage from LlmResponse (as mentioned in the text above), casting event to any is unnecessary and reduces type safety in the documentation example. We can access these properties directly.
if (event.errorCode) {
console.error(
"Error " + event.errorCode + ": " + event.errorMessage,
);
There was a problem hiding this comment.
Pull request overview
This PR rewrites the ADK-TS “Events” documentation section to align the docs with the current implementation in packages/adk/src/events/, replacing older generic guidance with ADK-TS-specific APIs and patterns.
Changes:
- Rewrites the Events docs pages to document actual
Event,EventActions, compaction, and streaming behaviors. - Adds/updates examples and diagrams (Mermaid) for event flow and compaction.
- Updates navigation ordering by removing
"index"fromapps/docs/.../events/meta.json.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| apps/docs/content/docs/framework/events/index.mdx | Updates the Events landing page with current Event fields, helper methods, flow diagram, and quick-start example. |
| apps/docs/content/docs/framework/events/event-actions.mdx | Rewrites EventActions reference with examples for state/artifacts/transfers/escalation/auth/compaction/rewind. |
| apps/docs/content/docs/framework/events/working-with-events.mdx | Adds practical patterns for reading content, detecting final responses, handling tool calls, deltas, filtering, and errors. |
| apps/docs/content/docs/framework/events/streaming.mdx | Documents streaming utilities (textStreamFrom, collectTextFrom, streamTextWithFinalEvent) and manual streaming patterns. |
| apps/docs/content/docs/framework/events/patterns.mdx | Replaces generic patterns with ADK-TS event patterns (chat loop, tool activity, transfers, replay, audit log). |
| apps/docs/content/docs/framework/events/compaction.mdx | Rewrites compaction docs with diagrams, configuration, summarizer examples, and inspection guidance. |
| apps/docs/content/docs/framework/events/meta.json | Removes "index" from the pages list to match section/index behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+34
to
+35
| event.getFunctionCalls(); // Part[] — tool calls the agent wants to make | ||
| event.getFunctionResponses(); // Part[] — results returned from tools |
Comment on lines
+17
to
25
| for await (const event of runner.runAsync(request)) { | ||
| if (!event.content?.parts) continue; | ||
|
|
||
| for (const part of event.content.parts) { | ||
| if (part.text) { | ||
| process.stdout.write(part.text); | ||
| } | ||
| } | ||
| } |
Comment on lines
+167
to
+169
| if ((event as any).errorCode) { | ||
| console.error( | ||
| `Error ${(event as any).errorCode}: ${(event as any).errorMessage}`, |
Comment on lines
+14
to
20
| When the LLM is mid-generation, the runner emits `Event` objects with `partial: true`. Each partial event contains a text fragment in `event.content.parts`. Once generation finishes, a final event arrives with `partial` unset (or `false`) — this is the event `isFinalResponse()` returns `true` for. | ||
|
|
||
| ### Event Properties for Streaming | ||
|
|
||
| Key properties that control streaming behavior: | ||
|
|
||
| ```typescript | ||
| interface Event { | ||
| partial?: boolean; // True for incomplete streaming chunks | ||
| turnComplete?: boolean; // True when the agent's turn is finished | ||
| content?: any; // Contains the partial or complete content | ||
| // ... other properties | ||
| } | ||
| ``` | ||
|
|
||
| ## Basic Streaming Patterns | ||
|
|
||
| ### Simple Text Streaming | ||
|
|
||
| Handle streaming text responses: | ||
|
|
||
| ```typescript | ||
| async function handleStreamingResponse(runner, query, session) { | ||
| let accumulatedText = ""; | ||
|
|
||
| for await (const event of runner.runAsync(query, session)) { | ||
| if (event.content?.parts?.[0]?.text) { | ||
| if (event.partial) { | ||
| // Partial chunk - accumulate and display | ||
| accumulatedText += event.content.parts[0].text; | ||
| displayPartialText(accumulatedText); | ||
| } else { | ||
| // Complete chunk | ||
| accumulatedText += event.content.parts[0].text; | ||
| if (event.isFinalResponse()) { | ||
| displayFinalText(accumulatedText); | ||
| accumulatedText = ""; // Reset for next response | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| Event { partial: true, content: { parts: [{ text: "The answer" }] } } | ||
| Event { partial: true, content: { parts: [{ text: " is 42." }] } } | ||
| Event { partial: false, content: { parts: [{ text: "" }] } } ← final | ||
| ``` |
| // Final response | ||
| if (event.isFinalResponse()) { | ||
| const text = event.content?.parts?.[0]?.text ?? ""; | ||
| finalizeUI(buffer + text); |
|
|
||
| ### State Management | ||
| // OAuth / API-key auth configs requested by tools. | ||
| requestedAuthConfigs: { "gmail-tool": { type: "oauth" } }, |
Comment on lines
141
to
152
| Tools that need OAuth or API-key credentials populate `requestedAuthConfigs` with one entry per tool. The framework surfaces this to your application so it can trigger an auth flow before the tool call is retried. | ||
|
|
||
| ```typescript | ||
| for await (const event of runner.runAsync(query, session)) { | ||
| if (event.actions) { | ||
| // Check for state changes | ||
| if (Object.keys(event.actions.stateDelta).length > 0) { | ||
| console.log("State updated:", event.actions.stateDelta); | ||
| } | ||
|
|
||
| // Check for artifact updates | ||
| if (Object.keys(event.actions.artifactDelta).length > 0) { | ||
| console.log("Artifacts saved:", event.actions.artifactDelta); | ||
| } | ||
|
|
||
| // Check for control signals | ||
| if (event.actions.transferToAgent) { | ||
| console.log(`Transferring to: ${event.actions.transferToAgent}`); | ||
| } | ||
|
|
||
| if (event.actions.escalate) { | ||
| console.log("Escalation signal received"); | ||
| // Reading auth requests from events | ||
| for await (const event of runner.runAsync(request)) { | ||
| if (event.actions.requestedAuthConfigs) { | ||
| for (const [toolName, config] of Object.entries( | ||
| event.actions.requestedAuthConfigs, | ||
| )) { | ||
| console.log(`Tool "${toolName}" needs auth:`, config); | ||
| } | ||
| } |
Comment on lines
+103
to
+107
| import { AgentBuilder, LlmEventSummarizer } from "@iqai/adk"; | ||
| import { LlmRegistry } from "@iqai/adk"; | ||
|
|
||
| ### Basic Usage with AgentBuilder | ||
|
|
||
| ```typescript | ||
| import { AgentBuilder } from "@iqai/adk"; | ||
| const cheapModel = LlmRegistry.newLlm("gemini-2.0-flash-lite"); | ||
| const summarizer = new LlmEventSummarizer(cheapModel); |
errorCode and errorMessage are typed on LlmResponse which Event extends, so the cast was never needed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Fix getFunctionCalls/getFunctionResponses return type comments (Part[]
was wrong — they return {name,args}[] and {name,response}[])
- Fix text streaming loop to only write partial deltas, not all events
- Fix streaming diagram to show final event carries full accumulated text
- Fix manual streaming loop to use final event text directly (not buffer+text)
- Fix requestedAuthConfigs key description: keys are functionCallId, not tool name
- Fix LlmRegistry -> LLMRegistry and newLlm -> newLLM (correct export names)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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.
Closes #702
Summary
apps/docs/content/docs/framework/events/against the actual source inpackages/adk/src/events/"index"frommeta.jsonpages array (section heading opens the index automatically)patterns.mdx(contained generic software patterns — CQRS, Saga, Circuit Breaker — with no ADK-TS API usage) and replaces it with ADK-TS-specific patterns built on real framework APIsPage-by-page changes
index.mdx— documents actualEventclass fields from source (longRunningToolIds,branch, both helper methods), adds a Mermaid event flow diagram, and a concrete quick-start example.event-actions.mdx— covers every field inEventActionsincluding two previously undocumented ones:rewindBeforeInvocationIdandcompaction. Each field has a prose explanation and a code example.working-with-events.mdx— focused on practical ADK-TS API usage: readingcontent.parts,isFinalResponse()with all three true-cases explained,getFunctionCalls()/getFunctionResponses(), readingstateDeltaandartifactDelta, filtering, error fields, and multi-agent author routing.compaction.mdx— adds a Mermaid sequence diagram of the compaction engine, a config reference table,LlmEventSummarizerwith custom model and prompt examples, a full customEventsSummarizerimplementation, and how to inspect compaction events in the stream.streaming.mdx— rewritten around the three utility functions exported from@iqai/adk/utils(textStreamFrom,collectTextFrom,streamTextWithFinalEvent) that were entirely undocumented. Includes a comparison table and a manual streaming loop for full-event-access cases.patterns.mdx— replaced with seven ADK-TS-specific patterns: multi-turn chat loop, tool activity indicator, long-running tool handling, agent transfer tracking, reactive state updates, artifact save notifications, state rebuild from session history, and session audit log.Test plan
pnpm build:docs)@iqai/adkimports andgemini-2.5-flashas the default modelmeta.jsonreflects the correct page order🤖 Generated with Claude Code