release v0.4.0 at 2026-06-10 17:09:22 UTC

Author: eliasecchig

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "google-agents-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold, develop, evaluate, and deploy AI agents with Google ADK. Bundles 7 skills for the agent development lifecycle.",
   "author": { "name": "Google LLC" },
   "homepage": "https://github.com/google/agents-cli",

RELEASE_NOTES.md

@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.4.0] - 2026-06-10
+- Scaffolded Python templates now use **ADK 2.0 GA**. New `adk`, `adk_a2a`, and `agentic_rag` projects pin `google-adk[gcp]>=2.0.0,<3.0.0`; the `[gcp]` extra restores the OpenTelemetry GCP exporters and bundles the BigQuery client, so the separate `[bigquery-analytics]` extra is no longer needed. Cloud SQL sessions on Cloud Run and GKE keep working under 2.0. The bundled ADK coding skill and its reference docs were refreshed for 2.0.
+  - https://github.com/google/agents-cli/issues/24
+- Agent Runtime deploys no longer overwrite a user-supplied `AGENT_VERSION` (or `NUM_WORKERS`) passed via `--update-env-vars`, matching Cloud Run behavior. The "version not found" warning now names the `pyproject.toml` field to set.
+- Fixed a stale `deployment/terraform/dev/` path in the Cloud Trace observability guide so it matches the current `single-project` terraform layout.
+
 ## [0.3.1] - 2026-06-04
 - `eval generate` now works on ADK 2.x projects that use built-in tools such as `VertexAiSearchTool`. Raised the `google-cloud-aiplatform` floor to 1.156.0, which carries the SDK fix.
   - https://github.com/google/agents-cli/issues/27

docs/src/guide/observability/bq-agent-analytics.md

@@ -26,7 +26,6 @@ Compared to the always-on [Cloud Trace telemetry](cloud-trace.md), this plugin p
 ## Prerequisites
 
 *   Agent project generated with an **ADK-based** template (e.g., `adk`, `adk_a2a`, `agentic_rag`).
-*   `google-adk` version `>=1.21.0` (added automatically when you enable the plugin).
 *   A Google Cloud project with BigQuery API and BigQuery Storage API enabled (typically handled by Terraform).
 
 ---
