Ben Taylor
9b35950bee
## What
- Adds `integrations/adk/agent-app-context.mdx`, the page ADK was
missing.
- Lists it under **App Control** in `adk/meta.json`, beside
`frontend-tools` and `shared-state`, matching Mastra.
- Scopes the built-in-agent page's "no backend configuration needed" to
the built-in agent, and points at the per-framework pages.
## Why
`ag_ui_adk` stores `RunAgentInput.context` in ADK session state under
`CONTEXT_STATE_KEY` (`"_ag_ui_context"`) and stops there. Its own
docstring says so:
> Context from RunAgentInput is always stored in session state under the
`_ag_ui_context` key (CONTEXT_STATE_KEY), making it accessible to both
tools (via `tool_context.state`) and instruction providers (via
`ctx.state`).
Nothing in the package puts it in front of the model —
`CONTEXT_STATE_KEY` is read in exactly one place, `a2ui_tool.py`, for
the A2UI catalog entry. ADK's `inject_session_state` substitutes only
explicit `{key}` placeholders, so an `LlmAgent` built with a plain
string `instruction` (the form every ADK quickstart shows) never sees
what `useAgentContext` sent.
The agent still answers. Probing one such agent with the page's full
queue in `context` and then with `context: []`:
| context sent | report the model passed to its own tool |
| -- | -- |
| full queue | `"The payment gateway is returning 500 errors for 40% of
checkout requests…"` |
| full queue, repeated | `"The production payment service is returning
500 errors for 80%…"` |
| **empty** | `"Database connection pool exhausted on us-east-1
production cluster…"` |
Three inventions, and the empty-context run is indistinguishable from
the two full ones. Nothing errors, nothing is missing from the UI, and
the answer is well formed — which is exactly why a page is the right fix
rather than a troubleshooting note.
Mastra and LangGraph both document their retrieval step. ADK had none,
and `langgraph/programmatic-control.mdx` already links to a sibling page
that did not exist for ADK.
The page covers both retrieval forms — an `InstructionProvider` reaching
`ctx.state` (with the note that `canonical_instruction` reports
`bypass_state_injection=True` for a provider, so JSON braces in the
rendered context survive), and `tool_context.state` when only one tool
needs the data — and closes with the empty-context control as the way to
check the wiring.
## Testing
- Both `.mdx` files compile under `@mdx-js/mdx`.
- `adk/meta.json` parses, and `agent-app-context` sits in the group
Mastra puts it in.
- Internal links use the repo's own convention (`/adk/…`,
`/langgraph/agent-app-context`, `/mastra/agent-app-context`), matching
links already in the tree.
- `<Callout type="warn" title="…">` matches existing usage.
- The docs site build was not run locally — the worktree has no install.
Leaving that to CI.
Filed as OSS-1045 internally, a sibling of OSS-1027 (Pydantic AI's
adapter drops the same field outright).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added ADK integration guidance for sharing application context with
agents, including setup steps and access from instructions and tools.
* Updated documentation navigation to include the new ADK application
context page.
* Clarified how built-in and self-hosted agents receive and process
application context, with links to framework-specific guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Shell Docs
showcase/shell-docs is the Next.js app that builds and serves
docs.copilotkit.ai. Author CopilotKit product documentation here, not in the retired
top-level docs/ app.
Run Locally
Shell-docs is a standalone npm-based app. You do not need a root install just to run the docs app locally.
cd showcase/scripts
npm install
cd ../shell-docs
npm install
npm run dev
The local dev server runs on port 3003.
http://localhost:3003
The shell-docs npm lifecycle generates registry, demo-content, setup-content, and search
data before dev, build, and typecheck.
Validate Changes
Run these from showcase/shell-docs:
npm run build
npm run typecheck
npm run test
For repo-level CI parity, prefer Nx when a shell-docs target is available in the current checkout and root dependencies are installed. For normal shell-docs local development, the npm commands above are the canonical path.
Authoring Recipes
Showcase-Driven Framework Docs
Showcase-driven frameworks use docs_mode: generated. The docs are assembled from showcase
registry/generated data, demos, source regions, shared/root MDX, snippets, and sparse
framework overrides.
To update showcase-driven docs:
- Edit the showcase source of truth: manifests, demos, feature coverage, source regions, or registry inputs.
- Edit shared/root MDX only when the change applies across generated frameworks.
- Add sparse framework overrides only for real framework-specific differences.
- Do not hand-edit generated files under
src/data/frameworks/. - Validate routes, sidebar state, search results, snippets, and framework switching.
Authored Framework Docs
Authored frameworks use docs_mode: authored. The framework owns an MDX tree under
src/content/docs/integrations/<docsFolder>/ with a meta.json sidebar.
To update authored docs:
- Check
getDocsFolder()insrc/lib/registry.ts; the URL slug and folder name may differ. - Edit the MDX page under
src/content/docs/integrations/<docsFolder>/. - Update that folder's
meta.jsonwhen adding, removing, or moving pages. - Reuse shared snippets from
src/content/snippets/when content should stay consistent across frameworks. - Validate the framework route, sidebar, search result, and any shared snippet render.
Reference Docs
Edit API reference pages under src/content/reference/.
The v2 reference does not use meta.json; navigation is generated by walking the tree and
reading each page's title and description frontmatter. Only the legacy reference/v1/
tree uses meta.json.
Snippets
Reusable snippets live under src/content/snippets/. Snippets may be rendered by root docs,
authored framework pages, and showcase-driven framework pages, so keep them general unless
the path is intentionally framework-specific.
Frontend Applicability
Frontend routes use page-level applicability metadata, independent from where the content is authored. A page can be authored MDX, showcase-generated content, mirrored protocol docs, or reference content and still be universal across frontends.
Use the frontend field in page frontmatter or meta.json when a root doc should appear in
non-React frontend docs:
universal— render the same page under/<frontend>/....frontend-variant— render only when a matching page exists undersrc/content/docs/frontends/<frontend>/....hide— omit the page from frontend-scoped docs.
Do not use "showcase-driven" as a proxy for frontend availability. Showcase derivation is an authoring/source detail; frontend applicability controls routing and sidebar inclusion.
AG-UI Mirrored Docs
AG-UI protocol docs are authored upstream in ag-ui-protocol/ag-ui. The
src/content/ag-ui/ tree is a downstream mirror rendered on the CopilotKit docs host.
Change AG-UI docs upstream first, then sync the mirror back into shell-docs.
Top-Level Docs Symlink
The repository's top-level docs/ path is a symlink to showcase/shell-docs/ for
contributor muscle memory. It is not a separate docs app. Do not recreate the old
docs/content/docs/ tree; author CopilotKit docs in showcase/shell-docs/src/content/.