diff --git a/docs/composer.md b/docs/composer.md index f2f283137..44f9be31c 100644 --- a/docs/composer.md +++ b/docs/composer.md @@ -8,9 +8,11 @@ Try building A2UI widgets interactively with the **CopilotKit A2UI Widget Builde ## What it does -- Experiment with A2UI components visually -- Generate A2UI JSON by describing what you want -- See real-time previews -- Copy JSON to use in your agents +The Widget Builder enables you to: + +- Experiment with A2UI components visually. +- Generate A2UI JSON by describing desired interfaces. +- View real-time previews. +- Copy the generated JSON for use in agents. Built by the [CopilotKit](https://www.copilotkit.ai/) team. \ No newline at end of file diff --git a/docs/concepts/catalogs.md b/docs/concepts/catalogs.md index fd3577ed4..fa943bec1 100644 --- a/docs/concepts/catalogs.md +++ b/docs/concepts/catalogs.md @@ -6,9 +6,9 @@ This guide defines the A2UI Catalog architecture and provides a roadmap for impl ## Catalog Schema -A catalog schema is a [JSON Schema file](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) outlining the components, functions, and themes that agents can use to define A2UI surfaces using server-driven UI. All A2UI JSON sent from the agent is validated against the chosen catalog. +A catalog schema is a [JSON Schema file](../../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) outlining the components, functions, and themes that agents can use to define A2UI surfaces using server-driven UI. All A2UI JSON sent from the agent is validated against the chosen catalog. -[Catalog JSON Schema](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) is below +[Catalog JSON Schema](../../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) is below ```json { @@ -59,7 +59,7 @@ Whether you are building a simple prototype or a complex production application, ### The Basic Catalog -To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../specification/v0_9/json/basic_catalog.json). +To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../../specification/v0_9/json/basic_catalog.json). This is a pre-defined catalog file that contains a standard set of general-purpose components (Buttons, Inputs, Cards) and functions. It is not a special "type" of catalog; it is simply a version of a catalog that we have already written and have open source renderers for. @@ -67,7 +67,7 @@ The basic catalog allows you to bootstrap an application or validate A2UI concep Since A2UI is designed for LLMs to generate the UI at either design time or runtime, we do not think portability requires a standardized catalog across multiple clients; the LLM can interpret the catalog for each individual frontend. -[See the A2UI v0.9 basic catalog](../specification/v0_9/json/basic_catalog.json) +[See the A2UI v0.9 basic catalog](../../specification/v0_9/json/basic_catalog.json) ### Defining Your Own Catalog @@ -77,7 +77,7 @@ By defining your own catalog, you restrict the agent to using exactly the compon For simplicity we recommend building catalogs that directly reflect a client's design system rather than trying to map the Basic Catalog to it through an adapter. Since A2UI is designed for GenUI, we expect the LLM can interpret different catalogs for different clients. -[See an example Rizzcharts catalog](../samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json) +[See an example Rizzcharts catalog](../../samples/agent/adk/rizzcharts/catalog_schemas/0.9/rizzcharts_catalog_definition.json) ### Recommendations @@ -88,7 +88,7 @@ For simplicity we recommend building catalogs that directly reflect a client's d ## Building a Catalog -A catalog is a JSON Schema file that conforms to the [Catalog schema](../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) that defines the components, themes and functions an agent can use when building a surface. +A catalog is a JSON Schema file that conforms to the [Catalog schema](../../specification/v0_9/json/client_capabilities.json#L62C5-L95C6) that defines the components, themes and functions an agent can use when building a surface. ### Example: A Minimal Catalog @@ -275,7 +275,7 @@ export class HelloWorldBanner extends DynamicComponent { } ``` -You can see a working example of a client renderer in the [Rizzcharts demo](../samples/client/angular/projects/rizzcharts/src/a2ui-catalog/catalog.ts). +You can see a working example of a client renderer in the [Rizzcharts demo](../../samples/client/angular/projects/rizzcharts/src/a2ui-catalog/catalog.ts). ## A2UI Catalog Negotiation @@ -461,4 +461,4 @@ Example of client reporting a missing required field ## Inline Catalogs -Inline catalogs sent by the client at runtime are supported but not recommended in production. More details about them can be found [here](../specification/v0_9/docs/a2ui_protocol.md#client-capabilities--metadata). +Inline catalogs sent by the client at runtime are supported but not recommended in production. More details about them can be found [here](../../specification/v0_9/docs/a2ui_protocol.md#client-capabilities--metadata). diff --git a/docs/concepts/components.md b/docs/concepts/components.md index 27fd29648..50c207a5c 100644 --- a/docs/concepts/components.md +++ b/docs/concepts/components.md @@ -12,10 +12,10 @@ A2UI uses an **adjacency list model** for component hierarchies. Instead of nest **A2UI adjacency list:** -- ✅ Flat structure, easy for LLMs to generate -- ✅ Send components incrementally -- ✅ Update any component by ID -- ✅ Clear separation of structure and data +- Flat structure, easy for LLMs to generate. +- Send components incrementally. +- Update any component by ID. +- Clear separation of structure and data. ## The Adjacency List Model @@ -171,7 +171,7 @@ Every component has: ## The Basic Catalog -To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../specification/v0_9/json/basic_catalog.json). +To help developers get started quickly, the A2UI team maintains the [Basic Catalog](../../specification/v0_9/json/basic_catalog.json). This is a pre-defined catalog file that contains a standard set of general-purpose components (Buttons, Inputs, Cards). It is not a special "type" of catalog; it is simply a version of a catalog that has open source renderers available. @@ -233,6 +233,8 @@ A surface is a complete, cohesive UI (form, dashboard, chat, etc.). ## Incremental Updates +Incremental updates support the following operations: + - **Add** - Send new component definitions with new IDs - **Update** - Send component definitions with existing ID and new properties - **Remove** - Update parent's `children` list to exclude removed IDs diff --git a/docs/concepts/data-binding.md b/docs/concepts/data-binding.md index 82a9f8cbe..a23d97746 100644 --- a/docs/concepts/data-binding.md +++ b/docs/concepts/data-binding.md @@ -1,6 +1,6 @@ # Data Binding -Data binding connects UI components to application state using JSON Pointer paths ([RFC 6901](https://tools.ietf.org/html/rfc6901)). It's what allows A2UI to efficiently define layouts for large arrays of data, or to show updated content without being regenerated from scratch. +Data binding connects UI components to application state using JSON Pointer paths ([RFC 6901](https://tools.ietf.org/html/rfc6901)). It allows A2UI to efficiently define layouts for large arrays of data and to show updated content without regenerating it from scratch. ## Structure vs. State @@ -9,7 +9,11 @@ A2UI separates: 1. **UI Structure** (Components): What the interface looks like 2. **Application State** (Data Model): What data it displays -This enables: reactive updates, data-driven UIs, reusable templates, and bidirectional binding. +This enables: +- Reactive updates. +- Data-driven UIs. +- Reusable templates. +- Bidirectional binding. ## The Data Model @@ -176,24 +180,24 @@ Interactive components update the data model bidirectionally: ## Best Practices -**1. Use granular updates** - Update only changed paths: -```json -{ - "dataModelUpdate": { - "path": "/user", - "contents": [ - { "key": "name", "valueString": "Alice" } - ] +- **Use granular updates**: Update only changed paths. + ```json + { + "dataModelUpdate": { + "path": "/user", + "contents": [ + { "key": "name", "valueString": "Alice" } + ] + } } -} -``` + ``` -**2. Organize by domain** - Group related data: -```json -{"user": {...}, "cart": {...}, "ui": {...}} -``` +- **Organize by domain**: Group related data. + ```json + {"user": {...}, "cart": {...}, "ui": {...}} + ``` -**3. Pre-compute display values** - Agent formats data (currency, dates) before sending: -```json -{"price": "$19.99"} // Not: {"price": 19.99} -``` +- **Pre-compute display values**: Formats data (currency, dates) on the agent before sending. + ```json + {"price": "$19.99"} // Not: {"price": 19.99} + ``` diff --git a/docs/concepts/data-flow.md b/docs/concepts/data-flow.md index d5a4e5f0a..8021e21a9 100644 --- a/docs/concepts/data-flow.md +++ b/docs/concepts/data-flow.md @@ -311,11 +311,15 @@ Users see UI building in real-time instead of staring at a spinner. ## Error Handling -- **Malformed messages:** Skip and continue, or send error back to agent for correction -- **Network interruptions:** Display error state, reconnect, agent resends or resumes +The system handles errors as follows: + +- **Malformed messages:** Skip and continue, or send error back to agent for correction. +- **Network interruptions:** Display error state, reconnect, agent resends or resumes. ## Performance -- **Batching:** Buffer updates for 16ms, batch render together -- **Diffing:** Compare old/new components, update only changed properties -- **Granular updates:** Update `/user/name` not entire `/` model +To optimize performance: + +- **Batching:** Buffer updates for 16ms, batch render together. +- **Diffing:** Compare old/new components, update only changed properties. +- **Granular updates:** Update `/user/name` not entire `/` model. diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md index 313b9e17e..794f564ce 100644 --- a/docs/concepts/overview.md +++ b/docs/concepts/overview.md @@ -27,6 +27,8 @@ How components connect to application state using JSON Pointer paths. Covers rea === "v0.8 (Stable)" + Version 0.8 uses the following message types: + - **`surfaceUpdate`**: Define or update UI components - **`dataModelUpdate`**: Update application state - **`beginRendering`**: Signal the client to render @@ -34,6 +36,8 @@ How components connect to application state using JSON Pointer paths. Covers rea === "v0.9 (Draft)" + Version 0.9 uses the following message types: + - **`createSurface`**: Create a new surface and specify its catalog - **`updateComponents`**: Add or update UI components in a surface - **`updateDataModel`**: Update application state diff --git a/docs/concepts/transports.md b/docs/concepts/transports.md index 28f6c0646..72fb028d8 100644 --- a/docs/concepts/transports.md +++ b/docs/concepts/transports.md @@ -31,9 +31,9 @@ standardized agent communication. An A2A extension provides easy integration wi **Benefits:** -- Security and authentication built-in -- Bindings for many message formats, auth, and transport protocols -- Clean separation of concerns +- Security and authentication built-in. +- Bindings for many message formats, auth, and transport protocols. +- Clean separation of concerns. If you are using A2A, this should be nearly automatic. diff --git a/docs/ecosystem/a2ui-in-the-world.md b/docs/ecosystem/a2ui-in-the-world.md index d4b1ed937..236cb977b 100644 --- a/docs/ecosystem/a2ui-in-the-world.md +++ b/docs/ecosystem/a2ui-in-the-world.md @@ -12,9 +12,9 @@ A2UI is being adopted by teams at Google and partner organizations to build the The Opal team at Google has been a **core contributor to A2UI** from the beginning. They use A2UI to power the dynamic, generative UI system that makes Opal's AI mini-apps possible. -- **Rapid prototyping**: Build and test new UI patterns quickly -- **User-generated apps**: Anyone can create apps with custom UIs -- **Dynamic interfaces**: UIs adapt to each use case automatically +- **Rapid prototyping**: Build and test new UI patterns quickly. +- **User-generated apps**: Anyone can create apps with custom UIs. +- **Dynamic interfaces**: UIs adapt to each use case automatically. > "A2UI is foundational to our work. It gives us the flexibility to let the AI drive the user experience in novel ways, without being constrained by a fixed front-end. Its declarative nature and focus on security allow us to experiment quickly and safely." > @@ -32,10 +32,10 @@ Gemini Enterprise enables businesses to build powerful, custom AI agents tailore A2UI is being integrated to allow enterprise agents to render **rich, interactive UIs** within business applications—going beyond simple text responses to guide employees through complex workflows. -- **Data entry forms**: AI-generated forms for structured data collection -- **Approval dashboards**: Dynamic UIs for review and approval processes -- **Workflow automation**: Step-by-step interfaces for complex tasks -- **Custom enterprise UIs**: Tailored interfaces for industry-specific needs +- **Data entry forms**: AI-generated forms for structured data collection. +- **Approval dashboards**: Dynamic UIs for review and approval processes. +- **Workflow automation**: Step-by-step interfaces for complex tasks. +- **Custom enterprise UIs**: Tailored interfaces for industry-specific needs. > "Our customers need their agents to do more than just answer questions; they need them to guide employees through complex workflows. A2UI will allow developers building on Gemini Enterprise to have their agents generate the dynamic, custom UIs needed for any task, from data entry forms to approval dashboards, dramatically accelerating workflow automation." > @@ -53,10 +53,10 @@ The [Flutter GenUI SDK](https://docs.flutter.dev/ai/genui) brings dynamic, AI-ge GenUI SDK uses **A2UI as the underlying protocol** for communication between server-side agents and Flutter applications. When you use GenUI, you're using A2UI under the covers. -- **Cross-platform support**: Same agent works on iOS, Android, web, desktop -- **Native performance**: Flutter widgets rendered natively on each platform -- **Brand consistency**: UIs match your app's design system -- **Server-driven UI**: Agents control what's shown without app updates +- **Cross-platform support**: Same agent works on iOS, Android, web, desktop. +- **Native performance**: Flutter widgets rendered natively on each platform. +- **Brand consistency**: UIs match your app's design system. +- **Server-driven UI**: Agents control what's shown without app updates. > "Our developers choose Flutter because it lets them quickly create expressive, brand-rich, custom design systems that feel great on every platform. A2UI was a great fit for Flutter's GenUI SDK because it ensures that every user, on every platform, gets a high quality native feeling experience." > @@ -78,9 +78,9 @@ The [Agent Development Kit](https://google.github.io/adk-docs/) (ADK) is Google' ADK integrated the A2UI v0.8 standard catalog to automatically render spec-compliant agent parts as native UI components directly in the chat. ADK also handles A2UI↔A2A message conversion, so agents built with ADK can send rich UI to any A2UI-capable client. -- **Built-in rendering**: ADK Web renders A2UI components natively in the dev UI -- **A2A integration**: A2UI messages are converted between A2A DataPart metadata and ADK events -- **Agent SDK**: The [A2UI Python agent SDK](https://github.com/google/A2UI/tree/main/agent_sdks/python) provides an ADK extension for generating A2UI from agents +- **Built-in rendering**: ADK Web renders A2UI components natively in the dev UI. +- **A2A integration**: A2UI messages are converted between A2A DataPart metadata and ADK events. +- **Agent SDK**: The [A2UI Python agent SDK](https://github.com/google/A2UI/tree/main/agent_sdks/python) provides an ADK extension for generating A2UI from agents. **Try it:** - [ADK Documentation](https://google.github.io/adk-docs/) @@ -99,10 +99,10 @@ ADK integrated the A2UI v0.8 standard catalog to automatically render spec-compl AG UI excels at creating high-bandwidth connections between custom frontends and their dedicated agents. By adding A2UI support, developers get the best of both worlds: -- **State synchronization**: AG UI handles app state and chat history -- **A2UI rendering**: Render dynamic UIs from third-party agents -- **Multi-agent support**: Coordinate UIs from multiple agents -- **React integration**: Seamless integration with React applications +- **State synchronization**: AG UI handles app state and chat history. +- **A2UI rendering**: Render dynamic UIs from third-party agents. +- **Multi-agent support**: Coordinate UIs from multiple agents. +- **React integration**: Seamless integration with React applications. > "AG UI excels at creating a high-bandwidth connection between a custom-built front-end and its dedicated agent. By adding support for A2UI, we're giving developers the best of both worlds. They can now build rich, state-synced applications that can also render dynamic UIs from third-party agents via A2UI. It's a perfect match for a multi-agent world." > @@ -123,10 +123,10 @@ AG UI excels at creating high-bandwidth connections between custom frontends and A2UIAgent extends AG2's ConversableAgent with built-in A2UI capabilities — prompt engineering, schema validation with retry, and action handling — so developers can add generative UI to their agents without custom rendering code. -- **Validated output**: Built-in schema validation and retry ensures reliable A2UI generation -- **Dual transport**: Serves the same UI over A2A (JSON-RPC) and AG-UI (SSE) -- **Cross-platform**: One agent serves web, desktop, and mobile clients -- **Custom catalogs**: Extend the component catalog with domain-specific components +- **Validated output**: Built-in schema validation and retry ensures reliable A2UI generation. +- **Dual transport**: Serves the same UI over A2A (JSON-RPC) and AG-UI (SSE). +- **Cross-platform**: One agent serves web, desktop, and mobile clients. +- **Custom catalogs**: Extend the component catalog with domain-specific components. > "A2UIAgent brings the A2UI protocol to AG2, enabling agent expression with dynamic, rich, and interactive UIs. Reliable, client-agnostic rendering means our developers spend less time on integration and more time building great experiences." > @@ -147,10 +147,10 @@ As Google adopts AI across the company, A2UI provides a **standardized way for A **Internal agent adoption:** -- **Multi-agent workflows**: Multiple agents contribute to the same surface -- **Remote agent support**: Agents running on different services can provide UI -- **Standardization**: Common protocol across teams reduces integration overhead -- **External exposure**: Internal agents can be easily exposed externally (e.g., Gemini Enterprise) +- **Multi-agent workflows**: Multiple agents contribute to the same surface. +- **Remote agent support**: Agents running on different services can provide UI. +- **Standardization**: Common protocol across teams reduces integration overhead. +- **External exposure**: Internal agents can be easily exposed externally (e.g., Gemini Enterprise). > "Much like A2A lets any agent talk to another agent regardless of platform, A2UI standardizes the user interface layer and supports remote agent use cases through an orchestrator. This has been incredibly powerful for internal teams, allowing them to rapidly develop agents where rich user interfaces are the norm, not the exception. As Google pushes further into generative UI, A2UI provides a perfect platform for server-driven UI that renders on any client." > @@ -192,10 +192,12 @@ Have you built something with A2UI? [Share it with the community!](community.md) ## Next Steps -- [Quickstart Guide](../quickstart.md) - Try the demo -- [Agent Development](../guides/agent-development.md) - Build an agent -- [Client Setup](../guides/client-setup.md) - Integrate a renderer -- [Community](community.md) - Join the community +For more information, see the following resources: + +- [Quickstart Guide](../quickstart.md) - Try the demo. +- [Agent Development](../guides/agent-development.md) - Build an agent. +- [Client Setup](../guides/client-setup.md) - Integrate a renderer. +- [Community](community.md) - Join the community. --- diff --git a/docs/ecosystem/community.md b/docs/ecosystem/community.md index 55b76928a..d904381c3 100644 --- a/docs/ecosystem/community.md +++ b/docs/ecosystem/community.md @@ -1,25 +1,25 @@ # Community -Welcome to the A2UI community! We're building the future of agent-driven interfaces together. +Welcome to the A2UI community! The project is building the future of agent-driven interfaces together. ## Get Involved -A2UI is an open-source project licensed under Apache 2.0. We welcome contributions from developers, researchers, and anyone interested in advancing agentic user interfaces. +A2UI is an open-source project licensed under Apache 2.0. Contributions are welcome from developers, researchers, and anyone interested in advancing agentic user interfaces. ## Community Showcase Built something with A2UI? Show it off! -The best way to share your work is to **post in [GitHub Discussions](https://github.com/google/A2UI/discussions)** with a short description, a link to your code, and a demo video (4 minutes or less). We feature notable projects in the docs and release notes. +The best way to share your work is to **post in [GitHub Discussions](https://github.com/google/A2UI/discussions)** with a short description, a link to your code, and a demo video (4 minutes or less). Notable projects are featured in the docs and release notes. **Community-built renderers** are listed on the [Ecosystem Renderers](renderers.md) page — check there for community implementations and instructions for adding your own. **Official samples** in the repo are a great reference for what good A2UI projects look like: -- [Restaurant Finder](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder) — ADK agent with dynamic forms -- [Contact Lookup](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup) — search UI with data binding -- [Angular client](https://github.com/google/A2UI/tree/main/samples/client/angular) — gallery + restaurant client -- [Lit shell](https://github.com/google/A2UI/tree/main/samples/client/lit/shell) — minimal web component client +- [Restaurant Finder](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder) — ADK agent with dynamic forms. +- [Contact Lookup](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup) — search UI with data binding. +- [Angular client](https://github.com/google/A2UI/tree/main/samples/client/angular) — gallery + restaurant client. +- [Lit shell](https://github.com/google/A2UI/tree/main/samples/client/lit/shell) — minimal web component client. ## Project Partners @@ -29,44 +29,48 @@ If you have made significant contributions to A2UI, please submit your name to t ## Code of Conduct -We are committed to providing a welcoming and inclusive environment for everyone. All participants are expected to: +A2UI is committed to providing a welcoming and inclusive environment for everyone. All participants are expected to: -- Be respectful and considerate -- Welcome newcomers and help them get started -- Focus on what's best for the community -- Show empathy towards others +- Be respectful and considerate. +- Welcome newcomers and help them get started. +- Focus on what's best for the community. +- Show empathy towards others. Unacceptable behavior will not be tolerated. Report concerns to the project maintainers. ## Recognition -We appreciate all contributions! Contributors are recognized in: +All contributions are appreciated! Contributors are recognized in: -- GitHub's contributor graph -- Release notes -- Project acknowledgments +- GitHub's contributor graph. +- Release notes. +- Project acknowledgments. Significant contributors may be invited to join the project's maintainer team. ## Stay Updated -- **Watch the GitHub repo** for notifications -- **Star the repo** to bookmark and show support -- **Follow releases** to get notified of new versions +To stay informed about project updates: + +- **Watch the GitHub repo** for notifications. +- **Star the repo** to bookmark and show support. +- **Follow releases** to get notified of new versions. ## Ways to Contribute **[github.com/google/A2UI](https://github.com/google/A2UI)** -- **Report Issues**: Found a bug? [Open an issue](https://github.com/google/A2UI/issues) -- **Build Renderers**: See the [roadmap](../roadmap.md) for planned frameworks -- **Share Examples**: Post with `#A2UI` on X/LinkedIn, start a [discussion](https://github.com/google/A2UI/discussions) -- **Improve Docs**: PRs welcome in the `docs/` directory +- **Report Issues**: Found a bug? [Open an issue](https://github.com/google/A2UI/issues). +- **Build Renderers**: See the [roadmap](../roadmap.md) for planned frameworks. +- **Share Examples**: Post with `#A2UI` on X/LinkedIn, start a [discussion](https://github.com/google/A2UI/discussions). +- **Improve Docs**: PRs welcome in the `docs/` directory. ## Questions? -- Check the [documentation](../introduction/what-is-a2ui.md) -- Search [GitHub Discussions](https://github.com/google/A2UI/discussions) -- Ask in [GitHub Issues](https://github.com/google/A2UI/issues) +If you have questions: + +- Check the [documentation](../introduction/what-is-a2ui.md). +- Search [GitHub Discussions](https://github.com/google/A2UI/discussions). +- Ask in [GitHub Issues](https://github.com/google/A2UI/issues). Thank you for being part of the A2UI community! diff --git a/docs/ecosystem/renderers.md b/docs/ecosystem/renderers.md index 680b46fd2..b228f8bdc 100644 --- a/docs/ecosystem/renderers.md +++ b/docs/ecosystem/renderers.md @@ -2,12 +2,11 @@ Community and third-party A2UI renderer implementations. -!!! note - These renderers are maintained by their respective authors, not the A2UI team. - Check each project for compatibility, version support, and maintenance status. +> NOTE +> These renderers are maintained by their respective authors, not the A2UI team. Check each project for compatibility, version support, and maintenance status. -!!! tip - Looking for the **official** A2UI React renderer? See [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react) — the core A2UI React renderer maintained by the A2UI team. +> TIP +> Looking for the **official** A2UI React renderer? See [`@a2ui/react`](https://www.npmjs.com/package/@a2ui/react) — the core A2UI React renderer maintained by the A2UI team. ## Community Renderers @@ -25,9 +24,9 @@ Community and third-party A2UI renderer implementations. These projects are early-stage or experimental: -- **[xpert-ai/a2ui-react](https://www.npmjs.com/package/@xpert-ai/a2ui-react)** (`@xpert-ai/a2ui-react`) — React renderer with ShadCN UI components (v0.0.1, published Jan 2026) -- **[josh-english-2k18/a2ui-3d-renderer](https://github.com/josh-english-2k18/a2ui-3d-renderer)** — Experimental Three.js/WebGL 3D renderer for A2UI (~2 stars) -- **[AINative-Studio/ai-kit-a2ui](https://github.com/AINative-Studio/ai-kit-a2ui)** — React + ShadCN renderer for the AIKit framework (~2 stars) +- **[xpert-ai/a2ui-react](https://www.npmjs.com/package/@xpert-ai/a2ui-react)** (`@xpert-ai/a2ui-react`) — React renderer with ShadCN UI components (v0.0.1, published Jan 2026). +- **[josh-english-2k18/a2ui-3d-renderer](https://github.com/josh-english-2k18/a2ui-3d-renderer)** — Experimental Three.js/WebGL 3D renderer for A2UI (~2 stars). +- **[AINative-Studio/ai-kit-a2ui](https://github.com/AINative-Studio/ai-kit-a2ui)** — React + ShadCN renderer for the AIKit framework (~2 stars). ### Related Projects @@ -49,10 +48,12 @@ These projects are not directly A2UI renderers but are closely related and do su ## Submitting a Renderer -Built an A2UI renderer? We'd love to list it here. +If you have built an A2UI renderer, submit it to be listed here. ### How to submit +To submit a renderer, follow these steps: + 1. **Fork** the [google/A2UI](https://github.com/google/A2UI) repository 2. **Edit** this file (`docs/ecosystem/renderers.md`) — add a row to the Community Renderers table with your renderer's name, platform, npm package (if any), version support, and a link to the source 3. **Open a PR** against `google/A2UI` with a short description of your renderer @@ -62,12 +63,12 @@ Need inspiration? Browse the **[community samples](https://github.com/google/A2U ### What makes a good community renderer? -A listing is more likely to be accepted and used if it: +A listing is more likely to be accepted and used if it meets the following criteria: -- Has **published source code** (open-source preferred, MIT or Apache 2.0) -- Clearly states **which A2UI spec version** it supports (v0.8, v0.9, or both) -- Covers the **basic components** from the other A2UI renderers: text, buttons, inputs, basic layout components, etc -- Includes a **README** with install instructions and a minimal usage example -- Is **actively maintained** — flag it as archived if you're no longer supporting it +- Has **published source code** (open-source preferred, MIT or Apache 2.0). +- Clearly states **which A2UI spec version** it supports (v0.8, v0.9, or both). +- Covers the **basic components** from the other A2UI renderers: text, buttons, inputs, basic layout components, etc. +- Includes a **README** with install instructions and a minimal usage example. +- Is **actively maintained** — flag it as archived if you're no longer supporting it. Community renderers don't need to be production-ready to be listed — experimental and early-stage projects are welcome in the Notable Mentions section. diff --git a/docs/glossary.md b/docs/glossary.md index 63729e88b..53187cf03 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -47,7 +47,7 @@ It is observed that depending on use case, catalog components may be more or les A catalog maintained by the A2UI team to get up and running quickly with A2UI. -See [basic catalog](https://github.com/google/A2UI/blob/main/specification/v0_10/json/basic_catalog.json). +See the [basic catalog](../specification/v0_10/json/basic_catalog.json). ### Surface @@ -92,13 +92,13 @@ Functionality of A2UI renderer consists of layers that can be developed separate Set of primitives, needed to describe catalog and to interact with the agent. - Fore example, [JavaScript web core library](https://github.com/google/A2UI/tree/main/renderers/web_core/README.md). + For example, see the [JavaScript web core library](../renderers/web_core/README.md). - **Catalog Schema**: Definition of catalog in the form of JSON. - For example, [basic catalog schema](https://github.com/google/A2UI/tree/main/specification/v0_10/json/basic_catalog.json). + For example, see the [basic catalog schema](../specification/v0_10/json/basic_catalog.json). - **Framework adapter**: @@ -107,7 +107,7 @@ Functionality of A2UI renderer consists of layers that can be developed separate - JavaScript core and catalogs may be adapted to Angular, Electron, React and Lit frameworks. - Dart core and catalogs may be adapted to Flutter and Jaspr frameworks. - See [Angular adapter](https://github.com/google/A2UI/tree/main/renderers/angular/README.md). + See the [Angular adapter](../renderers/angular/README.md). - **Catalog Implementation**: @@ -115,7 +115,7 @@ Functionality of A2UI renderer consists of layers that can be developed separate For example: - - [Angular implementation of basic catalog](https://github.com/google/A2UI/blob/main/renderers/angular/src/v0_9/catalog/basic) + - See the [Angular implementation of the basic catalog](../renderers/angular/src/v0_9/catalog/basic) ```mermaid @@ -132,7 +132,7 @@ A message between agent and renderer. As the protocol allows streaming, any message can be finished (completely delivered) or not finished (partially delivered). A finished message may be completed (successfully delivered) or interrupted (delivery stopped because of some technical issues). -See [data flow](https://github.com/google/A2UI/blob/main/docs/concepts/data-flow.md). +See the [data flow guide](concepts/data-flow.md). ### Agent turn @@ -146,13 +146,13 @@ Components can be bound to nodes of the data model, in order to auto-update when Data model allows bidirectional synchronization by capturing user interactions into a state object for transmission to the agent, while also allowing agent to push data updates back to the UI. -See [data binding](https://github.com/google/A2UI/blob/main/docs/concepts/data-binding.md). +See the [data binding guide](concepts/data-binding.md). ### Data reference In component definition, a reference to a data element, resolvable either by path in the data model or by value. -See [example in basic catalog](https://github.com/google/A2UI/blob/db1fbe726b8d464f8f8493d9991cf0c6e4f8499d/specification/v0_10/json/basic_catalog.json#L18). +See the [example in the basic catalog](../specification/v0_10/json/basic_catalog.json#L18). ### Client function @@ -168,13 +168,13 @@ Do not confuse with LLM tool: | Definition | Registered in client side function registry and advertised in catalog | Defined in ToolDefinition (passed to LLM) | | State Access | Access to DataContext and Input values. | No access to trigger requests to AI. Access to external APIs, databases, and services | -See [example](https://github.com/google/A2UI/blob/main/specification/v0_9/json/common_types.json#L200). +See the [example in common types](../specification/v0_9/json/common_types.json#L200). ### Action -Interactivity defined in the component schema using the `action` property. Actions have two types: -- **Events**: Dispatched to the agent for processing. -- **Functions**: Executed locally on the renderer. +A container for an interaction triggered by the user in the UI. Actions come in two types: +- **Event**: Dispatched to the agent for processing (e.g., clicking "Submit"). +- **Function**: Executed locally on the renderer (e.g., opening a URL). See the [detailed guide on actions](concepts/actions.md). diff --git a/docs/guides/a2ui_over_mcp.md b/docs/guides/a2ui_over_mcp.md index 37811af5b..0f719608f 100644 --- a/docs/guides/a2ui_over_mcp.md +++ b/docs/guides/a2ui_over_mcp.md @@ -9,9 +9,11 @@ This guide shows you how to serve **rich, interactive A2UI interfaces** from an ## Prerequisites -- **Python 3.10+** -- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager -- **Node.js 18+** (for the MCP Inspector) +Ensure you have the following installed before you begin: + +- **Python** (version 3.10 or later). +- **[uv](https://docs.astral.sh/uv/)** for fast Python package management. +- **Node.js** (version 18 or later) for the MCP Inspector. ## Quick Start: Run the Sample @@ -39,7 +41,7 @@ In the Inspector: 3. Click **List Tools** → you'll see `get_recipe_a2ui` 4. Run the tool → the response contains A2UI JSON that renders a recipe card -> ⚠️ **Note** +> NOTE: Note > > The sample uses a local path reference to the A2UI Agent SDK. For your own projects, install from PyPI: > ```bash @@ -187,7 +189,7 @@ def get_hello_world_ui(): return types.CallToolResult(content=[text_content, a2ui_resource]) ``` -> ⚠️ **Tip** +> TIP: Tip > > Always include a `TextContent` alongside your A2UI resource. Clients that don't support A2UI will fall back to showing the text. diff --git a/docs/guides/agent-development.md b/docs/guides/agent-development.md index 1215af8ba..16e152d3b 100644 --- a/docs/guides/agent-development.md +++ b/docs/guides/agent-development.md @@ -13,7 +13,7 @@ Building an A2UI agent: ## Start with a simple agent -We will use the ADK to build a simple agent. We will start with text and eventually upgrade it to A2UI. +This guide uses the ADK to build a simple agent, starting with text and upgrading it to A2UI. See step-by-step instructions at the [ADK quickstart](https://google.github.io/adk-docs/get-started/python/). @@ -94,24 +94,23 @@ Select `my_agent` from the list, and ask questions about restaurants in New York Getting the LLM to generate A2UI messages requires some prompt engineering. -> ⚠️ **Attention** -> -> This is an area we are still designing. The developer ergonomics of this are not yet finalized. +IMPORTANT: Attention +This area is under active design. The developer ergonomics are not yet finalized. -For now, let's copy the `a2ui_schema.py` from the contact lookup example. This is the easiest way to get the A2UI schema and examples for your agent (subject to change). +For now, copy the `a2ui_schema.py` from the contact lookup example. This is the easiest way to get the A2UI schema and examples for your agent (subject to change). ```bash cp samples/agent/adk/contact_lookup/a2ui_schema.py my_agent/ ``` -First lets add the new imports to the `agent.py` file: +First, add the new imports to the `agent.py` file: ```python # The schema for any A2UI message. This never changes. from .a2ui_schema import A2UI_SCHEMA ``` -Now we will modify the agent instructions to generate A2UI messages instead of plain text. We will leave a placeholder for future UI examples. +Now, modify the agent instructions to generate A2UI messages instead of plain text. Leave a placeholder for future UI examples. ```python @@ -131,6 +130,7 @@ To generate the response, you MUST follow these rules: 4. The JSON part MUST validate against the A2UI JSON SCHEMA provided below. --- UI TEMPLATE RULES --- +Follow these rules to select the appropriate UI template: - If the query is for a list of restaurants, use the restaurant data you have already received from the `get_restaurants` tool to populate the `dataModelUpdate.contents` array (e.g., as a `valueMap` for the "items" key). - If the number of restaurants is 5 or fewer, you MUST use the `SINGLE_COLUMN_LIST_EXAMPLE` template. - If the number of restaurants is more than 5, you MUST use the `TWO_COLUMN_LIST_EXAMPLE` template. diff --git a/docs/guides/authoring-components.md b/docs/guides/authoring-components.md index 67b43a101..d6e93f11e 100644 --- a/docs/guides/authoring-components.md +++ b/docs/guides/authoring-components.md @@ -19,7 +19,7 @@ The catalog schema defines the API of your catalog. It lists available component **This schema acts as a contract between the client and the server (agent).** Both must agree on this schema for rendering to work. The client advertises what catalogs it supports, and the server selects a compatible one. For details on how this handshake works, see [A2UI Catalog Negotiation](../concepts/catalogs.md#a2ui-catalog-negotiation). -In the [`rizzcharts`](../../samples/agent/adk/rizzcharts/README.md) example, the catalog schema is defined in [`rizzcharts_catalog_definition.json`](../../samples/agent/adk/rizzcharts/rizzcharts_catalog_definition.json). +In the [`rizzcharts`](../../samples/agent/adk/rizzcharts/README.md) example, the catalog schema is defined in [`rizzcharts_catalog_definition.json`](../../samples/agent/adk/rizzcharts/catalog_schemas/0.9/rizzcharts_catalog_definition.json). Here is the schema for the `Chart` component: @@ -137,9 +137,9 @@ export class Chart extends DynamicComponent { } ``` -Key points: -- **Extend `DynamicComponent`**: This gives you access to `resolvePrimitive` for data binding resolution. -- **Use Angular Inputs**: Map properties from the schema to Angular inputs. +Keep these key points in mind when implementing components: +- **Extend `DynamicComponent`**: This gives you access to `resolvePrimitive` for data binding resolution. +- **Use Angular Inputs**: Map properties from the schema to Angular inputs. --- @@ -169,9 +169,9 @@ export const RIZZ_CHARTS_CATALOG = { } as Catalog; ``` -Key points: -- **Lazy Loading**: Use `import()` to lazy-load the component code. -- **Input Bindings**: Use `inputBinding` to map properties from the schema to Angular inputs. +Key points for registration: +- **Lazy Loading**: Use `import()` to lazy-load the component code. +- **Input Bindings**: Use `inputBinding` to map properties from the schema to Angular inputs. --- diff --git a/docs/guides/client-setup.md b/docs/guides/client-setup.md index 05e9e5523..df0d8920c 100644 --- a/docs/guides/client-setup.md +++ b/docs/guides/client-setup.md @@ -27,10 +27,9 @@ This means core protocol handling is consistent across web platforms — only th ## Web Components (Lit) -> ⚠️ **Attention** +> NOTE: Attention > -> The Lit client library is not yet published to NPM. Check back in the -> coming days. +> The Lit client library is not yet published to NPM. Check back in the coming days. ```bash npm install @a2ui/web-lib lit @lit-labs/signals @@ -38,9 +37,9 @@ npm install @a2ui/web-lib lit @lit-labs/signals The Lit renderer uses: -- **Message Processor**: Manages A2UI state and processes incoming messages -- **`` component**: Renders surfaces in your app -- **Lit Signals**: Provides reactive state management for automatic UI updates +- **Message Processor**: Manages A2UI state and processes incoming messages. +- **`` component**: Renders surfaces in your app. +- **Lit Signals**: Provides reactive state management for automatic UI updates. TODO: Add verified setup example. @@ -48,10 +47,9 @@ TODO: Add verified setup example. ## Angular -> ⚠️ **Attention** +> NOTE: Attention > -> The Angular client library is not yet published to NPM. Check back in the -> coming days. +> The Angular client library is not yet published to NPM. Check back in the coming days. ```bash npm install @a2ui/angular @a2ui/web_core @@ -150,10 +148,10 @@ TODO: Add action handling examples. Common errors to handle: -- **Invalid Surface ID**: Surface referenced before `beginRendering` (v0.8) or `createSurface` (v0.9) was received -- **Invalid Component ID**: Component IDs must be unique within a surface -- **Invalid Data Path**: Check data model structure and JSON Pointer syntax -- **Schema Validation Failed**: Verify message format matches A2UI specification +- **Invalid Surface ID**: Surface referenced before `beginRendering` (v0.8) or `createSurface` (v0.9) was received. +- **Invalid Component ID**: Component IDs must be unique within a surface. +- **Invalid Data Path**: Check data model structure and JSON Pointer syntax. +- **Schema Validation Failed**: Verify message format matches A2UI specification. TODO: Add error handling examples. diff --git a/docs/guides/defining-your-own-catalog.md b/docs/guides/defining-your-own-catalog.md index 4570009ef..add5c6622 100644 --- a/docs/guides/defining-your-own-catalog.md +++ b/docs/guides/defining-your-own-catalog.md @@ -1,6 +1,6 @@ # Defining Your Own Catalog -While the [Basic Catalog](../specification/v0_9/json/basic_catalog.json) is useful for starting out and bootstrapping an application, most production applications will define their own catalog to reflect their specific design system. +While the [Basic Catalog](../../specification/v0_9/json/basic_catalog.json) is useful for starting out and bootstrapping an application, most production applications will define their own catalog to reflect their specific design system. By defining your own catalog, you restrict the agent to using exactly the components and visual language that exist in your application, rather than generic inputs or buttons. @@ -8,9 +8,10 @@ By defining your own catalog, you restrict the agent to using exactly the compon Every A2UI surface is driven by a **Catalog**. A catalog is simply a JSON Schema file that tells the agent which components, functions, and themes are available for it to use. +Defining your own catalog offers the following benefits: - **Design System Alignment**: Restrict the agent to using exactly the components and visual language that exist in your application. - **Security and Type Safety**: You register entire catalogs with your client application, ensuring that only trusted components are rendered. -- **No Mappers Needed**: We recommend building catalogs that directly reflect your client's design system rather than trying to map a generic catalog (like the Basic Catalog) to it through an adapter. +- **No Mappers Needed**: It is recommended to build catalogs that directly reflect your client's design system rather than trying to map a generic catalog (like the Basic Catalog) to it through an adapter. The Basic Catalog is just one example and is intentionally sparse to remain easily implementable by different renderers. @@ -24,7 +25,7 @@ The Basic Catalog is just one example and is intentionally sparse to remain easi ## Implementation Guide -We recommend creating catalogs that directly map to your existing component library. +It is recommended to create catalogs that directly map to your existing component library. === "Web (Lit / Angular / React)" diff --git a/docs/guides/mcp-apps-in-a2ui-surface.md b/docs/guides/mcp-apps-in-a2ui-surface.md index 2d86e22f1..d76c0bb7c 100644 --- a/docs/guides/mcp-apps-in-a2ui-surface.md +++ b/docs/guides/mcp-apps-in-a2ui-surface.md @@ -2,7 +2,7 @@ This guide explains how **Model Context Protocol (MCP) Applications** are integrated and displayed within the **A2UI** surface, along with the security model and testing guidelines. -> **Looking for the core A2UI-over-MCP protocol?** See [A2UI over MCP](a2ui_over_mcp.md) for how to return A2UI JSON payloads from MCP tool calls. +> NOTE: Looking for the core A2UI-over-MCP protocol? See [A2UI over MCP](a2ui_over_mcp.md) for how to return A2UI JSON payloads from MCP tool calls. ## Overview @@ -70,7 +70,7 @@ export const DEMO_CATALOG = { ### 2. Usage in A2UI Message -In the Host or Agent context, you send an A2UI message that translates to this custom node. +In the Host or Agent context, send an A2UI message that translates to this custom node. ```json { diff --git a/docs/guides/renderer-development.md b/docs/guides/renderer-development.md index a59b458db..92c05f1f7 100644 --- a/docs/guides/renderer-development.md +++ b/docs/guides/renderer-development.md @@ -2,8 +2,9 @@ This document outlines the required features for a new renderer implementation of the A2UI protocol. It is intended for developers building new renderers (e.g., for React, Flutter, iOS, etc.). -!!! info "Version Notes" - This guide primarily describes the v0.8 message flow. v0.9 renames several messages (`surfaceUpdate` → `updateComponents`, `dataModelUpdate` → `updateDataModel`, `beginRendering` → `createSurface`) and uses a flatter component format. See the [v0.9 specification](../specification/v0.9-a2ui.md) for details. +> NOTE: Version Notes +> +> This guide primarily describes the v0.8 message flow. v0.9 renames several messages (`surfaceUpdate` → `updateComponents`, `dataModelUpdate` → `updateDataModel`, `beginRendering` → `createSurface`) and uses a flatter component format. See the [v0.9 specification](../specification/v0.9-a2ui.md) for details. ## Web Renderers: Use `@a2ui/web-lib` (`web_core`) @@ -56,8 +57,9 @@ See the [React renderer](https://github.com/google/A2UI/tree/main/renderers/reac - `@a2ui/web_core/v0_9` — v0.9 with `createSurface`, custom catalogs, client-side functions - `@a2ui/web_core/v0_9/basic_catalog` — v0.9 basic catalog expression parser and built-in functions -!!! tip "Start with `web_core`" - Building a web renderer without `web_core` means reimplementing ~3,000 lines of message processing, state management, and schema validation. Unless you have a specific reason to diverge, use it. +> TIP: Start with `web_core` +> +> Building a web renderer without `web_core` means reimplementing ~3,000 lines of message processing, state management, and schema validation. Unless you have a specific reason to diverge, use it. --- @@ -67,6 +69,8 @@ This section details the fundamental mechanics of the A2UI protocol. A compliant ### Message Processing & State Management +A compliant renderer must implement the following message processing and state management features: + - **JSONL Stream Parsing**: Implement a parser that can read a streaming response line by line, decoding each line as a distinct JSON object. - **Message Dispatcher**: Create a dispatcher to identify the message type (`beginRendering`, `surfaceUpdate`, `dataModelUpdate`, `deleteSurface`) and route it to the correct handler. - **Surface Management**: @@ -82,6 +86,8 @@ This section details the fundamental mechanics of the A2UI protocol. A compliant ### Rendering Logic +Implement the following rendering logic: + - **Progressive Rendering Control**: - Buffer all incoming `surfaceUpdate` and `dataModelUpdate` messages without rendering immediately. - Handle `beginRendering`: This message acts as the explicit signal to perform the initial render of a surface and set the root component ID. @@ -99,6 +105,8 @@ This section details the fundamental mechanics of the A2UI protocol. A compliant ### Client-to-Server Communication +Implement the following communication features: + - **Event Handling**: - When a user interacts with a component that has an `action` defined, construct a `userAction` payload. - Resolve all data bindings within the `action.context` against the data model. @@ -115,6 +123,8 @@ To ensure a consistent user experience across platforms, A2UI defines a standard ### Basic Content +The standard catalog includes the following basic content components: + - **Text**: Render text content. Must support data binding on `text` and a `usageHint` for styling (h1-h5, body, caption). - **Image**: Render an image from a URL. Must support `fit` (cover, contain, etc.) and `usageHint` (avatar, hero, etc.) properties. - **Icon**: Render a predefined icon from the standard set specified in the catalog. @@ -124,6 +134,8 @@ To ensure a consistent user experience across platforms, A2UI defines a standard ### Layout & Containers +The standard catalog includes the following layout and container components: + - **Row**: Arrange children horizontally. Must support `distribution` (justify-content) and `alignment` (align-items). Children can have a `weight` property to control flex-grow behavior. - **Column**: Arrange children vertically. Must support `distribution` and `alignment`. Children can have a `weight` property to control flex-grow behavior. - **List**: Render a scrollable list of items. Must support `direction` (`horizontal`/`vertical`) and `alignment`. @@ -133,6 +145,8 @@ To ensure a consistent user experience across platforms, A2UI defines a standard ### Interactive & Input Components +The standard catalog includes the following interactive and input components: + - **Button**: A clickable element that triggers a `userAction`. Must be able to contain a `child` component (typically Text or Icon) and may vary in style based on the `primary` boolean. - **CheckBox**: A checkbox that can be toggled, reflecting a boolean value. - **TextField**: An input field for text. Must support a `label`, `text` (value), `textFieldType` (`shortText`, `longText`, `number`, `obscured`, `date`), and `validationRegexp`. diff --git a/docs/guides/theming.md b/docs/guides/theming.md index 25d717a37..eb57d044e 100644 --- a/docs/guides/theming.md +++ b/docs/guides/theming.md @@ -9,12 +9,12 @@ A2UI follows a **renderer-controlled styling** approach: - **Agents describe *what* to show** (components and structure) - **Renderers decide *how* it looks** (colors, fonts, spacing) -This ensures: +A renderer-controlled approach provides the following benefits: -- ✅ **Brand consistency**: All UIs match your app's design system -- ✅ **Security**: Agents can't inject arbitrary CSS or styling -- ✅ **Accessibility**: You control contrast, focus states, and ARIA attributes -- ✅ **Platform-native feel**: Web apps look like web, mobile looks like mobile +- **Brand consistency**: All UIs match your app's design system. +- **Security**: Agents cannot inject arbitrary CSS or styling. +- **Accessibility**: You control contrast, focus states, and ARIA attributes. +- **Platform-native feel**: Web apps look like web, mobile looks like mobile. ## Styling Layers @@ -23,8 +23,8 @@ A2UI styling works in layers: ```mermaid flowchart TD A["1. Semantic Hints
Agent provides hints
(e.g., usageHint: 'h1')"] - B["2. Theme Configuration
You configure
(colors, fonts, spacing)"] - C["3. Component Overrides
You customize
(CSS/styles for specific components)"] + B["2. Theme Configuration
Developer configures
(colors, fonts, spacing)"] + C["3. Component Overrides
Developer customizes
(CSS/styles for specific components)"] D["4. Rendered Output
Native platform widgets"] A --> B --> C --> D diff --git a/docs/index.md b/docs/index.md index 214fe1423..44fe2a6a9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -31,15 +31,14 @@ A2UI is Apache 2.0 licensed, created by Google with contributions from CopilotKit and the open source community, and is in active development [on GitHub](https://github.com/google/A2UI). -The problem A2UI solves is: **how can AI agents safely send rich UIs across trust boundaries?** +A2UI solves the following problem: **how can AI agents safely send rich UIs across trust boundaries?** Instead of text-only responses or risky code execution, A2UI lets agents send **declarative component descriptions** that clients render using their own native widgets. It's like having agents speak a universal UI language. -In this repo you will find -[A2UI specifications](specification/v0.8-a2ui.md) (v0.8 stable, v0.9 draft), -implementations for -[renderers](reference/renderers.md) (Angular, Flutter, Lit, Markdown, etc.) on the client side, -and [transports](concepts/transports.md) (A2A, etc.) which communicate A2UI messages between agents and clients. +This repository contains: +- **[A2UI specifications](specification/v0.8-a2ui.md)** (v0.8 stable, v0.9 draft). +- **Implementations for [renderers](reference/renderers.md)** (Angular, Flutter, Lit, Markdown, etc.) on the client side. +- **Transports like [A2A](concepts/transports.md)** which communicate A2UI messages between agents and clients.
@@ -109,6 +108,8 @@ and [transports](concepts/transports.md) (A2A, etc.) which communicate A2UI mess ## How It Works +The typical interaction flow consists of these steps: + 1. **User sends a message** to an AI agent 2. **Agent generates A2UI messages** describing the UI (structure + data) 3. **Messages stream** to the client application diff --git a/docs/introduction/agent-ui-ecosystem.md b/docs/introduction/agent-ui-ecosystem.md index b17ac8539..9f2469cf0 100644 --- a/docs/introduction/agent-ui-ecosystem.md +++ b/docs/introduction/agent-ui-ecosystem.md @@ -31,12 +31,14 @@ The agentic UI space is evolving rapidly. Here's how A2UI relates to the other m These approaches are complementary, not competing: -- **A2UI + AG UI** — AG UI as transport, A2UI as the generative UI format -- **A2UI + A2A** — A2UI messages sent via the [A2A protocol](../concepts/transports.md) for multi-agent systems -- **A2UI + MCP** — Upcoming bridge lets MCP servers provide A2UI blueprints alongside HTML resources +- **A2UI + AG UI** — AG UI as transport, A2UI as the generative UI format. +- **A2UI + A2A** — A2UI messages sent via the [A2A protocol](../concepts/transports.md) for multi-agent systems. +- **A2UI + MCP** — Upcoming bridge lets MCP servers provide A2UI blueprints alongside HTML resources. ## Further Reading -- [What is A2UI?](what-is-a2ui.md) — Protocol overview -- [Transports](../concepts/transports.md) — How A2UI messages travel between agents and clients -- [Where is A2UI Used?](../ecosystem/a2ui-in-the-world.md) — Case studies and adopters +For more information, see the following resources: + +- [What is A2UI?](what-is-a2ui.md) — Protocol overview. +- [Transports](../concepts/transports.md) — How A2UI messages travel between agents and clients. +- [Where is A2UI Used?](../ecosystem/a2ui-in-the-world.md) — Case studies and adopters. diff --git a/docs/introduction/how-to-use.md b/docs/introduction/how-to-use.md index 47ae3525c..b5c7d3ee5 100644 --- a/docs/introduction/how-to-use.md +++ b/docs/introduction/how-to-use.md @@ -1,4 +1,4 @@ -# How Can I Use A2UI? +# How to Use A2UI Choose the integration path that matches your role and use case. @@ -10,8 +10,8 @@ Integrate A2UI rendering into your existing app or build a new agent-powered fro **Choose a renderer:** -- **Web:** Lit, Angular, React -- **Mobile/Desktop:** Flutter GenUI SDK +- **Web:** Lit, Angular, React. +- **Mobile/Desktop:** Flutter GenUI SDK. **Quick setup:** @@ -39,8 +39,8 @@ Create an agent that generates A2UI responses for any compatible client. **Choose your framework:** -- **Python:** Google ADK, LangChain, custom -- **Node.js:** A2A SDK, Vercel AI SDK, custom +- **Python:** Google ADK, LangChain, custom. +- **Node.js:** A2A SDK, Vercel AI SDK, custom. Include the A2UI schema in your LLM prompts, generate JSONL messages, and stream to clients over SSE, WebSockets, or A2A. @@ -52,7 +52,7 @@ Include the A2UI schema in your LLM prompts, generate JSONL messages, and stream Use A2UI through frameworks with built-in support: -- **[AG UI / CopilotKit](https://ag-ui.com/)** - Full-stack React framework with A2UI rendering -- **[Flutter GenUI SDK](https://docs.flutter.dev/ai/genui)** - Cross-platform generative UI (uses A2UI internally) +- **[AG UI / CopilotKit](https://ag-ui.com/)** - Full-stack React framework with A2UI rendering. +- **[Flutter GenUI SDK](https://docs.flutter.dev/ai/genui)** - Cross-platform generative UI (uses A2UI internally). **Next:** [Agent UI Ecosystem](agent-ui-ecosystem.md) | [Where is A2UI Used?](../ecosystem/a2ui-in-the-world.md) diff --git a/docs/introduction/what-is-a2ui.md b/docs/introduction/what-is-a2ui.md index 9f2a6f9ed..b9cb5953c 100644 --- a/docs/introduction/what-is-a2ui.md +++ b/docs/introduction/what-is-a2ui.md @@ -20,11 +20,11 @@ Agent: "What time?" In multi-agent systems, agents often run remotely (different servers, organizations). They can't directly manipulate your UI—they must send messages. -**Traditional approach:** Send HTML/JavaScript in iframes +**Traditional approach:** Send HTML/JavaScript in iframes. -- Heavy, visually disjointed -- Security complexity -- Doesn't match app styling +- Heavy, visually disjointed. +- Security complexity. +- Doesn't match app styling. **Need:** Transmit UI that's safe like data, expressive like code. @@ -32,9 +32,9 @@ In multi-agent systems, agents often run remotely (different servers, organizati A2UI: JSON messages describing UI that: -- LLMs generate as structured output -- Travel over any transport (A2A, AG UI, SSE, WebSockets) -- Client renders using its own native components +- LLMs generate as structured output. +- Travel over any transport (A2A, AG UI, SSE, WebSockets). +- Client renders using its own native components. **Result:** Client controls security and styling, agent-generated UI feels native. @@ -184,17 +184,19 @@ Client renders these messages as native components (Angular, Flutter, React, etc ## What A2UI Is NOT -- Not a framework (it's a protocol) -- Not a replacement for HTML (for agent-generated UIs, not static sites) -- Not a robust styling system (client controls styling with limited serverside styling support) -- Not limited to web (works on mobile and desktop) +- Not a framework (it is a protocol). +- Not a replacement for HTML (for agent-generated UIs, not static sites). +- Not a robust styling system (client controls styling with limited server-side styling support). +- Not limited to web (works on mobile and desktop). ## Key Concepts -- **Surface**: Canvas for components (dialog, sidebar, main view) -- **Component**: UI element (Button, TextField, Card, etc.) -- **Data Model**: Application state, components bind to it -- **Catalog**: Available component types -- **Message**: JSON object (`surfaceUpdate`, `dataModelUpdate`, `beginRendering`, etc.) +A2UI relies on the following key concepts: + +- **Surface**: Canvas for components (dialog, sidebar, main view). +- **Component**: UI element (Button, TextField, Card, etc.). +- **Data Model**: Application state, components bind to it. +- **Catalog**: Available component types. +- **Message**: JSON object (`surfaceUpdate`, `dataModelUpdate`, `beginRendering`, etc.). For a comparison of similar projects, see [Agent UI Ecosystem](agent-ui-ecosystem.md). diff --git a/docs/introduction/who-is-it-for.md b/docs/introduction/who-is-it-for.md index e1c40c4aa..b94ff40c3 100644 --- a/docs/introduction/who-is-it-for.md +++ b/docs/introduction/who-is-it-for.md @@ -10,11 +10,11 @@ Build multi-agent platforms, enterprise assistants, or cross-platform apps where **Why A2UI:** -- Brand control: client owns styling and design system -- Multi-agent: support local, remote, and third-party agents -- Secure: declarative data, no code execution -- Cross-platform: web, mobile, desktop -- Interoperable: open source, same spec with multiple renderers +- Brand control: client owns styling and design system. +- Multi-agent: support local, remote, and third-party agents. +- Secure: declarative data, no code execution. +- Cross-platform: web, mobile, desktop. +- Interoperable: open source, same spec with multiple renderers. **Get started:** [Client Setup](../guides/client-setup.md) | [Theming](../guides/theming.md) | [Defining Your Own Catalog](../guides/defining-your-own-catalog.md) @@ -24,11 +24,11 @@ Build agents that generate forms, dashboards, and interactive workflows. **Why A2UI:** -- LLM-friendly: flat structure, easy to generate incrementally -- Rich interactions: beyond text (forms, tables, visualizations) -- Generations not tools: UI as part of the generated output from the agent -- Portable: one agent response works across all A2UI clients -- Streamable: progressive rendering as you generate +- LLM-friendly: flat structure, easy to generate incrementally. +- Rich interactions: beyond text (forms, tables, visualizations). +- Generations not tools: UI as part of the generated output from the agent. +- Portable: one agent response works across all A2UI clients. +- Streamable: progressive rendering as you generate. **Get started:** [Agent Development](../guides/agent-development.md) @@ -42,9 +42,9 @@ Do you ship your agent into other apps you don't necessarily control? **Why A2UI:** -- Standard protocol: interoperable with A2A and other transports -- Extensible: custom component catalogs -- Open source (Apache 2.0) +- Standard protocol: interoperable with A2A and other transports. +- Extensible: custom component catalogs. +- Open source (Apache 2.0). **Get started:** [Community](../ecosystem/community.md) | [Roadmap](../roadmap.md) @@ -52,15 +52,17 @@ Do you ship your agent into other apps you don't necessarily control? ## When to Use A2UI -- ✅ **Agent-generated UI** - Core purpose -- ✅ **Multi-agent systems** - Standard protocol across trust boundaries -- ✅ **Cross-platform apps** - One agent, many renderers (web/mobile/desktop) -- ✅ **Security critical** - Declarative data, no code execution -- ✅ **Brand consistency** - Client controls styling - -- ❌ **Static websites** - Use HTML/CSS -- ❌ **Simple text-only chat** - Use Markdown -- ❌ **Remote widgets not integrated with client** - Use iframes, like [MCP Apps](../introduction/agent-ui-ecosystem.md) -- ❌ **Rapid UI + Agent app built together** - Use [AG UI / CopilotKit](../introduction/agent-ui-ecosystem.md) +Use A2UI in the following scenarios: +- **Agent-generated UI**: Core purpose. +- **Multi-agent systems**: Standard protocol across trust boundaries. +- **Cross-platform apps**: One agent, many renderers (web/mobile/desktop). +- **Security critical**: Declarative data, no code execution. +- **Brand consistency**: Client controls styling. + +Do not use A2UI for: +- **Static websites**: Use HTML/CSS. +- **Simple text-only chat**: Use Markdown. +- **Remote widgets not integrated with client**: Use iframes, like [MCP Apps](../introduction/agent-ui-ecosystem.md). +- **Rapid UI + Agent app built together**: Use [AG UI / CopilotKit](../introduction/agent-ui-ecosystem.md). See [Agent UI Ecosystem](../introduction/agent-ui-ecosystem.md) for a detailed comparison. diff --git a/docs/quickstart.md b/docs/quickstart.md index 51b1ec25f..ca5f1d25e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -6,10 +6,10 @@ Get hands-on with A2UI by running the restaurant finder demo. This guide will ha By the end of this quickstart, you'll have: -- ✅ A running web app with A2UI Lit renderer -- ✅ A Gemini-powered agent that generates dynamic UIs -- ✅ An interactive restaurant finder with form generation, time selection, and confirmation flows -- ✅ Understanding of how A2UI messages flow from agent to UI +- A running web app with A2UI Lit renderer. +- A Gemini-powered agent that generates dynamic UIs. +- An interactive restaurant finder with form generation, time selection, and confirmation flows. +- Understanding of how A2UI messages flow from agent to UI. ## Prerequisites @@ -19,9 +19,9 @@ Before you begin, make sure you have: - **uv** (Python package manager) — [Install here](https://docs.astral.sh/uv/getting-started/installation/) (used to run the Python agent backend) - **A Gemini API key** — [Get one free from Google AI Studio](https://aistudio.google.com/apikey) -> ⚠️ **Security Notice** -> -> This demo runs an A2A agent that uses Gemini to generate A2UI responses. The agent has access to your API key and will make requests to Google's Gemini API. Always review agent code before running it in production environments. +WARNING: Security Notice + +This demo runs an A2A agent that uses Gemini to generate A2UI responses. The agent has access to your API key and will make requests to Google's Gemini API. Always review agent code before running it in production environments. ## Step 1: Clone the Repository @@ -61,9 +61,9 @@ This command will: 4. Launch the development server 5. Open your browser to `http://localhost:5173` -> ✅ **Demo Running** -> -> If everything worked, you should see the web app in your browser. The agent is now ready to generate UI! +NOTE: Demo Running + +If everything worked, you should see the web app in your browser. The agent is now ready to generate UI! ## Step 5: Try It Out @@ -168,9 +168,9 @@ Let's peek at what the agent is sending. Here's a simplified example of the JSON Note: In v0.9, `createSurface` replaces `beginRendering`, components use a flatter format, and the data model uses plain JSON values instead of typed adjacency lists. -> 💡 **It's Just JSON** -> -> Notice how readable and structured this is? LLMs can generate this easily, and it's safe to transmit and render—no code execution required. +TIP: It's Just JSON + +Notice how readable and structured this is? LLMs can generate this easily, and it's safe to transmit and render—no code execution required. ## Exploring Other Demos @@ -249,7 +249,7 @@ uv run . ### Still Having Issues? - Check the [GitHub Issues](https://github.com/google/a2ui/issues) -- Review the [samples/client/lit/README.md](https://github.com/google/a2ui/tree/main/samples/client/lit) +- Review the [samples/client/lit/README.md](../samples/client/lit) - Join the community discussions ## Understanding the Demo Code diff --git a/docs/reference/agents.md b/docs/reference/agents.md index b921dbb00..64e82e968 100644 --- a/docs/reference/agents.md +++ b/docs/reference/agents.md @@ -8,14 +8,12 @@ The agent is only responsible for generating the A2UI messages. ## How Agents Work -``` -User Input → Agent Logic → LLM → A2UI JSON → Send to Client -``` +The agent workflow typically involves the following steps: -1. **Receive** user message -2. **Process** with LLM (Gemini, GPT, Claude, etc.) -3. **Generate** A2UI JSON messages as structured output -4. **Send** to client via transport +1. **Receive** user message. +2. **Process** with LLM (Gemini, GPT, Claude, etc.). +3. **Generate** A2UI JSON messages as structured output. +4. **Send** to client via transport. User interactions from the client can be treated as new user input. @@ -24,19 +22,19 @@ User interactions from the client can be treated as new user input. The A2UI repository includes sample agents you can learn from: - [Restaurant Finder](https://github.com/google/A2UI/tree/main/samples/agent/adk/restaurant_finder) - - Table reservations with forms - - Written with the ADK + - Table reservations with forms. + - Written with the ADK. - [Contact Lookup](https://github.com/google/A2UI/tree/main/samples/agent/adk/contact_lookup) - - Search with result lists - - Written with the ADK + - Search with result lists. + - Written with the ADK. - [Rizzcharts](https://github.com/google/A2UI/tree/main/samples/agent/adk/rizzcharts) - - A2UI Custom components demo - - Written with the ADK + - A2UI Custom components demo. + - Written with the ADK. - [Orchestrator](https://github.com/google/A2UI/tree/main/samples/agent/adk/orchestrator) - - Passes A2UI messages from remote subagents - - Written with the ADK + - Passes A2UI messages from remote subagents. + - Written with the ADK. -## Different types of agents you will use A2A with +## Agent Types in A2A ### 1. User Facing Agent (standalone) @@ -46,8 +44,9 @@ A user facing agent is one that is directly interacted with by the user. This is a pattern where the user facing agent is a host for one or more remote agents. The user facing agent will call the remote agent and the remote agent will generate the A2UI messages. This is a common pattern in [A2A](https://a2a-protocol.org) with the client agent calling the server agent. -- The user facing agent may "passthrough" the A2UI message without altering them -- The user facing agent may alter the A2UI message before sending it to the client +In this pattern, the user-facing agent can handle messages in two ways: +- The user facing agent may "passthrough" the A2UI message without altering them. +- The user facing agent may alter the A2UI message before sending it to the client. ### 3. Remote Agent diff --git a/docs/reference/components.md b/docs/reference/components.md index 36f252606..9a050ec83 100644 --- a/docs/reference/components.md +++ b/docs/reference/components.md @@ -2,15 +2,15 @@ This page showcases all A2UI components with examples and usage patterns. -!!! abstract "Schema Files" - - === "v0.8" - - [:material-code-json: Standard Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_8/standard_catalog_definition.json) - - === "v0.9" - - [:material-code-json: Basic Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_9/basic_catalog.json) +> NOTE: Schema Files +> +> === "v0.8" +> +> [:material-code-json: Standard Catalog Definition (JSON Schema)](../../specification/v0_8/json/standard_catalog_definition.json) +> +> === "v0.9" +> +> [:material-code-json: Basic Catalog Definition (JSON Schema)](../../specification/v0_9/json/basic_catalog.json) --- @@ -604,9 +604,9 @@ Tabbed interface for organizing content into switchable panels. All components share: -- `id` (required): Unique identifier within the surface -- `accessibility`: Accessibility attributes (label, role) -- `weight`: Flex-grow value when inside a Row or Column +- `id` (required): Unique identifier within the surface. +- `accessibility`: Accessibility attributes (label, role). +- `weight`: Flex-grow value when inside a Row or Column. ## Version Differences Summary @@ -636,15 +636,15 @@ npm start -- gallery ## Further Reading -!!! abstract "Schema Files" - - === "v0.8" - - [:material-code-json: Standard Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_8/standard_catalog_definition.json) - - === "v0.9" - - [:material-code-json: Basic Catalog Definition (JSON Schema)](https://a2ui.org/specification/v0_9/basic_catalog.json) +> NOTE: Schema Files +> +> === "v0.8" +> +> [:material-code-json: Standard Catalog Definition (JSON Schema)](../../specification/v0_8/json/standard_catalog_definition.json) +> +> === "v0.9" +> +> [:material-code-json: Basic Catalog Definition (JSON Schema)](../../specification/v0_9/json/basic_catalog.json) - **[Defining Your Own Catalog](../guides/defining-your-own-catalog.md)**: Build your own components - **[Theming Guide](../guides/theming.md)**: Style components to match your brand diff --git a/docs/reference/messages.md b/docs/reference/messages.md index 063d0bcc7..77f634705 100644 --- a/docs/reference/messages.md +++ b/docs/reference/messages.md @@ -248,6 +248,7 @@ Add or update components within a surface. ### Usage Notes + Keep these usage notes in mind: - One component must be designated as the `root` in the `beginRendering` message to serve as the tree root. - Components form an adjacency list (flat structure with ID references). - Sending a component with an existing ID updates that component. @@ -362,6 +363,7 @@ Add or update components within a surface. ### Usage Notes + Keep these usage notes in mind: - One component must have `"id": "root"` to serve as the tree root (convention, not a separate message field). - Component type is a string (`"component": "Text"`) instead of a wrapper object. - Properties are flat on the component object (no nesting under type key). @@ -455,6 +457,7 @@ Update the data model that components bind to. ### Usage Notes + Keep these usage notes in mind: - Data model is per-surface. - Components automatically re-render when their bound data changes. - Prefer granular updates to specific paths over replacing the entire model. @@ -520,6 +523,7 @@ Update the data model that components bind to. ### Usage Notes + Keep these usage notes in mind: - v0.9 uses standard JSON Pointer paths and plain JSON values — no typed wrappers. - `path` defaults to `"/"` (root) if omitted. - `value` can be any JSON type (string, number, boolean, object, array, null). Omit to delete. @@ -586,12 +590,13 @@ Remove a surface and all its components and data. ### Usage Notes -- Removes all components associated with the surface -- Clears the data model for the surface -- Client should remove the surface from the UI -- Safe to delete non-existent surface (no-op) -- Use when closing modals, dialogs, or navigating away -- Identical structure in both versions (v0.9 just adds the `version` field) +Keep these usage notes in mind: +- Removes all components associated with the surface. +- Clears the data model for the surface. +- Client should remove the surface from the UI. +- Safe to delete non-existent surface (no-op). +- Use when closing modals, dialogs, or navigating away. +- Identical structure in both versions (v0.9 just adds the `version` field). --- @@ -599,6 +604,8 @@ Remove a surface and all its components and data. ### Requirements +Message ordering must satisfy the following requirements: + 1. `beginRendering` must come after the initial `surfaceUpdate` messages for that surface. 2. `surfaceUpdate` can come before or after `dataModelUpdate`. 3. Messages for different surfaces are independent. @@ -649,15 +656,15 @@ Remove a surface and all its components and data. Validate against: - - **[server_to_client.json](https://a2ui.org/specification/v0_8/server_to_client.json)**: Message envelope schema - - **[standard_catalog_definition.json](https://a2ui.org/specification/v0_8/standard_catalog_definition.json)**: Component schemas + - **[server_to_client.json](../../specification/v0_8/json/server_to_client.json)**: Message envelope schema. + - **[standard_catalog_definition.json](../../specification/v0_8/json/standard_catalog_definition.json)**: Component schemas. === "v0.9" Validate against: - - **[server_to_client.json](https://a2ui.org/specification/v0_9/server_to_client.json)**: Message envelope schema - - **[basic_catalog.json](https://a2ui.org/specification/v0_9/basic_catalog.json)**: Component schemas + - **[server_to_client.json](../../specification/v0_9/json/server_to_client.json)**: Message envelope schema. + - **[basic_catalog.json](../../specification/v0_9/json/basic_catalog.json)**: Component schemas. ## Further Reading diff --git a/docs/reference/renderers.md b/docs/reference/renderers.md index 839919c14..d19fde72c 100644 --- a/docs/reference/renderers.md +++ b/docs/reference/renderers.md @@ -33,14 +33,12 @@ See the **[full ecosystem renderers list](../ecosystem/renderers.md)** for more ## How Renderers Work -``` -A2UI JSON → Renderer → Native Components → Your App -``` +The rendering process typically involves the following steps: -1. **Receive** A2UI messages from the transport -2. **Parse** the JSON and validate against the schema -3. **Render** using platform-native components -4. **Style** according to your app's theme +1. **Receive** A2UI messages from the transport. +2. **Parse** the JSON and validate against the schema. +3. **Render** using platform-native components. +4. **Style** according to your app's theme. ## Using a Renderer @@ -59,17 +57,17 @@ Want to build a renderer for your platform? - Review existing renderers for patterns. - Check out our [Renderer Development Guide](../guides/renderer-development.md) for details on implementing a renderer. -### Key requirements: +A compliant renderer must meet the following key requirements: -- Parse A2UI JSON messages, specifically the adjacency list format -- Map A2UI components to native widgets -- Handle data binding, lifecycle events -- Process a sequence of incremental A2UI messages to build and update the UI -- Support server initiated updates -- Support user actions +- Parse A2UI JSON messages, specifically the adjacency list format. +- Map A2UI components to native widgets. +- Handle data binding, lifecycle events. +- Process a sequence of incremental A2UI messages to build and update the UI. +- Support server-initiated updates. +- Support user actions. -### Next Steps +For more information, see the following resources: -- **[Client Setup Guide](../guides/client-setup.md)**: Integration instructions -- **[Quickstart](../quickstart.md)**: Try the Lit renderer -- **[Component Reference](components.md)**: What components to support +- **[Client Setup Guide](../guides/client-setup.md)**: Integration instructions. +- **[Quickstart](../quickstart.md)**: Try the Lit renderer. +- **[Component Reference](components.md)**: What components to support. diff --git a/docs/roadmap.md b/docs/roadmap.md index 91f685eb1..930d29dfb 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -13,11 +13,11 @@ This roadmap outlines the current state and future plans for the A2UI project. T Key features: -- ✅ Streaming JSONL message format -- ✅ Four core message types (`surfaceUpdate`, `dataModelUpdate`, `beginRendering`, `deleteSurface`) -- ✅ Adjacency list component model -- ✅ JSON Pointer-based data binding -- ✅ Separation of structure and state +- Streaming JSONL message format. +- Four core message types (`surfaceUpdate`, `dataModelUpdate`, `beginRendering`, `deleteSurface`). +- Adjacency list component model. +- JSON Pointer-based data binding. +- Separation of structure and state. ### Renderers @@ -57,7 +57,7 @@ Key features: | Integration | Status | Notes | |-------------|--------|-------| | **Any agent with A2A support** | ✅ Complete | Day-zero compatibility thanks to A2A protocol | -| **ADK** | 📋 Planned | Still designing developer ergonomics, see [samples](https://github.com/google/A2UI/tree/main/samples/agent/adk) | +| **ADK** | 📋 Planned | Still designing developer ergonomics, see [samples](../samples/agent/adk) | | **Genkit** | 💡 Proposed | Community interest | | **LangGraph** | 💡 Proposed | Community interest | | **CrewAI** | 💡 Proposed | Community interest | diff --git a/docs/scripts/README.md b/docs/scripts/README.md index 5ff9ff1e8..b21d2df6a 100644 --- a/docs/scripts/README.md +++ b/docs/scripts/README.md @@ -4,7 +4,7 @@ This directory contains utility scripts to prepare our documentation for the **M ## Purpose -To ensure a great reading experience both on GitHub and the hosted site, we use **GitHub-flavored Markdown** as our primary source of truth. This script transforms GitHub's native syntax into **MkDocs-compatible syntax** (specifically for the `pymdown-extensions`) during the build pipeline. +To ensure a great reading experience both on GitHub and the hosted site, the project uses **GitHub-flavored Markdown** as the primary source of truth. This script transforms GitHub's native syntax into **MkDocs-compatible syntax** (specifically for the `pymdown-extensions`) during the build pipeline. ## Supported Conversions (Uni-directional) @@ -12,6 +12,7 @@ The script performs a uni-directional transformation: **GitHub Markdown → MkDo ### Alert/Admonition Conversion +The script handles the following conversions: - GitHub uses a blockquote-based syntax for alerts. - MkDocs requires the `!!!` or `???` syntax to render colored callout boxes. diff --git a/docs/specification/v0.8-a2a-extension.md b/docs/specification/v0.8-a2a-extension.md index 255814932..e1fa89d33 100644 --- a/docs/specification/v0.8-a2a-extension.md +++ b/docs/specification/v0.8-a2a-extension.md @@ -1,18 +1,18 @@ # A2UI Extension for A2A Protocol v0.8 — Stable -> ℹ️ **Living Document** +> NOTE: Living Document > > This specification is automatically included from `specification/v0_8/docs/a2ui_extension_specification.md`. Any updates to the specification will automatically appear here. -> 📝 **Version Compatibility** +> NOTE: Version Compatibility > > This extension specification applies to A2UI v0.8 and the A2A Protocol. For the base A2UI protocol, see [v0.8 Protocol Specification](v0.8-a2ui.md). -**Related Documentation:** +For more information, see the following related documentation: -- [A2UI Protocol v0.8](v0.8-a2ui.md) (Stable) -- [A2A Protocol Documentation](https://a2a-protocol.org) +- [A2UI Protocol v0.8](v0.8-a2ui.md) (Stable). +- [A2A Protocol Documentation](https://a2a-protocol.org). --- diff --git a/docs/specification/v0.8-a2ui.md b/docs/specification/v0.8-a2ui.md index 4eb43e196..eda04d6b4 100644 --- a/docs/specification/v0.8-a2ui.md +++ b/docs/specification/v0.8-a2ui.md @@ -2,15 +2,15 @@ > > Version 0.8 is the current stable release, recommended for production use. -> ℹ️ **Living Document** +> NOTE: Living Document > > This specification is automatically included from `specification/v0_8/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. -**See also:** +For more information, see the following related documentation: -- [v0.9 Protocol Specification](v0.9-a2ui.md) (Draft) -- [Evolution Guide: v0.8 → v0.9](v0.9-evolution-guide.md) -- [A2A Extension Specification](v0.8-a2a-extension.md) (for v0.8) +- [v0.9 Protocol Specification](v0.9-a2ui.md) (Draft). +- [Evolution Guide: v0.8 → v0.9](v0.9-evolution-guide.md). +- [A2A Extension Specification](v0.8-a2a-extension.md) (for v0.8). --- diff --git a/docs/specification/v0.9-a2ui.md b/docs/specification/v0.9-a2ui.md index 911c809d5..810c35806 100644 --- a/docs/specification/v0.9-a2ui.md +++ b/docs/specification/v0.9-a2ui.md @@ -2,14 +2,14 @@ > > Version 0.9 is currently in draft status. For production use, consider [v0.8 (Stable)](v0.8-a2ui.md). -> ℹ️ **Living Document** +> NOTE: Living Document > > This specification is automatically included from `specification/v0_9/docs/a2ui_protocol.md`. Any updates to the specification will automatically appear here. -**See also:** +For more information, see the following related documentation: -- [v0.8 Protocol Specification](v0.8-a2ui.md) (Stable) -- [Evolution Guide: v0.8 → v0.9](v0.9-evolution-guide.md) +- [v0.8 Protocol Specification](v0.8-a2ui.md) (Stable). +- [Evolution Guide: v0.8 → v0.9](v0.9-evolution-guide.md). --- diff --git a/docs/specification/v0.9-evolution-guide.md b/docs/specification/v0.9-evolution-guide.md index 6816d21d4..c5f2c8d91 100644 --- a/docs/specification/v0.9-evolution-guide.md +++ b/docs/specification/v0.9-evolution-guide.md @@ -2,10 +2,10 @@ > > This guide is automatically included from `specification/v0_9/docs/evolution_guide.md`. Any updates will automatically appear here. -**Related Documentation:** +For more information, see the following related documentation: -- [A2UI Protocol v0.8](v0.8-a2ui.md) (Stable - what you're migrating from) -- [A2UI Protocol v0.9](v0.9-a2ui.md) (Draft - what you're migrating to) +- [A2UI Protocol v0.8](v0.8-a2ui.md) (Stable - what you're migrating from). +- [A2UI Protocol v0.9](v0.9-a2ui.md) (Draft - what you're migrating to). ---