google-agents-cli 1.5.0__tar.gz → 1.6.1__tar.gz

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.5.0
+Version: 1.6.1
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11
@@ -20,6 +20,7 @@ Requires-Dist: pyopenssl<26.2
 Requires-Dist: rich>=13.7.0
 Requires-Dist: backoff>=2.2.1
 Requires-Dist: requests>=2.31.0
+Requires-Dist: websockets>=13.0
 Requires-Dist: a2a-sdk>=1.0,<2
 Requires-Dist: protobuf>=5.29.5,<7
 Requires-Dist: tomlkit>=0.13.0,<1

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.5.0"
+version = "1.6.1"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -25,6 +25,7 @@ dependencies = [
   "rich>=13.7.0",
   "backoff>=2.2.1",
   "requests>=2.31.0",
+  "websockets>=13.0",
   "a2a-sdk>=1.0,<2",
   # Pin the a2a-sdk (>=5.29.5) .. aiplatform (<7) window so pip won't chase
   # protobuf 7 and backtrack into old google-api-core (protobuf<5).

google_agents_cli-1.6.1/src/google/agents/cli/_adk_client.py

@@ -0,0 +1,382 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared ADK FastAPI client: session create + ``/run_sse`` and ``/run_live``."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import (
+    AsyncGenerator,
+    Iterable,
+    Iterator,
+)
+from typing import NamedTuple
+from urllib.parse import urlencode
+
+import requests
+
+_SESSION_TIMEOUT = 30
+_RUN_SSE_TIMEOUT = 120
+_APP_INFO_TIMEOUT = 10
+
+DEFAULT_WS_PATH = "/run_live"
+DEFAULT_TURN_TIMEOUT = 120  # seconds to wait for a turn's turnComplete
+
+# /run_live transcribes it back to text, so output stays gradable.
+DEFAULT_MODALITIES = ("AUDIO",)
+
+
+def create_session(
+    base_url: str,
+    app_name: str,
+    user_id: str,
+    *,
+    headers: dict,
+    prior_events: list[dict] | None = None,
+) -> str:
+    """Create an ADK session and return its ID.
+
+    When ``prior_events`` are supplied, the ADK server seeds the fresh
+    session with them.
+    """
+    session_url = f"{base_url}/apps/{app_name}/users/{user_id}/sessions"
+    body: dict = {}
+    if prior_events:
+        body["events"] = prior_events
+
+    resp = requests.post(
+        session_url, headers=headers, json=body, timeout=_SESSION_TIMEOUT
+    )
+    resp.raise_for_status()
+    return resp.json().get("id")
+
+
+def fetch_app_info(
+    *,
+    base_url: str,
+    app_name: str,
+    headers: dict,
+) -> tuple[str | None, dict]:
+    """Fetch agent metadata from ADK's /apps/{app_name}/app-info endpoint.
+
+    Returns (root_agent_name, agents), where agents is the raw ADK agents
+    map keyed by agent id. root_agent_name may be None if the server omits
+    it; agents may be empty.
+
+    Raises requests.RequestException (or a subclass: ConnectionError,
+    HTTPError, JSONDecodeError) if the endpoint isn't reachable, returns a
+    non-2xx status, or returns a body that isn't valid JSON.
+    """
+    url = f"{base_url}/apps/{app_name}/app-info"
+    resp = requests.get(url, headers=headers, timeout=_APP_INFO_TIMEOUT)
+    resp.raise_for_status()
+    payload = resp.json()
+    # Accept both camelCase and snake_case for cross language compatibility
+    root_agent_name = payload.get("rootAgentName", payload.get("root_agent_name"))
+    agents = payload.get("agents") or {}
+    return root_agent_name, agents
+
+
+def run_sse(
+    base_url: str,
+    app_name: str,
+    session_id: str,
+    *,
+    user_message: dict,
+    headers: dict,
+    user_id: str,
+) -> Iterator[dict]:
+    """Stream ADK events for a single user turn.
+
+    Yields each ``data:`` line's decoded JSON dict as it arrives. Blank
+    lines, non-``data:`` lines, and payloads that fail to JSON-decode are
+    silently skipped.
+    """
+    run_url = f"{base_url}/run_sse"
+    payload = {
+        "appName": app_name,
+        "userId": user_id,
+        "sessionId": session_id,
+        "newMessage": user_message,
+    }
+
+    with requests.post(
+        run_url, headers=headers, json=payload, stream=True, timeout=_RUN_SSE_TIMEOUT
+    ) as resp:
+        resp.raise_for_status()
+        # Honor the server's explicit charset if provided; otherwise,
+        # fall back to UTF-8 rather than latin-1.
+        if "charset" not in resp.headers.get("Content-Type", "").lower():
+            resp.encoding = "utf-8"
+        for line in resp.iter_lines(decode_unicode=True):
+            if not isinstance(line, str) or not line.startswith("data: "):
+                continue
+            data_str = line[len("data: ") :]
+            try:
+                yield json.loads(data_str)
+            except json.JSONDecodeError:
+                continue
+
+
+def _event_parts(event: dict) -> list:
+    """Return event's content parts, or an empty list when it carries none."""
+    content = event.get("content")
+    if not isinstance(content, dict):
+        return []
+    parts = content.get("parts")
+    return parts if isinstance(parts, list) else []
+
+
+def _event_has_function_call(event: dict) -> bool:
+    """Return True if event carries a model function call."""
+    return any(
+        isinstance(part, dict) and part.get("functionCall")
+        for part in _event_parts(event)
+    )
+
+
+def _event_has_function_response(event: dict) -> bool:
+    """Return True if event carries a tool's function response."""
+    return any(
+        isinstance(part, dict) and part.get("functionResponse")
+        for part in _event_parts(event)
+    )
+
+
+def _event_has_answer_content(event: dict) -> bool:
+    """Return true if event carries gradable model answer content."""
+    transcription = event.get("outputTranscription")
+    if isinstance(transcription, dict) and transcription.get("text"):
+        return True
+    return any(
+        isinstance(part, dict) and (part.get("text") or part.get("inlineData"))
+        for part in _event_parts(event)
+    )
+
+
+class FinishedTranscript(NamedTuple):
+    """A completed Live transcription frame."""
+
+    # "user" for input transcription, else the event's author (or "model").
+    author: str
+    # "user" or "model" -- the genai Content role for the rendered text.
+    role: str
+    text: str
+
+
+# Live transcription keys mapped to the Content role they represent.
+_TRANSCRIPTION_KEYS = (
+    ("inputTranscription", "user"),
+    ("outputTranscription", "model"),
+)
+
+
+def finished_transcript(event: dict) -> FinishedTranscript | None:
+    """Return the finished transcript carried by event, else None"""
+    for key, role in _TRANSCRIPTION_KEYS:
+        transcription = event.get(key)
+        if not isinstance(transcription, dict):
+            continue
+        if not transcription.get("finished"):
+            return None  # partial chunk; the finished aggregate carries the text
+        text = transcription.get("text")
+        if not text:
+            return None
+        author = "user" if role == "user" else (event.get("author") or "model")
+        return FinishedTranscript(author=author, role=role, text=text)
+    return None
+
+
+def is_transcription_event(event: dict) -> bool:
+    """True if event is a Live transcription frame (finished or partial)."""
+    # An empty transcription is still a transcription frame, not a malformed one.
+    return any(key in event for key, _ in _TRANSCRIPTION_KEYS)
+
+
+def stream_live_events(
+    ws_base: str,
+    app_name: str,
+    session_id: str,
+    *,
+    user_turns: Iterable[dict],
+    headers: dict,
+    user_id: str,
+) -> Iterator[dict | None]:
+    """Stream ADK events for a Live conversation over one /run_live socket."""
+    return _iter_async(
+        _stream_live_events(
+            ws_base,
+            app_name,
+            session_id,
+            user_turns=user_turns,
+            headers=headers,
+            user_id=user_id,
+        )
+    )
+
+
+def group_turns(stream: Iterable[dict | None]) -> Iterator[list[dict]]:
+    """Batch a stream_live_events stream into one event list per turn."""
+    events: list[dict] = []
+    for item in stream:
+        if item is None:
+            yield events
+            events = []
+        else:
+            events.append(item)
+
+
+def build_run_live_url(
+    ws_base: str,
+    app_name: str,
+    session_id: str,
+    *,
+    user_id: str,
+) -> str:
+    """Build the ADK /run_live WebSocket URL from a ws-base."""
+    base = ws_base.rstrip("/")
+    query = [
+        ("app_name", app_name),
+        ("user_id", user_id),
+        ("session_id", session_id),
+    ]
+    query.extend(("modalities", m) for m in DEFAULT_MODALITIES)
+    return f"{base}{DEFAULT_WS_PATH}?{urlencode(query)}"
+
+
+async def _stream_live_events(
+    ws_base: str,
+    app_name: str,
+    session_id: str,
+    *,
+    user_turns: Iterable[dict],
+    headers: dict,
+    user_id: str,
+) -> AsyncGenerator[dict | None, None]:
+    """Play user_turns over one socket, yielding each event as it arrives."""
+    from websockets.asyncio.client import connect as ws_connect
+    from websockets.exceptions import ConnectionClosed, ConnectionClosedOK
+
+    ws_url = build_run_live_url(ws_base, app_name, session_id, user_id=user_id)
+    user_turns = list(user_turns)
+    expected_turns = len(user_turns)
+    extra_headers = {
+        k: v for k, v in (headers or {}).items() if k.lower() != "content-type"
+    }
+
+    async with ws_connect(ws_url, additional_headers=extra_headers or None) as ws:
+        try:
+            for turn_index, content in enumerate(user_turns):
+                # One `content` frame per turn; ADK validates each frame.
+                await ws.send(json.dumps({"content": content}))
+
+                boundary = _TurnBoundary()
+                while True:
+                    try:
+                        raw = await asyncio.wait_for(
+                            ws.recv(), timeout=DEFAULT_TURN_TIMEOUT
+                        )
+                    except TimeoutError:
+                        logging.warning(
+                            "Turn %d: no event for %ds, giving up on the turn.",
+                            turn_index,
+                            DEFAULT_TURN_TIMEOUT,
+                        )
+                        break
+                    except ConnectionClosedOK:
+                        if turn_index + 1 < expected_turns:
+                            logging.warning(
+                                "Turn %d: the agent closed the stream; "
+                                "%d later turn(s) were never sent.",
+                                turn_index,
+                                expected_turns - turn_index - 1,
+                            )
+                        yield None  # end of turn
+                        return
+
+                    event = _decode_ws_frame(raw)
+                    if event is None:
+                        continue
+                    yield event
+                    if boundary.is_terminal(event):
+                        break
+
+                yield None  # end of turn
+        finally:
+            try:
+                await ws.send(json.dumps({"close": True}))
+            except ConnectionClosed:
+                pass
+
+
+class _TurnBoundary:
+    """Detect the terminal turnComplete of one logical live turn."""
+
+    def __init__(self) -> None:
+        self._tool_call_open = False
+        self._tool_response_seen = False
+
+    def is_terminal(self, event: dict) -> bool:
+        """Feed one event; return True if it ends the current logical turn."""
+        if _event_has_function_call(event):
+            # Anything spoken before the call is not the post-tool answer.
+            self._tool_call_open = True
+            self._tool_response_seen = False
+        elif _event_has_function_response(event):
+            if self._tool_call_open:
+                self._tool_response_seen = True
+        elif _event_has_answer_content(event):
+            self._tool_call_open = False
+            self._tool_response_seen = False
+
+        if event.get("turnComplete"):
+            if self._tool_call_open and self._tool_response_seen:
+                # Terminator for the tool round-trip; keep reading for the answer.
+                self._tool_call_open = False
+                self._tool_response_seen = False
+                return False
+            return True
+        return False
+
+
+def _decode_ws_frame(raw) -> dict | None:
+    """Decode a /run_live frame into an ADK event dict, or None for audio."""
+    if isinstance(raw, (bytes, bytearray)):
+        try:
+            return json.loads(bytes(raw).decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+def _iter_async(agen) -> Iterator:
+    """Drive an async generator from sync code on a dedicated event loop."""
+    loop = asyncio.new_event_loop()
+    try:
+        while True:
+            try:
+                yield loop.run_until_complete(agen.__anext__())
+            except StopAsyncIteration:
+                break
+    finally:
+        loop.run_until_complete(agen.aclose())
+        # Finalize websockets' own async generators before closing the loop.
+        loop.run_until_complete(loop.shutdown_asyncgens())
+        loop.close()

google_agents_cli-1.6.1/src/google/agents/cli/_defaults.py

@@ -0,0 +1,22 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Defaults shared by the CLI and the projects it scaffolds."""
+
+from __future__ import annotations
+
+# Reaches the templates as the ``default_model`` cookiecutter variable. Nothing
+# renders the skills, docs, eval goldens or extension templates, so their copies
+# of the model id are updated by hand alongside this one.
+DEFAULT_MODEL = "gemini-3.8-flash"

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/src/google/agents/cli/_experiments.py

@@ -27,7 +27,7 @@ class Experiment(NamedTuple):
 # Central registry of experiments: new experiment flags get added here.
 _REGISTRY: dict[str, Experiment] = {
     # Hides the `build` command until Go (compiled-language) support launches.
-    "build_command": Experiment("build_command", bool, False),
+    "build_command": Experiment("build_command", bool, True),
 }
 
 

google_agents_cli-1.6.1/src/google/agents/cli/_modes.py

@@ -0,0 +1,31 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Protocol values shared by every command that talks to an agent."""
+
+# A2A protocol.
+MODE_A2A = "a2a"
+# ADK over HTTP: POST /run_sse, or :streamQuery on Agent Runtime.
+MODE_ADK = "adk"
+# ADK over a bidi WebSocket: /run_live, the transport Live (voice) agents use.
+MODE_ADK_LIVE = "adk_live"
+
+# What each command accepts. Build every click.Choice and every "choose from"
+# message from these, so adding a mode is one edit per set rather than one per
+# call site.
+RUN_MODES = (MODE_A2A, MODE_ADK, MODE_ADK_LIVE)
+# A local server serves ADK only, so a2a needs a --url.
+LOCAL_RUN_MODES = (MODE_ADK, MODE_ADK_LIVE)
+# eval speaks ADK only.
+EVAL_MODES = (MODE_ADK, MODE_ADK_LIVE)

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/src/google/agents/cli/_project.py

@@ -45,6 +45,9 @@ class ProjectConfig:
     cicd_runner: str = "skip"
     agent_gateway: bool = False
     agent_guidance_filename: str = "GEMINI.md"
+    # The ADK name of the root agent. Empty means "derive it from the project
+    # name"; see resolve_root_agent_name.
+    root_agent_name: str = ""
 
     @property
     def create_params(self) -> dict[str, Any]:
@@ -55,6 +58,7 @@ class ProjectConfig:
             "cicd_runner": self.cicd_runner,
             "agent_gateway": self.agent_gateway,
             "agent_guidance_filename": self.agent_guidance_filename,
+            "root_agent_name": self.root_agent_name,
         }
 
     @classmethod
