Add tutorial: give your AI agent session context with Signals agentic contexts

[jborlase-snowplow]

What changed?

New tutorial tutorials/signals-agentic-contexts/ (5 pages + 2 live Console screenshots): define an EventLog agentic context (Console and Python SDK), retrieve the rolling session record as JSON and as an LLM-ready narrative (Python + Node.js), use it with any chat LLM, and iterate on the prompt field. Framework-agnostic, ~15 minutes, no agent scaffolding.

Why?

Agentic contexts are GA but had no tutorial; this is the canonical walkthrough the agent-framework retrofits link back to.

Reviewer guidance

• Verified end-to-end against a trial org: every code block executed in order from fresh environments, 17 exact-value assertions, all example outputs are genuine sanitized captures (including both narrative and JSON shapes). Console create/publish/edit flows walked live; the pages describe the real form (single scrolling Create context form; Prompt / Primary owner fields) — the docs page's prose invites different field names and needs its own fix.
• Found during verification, needs a product ticket: the Python SDK's create-or-update falls back to PUT only on HTTP 400 while the registry returns 409 — so publish() works for fresh names but unpublish()/delete() can never succeed for event logs via the SDK (raw endpoints verified working; same latent pattern across all five resource types). The docs' documented unpublish/delete lifecycle doesn't currently work in code; the tutorial routes tidy-up through Console.
• A third screenshot (agentic-context-draft-publish.png) is committed but unreferenced — it shows a dev-org prefixed resource name; re-shoot on a session_context-named resource or drop it.
• Honestly unverified: the Snowplow Inspector step, the getDomainSessionId one-liner, and the details-page ⋮ menu contents (all need a live tracked browser session).

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	22d76f5	Commit Preview URL Branch Preview URL	Aug 04 2026, 02:10 PM

[claude]

Style review

