documented render_ui widgets method

[JuanCaCoder]

No description provided.

[JuanCaCoder]

📝 Executive Summary

This PR documents the context.render_ui_widget() method and UiWidget model (introduced in ADK Python v1.27.0) on the Agent Context guide. It explains how tools and callbacks can attach rich interactive UI component metadata (such as MCP App iframes) to EventActions so client UI hosts can render interactive widgets alongside agent responses, complete with a copy-pasteable Python ToolContext example and best-practice guidance.

• Target Doc: docs/context/index.md
• Branch Comparison: main...render_ui_widget

---

🗂️ PR Consolidation & Verification Mapping

PR / Source Reference	Original Section	New / Updated Section	Change Description	Codebase Verification & GitHub Source
adk-python@530ff06 / adk-python@86db35c	### Accessing Services (after #### Searching Memory)	### Render UI Widgets	Adds a new subsection with Python v1.27.0 version tag, conceptual overview of context.render_ui_widget(), and a Python example constructing a UiWidget with an mcp provider payload inside a tool using ToolContext.	✅ PASS – context.py:L835-L856, ui_widget.py:L25-L59
adk-python@530ff06	## Key Takeaways & Best Practices	## Key Takeaways & Best Practices	Adds the UI Rendering takeaway bullet highlighting context.render_ui_widget(widget) for sending rich UI components (like MCP App iframes) to the client.	✅ PASS – context.py:L835-L844, event_actions.py:L201-L202

---

🔍 Technical Verification Report

1. Context.render_ui_widget(ui_widget: UiWidget) -> None:

   • Claimed Doc Behavior: Sends rich UI components (such as MCP App iframes) to the client alongside agent responses by calling context.render_ui_widget(widget) on a Context / ToolContext instance, automatically linking changes to the current step's EventActions.
   • Verified Code Implementation: Defined on Context as def render_ui_widget(self, ui_widget: UiWidget) -> None:. Initializes self._event_actions.render_ui_widgets = [] if None, validates that no existing widget in self._event_actions.render_ui_widgets shares the same ui_widget.id (raising ValueError on duplicate IDs), and appends ui_widget to self._event_actions.render_ui_widgets (Optional[list[UiWidget]] = None on EventActions).
   • GitHub Source Link: src/google/adk/agents/context.py#L835-L856, src/google/adk/events/event_actions.py#L201-L202, tests/unittests/agents/test_context.py#L624-L693
   • Status: ✅ PASS

2. UiWidget Model & MCP Payload Schema (google.adk.events.ui_widget.UiWidget):

   • Claimed Doc Behavior: Imported via from google.adk.events.ui_widget import UiWidget and instantiated with id="status_dashboard", provider="mcp", and payload={"resource_uri": "ui://analytics/status", "tool": {"name": "get_system_status"}, "tool_args": {"theme_color": color}}.
   • Verified Code Implementation: class UiWidget(BaseModel) enforces ConfigDict(extra='forbid', alias_generator=alias_generators.to_camel, populate_by_name=True) and defines id: str, provider: str, and payload: dict[str, Any] = Field(default_factory=dict). Its docstring and MCPTool._run_async_impl explicitly specify provider="mcp" with payload keys "resource_uri", "tool", and "tool_args".
   • GitHub Source Link: src/google/adk/events/ui_widget.py#L25-L59, src/google/adk/tools/mcp_tool/mcp_tool.py#L744-L754
   • Status: ✅ PASS

3. ToolContext Re-export & Type-Based Context Parameter Injection (context: ToolContext):

   • Claimed Doc Behavior: Imports from google.adk.tools import ToolContext and declares a tool function signature def render_styled_widget(color: str, context: ToolContext) -> str: where context receives the active ToolContext instance.
   • Verified Code Implementation: ToolContext is exposed in google.adk.tools.__all__ via lazy re-export from google.adk.tools.tool_context, where ToolContext = Context. During function tool declaration and invocation, find_context_parameter(func) inspects parameter type annotations via _is_context_type(annotation) (annotation is Context), resolving any parameter annotated with ToolContext regardless of whether it is named context or tool_context.
   • GitHub Source Link: src/google/adk/tools/__init__.py#L88, src/google/adk/tools/tool_context.py#L27, src/google/adk/utils/context_utils.py#L38-L100
   • Status: ✅ PASS

4. Language Support & Version Tag (Python v1.27.0):

   • Claimed Doc Behavior: Marked with <span class="lst-python">Python v1.27.0</span>.
   • Verified Code Implementation: UiWidget and Context.render_ui_widget() were added in commit 530ff06ece61a93855a53235e85af18b46b2a6a0 and first released in v1.27.0 (2026-03-12) as recorded in CHANGELOG.md.
   • GitHub Source Link: CHANGELOG.md#L1835-L1840, adk-python@530ff06
   • Status: ✅ PASS