@@ -93,6 +97,7 @@ class ProjectConfig:
         )
         cfg.is_a2a = create_params.get("is_a2a", cfg.is_a2a)
         cfg.agent_gateway = create_params.get("agent_gateway", cfg.agent_gateway)
+        cfg.root_agent_name = create_params.get("root_agent_name") or ""
 
         return cfg
 
@@ -108,10 +113,12 @@ def _warn_legacy_config() -> None:
             "\n⚠️  Legacy configuration detected in pyproject.toml.",
             fg="yellow",
             bold=True,
+            err=True,
         )
         click.secho(
             "   Run `agents-cli scaffold upgrade` to migrate to agents-cli-manifest.yaml.\n",
             fg="yellow",
+            err=True,
         )
         _WARNED_LEGACY_CONFIG = True
 
@@ -216,13 +223,15 @@ def check_cli_version(cfg: ProjectConfig) -> None:
         click.echo(
             f"\n⚠️  Version mismatch: project was scaffolded with agents-cli {acli_version},"
             f" running {__version__}.\n"
-            f"   Upgrade the CLI: uv tool install google-agents-cli@{acli_version}\n"
+            f"   Upgrade the CLI: uv tool install google-agents-cli@{acli_version}\n",
+            err=True,
         )
     elif cli_ver > project_ver:
         click.echo(
             f"\n⚠️  Version mismatch: project was scaffolded with agents-cli {acli_version},"
             f" running {__version__}.\n"
-            "   Upgrade the project: agents-cli scaffold upgrade\n"
+            "   Upgrade the project: agents-cli scaffold upgrade\n",
+            err=True,
         )
 
 
