Docs: Medium blog post #1 plan — 'Your agent_events table is a graph'

[caohy1988]

Context

This is the first post in the Medium blog series tracked in #51. Topic: trace reconstruction + DAG rendering — the highest-value, lowest-barrier entry point for BQ Agent Analytics users.

Goal of the post: convert ADK users who have just installed the BigQuery Agent Analytics plugin into active SDK users, by showing the fastest possible "aha" moment (raw agent_events rows → readable conversation tree in one line of Python).

Title candidates

1. "Your BigQuery Agent Analytics table is a graph. Here's how to see it." ← recommended
2. "From event rows to conversation DAGs: debugging ADK agents with BigQuery Agent Analytics"
3. "I stopped reading agent logs. Here's what I use instead."

Recommendation: #1 — concrete, specific curiosity-gap, promises a concrete outcome.

Target audience

ADK agent developers and ML platform engineers who:

• Have installed the BigQuery Agent Analytics plugin
• Have opened the agent_events table in the BigQuery console
• Have bounced off its complexity at least once
• Want a faster debugging / observability loop than writing CTEs against raw events

Structure (Medium best practices)

Target length: 1,400–1,800 words (6–8 min read — Medium's sweet spot). One lede image, 3–4 inline images (code output, DAG screenshot, INFORMATION_SCHEMA query result), one closing image.

H1:  Your BigQuery Agent Analytics table is a graph. Here's how to see it.
Sub: A 10-minute tour of turning raw agent_events rows into readable traces
     with the BQ Agent Analytics SDK.

1. Hook (80 words)
   - Real screenshot: a 47-row BQ query result of agent_events
   - "This is what production looks like to most ADK teams. Good luck
     debugging a multi-turn tool-call failure from that."

2. The problem in one paragraph (120 words)
   - ADK plugin logs events. Events are flat. Conversations are trees.
   - Before: write SQL CTEs to JOIN events by span_id, unnest JSON, pray.
   - After: one SDK call.

3. Setup in 30 seconds (150 words)
   - `pip install bigquery-agent-analytics`
   - `bq-agent-sdk doctor --project-id=... --dataset-id=...`
   - Screenshot of doctor output

4. The demo (600 words, the core)
   - Real scenario: "The Calendar-Assistant bug" (narrative framing)
   - User asks "book me a 1:1 with Priya next Tuesday"
   - Agent fails — plain SQL shows the rows, nothing obvious
   - One line: client.get_session_trace(id).render()
   - ASCII tree reveals: tool_call search_contacts(name="Priya") →
     returned 3 hits → agent picked wrong one → booked wrong meeting
   - trace.tool_calls and trace.error_spans → extract structured data

5. Going deeper (250 words)
   - list_traces(filter=...) to find similar failures
   - Feed into post #2 (code-based eval in CI) — teaser, cross-link

6. What happens behind the scenes (200 words)
   - "Every query the SDK runs is labeled — here's the one
     INFORMATION_SCHEMA query that shows you exactly what it cost."
   - Screenshot of IJOBS query output
   - Bridges to the telemetry work (blocks on issue for label emission);
     useful for eng-leader readers evaluating the SDK

7. Try it (100 words)
   - Link to plugin quickstart + SDK GitHub + post #2 preview
   - One-liner: "Install the plugin today, see your first DAG in 10 min"

Demo requirements

1. Real ADK agent — build a small Calendar-Assistant ADK agent with 3 tools: search_contacts, get_calendar_availability, book_meeting. Runs on real Gemini. Seeds a real failure mode (ambiguous contact name).
2. Real BQ data — deploy the plugin to a sandbox GCP project, run 20–30 real sessions (some good, some failing), let the plugin log everything to agent_events.
3. Real scenario narrative — the "Priya ambiguity" bug is concrete, reproducible, and representative of a bug an agent builder would actually debug.

SDK improvements to ship alongside the post

Two code improvements that would make the post stronger. Worth PRing before publication:

1. Trace.render() output polish — audit for ASCII tree alignment with Unicode tool names, truncation of long prompts (>200 chars → …), optional color codes for errors in TTY mode (opt-in via render(color=True)). Current output works; this is about making screenshots camera-ready.
2. trace.error_spans convenience properties — verify error_message, tool_name, parent_span_id are first-class attrs (not requiring .raw_event["content"] digging). If not, add them.

Small, low-risk, makes the demo smoother and the reader's copy-paste experience reliable.

Dependency

Post section 6 ("What happens behind the scenes") depends on SDK query labeling — tracked in the companion issue. The post can still ship without it by removing section 6, but it's a stronger story with the INFORMATION_SCHEMA screenshot included.

Medium-specific tactics

• Publication: Submit to The Generator (tech audience, 50k+ subs) or Google Cloud Community (primary audience). The Google Cloud handle typically gets better reach for GCP content.
• Opening image: A stylized graphic of "rows → tree" — not a stock photo. Hire a designer or prompt Nano Banana Pro.
• Code blocks: Use Medium's embedded Gist renderer, not inline code blocks, for anything >5 lines. Gists render with syntax highlighting and a "Open in GitHub" link — doubles as SDK backlink.
• Callouts: Use blockquote for one key insight per section. Medium readers skim.
• Tags: bigquery, ai-agents, google-cloud, python, observability (Medium max is 5).
• Links: Canonical URL on the Google Cloud dev blog if available, to preserve SEO juice.
• Closing CTA: Two actions — (1) install the plugin (primary), (2) star the SDK repo (secondary). Skip "follow me on Medium" — low-conversion.

Timeline

• Week 1: Ship SDK polish (render() + error_spans convenience props)
• Week 1–2: Ship query labeling Phase 0 + Phase 1 (enables section 6 screenshot)
• Week 2: Build the Calendar-Assistant demo agent, generate real traces
• Week 2: Draft the post in Google Docs, iterate on hook and screenshots
• Week 3: Internal review (Google Cloud DevRel), publish

Open questions

1. Publication target — Google Cloud publication, The Generator, or personal Medium under Google Cloud co-promotion?
2. Do we have an existing real ADK agent with trace data we can reuse, or do we build the Calendar-Assistant demo from scratch? (Latter adds 2–3 days.)
3. Who owns internal review and co-promotion amplification?
4. Should the companion query-labeling work get its own launch post later, tying in a "how we track SDK adoption" engineering story?

Related

• Series plan and ranking: Docs: Medium blog post series plan — downstream value for BQ Agent Analytics users #51
• Query labeling (blocker for section 6): companion issue filed alongside this one