Pair agentic contexts with profile attributes in the Google ADK tutorial - #1897
Pair agentic contexts with profile attributes in the Google ADK tutorial#1897jborlase-snowplow wants to merge 5 commits into
Conversation
The signals-google-adk-agent tutorial pre-dates agentic contexts and hand-rolled what the feature now provides: build-agent.md composed a "Real-Time User Context" markdown block from attribute values via a custom _format_attributes() helper. Retrofit it as a pairing rather than a replacement, matching the U1 Vercel retrofit. The before_model_callback now fetches both kinds of Signals context and appends both to the system instruction, and the tutorial explains when each is the right tool: - user-level profile attributes (computed aggregates, via the service) - in-session agentic context (recent activity as an LLM-ready narrative, via get_agentic_context with format="narrative") Changes: - configure-signals.md: add an agentic-context definition step with Console and Python SDK tabs, selecting event_name and page_urlpath so the narrative's table columns populate - build-agent.md: replace the hand-built session-activity block with get_agentic_context(); the two fetches degrade independently, and append_instructions() takes both sections as a list. Both the narrative and the composed system instruction are real captures. Add the Snowplow Inspector verification step - introduction.md: describe both context types and both fetches in the component flow; add the missing free-trial note; point the prerequisite at /docs/signals/setup/ instead of the credentials page - project-setup.md: add SNOWPLOW_SIGNALS_AGENTIC_CONTEXT_NAME; correct the Signals base URL placeholder to https://YOUR_ID.signals... - conclusion.md: list the agentic context in the summary Two fixes beyond the retrofit itself: - Drop None-valued attributes before formatting the profile section. get_service_attributes() returns a key for every attribute in the service, valued None until the session produces one, so the old "if not attributes" guard never fired and the agent would have sent "page_views_count: None" to the model. - Unpin the preview model ID (gemini-3-flash-preview -> gemini-2.5-flash) and add a note on changing the model string. Verified against a live trial org: the Python SDK block publishes as written, six real Collector events produce the documented attribute values and narrative, and the ADK before_model_callback composes an instruction containing both sections. The Gemini call itself is unverified — no Google AI/Vertex key was available. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…e PNG Two gaps left open by d21b7ee, both closable without a browser. The Console tab for the new agentic-context step was written from docs/signals/agentic-contexts/index.md, which describes the create form in prose rather than quoting its labels. Turning that prose into bold control names produced fields the product doesn't have. Align it with the form as observed in the live Console by the T4 tutorial's run: - one scrolling Create context form with Details, Prompt, Lookback Window, and Events and Properties sections, not a five-step wizard - Prompt, not "Prompt instructions"; Primary owner, not "Owner", and it arrives pre-filled - Max events and Max age with a unit dropdown, so 30 minutes rather than 1800 seconds, and Console restates the resulting window - Add event and Add property in Events and Properties - Publish and Edit live on the details page, and edits start as drafts - the list page's create button stays unnamed, since its label is unverified Replace adk-architecture.png with a Mermaid flowchart. The PNG drew only the attributes fetch, so it stopped matching the callback once the agentic context landed alongside it, and it labelled the agent gemini-3 while the page uses gemini-2.5-flash. It can't be regenerated here, and the style guide prefers Mermaid for architecture visuals. The diagram carries what the PNG had plus the agentic context: both Signals resources fed from enriched events, both fetches as labelled edges off before_model_callback, and the two sections joining at append_instructions. Deleting the PNG retires its now-incomplete alt text, and the flow bullets above the diagram serve as its text equivalent. Verified with mermaid 11.14.0, the version the site ships: parse and render both succeed, and the built HTML emits the same wrapper an existing repo diagram does. yarn build passes. No code the reader runs changed, and no Signals resources were created. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
documentation | c8e5599 | Commit Preview URL Branch Preview URL |
Jul 31 2026, 03:50 PM |
Style reviewOverall this is a solid, well-organized addition — the agentic context material is clearly explained, the new Mermaid diagram is a good replacement for the PNG (and no stale references to A handful of style points below. 1. "frontend" should be hyphenated (
|
Walked every Console instruction in this tutorial against the live trial org, built each resource through the UI in the order the pages describe, and corrected what the walk contradicted. Two claims were false and are gone: - Run Preview does not exist. Searched the DOM for "preview" at three points in the attribute-group lifecycle (create form with the template applied, details page while v1 (Not published), details page once v1 (Published)) and got zero matches every time. Both places that named it are rewritten: configure-signals.md gets the verified type/aggregation/property table, build-agent.md gets the null-attribute explanation that actually helps at that point. Caveat: this trial org has no warehouse connection and the removed copy described a warehouse query, so the control may be gated rather than absent — but the instruction was unconditional and wrong for a reader on the trial pipeline the prerequisites describe. - unique_pages_viewed holds full URLs, not paths. The Basic Web template defines it as unique_list over the atomic page_url property, read from the create form and again from the created group's details page. The page's own example was right; the capture added by the previous run was the artifact, because it came from an SDK-built group using page_urlpath. Rather than edit numbers by hand, the group was rebuilt through Console from the template, republished, and the six-event journey re-sent. The service response, the narrative, the composed system instruction, and the agent log lines in build-agent.md now all come from one real session, and configure-signals.md shows the same capture in place of an illustrative block with invented values. The hedging sentence is replaced by the real contrast: the service reads page_url, the agentic context reads page_urlpath. Console labels corrected from first-hand observation: - sidebar is Attribute groups, and the create-form field is Attribute key - the Basic Web template is applied by clicking Use on its card - publishing a group deploys it to the Profiles Store, v1 (Not published) becomes v1 (Published) - the service form's Attribute groups picker lists published groups only, so publishing first is required, not tidy - service names take letters, numbers, and underscores only - the agentic-contexts list page button is Create context - Details fields are Name, Primary owner, Description in that order, and Primary owner is pre-filled and read-only - Add event uses the Data structures tab and auto-fills version 1-0-0; Add property uses the Atomic tab - the form submits with Create, the details page then shows Status Draft, and Publish opens a confirm dialog - the details page shows Max Age (seconds) 1800 for the form's 30 minutes Adds one screenshot of the Create context form, showing the Details and Prompt sections with this tutorial's own values. The Lookback Window and Events and Properties screen is identical to the one the agentic-contexts tutorial already ships, so it is covered in prose instead of duplicated. The Snowplow Inspector step is rewritten so every claim matches the page it links, and now names the connect-and-credentials prerequisite and the Attributes tab. It remains unexercised: this Chrome profile has no extensions installed and installing one was out of scope. yarn build passes with the image. Everything created was torn down and the registry is confirmed empty. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Pushed
Remaining known gap (unchanged): the Gemini call needs a Google AI/Vertex credential; everything up to and including the composed instructions is verified. 🤖 Generated with Claude Code |
Rephrase the sample service response and narrative capture so they no longer refer to our own test runs, and point readers at the Console edit-and-publish flow for changing a published agentic context.
|
Pushed 🤖 Generated with Claude Code |
Featured the AI-assisted route: a new "Ask the Snowplow Assistant" section carries a copy/paste prompt that creates and publishes the attribute group, service, and agentic context, ahead of the manual Console steps. Trimmed to the owner's lens: dropped the Micro/"full pipeline" panel for a minimal prerequisite and added the missing completion-time line, converted the React-framework and model-choice panels to prose, removed the duplicated attributes-vs-agentic-context explanation that introduction.md already carries, and reframed the verification steps positively. Dropped internal-verification artifacts from the agent log sample (HTTP status lines and the character count), and matched the log statement in the code to the output now shown. Folded "Try it out", "Verify Signals context", and the Inspector section together, and collapsed six next-step headings into one list, bringing build-agent.md and conclusion.md within the 3-5 H2 guidance. Load-bearing constraints stay as positive prose: the page_url/page_urlpath contrast, the published-groups-only picker, and the narrative column mapping. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Pushed 🤖 Generated with Claude Code |
2 participants
What changed?
Retrofits
tutorials/signals-google-adk-agent/to use agentic contexts natively: an agentic-context definition step (Console + Python SDK tabs, mirroring the Vercel retrofit's structure), and thebefore_model_callbacknow composes BOTH the profile attributes and the narrative into the instructions viaappend_instructions, with when-to-use-which guidance (per product direction). Also fixes the same truthy-Noneguard bug in its Python (if not attributes:never fires on a dict ofNones), fixes four pre-existing convention violations (missing free-trial note among them), and replaces the stale architecture PNG (which contradicted the page's own model name) with a Mermaid diagram.Why?
Same rationale as the Vercel retrofit — the tutorial hand-rolled what agentic contexts now provide.
Reviewer guidance
page_views_count == 6,unique_pages_viewedwith one revisit correctly deduplicated), instruction composition proven. The Gemini call is unverified — noGOOGLE_API_KEYavailable, none substituted.unique_pages_viewedholds full URLs or paths (the one place two examples disagree; flagged rather than invented).web_agent_context(underscores) while the Vercel tutorial's isweb-agent-context(hyphens) — pick a convention; neither PR silently renames.🤖 Generated with Claude Code