Adds an ADK-related skill for reference in an upcoming blog post.

flutter-frontend-for-adk/README.md

@@ -0,0 +1,84 @@
+# Flutter Frontend for ADK Agents (Custom Skill)
+
+This repository contains a skill intended for use with [Antigravity](https://antigravity.google). It will guide the agent through the discovery, architecture, design, and implementation of a Flutter-based frontend for an Agent Development Kit (ADK) agent written in Python.
+
+> [!NOTE]
+> This repository is a learning resource and an open-source sample. Use it with an experimental project as a way of learning how to use Antigravity to get things done with Flutter.
+
+---
+
+## Capabilities
+
+The `flutter-frontend-for-adk` skill orchestrates a structured, multi-phase workflow to construct a responsive Flutter client that interfaces with an ADK Python agent:
+
+1. **Workspace & Agent Discovery:** Maps the agent's purpose, sub-agent hierarchy, API endpoints, event streams, and human-in-the-loop triggers.
+2. **Frontend Usage & Behavior:** Defines target platforms (mobile, web, desktop), user experience flows, and screen requirements.
+3. **Frontend Architecture:** Establishes directory structure, state management using the `provider` package, and manual JSON serialization models.
+4. **Frontend Design & Layout:** Configures visual styles, responsive column layouts, interactive states, and micro-animations.
+5. **Scaffolding & Implementation:** Scaffolds the Flutter project, implements the API service (handling REST and Server-Sent Events/SSE streams), and builds the views.
+6. **Workspace Integration:** Integrates frontend execution commands into workspace build tools (e.g., Makefiles, script runners) and updates version control settings.
+
+---
+
+## Installation
+
+To make this skill available to Antigravity, you can install it either globally or locally within a specific workspace.
+
+### Global Installation
+
+To make the skill available across all your projects, copy this repository into your global Antigravity customizations directory:
+
+```bash
+mkdir -p ~/.gemini/config/skills/flutter-frontend-for-adk
+cp -r . ~/.gemini/config/skills/flutter-frontend-for-adk
+```
+
+### Local Project Installation
+
+To make the skill available only within a specific project, copy this repository into the `.agents/skills` directory at the root of that project:
+
+```bash
+mkdir -p /path/to/your/project/.agents/skills/flutter-frontend-for-adk
+cp -r . /path/to/your/project/.agents/skills/flutter-frontend-for-adk
+```
+
+Once copied, Antigravity will automatically discover the skill via its `SKILL.md` definition.
+
+---
+
+## Step-by-Step Usage Example
+
+This section outlines how to use the skill to replace an existing web frontend with a Flutter client, using the official `deep_search` ADK sample agent as an example.
+
+### 1. Clone the ADK Samples Repository
+Clone the official repository containing the Agent Development Kit samples to your local machine:
+
+```bash
+git clone https://github.com/google/adk-samples.git
+cd adk-samples
+```
+
+### 2. Open the Target Sample
+Navigate to the Python version of the `deep_search` sample and open it in your workspace:
+
+```bash
+cd python/deep_search
+```
+
+Ensure this directory is open in your IDE workspace where Antigravity is active.
+
+### 3. Remove the Existing Frontend
+Prompt Antigravity to remove the React-based frontend that is bundled with the sample. This ensures a clean slate for the new Flutter application.
+
+You can use a prompt such as:
+> "Please remove the React frontend that ships with this sample, along with any mention of it in associated documentation, configuration files, and build scripts."
+
+Antigravity will delete the React source files, remove web-related dependencies, and clean up workspace references.
+
+### 4. Generate the Flutter Frontend
+Once the workspace is cleaned, instruct Antigravity to use the installed custom skill to build a new Flutter frontend.
+
+You can use a prompt such as:
+> "Please use the `flutter-frontend-for-adk` skill to create a new, Flutter-based frontend for the agent."
+
+Antigravity will activate the skill and proceed through the six phases described in the [SKILL.md](file:///Users/redbrogdon/source/demos/flutter-frontend-for-adk/SKILL.md) file, prompting you for input and approval at the end of each phase before continuing to the next.

flutter-frontend-for-adk/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: flutter-frontend-for-adk
+description: >
+  Orchestrates the discovery, mapping, design, and implementation of a premium
+  Flutter-based frontend for an Agent Development Kit (ADK) agent written with Python.
+metadata:
+  author: Antigravity
+  version: 1.0.0
+  requires:
+    bins:
+      - flutter
+      - dart
+---
+
+# Building a Flutter Frontend for an ADK Agent
+
+This skill orchestrates the end-to-end workflow of designing, specifying, and implementing a premium Flutter-based frontend for any Agent Development Kit (ADK) agent.
+
+## Prerequisites & External References
+
+Before starting, the developer or coding agent should locate ADK framework-level specifications using the following resources instead of restating them in this skill:
+1.  **Activate ADK Code Skill:** Ensure that `/google-agents-cli-adk-code` is active in the current session. Refer to its reference file `adk-python.md` to understand the core `Event`, `EventActions`, and state management models.
+2.  **Fetch Official Docs:** Retrieve the official documentation index by calling `curl https://adk.dev/llms.txt` and search for pages related to client serving, networking, or the Python API server.
+3.  **Inspect Local Code:** To see exact Pydantic definitions and FastAPI endpoint details directly:
+    *   Open and inspect the local server definition inside your python environment at `.venv/lib/python*/site-packages/google/adk/cli/adk_web_server.py`.
+    *   Open and inspect the event schemas at `.venv/lib/python*/site-packages/google/adk/events/event.py` and `event_actions.py`.
+
+Follow the phases below sequentially. **Do not skip ahead.** You must complete and record the findings of each phase before beginning the next. When creating an implementation plan, add a blocking task for the "Review" step in each phase that has one and wait for the user to perform a review before beginning the next phase.
+
+---
+
+## Phase 1: Workspace & Agent Discovery
+Identify the core purpose of the agent in this repository, understand its sub-agent hierarchy, map its API endpoints, event streams, and human-in-the-loop triggers, and record this information.
+*   **Action:** Read [references/agent_discovery.md](references/agent_discovery.md) for step-by-step discovery instructions.
+*   **Deliverable:** Create the [AGENT_INTERFACE_NOTES.md](AGENT_INTERFACE_NOTES.md) file in the root of the project.
+*   **Review:** Summarize (in a paragraph or two) what you just learned for the user. Invite them to inspect `AGENT_DISCOVERY_NOTES.md`, and do not proceed to Phase 2 until they indicate that you should do so.
+
+---
+
+## Phase 2: Frontend Usage & Behavior
+Define the high-level behavioral and functional requirements of the frontend: target platforms, screen specifications, feature details, and user experience flows.
+*   **Action:** Read [references/frontend_usage.md](references/frontend_usage.md) for instructions on defining app behavior.
+*   **Deliverable:** Create the [FRONTEND_USAGE_NOTES.md](FRONTEND_USAGE_NOTES.md) file in the root of the project.
+*   **Review:** Summarize (in a paragraph or two) what you just learned for the user. Invite them to inspect `FRONTEND_USAGE_NOTES.md`, and do not proceed to Phase 3 until they indicate that you should do so.
+
+---
+
+## Phase 3: Frontend Architecture
+Define the structural patterns of the application, including core folder directory layouts, manual model serializations, and state management setups.
+*   **Action:** Read [references/frontend_architecture.md](references/frontend_architecture.md) for instructions on defining app architecture.
+*   **Deliverable:** Create the [FRONTEND_ARCHITECTURE_NOTES.md](FRONTEND_ARCHITECTURE_NOTES.md) file in the root of the project.
+*   **Review:** Summarize (in a paragraph or two) what you just learned for the user. Invite them to inspect `FRONTEND_ARCHITECTURE_NOTES.md`, and do not proceed to Phase 4 until they indicate that you should do so.
+
+---
+
+## Phase 4: Frontend Design & Layout
+Design the visual structure, layout columns, styling guides, states, and micro-animations for the frontend application.
+*   **Action:** Read [references/frontend_design.md](references/frontend_design.md) for styling and UI blueprints.
+*   **Deliverable:** Create the [FRONTEND_DESIGN_NOTES.md](FRONTEND_DESIGN_NOTES.md) file in the root of the project.
+*   **Review:** Summarize (in a paragraph or two) what you just learned for the user. Invite them to inspect `FRONTEND_DESIGN_NOTES.md`, and do not proceed to Phase 5 until they indicate that you should do so.
+
+----
+
+## Phase 5: Scaffolding & Implementation
+Create and program the Flutter client application within the workspace, implementing all designs and specifications.
+*   **Action:**
+    1. Read [references/frontend_best_practices.md](references/frontend_best_practices.md) for specific implementation patterns and best practices.
+    2. Scaffold a fresh Flutter project inside a folder named `frontend/` at the root of the workspace. Do not specify an org name unless instructed. Create the app to build for only those platforms specified by the user -- if you're not sure, ask.
+    3. Add the approved packages (`provider`, `flutter_markdown`, `url_launcher`, and `http`) to `frontend/pubspec.yaml`.
+    4. Write the manual serialization models, the `AdkApiService` (implementing standard REST and SSE HTTP streamed response parsers), the `AgentProvider` state notifier, and the responsive views/widgets following `FRONTEND_ARCHITECTURE_NOTES.md` and `FRONTEND_DESIGN_NOTES.md`.
+    5. Verify code cleanliness and correctness by running `flutter format`, `flutter analyze`, and `flutter test` inside the `frontend/` directory.
+*   **Deliverable:** A fully compiled and functional Flutter application located inside the `frontend/` folder.
+
+---
+
+## Phase 6: Workspace Integration & Documentation
+Integrate the frontend into the workspace build flows, update version control settings, and document the client setup for developers.
+*   **Action:**
+    1.  **Build Configuration:** Examine the codebase to determine how a developer builds and runs the backend agent (e.g. searching for `Makefile` targets, task configurations in `pyproject.toml` like Poe/Taskipy, `package.json` scripts, or custom `run.sh` / `build.sh` scripts). Update these automation tools or files to provide simple commands for developers to build, test, and launch the new Flutter frontend.
+    2.  **VCS Ignore Setup:** Update the project's version control ignore configurations to make sure they account for the new project and its artifacts. The Flutter frontend should have a nested `.gitignore` file that will account for most things. If the root `.gitignore` file ignores `lib/`, though, make sure to add an exclusion for Flutter's `lib` directory (`!frontend/lib`).
+    3.  **Documentation Update:**
+        *   If the project has a `README.md` in the root directory, update it to reference the new frontend, detail prerequisites (such as the Flutter SDK version), and outline startup instructions.
+        *   Update the default `frontend/README.md` file to describe the frontend client, its structure, and how to launch both the agent and the client using the build configuration tools updated in step 1.
+        *   Look for any additional pre-existing docs that might need to be updated and do so.
+*   **Deliverable:** Updated workspace integration configurations, build scripts, and documentation files.

flutter-frontend-for-adk/references/agent_discovery.md

@@ -0,0 +1,94 @@
+# Agent Discovery & Mapping Reference
+
+This document directs the agent or developer to analyze the target ADK workspace and compile the `AGENT_INTERFACE_NOTES.md` file.
+
+---
+
+## Phase 1: Workspace & Agent Discovery
+
+Before writing any frontend code, you must analyze the backend agent to understand its capabilities, state variables, and execution patterns.
+
+### 1. Identify Workspace Entrypoints
+*   Scan the root directory for documentation (`README.md`, developer specs) to grasp the core purpose of the agent.
+*   Locate the startup configurations, usually defined in a `Makefile` or `pyproject.toml` (e.g., look for `adk api_server`).
+
+### 2. Deep Dive Into Backend Agent Logic
+Analyze the core agent definition file (typically `app/agent.py` or similar) to map out:
+*   **The Execution Timeline (Agent Authors):**
+    *   Identify the `root_agent` (the primary coordinator that the server communicates with directly).
+    *   Trace all sub-agents (e.g., in sequential structures, loop structures, or conditional routing trees).
+    *   Note the exact `name` string of every agent. The agent's `name` string will be the value populated in the `author` field of incoming `Event` stream items. Construct a chronological list of these authors representing the pipeline execution flow.
+*   **State Keys & Custom Callbacks:**
+    *   Identify agent-specific state keys by searching for `output_key="key_name"` parameters on all agent instantiations.
+    *   Search the file for custom callbacks (functions containing parameters of type `ToolContext` or `CallbackContext`).
+    *   Inspect these callback bodies for references to the session's state dictionary (e.g., `callback_context.state["key_name"]` or `tool_context.state["key_name"]`).
+    *   Identify where these callbacks are registered (e.g., `before_agent_callback`, `after_agent_callback`, `after_model_callback`) on specific agents to understand exactly *when* these state variables are updated during the execution sequence.
+
+### 3. Determine Server Execution Flags
+*   Examine how the backend API server is run locally.
+*   Run the command with `--help` (e.g., `uv run adk api_server --help`) or check active configs to determine:
+    *   Port and host configurations (default is `http://127.0.0.1:8000`).
+    *   CORS origin settings (`--allow_origins`).
+    *   Session and artifact persistence backends (e.g., `--session_service_uri`, `--artifact_service_uri`).
+
+### 4. Record Your Findings
+*   Create a new file in the root of the project called `AGENT_INTERFACE_NOTES.md`.
+*   In `AGENT_INTERFACE_NOTES.md` create the following sections:
+    1. **Introduction**: a description of the agent, including its name, what its intended purpose is, and a rough description of how it is constructed.
+    2. **Agent Entrypoint**: A description of the entrypoint of the agent, including the exact command used to start the agent locally.
+    3. **Key Components**: A description of each sub-agent in the agent, including its name, class, and a description of what it does.
+
+---
+
+## Phase 2: ADK API & Event Mapping
+
+The ADK API server automatically wraps the agent and exposes standard HTTP and streaming endpoints. You must fully understand how communication with the agent works. To do so, you will read and analyze the agent's code, and then record your findings in additional sections in `AGENT_INTERFACE_NOTES.md`.
+
+### 1. Understand API Endpoints
+ADK-based agents expose a REST API that can be used to communicate with the agent. The API is documented in the ADK documentation, but you should also read the agent's code to fully understand how it works. Here are the key endpoints:
+
+*   **Run Agent (Blocking):** `POST /run`
+    *   Executes the agent and returns a complete list of events after completion.
+*   **Run Agent (SSE Streaming):** `POST /run_sse`
+    *   Establishes a Server-Sent Events stream of events. Used for live chat responses and progress indicators.
+*   **Session Management:** `GET/POST/DELETE` endpoints under `/apps/{app_name}/users/{user_id}/sessions` to list, create, or delete user sessions.
+*   **Artifact Loading:** `GET /apps/{app_name}/users/{user_id}/sessions/{session_id}/artifacts/{artifact_name}` to load binary files or documents generated by the agent.
+
+### 2. Map Payload Schemas
+The ADK API uses a specific JSON schema for requests and responses. You should thoroughly understand the schema and record your findings in `AGENT_INTERFACE_NOTES.md`. Here are the key fields:
+
+*   **Run Request (`RunAgentRequest`):**
+    ```json
+    {
+      "app_name": "app",
+      "user_id": "default_user",
+      "session_id": "session-uuid",
+      "new_message": {
+        "role": "user",
+        "parts": [{ "text": "Research quantum computing." }]
+      },
+      "streaming": true
+    }
+    ```
+*   **Response Event:** Each SSE line starting with `data: ` contains an ADK `Event` JSON object. Map out these key fields in Dart:
+    *   `id` (String): Unique identifier of the event.
+    *   `author` (String): The name of the agent or "user" that generated the event. Useful for progress tracking.
+    *   `content` (Object): Contains `parts`, which can hold `text` snippets, `functionCall` parameters (e.g., to `google_search`), `functionResponse` results, or `codeExecutionResult`.
+    *   `actions` (Object): Holds metadata like `stateDelta` (map of state updates) and `artifactDelta` (map of updated files).
+
+### 3. Understand State, Artifact, & HITL/Resumability Management
+The ADK provides global mechanisms for state persistence, file artifact delivery, and execution resumption. You must analyze the agent codebase to extract these specific implementations:
+
+*   **State Keys Schema:** Map each discovered state key to its data structure. Inspect Python helper functions, dataclasses, or Pydantic models to identify if a key stores a `String`, a list of goals, or a complex nested `Map` (e.g., source mapping).
+*   **Artifact Creation:** Identify if the agent saves file artifacts to GCS or disk using `tool_context.save_artifact("name", part)`. Note their filenames, mime-types, and namespaces (e.g., `user:` vs session-scoped).
+*   **Human-in-the-Loop (HITL) & Resumability:** Locate exactly how the agent pauses and handles user approval gates:
+    *   *Conversational Gate:* The agent stops execution, asks a question in text chat, and waits for a specific confirmation phrase (e.g., "looks good", "run it") to continue.
+    *   *Formal API Gate:* The agent uses the `request_input` tool, calls `tool_context.request_confirmation(hint)`, or utilizes `require_confirmation` on a `FunctionTool`.
+    *   *Resume Protocol:* If a formal gate is used, document how the client resumes the run (e.g., calling `/run_sse` with the corresponding `invocation_id` or `function_call_event_id` and the user's approval input).
+
+### 4. Record your Findings
+*   Add new sections to `AGENT_INTERFACE_NOTES.md` to record what you have learned:
+   4. **API Endpoints and Routes**: List the endpoints exposed by the agent, what URL routes are available and what parameters and uses they have.
+   5. **Payload Schemas**: List the data schemas used to send messages between the agent and client. Make sure to note which are used for requests vs responses. Record the schemas as JSON.
+   6. **State and Artifact Management**: List the state variables and artifacts that the agent uses, and how they are managed.
+   7. **Human-in-the-Loop (HITL) & Resumability**: Detail if and where the agent halts for user input or approval. Explain how the client should handle these gates (e.g., via chat text response or by calling a resume endpoint with specific invocation metadata).