Overall this is a well-written tutorial: second person throughout, no marketing language, sentence-case headings, descriptive alt text, imports via mdx-code-block matching sibling Signals tutorials, and every internal link and anchor I checked resolves (/docs/signals/concepts/#attribute-keys, /docs/signals/agentic-contexts/#selecting-events, /docs/sources/web-trackers/cookies-and-local-storage/getting-cookie-values/#domain-session-id, /docs/signals/connection/#signals-nodejs-sdk, and the three tutorial cross-links). The one external URL added, https://snowplow.io/get-started/snowplow-free-trial, returns 200.

A few things to fix:

1. Prerequisite list items aren't capitalized

start.md:

• a Snowplow pipeline with a Collector endpoint receiving events, because an agentic context buffers events from your live stream
• page view tracking on a website you can browse, to generate the session activity you'll read back

The style guide (Lists) says "Capitalize the first word of each item." Sibling tutorials follow this — signals-quickstart/start.md has "Snowplow page view tracking on a web application", "A Signals connection".

Fix: capitalize the first word of all four items, e.g. "A Snowplow pipeline with a [Collector endpoint]…" and "Page view tracking on a website you can browse…".

2. An added image is never referenced

images/agentic-context-draft-publish.png is added in this PR but no page links to it (grep -rn "draft-publish" across the repo returns nothing). Either reference it — the Publish it section in define-agentic-context.md that describes drafts is the natural home — or drop it from the PR.

3. Non-parallel construction

use-it-with-an-llm.md:

The answer should change, because the situation has: this user has reached a checkout, not idly browsing a product page.

"has reached … not idly browsing" doesn't parallel. Fix: "this user has reached a checkout rather than idly browsing a product page."

4. Wrong admonition type for the SDK bug

define-agentic-context.md uses a warning admonition for the publish() / 409 behavior:

:::warning[`publish()` only creates, it can't update]

Per CLAUDE.md, warning is for "important cautions about data loss or security risks" (style guide: "Warning for data loss or security risks, Danger for pipeline outages"). A 409 from a repeated publish() call is neither. Fix: use :::note[…] or :::info[…].

5. "back end" should be hyphenated

retrieve-the-context.md:

read it client-side with the browser tracker's getDomainSessionId method and send it to your back end, because retrieval happens server-side

The style guide (General technical terms) says "Always hyphenate: back-end, front-end, server-side, client-side." Fix: "send it to your back-end". (client-side and server-side in the same sentence are already correct.)

6. Ambiguous sentence

retrieve-the-context.md:

Remember that buffering only started when you published, and a minute or two after that.

As written, "and a minute or two after that" reads as a second, contradictory clause. Fix: "Remember that buffering only started a minute or two after you published."

Minor

• start.md lists credentials as a prerequisite: "You'll also need your Signals connection credentials for the SDK steps: the Signals API URL, an API key, an API key ID, and your organization ID." tutorial-requirements/README.md says "Don't list API keys as a prerequisite: include how to get them as one of the tutorial steps." Consider moving this into the Python SDK tab of define-agentic-context.md, where the environment variables are actually used.
• conclusion.md has no "Next steps" H2. The example structure in tutorial-requirements/example-tutorial/conclusion.md ends with one. The two sections you have do the job, so this is a judgment call — but if you want to match the template, nest Combine it with attributes and Build it into an agent under it.
• The narrative code blocks contain ## Real-time user behaviour (British spelling). If that's verbatim SDK output, leave it; flagging only in case it's hand-written, since the style guide requires US spelling.

[jborlase-snowplow]

Pushed 1a951a85 — editorial sweep per product direction: the SDK-behavior warning is gone; the tutorial now simply teaches the Console edit-and-publish flow for changing a published context, and measured propagation timings are neutral phrasing.

🤖 Generated with Claude Code

[jborlase-snowplow]

Pushed f2de1cce + 5b9fd56c — owner-lens edit round:

• The assistant route now leads: a default AI-assistant tab on the definition page with copy/paste prompts for create + publish, plus assistant prompts for retrieval, prompt-editing, and teardown; setup links out to the Snowplow Assistant and MCP server docs
• All five info panels removed (two constraints survive as single prose sentences); prerequisites cut to three items ending at "A Snowplow account and pipeline"; credentials and Python version moved into the SDK tab where they're used
• The Console-path reader can now finish page 3 (previously the retrieval step assumed an SDK client that Console-tab readers never set up)
• Duplicated instructions removed; the unreferenced draft-publish screenshot deleted (restorable if a re-shoot on a reader-facing name is preferred); 5b9fd56c defers the MCP-tutorial cross-link until that PR merges (docs links only for now)

🤖 Generated with Claude Code

[jborlase-snowplow]

Pushed a34246b8 (owner's own removal of assistant instructions from JSON retrieval) + d1b1abbe — the LLM page is reframed around the customer-facing agent: retitled Feed a Signals agentic context to your agent, centered on a per-turn retrieve-and-append-to-system-prompt pattern with one framework-agnostic snippet, MCP-retrieval framing removed throughout (the MCP tool that exists is a publish-verification affordance whose output is data-not-instructions — not a consumption path), and it closes by pointing at the three full agent tutorials. The introduction now opens with the problem: a customer-facing agent answers blind unless it can see what this user is doing right now.

🤖 Generated with Claude Code

[jborlase-snowplow]

Claude (@claude) review please

[jborlase-snowplow]

Pushed 22d76f56 — style-guide compliance pass against CLAUDE.md and the extended style guide: twelve fixes (tense, active voice, hyphenation, link text, one over-length sentence split, a banned "right now"). Deliberately not applied per owner direction and product accuracy: "agentic context" stays (feature name), verbatim narrative output keeps its British spelling, and no admonitions were reintroduced. Two flagged for reviewer judgment rather than changed: the definition step has no H2 (absent from the page TOC), and page 4's closing links duplicate the conclusion's.

🤖 Generated with Claude Code