docs(guides): improve A2UI over MCP guide for new developers

[zeroasterisk]

What changed

Rewrote the A2UI over MCP guide to be more developer-friendly. Walked through it as a new developer and fixed every pain point.

Key improvements

• Quick Start first — run the sample before learning protocol details
• Prerequisites section — what you need installed
• Step-by-step Inspector walkthrough — exact steps to see it working
• Flow diagram — visual showing how A2UI payloads flow through MCP
• a2ui-agent-sdk reference — mentions the pip package for production use
• Fixed error handler — was referencing error_payload['error'] but the payload has code and message at top level
• Audience annotation table — clearer than prose for visibility control options
• Next Steps links — where to go after this guide

Issues found (not fixed in this PR)

• The a2ui-over-mcp-recipe sample's pyproject.toml depends on a2ui-agent (local path) — may need updating to a2ui-agent-sdk for the published package name
• The sample uses v0.8 spec schemas but the guide references v0.10 — kept v0.10 in the guide since that's the current spec version

cc @nanyu @jacobsimionato

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Code Review

This pull request updates the A2UI over MCP documentation to include prerequisites, a quick start guide, and updated code examples using the v0.10 schema. The review feedback identifies several issues in the Python code snippets, including the use of an undefined 'self' variable in decorators and incorrect return types for tool handlers, which should return 'CallToolResult' instead of a list to ensure compatibility with the MCP SDK.

I am having trouble creating individual review comments. Click here to see my feedback.

docs/guides/a2ui_over_mcp.md (105)

Using @self.tool() is confusing in a standalone code snippet as self is not defined. While the note at line 228 explains this refers to the FastMCP API, it is more idiomatic for documentation to use a standard variable name like mcp (e.g., @mcp.tool()) to avoid implying a class context that isn't shown.

@mcp.tool()

docs/guides/a2ui_over_mcp.md (212-225)

The low-level MCP Server.call_tool handler is expected to return a types.CallToolResult object (or a dictionary matching its schema), which contains a content list. Returning a list[types.TextContent] directly will cause a validation error in the MCP SDK. This is inconsistent with the correct usage shown earlier in the guide (line 149).

async def handle_call_tool(name: str, arguments: dict) -> types.CallToolResult:
    if name == "action":
        action_name = arguments["name"]
        context = arguments.get("context", {})

        if action_name == "confirm_booking":
            start = context["start"]
            end = context["end"]
            return types.CallToolResult(content=[types.TextContent(
                type="text",
                text=f"Booking confirmed from {start} to {end}."
            )])

        raise ValueError(f"Unknown action: {action_name}")

docs/guides/a2ui_over_mcp.md (256-266)

Similar to the action handler, the error handler should return a types.CallToolResult to be compatible with the low-level MCP Server API. Returning a list of content items directly is not supported by the call_tool decorator's expected return type.

async def handle_call_tool(name: str, arguments: dict) -> types.CallToolResult:
    if name == "error":
        code = arguments.get("code", "UNKNOWN")
        message = arguments.get("message", "")
        surface_id = arguments.get("surfaceId", "")
        # Log or handle the error
        return types.CallToolResult(content=[types.TextContent(
            type="text",
            text=f"Received error {code} on surface {surface_id}: {message}"
        )])

[zeroasterisk]

Hey @wrenj — you wrote the original version of this guide, so wanted to loop you in on the rewrite. Main changes:

• Added a Quick Start section (run the sample first, learn protocol second)
• Updated to v0.9 spec throughout
• Fixed the error handler example (error_payload['error'] → code/message fields)
• Added a2ui-agent-sdk SDK section
• Added audience annotation table and Next Steps

Would love your review on whether the protocol details are still accurate after the restructure.

cc @nanyu

[wrenj]

thanks for the docs!