@@ -42,10 +41,7 @@ agents-cli create my-agent \
   --bq-analytics
 ```
 
-This flag:
-
-1.  Includes the plugin initialization code in `app/agent.py` and configures environment variables in Terraform.
-2.  Adds the `google-adk[bigquery-analytics]>=1.21.0` dependency to your project.
+This flag includes the plugin initialization code in `app/agent.py` and configures environment variables in Terraform.
 
 ---
 

docs/src/guide/observability/cloud-trace.md

@@ -63,7 +63,7 @@ agents-cli playground
 
 ## Disable Prompt-Response Logging in Deployments
 
-To disable it in a deployed environment, edit `deployment/terraform/[dev/]service.tf`:
+To disable it in a deployed environment, edit `deployment/terraform/single-project/service.tf`:
 
 ```hcl
 env {
@@ -75,8 +75,8 @@ env {
 Then apply:
 
 ```bash
-cd deployment/terraform
-terraform apply -var-file=vars/dev.tfvars
+cd deployment/terraform/single-project
+terraform apply -var-file=vars/env.tfvars
 ```
 
 ---

docs/src/guide/project-structure.md

@@ -98,7 +98,7 @@ name = "my-agent"
 version = "0.0.1"
 requires-python = ">=3.11"
 dependencies = [
-    "google-adk>=1.15.0,<2.0.0",
+    "google-adk[gcp]>=2.0.0,<3.0.0",
     # ... other dependencies
 ]
 ```

gemini-extension.json

@@ -1,5 +1,5 @@
 {
   "name": "google-agents-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold, develop, evaluate, and deploy AI agents with Google ADK. Bundles 7 skills for the agent development lifecycle."
 }

skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 0.3.1
+  version: 0.4.0
   requires:
     bins:
       - agents-cli
@@ -36,87 +36,33 @@ Do NOT write agent code until a project is scaffolded.
 
 ## Quick Reference — Most Common Patterns
 
-### Agent Creation
-
 ```python
 from google.adk.agents import Agent
 
-root_agent = Agent(
-    name="my_agent",
-    model="gemini-flash-latest",
-    instruction="You are a helpful assistant that ...",
-    tools=[my_tool],
-)
-```
-
-> **NEVER change an existing agent's `model=` value unless the user explicitly asks.** If a Gemini model returns a 404, it's almost always a `GOOGLE_CLOUD_LOCATION` issue — run the listing command to verify availability before changing anything. For model docs, fetch `https://adk.dev/agents/models/google-gemini/index.md`.
-> ```bash
-> uv run --with google-genai python -c "
-> from google import genai
-> client = genai.Client(vertexai=True, location='global')
-> for m in client.models.list(): print(m.name)
-> "
-> ```
-
-### Basic Tool
-
-```python
-from google.adk.tools import FunctionTool
-
 def get_weather(city: str) -> dict:
     """Get current weather for a city."""
     return {"city": city, "temp": "22°C", "condition": "sunny"}
 
-weather_tool = FunctionTool(func=get_weather)
-```
-
-> **ADK built-in tool imports:** Import the tool instance, not the module.
-> ```python
-> from google.adk.tools.load_web_page import load_web_page  # CORRECT
-> from google.adk.tools import load_web_page                 # WRONG
-> ```
-
-### Simple Callback
-
-```python
-from google.adk.agents.callback_context import CallbackContext
-
-async def initialize_state(callback_context: CallbackContext) -> None:
-    state = callback_context.state
-    if "history" not in state:
-        state["history"] = []
-
 root_agent = Agent(
     name="my_agent",
     model="gemini-flash-latest",
-    instruction="...",
-    before_agent_callback=initialize_state,
+    instruction="You are a helpful assistant that ...",
+    tools=[get_weather],
 )
 ```
----
-
-## Reference Files
-
-| File | When to read |
-|------|-------------|
-| `references/adk-python.md` | ADK Python API — agents, tools, callbacks, plugins, state, artifacts, context caching, session rewind |
-| `references/adk-2.0.md` | **ADK 2.0 Workflow API (experimental pre-GA, opt-in)** — graph-based workflows, nodes, edges, HITL, parallel processing |
 
-### ADK 2.0 Workflows — Opt-in
+---
 
-> **The Workflow API is experimental, pre-GA (ADK 2.0).** Do NOT recommend it by default.
->
-> **Before suggesting workflow patterns**, explain the following to the user and ask if they want to proceed:
->
-> 1. **What it is**: ADK 2.0 introduces a graph-based Workflow API — nodes (functions, LLM agents, tools) connected by edges with conditional routing, fan-out/fan-in parallelism, and human-in-the-loop interrupts.
-> 2. **When it helps**: Complex multi-step pipelines needing deterministic control flow, parallel processing of list items, structured approval gates, or retry logic — cases where SequentialAgent/ParallelAgent/LoopAgent feel limiting.
-> 3. **Risks**: Pre-GA — APIs may change before GA. Requires `google-adk >= 2.0.0` and **Python >= 3.11**. Incompatible with Live Streaming. Scaffolded projects need `pyproject.toml` changes before upgrade — see the reference file for step-by-step instructions.
->
-> **Only read `references/adk-2.0.md` after the user explicitly opts in.** If they decline or are unsure, use the standard ADK 1.x orchestration patterns from `references/adk-python.md` (SequentialAgent, ParallelAgent, LoopAgent, BaseAgent).
+## References
 
-## ADK Documentation
+The first two are cheatsheets for common patterns; for broad or deep knowledge, go to the source (docs index or installed package).
 
-For the ADK docs index (titles and URLs for fetching documentation pages), use `curl https://adk.dev/llms.txt`.
+| Reference | When to read |
+|------|-------------|
+| `references/adk-python.md` | Core ADK API: `Agent`, tools, callbacks, plugins, state, artifacts, multi-agent systems, `SequentialAgent` / `ParallelAgent` / `LoopAgent`, custom `BaseAgent`. Default for most agents. |
+| `references/adk-workflows.md` | Graph-based Workflow API (ADK 2.0): nodes, edges, fan-out/fan-in, HITL, parallel processing. Use when you need explicit graph topology. |
+| `curl https://adk.dev/llms.txt` | Docs index (every page title + URL). Fetch it, then `WebFetch` the specific page for anything beyond the cheatsheets. |
+| Installed ADK package | Exact signatures and symbols — inspect the source (see "Inspecting ADK Source Code" in `references/adk-python.md`). |
 
 ## Related Skills
 

skills/google-agents-cli-adk-code/references/adk-python.md

@@ -136,6 +136,8 @@ Rules:
 
 Workflow agents provide deterministic control flow without LLM orchestration.
 
+> These are `BaseAgent`-family composites (`SequentialAgent`, `ParallelAgent`, `LoopAgent`). For the new graph-based Workflow API introduced in ADK 2.0, see `references/adk-workflows.md`.
+
 ### SequentialAgent
 
 Executes sub-agents in order. State changes propagate to subsequent agents.
@@ -229,6 +231,25 @@ For a production LoopAgent with EscalationChecker, BuiltInPlanner, and grounding
     )
     ```
 
+4.  **Task Delegation (ADK 2.0)**: Set `mode` on a sub-agent for structured, schema-typed delegation — the coordinator gets a `request_task_{name}` tool; the sub-agent returns typed output via the auto-injected `finish_task` tool.
+    ```python
+    from pydantic import BaseModel
+
+    class ResearchOutput(BaseModel):
+        summary: str
+
+    researcher = Agent(
+        name="researcher",
+        model="gemini-flash-latest",
+        mode="task",                        # 'chat' (default) | 'task' | 'single_turn'
+        output_schema=ResearchOutput,
+        description="Researches a topic.",  # required for delegation
+        instruction="Research the topic, then call finish_task.",
+    )
+    coordinator = Agent(name="coordinator", model="gemini-flash-latest", sub_agents=[researcher])
+    ```
+    Modes: `task` (multi-turn, structured I/O) · `single_turn` (autonomous, no user turn). Sub-agents need a `description`; default I/O schemas (`goal`/`background` in, `result` out) are used if none set. Disabled inside graph `Workflow`s.
+
 ---
 
 ## 5. Building Custom Agents (`BaseAgent`)
@@ -407,6 +428,23 @@ def needs_approval(amount: float, **kwargs) -> bool:
 transfer_tool = FunctionTool(transfer_money, require_confirmation=needs_approval)
 ```
 
+### Human-in-the-Loop (pause & resume)
+
+Pause a run to ask the user something, then resume. This is a general runtime feature (not workflow-specific). Enable resumption at the app level:
+
+```python
+from google.adk.apps import App, ResumabilityConfig
+
+app = App(name="my_app", root_agent=root_agent,
+          resumability_config=ResumabilityConfig(is_resumable=True))
+```
+
+- **Let the model ask:** add the built-in `request_input` tool (`from google.adk.tools import request_input`) to `tools=` — the model calls it when it needs clarification.
+- **Approval gate inside a tool:** `tool_context.request_confirmation(hint="Approve this transfer?")`, or `FunctionTool(fn, require_confirmation=...)` (above).
+- **Custom long-running tool:** wrap a function with `LongRunningFunctionTool(fn)` to pause until an external result arrives.
+
+The user's reply is read from `ctx.resume_inputs` (available on `ToolContext` and `CallbackContext`). Inside graph workflows the same mechanism is node-based — see `adk-workflows.md` §7.
+
 ### Tool Authentication
 
 | Auth Type | Pattern |
@@ -560,7 +598,7 @@ memory_service = InMemoryMemoryService()
 # Add session to memory after conversation
 await memory_service.add_session_to_memory(session)
 # Search later
-results = await memory_service.search_memory(app_name, user_id, "query")
+results = await memory_service.search_memory(app_name=app_name, user_id=user_id, query="query")
 ```
 
 #### Memory Bank (Long-term Memory)
@@ -612,7 +650,8 @@ app = App(
 Prevent context overflow on long sessions by summarizing older events in a sliding window:
 
 ```python
-from google.adk.apps import App, EventsCompactionConfig
+from google.adk.apps import App
+from google.adk.apps.app import EventsCompactionConfig
 from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
 from google.adk.models import Gemini
 
@@ -650,31 +689,34 @@ app = App(name="my_custom_agent", root_agent=root_agent)
 from google.adk.agents.callback_context import CallbackContext
 from google.adk.models.llm_request import LlmRequest
 from google.adk.models.llm_response import LlmResponse
+from google.adk.tools import BaseTool, ToolContext
 from google.genai import types as genai_types
 
+# Callbacks are invoked by keyword — parameter names must match exactly.
+
 # Agent lifecycle
-async def before_agent_callback(ctx: CallbackContext) -> None:
-    ctx.state["started"] = True
+async def before_agent_callback(callback_context: CallbackContext) -> None:
+    callback_context.state["started"] = True
 
-async def after_agent_callback(ctx: CallbackContext) -> genai_types.Content | None:
+async def after_agent_callback(callback_context: CallbackContext) -> genai_types.Content | None:
     # Return None to continue, or Content to override
     return None
 
 # Model interaction
-async def before_model_callback(ctx: CallbackContext, request: LlmRequest) -> LlmResponse | None:
+async def before_model_callback(callback_context: CallbackContext, llm_request: LlmRequest) -> LlmResponse | None:
     # Return None to continue, or LlmResponse to skip model call
     return None
 
-async def after_model_callback(ctx: CallbackContext, response: LlmResponse) -> LlmResponse | None:
+async def after_model_callback(callback_context: CallbackContext, llm_response: LlmResponse) -> LlmResponse | None:
     # Return None to continue, or modified LlmResponse
     return None
 
 # Tool execution
-async def before_tool_callback(ctx: CallbackContext, tool_name: str, args: dict) -> dict | None:
+async def before_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext) -> dict | None:
     # Return None to continue, or dict to skip tool and use as result
     return None
 