@@ -309,7 +318,7 @@ def chdir_project_root(dir: Path | None = None) -> None:
         )
     # Only announce the root when we actually move (i.e. run from a subdir).
     if root.resolve() != Path.cwd().resolve():
-        click.echo(f"Using project root directory: {root}")
+        click.echo(f"Using project root directory: {root}", err=True)
     os.chdir(root)
 
 
@@ -383,3 +392,15 @@ def root_agent_name(project_name: str) -> str:
         return "root_agent"
     # A leading digit is legal in a project name but not in an identifier.
     return f"agent_{candidate}" if candidate[0].isdigit() else candidate
+
+
+def resolve_root_agent_name(cfg: ProjectConfig) -> str:
+    """The project's root agent name: recorded in the manifest, else derived.
+
+    The recorded value wins so that renaming the agent in code stays
+    expressible. Derivation alone can only produce names that follow from the
+    project name, so a project called ``it-support-agent`` whose agent is
+    ``billing_bot`` has no way to say so -- and nothing reports the mismatch,
+    because a telemetry query filtered on the wrong name simply returns no rows.
+    """
+    return cfg.root_agent_name or root_agent_name(cfg.project_name)

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/src/google/agents/cli/_remote.py

@@ -21,7 +21,8 @@ how a ``--url`` is classified and what auth token it gets.
 from __future__ import annotations
 
 import re
