docs(bqaa): document ADK 2.0 agent-workflow and pause/resume events#1843
Closed
caohy1988 wants to merge 8 commits into
Closed
docs(bqaa): document ADK 2.0 agent-workflow and pause/resume events#1843caohy1988 wants to merge 8 commits into
caohy1988 wants to merge 8 commits into
Conversation
Added reliability and observability fixes for BigQuery Agent Analytics, including cross-region storage write routing, dropped-event tracking, and improved span management in Cloud Trace.
Resolve the code-fence/content-tab indentation issues flagged in review: - Full example: restore the === "Python" content tab and indent the whole Python code block uniformly to 8 spaces so it is a proper sibling of the === "Java" tab (previously the block was half-de-indented with an orphaned opening fence next to a lone Java tab). - Public methods: move the Python list inside the === "Python" tab (it had been pasted at column 0, outside the tab) and remove the duplicated list that ended up wrongly nested under the "Async context manager" bullet.
Add documentation for the ADK 2.0 "minimum producer cut" support in the BigQuery Agent Analytics plugin: - New event types: AGENT_TRANSFER, AGENT_STATE_CHECKPOINT, EVENT_COMPACTION, and TOOL_PAUSED — with payload examples and auto-created views. - The `attributes.adk` envelope (schema_version, app_name, source_event_id, node, branch, scope, pause_kind, function_call_id) with a concise field reference and querying guidance. - TOOL_PAUSED <-> TOOL_COMPLETED pairing via function_call_id, with base-table and view-based SQL join recipes for measuring tool pause duration. - v_tool_completed gains the pause_kind / function_call_id columns. - Captured-events summary, schema event_type reference, views table, and a new use-case bullet updated to include the ADK 2.0 events. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA). View this failed invocation of the CLA check for more information. For the most up to date status, view the checks section at the bottom of the pull request. |
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
…paction Verified against google/adk-python main (the to-be-shipped code), which differs from the older fork branch the first draft referenced: - Version requirement: the ADK 2.0 workflow events are on main but not in any published release (not in v2.2.0). Reword the requirement note and intro to stop implying ADK 2.0 / v2.2.0 already ship them. - HITL pairing: HITL completions are logged as HITL_*_REQUEST_COMPLETED, never TOOL_COMPLETED, so a hitl_* pause cannot pair through the tool join. Restrict both pause/resume queries to pause_kind='tool' and rewrite the HITL note. - attributes.adk.node: the producer writes parent_run_id, not parent_path. - EVENT_COMPACTION: compacted_content is a plugin-formatted string (via _format_content_safely), not a structured object. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…r-key shape - Views table: mark the four ADK 2.0 workflow views and the new v_tool_completed pause_kind / function_call_id columns with a footnote noting they exist only in builds with the ADK 2.0 workflow event support (not in v2.2.0), so 1.27.0+ users don't look for views/columns that aren't there. Also label v_event_compaction.compacted_content as JSON holding the formatted summary. - attributes.adk envelope table: split pause_kind/function_call_id wording — TOOL_PAUSED carries tool or hitl_*, but a resumed TOOL_COMPLETED only ever carries pause_kind='tool' (HITL completions are HITL_*_REQUEST_COMPLETED). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Distinguish released plugin features from the unreleased ADK 2.0 workflow support in the top-level Version Requirement note, so 1.26.0+/v2.2.0 users are not told the whole document is available to them. Also note the 1.27.0+ requirement for automatic view creation. Correct the span_id description in three places (intro code comment, schema table, and Tracing section): span_id is not always internally generated. The root invocation span reuses the ambient OTel span id when one is active; only child BQAA spans are generated internally. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The manual CREATE TABLE DDL still described span_id as "Generated internally by the plugin." Align it with the corrected wording elsewhere: the root invocation span may reuse the ambient OTel span id while child BQAA spans are generated internally, and no OTel span is created/exported. Co-Authored-By: Claude Opus 4.8 (1M context) <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
2 participants
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
Documents the ADK 2.0 support added to the BigQuery Agent Analytics plugin (the "minimum producer cut") in
docs/integrations/bigquery-agent-analytics.md. ADK 2.0 introduced multi-agent workflows and long-running tools that pause/resume across turns; this PR makes those flows discoverable and queryable for users.What's added
AGENT_TRANSFER— one agent hands off to another (v_agent_transfer)AGENT_STATE_CHECKPOINT— agent state snapshot / end-of-run marker (v_agent_state_checkpoint)EVENT_COMPACTION— a window of events compacted into a summary (v_event_compaction)TOOL_PAUSED— a long-running tool or HITL request suspends (v_tool_paused)attributes.adkenvelope — a concise field reference (schema_version,app_name,source_event_id,node,branch,scope,pause_kind,function_call_id) plus querying guidance.TOOL_PAUSED↔TOOL_COMPLETEDjoined onfunction_call_id, with base-table and view-based SQL recipes for measuring how long a tool was suspended.v_tool_completedgainspause_kind/function_call_id; the captured-events summary,event_typeschema reference, views table, version note, and use-cases list are updated to include the ADK 2.0 events.Doc-vs-code accuracy
All event types, view columns, and envelope fields were verified against the plugin source (
src/google/adk/plugins/bigquery_agent_analytics_plugin.py): the_EVENT_VIEW_DEFSview definitions, the_build_adk_envelope/_enrich_attributesenvelope logic, and theTOOL_PAUSEDemission path. The existingAGENT_RESPONSEdocs (flatattributes.source_event_*) are intentionally left unchanged, since that event predates theattributes.adkenvelope.Note on basing
This PR is stacked on top of #1817 (
patch-19), which is still open and edits the same file. Until #1817 merges, this PR's diff also includes #1817's reliability/observability changes. Once #1817 merges, rebasing this branch ontomainwill reduce the diff to the ADK 2.0 additions only.🤖 Generated with Claude Code