-async def after_tool_callback(ctx: CallbackContext, tool_name: str, result: dict) -> dict | None:
+async def after_tool_callback(tool: BaseTool, args: dict, tool_context: ToolContext, tool_response: dict) -> dict | None:
     # Return None to continue, or modified dict
     return None
 ```
@@ -683,9 +725,9 @@ async def after_tool_callback(ctx: CallbackContext, tool_name: str, result: dict
 
 ```python
 # Initialize state before agent runs
-async def init_state(ctx: CallbackContext) -> None:
-    if "preferences" not in ctx.state:
-        ctx.state["preferences"] = {}
+async def init_state(callback_context: CallbackContext) -> None:
+    if "preferences" not in callback_context.state:
+        callback_context.state["preferences"] = {}
 
 agent = Agent(before_agent_callback=init_state, ...)
 ```
@@ -856,7 +898,7 @@ google/adk/
 ├── tools/            # Tool implementations (FunctionTool, google_search, etc.)
 ├── sessions/         # Session services (InMemory, Database, VertexAI)
 ├── memory/           # Memory services
-├── runners/          # Runner and execution engine
+├── runners.py        # Runner and execution engine
 ├── events/           # Event types and actions
 ├── models/           # Model integrations (Gemini, LiteLLM, etc.)
 ├── code_executors/   # Code execution (BuiltInCodeExecutor, etc.)