-from urllib.parse import urlparse
+from typing import NamedTuple
+from urllib.parse import urlparse, urlsplit, urlunsplit
 
 import click
 
@@ -32,6 +33,10 @@ _REASONING_ENGINE_PATH = "reasoningEngines"
 # A valid Agent Runtime host carries a location prefix: <location>-aiplatform.googleapis.com
 _AGENT_RUNTIME_HOST_RE = re.compile(rf".+-{re.escape(_AGENT_ENGINE_URL_FRAGMENT)}$")
 
+# WebSocket traffic has its own ingress; HTTP goes through reasoningEngines/v1.
+# https://github.com/GoogleCloudPlatform/generative-ai/blob/main/agents/agent_engine/tutorial_bidi_stream_v2.ipynb
+_AGENT_RUNTIME_WS_INGRESS = "reasoningEngines/ws/internal"
+
 
 def is_agent_runtime_url(url: str) -> bool:
     """Return ``True`` if *url* points to an Agent Runtime endpoint."""
@@ -79,6 +84,41 @@ def build_agent_runtime_passthrough_url(location: str, runtime_resource: str) ->
     )
 
 
+class AgentEndpoints(NamedTuple):
+    """HTTP and WebSocket base URLs for one remote agent."""
+
+    http_base: str
+    ws_base: str
+
+
+def http_to_ws_url(base_url: str) -> str:
+    """Normalize a URL's scheme to ws/wss"""
+    parts = urlsplit(base_url)
+    scheme = {"http": "ws", "https": "wss"}.get(parts.scheme, parts.scheme)
+    return urlunsplit(parts._replace(scheme=scheme))
+
+
+def build_agent_runtime_endpoints(location: str, runtime_resource: str) -> AgentEndpoints:
+    """Build Agent Runtime ingress base URLs for a deployed engine."""
+    host = f"{location}-{_AGENT_ENGINE_URL_FRAGMENT}"
+    resource = runtime_resource.strip("/")
+    return AgentEndpoints(
+        http_base=build_agent_runtime_passthrough_url(location, resource),
+        ws_base=f"wss://{host}/{_AGENT_RUNTIME_WS_INGRESS}/{resource}/api",
+    )
+
+
+def resolve_agent_endpoints(url: str) -> AgentEndpoints:
+    """Resolve the HTTP and WebSocket base URLs for a remote agent."""
+    http_url = url.rstrip("/")
+    if not is_agent_runtime_url(http_url):
+        return AgentEndpoints(http_base=http_url, ws_base=http_to_ws_url(http_url))
+
+    validate_agent_runtime_url(http_url)
+    location, resource = parse_agent_runtime_service_url(http_url)
+    return build_agent_runtime_endpoints(location, resource.removesuffix("/api"))
+
+
 def parse_agent_runtime_service_url(service_url: str) -> tuple[str, str]:
     """Split an Agent Runtime service URL into (location, runtime_resource).
 

{google_agents_cli-1.5.0 → google_agents_cli-1.6.1}/src/google/agents/cli/_skills_check.py

@@ -218,5 +218,6 @@ def check_skills_version() -> None:
         f"\n⚠️  Skills version mismatch — CLI is v{__version__}, "
         f"but {len(mismatched)} skill(s) differ:\n"
         + "\n".join(lines)
-        + "\n   Run 'agents-cli update' to sync.\n"
+        + "\n   Run 'agents-cli update' to sync.\n",
+        err=True,
     )