google-agents-cli 1.4.0__tar.gz → 1.4.1__tar.gz

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-agents-cli
-Version: 1.4.0
+Version: 1.4.1
 Summary: Agents CLI — Agent Development Lifecycle toolchain for ADK
 Author-email: Google LLC <agents-cli-dev-pypi@google.com>
 Requires-Python: >=3.11

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "google-agents-cli"
-version = "1.4.0"
+version = "1.4.1"
 description = "Agents CLI — Agent Development Lifecycle toolchain for ADK"
 readme = "README.md"
 license = "Apache-2.0"
@@ -79,7 +79,6 @@ dev = [
     "pytest-rerunfailures>=15.0",
     "pytest-xdist>=3.6.1",
     "pytest-cov>=4.1.0",
-    "pyfakefs>=5.7.0",
 ]
 
 [tool.ruff]
@@ -104,6 +103,7 @@ select = [
     "B",   # flake8-bugbear
     "UP",  # pyupgrade
     "RUF", # ruff specific rules
+    "TID251", # flake8-tidy-imports (banned-api)
     "PLW1514", # unspecified-encoding (require encoding in open calls)
     "PLR0917", # too-many-positional-arguments
 ]
@@ -111,6 +111,10 @@ ignore = ["E501", "C901", "RUF001", "UP036", "RUF067", "RUF069"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["PLR0917"]
+"src/google/agents/cli/_output.py" = ["TID251"]
+
+[tool.ruff.lint.flake8-tidy-imports.banned-api]
+"rich.console.Console" = { msg = "Use `google.agents.cli._output.Console` instead to ensure project-wide defaults (soft_wrap=True) are applied." }
 
 [tool.ruff.lint.pylint]
 max-positional-args = 5

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-adk-code/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli
@@ -50,7 +50,7 @@ def get_weather(city: str) -> dict:
 
 root_agent = Agent(
     name="my_agent",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="You are a helpful assistant that ...",
     tools=[get_weather],
 )

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-adk-code/references/adk-python.md

@@ -44,7 +44,7 @@ def get_weather(city: str) -> dict:
 
 my_agent = Agent(
     name="weather_agent",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="You help users check the weather. Use the get_weather tool.",
     description="Provides weather information.",  # Important for multi-agent delegation
     tools=[get_weather]
@@ -59,7 +59,7 @@ from google.adk.agents import Agent
 
 agent = Agent(
     name="my_agent",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="Your instructions here. Use {state_key} for dynamic injection.",
     description="Description for delegation.",
 
@@ -109,7 +109,7 @@ class Evaluation(BaseModel):
 
 evaluator = Agent(
     name="evaluator",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="Evaluate the input and provide structured feedback.",
     output_schema=Evaluation,
     output_key="evaluation_result",
@@ -147,14 +147,14 @@ from google.adk.agents import SequentialAgent, Agent
 
 summarizer = Agent(
     name="summarizer",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="Summarize the input.",
     output_key="summary"
 )
 
 question_gen = Agent(
     name="question_generator",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="Generate questions based on: {summary}"
 )
 
@@ -240,13 +240,13 @@ For a production LoopAgent with EscalationChecker, BuiltInPlanner, and grounding
 
     researcher = Agent(
         name="researcher",
-        model="gemini-3.6-flash",
+        model="gemini-3.7-flash",
         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-3.6-flash", sub_agents=[researcher])
+    coordinator = Agent(name="coordinator", model="gemini-3.7-flash", 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.
 
@@ -304,7 +304,7 @@ class EscalationChecker(BaseAgent):
 # Vertex AI (prod)
 # Set: GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, GOOGLE_GENAI_USE_VERTEXAI=True
 
-agent = Agent(model="gemini-3.6-flash", ...)
+agent = Agent(model="gemini-3.7-flash", ...)
 ```
 
 ### Other Models via LiteLLM
@@ -323,7 +323,7 @@ agent = Agent(model=LiteLlm(model="ollama_chat/llama3:instruct"), ...)
 from google.adk.models import Gemini
 
 # Vertex AI hosted Gemini (set GOOGLE_GENAI_USE_VERTEXAI=True)
-agent = Agent(model=Gemini(model="gemini-3.6-flash"), ...)
+agent = Agent(model=Gemini(model="gemini-3.7-flash"), ...)
 ```
 
 Provider guides: [Anthropic](https://adk.dev/agents/models/anthropic/index.md), [Ollama](https://adk.dev/agents/models/ollama/index.md), [vLLM](https://adk.dev/agents/models/vllm/index.md), [LiteLLM](https://adk.dev/agents/models/litellm/index.md)
@@ -671,7 +671,7 @@ app = App(
         token_threshold=32000,   # compact once prompt tokens reach this
         event_retention_size=5,  # keep the last 5 raw events un-compacted
         # Optional: custom summarizer model
-        summarizer=LlmEventSummarizer(llm=Gemini(model="gemini-3.6-flash")),
+        summarizer=LlmEventSummarizer(llm=Gemini(model="gemini-3.7-flash")),
     ),
 )
 ```
@@ -805,7 +805,7 @@ manager = A2uiSchemaManager(...)        # loads catalog(s) + few-shot examples
 instruction = manager.generate_system_prompt(...)
 
 # 2. Use it as the agent instruction
-root_agent = Agent(name="ui_agent", model="gemini-3.6-flash", instruction=instruction)
+root_agent = Agent(name="ui_agent", model="gemini-3.7-flash", instruction=instruction)
 
 # 3. Validate the model's JSON output, then wrap as an A2A DataPart
 #    (MIME application/a2ui+json) via a2ui.a2a before streaming to the client.

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-adk-code/references/adk-workflows.md

@@ -192,7 +192,7 @@ class DraftOutput(BaseModel):
 
 writer = LlmAgent(
     name="writer",
-    model="gemini-3.6-flash",
+    model="gemini-3.7-flash",
     instruction="Write a draft based on the user's request.",
     output_schema=DraftOutput,  # Always set for structured output
     output_key="draft",         # Also store in state['draft']

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-deploy/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli
@@ -114,7 +114,7 @@ agents-cli infra single-project
 | `--agent-gateway-ingress` | Bind the agent to an Agent Gateway governing inbound traffic. Full resource name of a gateway with `governedAccessPath=CLIENT_TO_AGENT`. Empty value unbinds; omit to leave unchanged | Agent Runtime |
 | `--memory` | Memory limit (default: `4Gi`) | Agent Runtime, Cloud Run |
 | `--cpu` | CPU limit (default: `1`) | Agent Runtime, Cloud Run |
-| `--min-instances` | Minimum number of instances (default: `1`) | Agent Runtime, Cloud Run |
+| `--min-instances` | Minimum number of instances (default: `0`, i.e. scale to zero; the generated Terraform uses `1`) | Agent Runtime, Cloud Run |
 | `--max-instances` | Maximum number of instances (default: `10`) | Agent Runtime, Cloud Run |
 | `--concurrency` | Concurrent requests per container (default: `8`; see [Sizing a deployment](#sizing-a-deployment)) | Agent Runtime, Cloud Run |
 | `--port` | Container port | Cloud Run, Agent Runtime |
@@ -137,7 +137,9 @@ Run `agents-cli deploy --help` for the full flag reference.
 
 ## Sizing a deployment
 
-Defaults (same on Agent Runtime, Cloud Run, and the generated `service.tf`): `--cpu 1`, `--memory 4Gi`, `--concurrency 8`, `--min-instances 1`, `--max-instances 10`.
+Defaults (same on Agent Runtime and Cloud Run): `--cpu 1`, `--memory 4Gi`, `--concurrency 8`, `--min-instances 0`, `--max-instances 10`. The generated `service.tf` matches, except it pins `min_instances = 1` so production deployments don't experience cold starts.
+
+`agents-cli deploy` scales to zero by default so idle dev and demo agents don't hold capacity. Pass `--min-instances 1` (or deploy via Terraform) when you need a warm instance.
 
 The params are coupled — scale them together:
 

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-eval/SKILL.md

@@ -11,7 +11,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-eval/references/metrics-guide.md

@@ -140,7 +140,7 @@ def evaluate(instance):
         'Return JSON: {"score": <fraction of criteria met>, "explanation": "<what failed>"}'
     )
     out = genai.Client().models.generate_content(
-        model="gemini-3.6-flash",
+        model="gemini-3.7-flash",
         contents=prompt,
         config={"response_mime_type": "application/json"},
     )
@@ -156,7 +156,7 @@ Evaluates responses using an LLM judge driven by a prompt template.
 | `name` | yes | Unique identifier for the metric. |
 | `prompt_template` | yes | Prompt template used by the judge model. With agents-cli's file-based `EvaluationDataset` use `{prompt}`, `{response}`, and `{agent_data}` (the full trajectory). `{reference}` and `{context}` resolve only when the eval case has those fields populated. |
 | `rubric_group_name` | n/a | **Rejected by agents-cli.** It makes the service demand rubric verdicts a custom prompt cannot emit (`400 No rubric verdicts found in LLM response`). Grade `rubric_groups` with a managed metric plus `metric_spec_parameters.rubric_group_key`. |
-| `judge_model` | no | Judge model (e.g., `gemini-3.6-flash`). |
+| `judge_model` | no | Judge model (e.g., `gemini-3.7-flash`). |
 | `judge_model_sampling_count` | no | Number of judge samples to compute the score (1–32). |
 | `judge_model_system_instruction` | no | System instruction for the judge model. |
 | `judge_model_generation_config` | no | Generation config for the judge LLM (e.g., `temperature`). |

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-eval/references/multimodal-eval.md

@@ -71,7 +71,7 @@ custom_metrics:
       Image: {response}
 
       Return JSON: {"score": <0.0-1.0>, "explanation": "<reason>"}
-    judge_model: gemini-3.6-flash
+    judge_model: gemini-3.7-flash
     judge_model_sampling_count: 3
 ```
 
@@ -125,7 +125,7 @@ custom_metrics:
 
       User input: {prompt}
       Agent response: {response}
-    judge_model: gemini-3.6-flash
+    judge_model: gemini-3.7-flash
     judge_model_sampling_count: 3
 ```
 
@@ -136,7 +136,7 @@ Run with `agents-cli eval run --config tests/eval/eval_config.yaml`.
 ## Notes
 
 - **Built-in adaptive metrics (`final_response_quality`, etc.) skip media parts.** They extract only `.text` parts when constructing the judge prompt. Use a custom `LLMMetric` for true multimodal grading.
-- **Choose a vision-capable `judge_model`.** `gemini-3.6-flash` handles images and video; verify capability before relying on it.
+- **Choose a vision-capable `judge_model`.** `gemini-3.7-flash` handles images and video; verify capability before relying on it.
 - **Sampling count** (`judge_model_sampling_count`) of 3–5 reduces variance for multimodal judges, which can be noisier than text-only.
 
 For the full custom-metric field reference, see `references/metrics-guide.md`. For dataset schema and the `inline_data` / `file_data` part types, see `references/dataset_schema.md`.

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-observability/SKILL.md

@@ -13,7 +13,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-publish/SKILL.md

@@ -15,7 +15,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-scaffold/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/skills/google-agents-cli-workflow/SKILL.md

@@ -12,7 +12,7 @@ description: >
 metadata:
   author: Google
   license: Apache-2.0
-  version: 1.4.0
+  version: 1.4.1
   requires:
     bins:
       - agents-cli
@@ -26,8 +26,8 @@ metadata:
 > **Before writing agent code, make sure a scaffolded project exists (see Phase 2).** Skipping scaffolding loses eval boilerplate, CI/CD config, and project conventions.
 
 
-> Requires: google-agents-cli ~= 1.4.0
-> If version is behind, run: uv tool install "google-agents-cli~=1.4.0"
+> Requires: google-agents-cli ~= 1.4.1
+> If version is behind, run: uv tool install "google-agents-cli~=1.4.1"
 
 > Check version: agents-cli info
 > [Install uv](https://docs.astral.sh/uv/getting-started/installation/index.md) first if needed.
@@ -238,7 +238,7 @@ Before finalizing any code replacement, verify the following:
   ```python
   root_agent = Agent(
       name="recipe_suggester",  # OK, related to new purpose
-      model="gemini-3.6-flash",  # PRESERVED
+      model="gemini-3.7-flash",  # PRESERVED
       instruction="You are a recipe suggester."  # OK, the direct target
   )
   ```

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/_click.py

@@ -22,6 +22,8 @@ from typing import Any
 
 import click
 
+from google.agents.cli._experiments import resolve_experiment
+
 
 class LazyGroup(click.Group):
     """Click group that defers importing subcommand modules until needed.
@@ -46,14 +48,45 @@ class LazyGroup(click.Group):
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self._lazy_commands: dict[str, tuple[str, str]] = {}
-
-    def add_lazy_command(self, name: str, import_path: str, short_help: str) -> None:
+        # name -> experiment label
+        self._experiment_gates: dict[str, str] = {}
+
+    def add_lazy_command(
+        self,
+        name: str,
+        import_path: str,
+        short_help: str,
+        experiment: str | None = None,
+    ) -> None:
+        """Register a subcommand for lazy loading.
+
+        If `experiment` is given, the command is only listed and invocable when
+        that experiment resolves truthy; otherwise it behaves as if it were
+        never registered (hidden from --help, "No such command" on invoke).
+
+        The experiment gate is resolved per invocation in `list_commands`/`get_command`,
+        not at this registration call: `main` is built once at import, so
+        guarding registration would freeze visibility before a unit test could
+        override the experiment.
+        """
         self._lazy_commands[name] = (import_path, short_help)
+        if experiment is not None:
+            self._experiment_gates[name] = experiment
+
+    def _is_visible(self, name: str) -> bool:
+        """True if `name` is not hidden via experiment."""
+        label = self._experiment_gates.get(name)
+        if label is None:
+            return True
+        return bool(resolve_experiment(label))
 
     def list_commands(self, ctx: click.Context) -> list[str]:
-        return sorted(set(super().list_commands(ctx)) | set(self._lazy_commands))
+        names = set(super().list_commands(ctx)) | set(self._lazy_commands)
+        return sorted(filter(self._is_visible, names))
 
     def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        if not self._is_visible(cmd_name):
+            return None
         if cmd_name in self._lazy_commands and cmd_name not in self.commands:
             import_path, _ = self._lazy_commands[cmd_name]
             module_path, attr = import_path.split(":")

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/_experiments.py

@@ -25,8 +25,10 @@ class Experiment(NamedTuple):
 
 
 # Central registry of experiments: new experiment flags get added here.
-# No experiments are currently registered.
-_REGISTRY: dict[str, Experiment] = {}
+_REGISTRY: dict[str, Experiment] = {
+    # Hides the `build` command until Go (compiled-language) support launches.
+    "build_command": Experiment("build_command", bool, False),
+}
 
 
 def resolve_experiment(label: str) -> Any:

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/_output.py

@@ -17,6 +17,9 @@
 import json
 import sys
 from enum import IntEnum
+from typing import Any
+
+from rich.console import Console as _RichConsole
 
 
 class ExitCode(IntEnum):
@@ -24,6 +27,14 @@ class ExitCode(IntEnum):
     ERROR = 1
 
 
+class Console(_RichConsole):
+    """Rich Console configured with project-wide defaults (soft_wrap=True)."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        kwargs.setdefault("soft_wrap", True)
+        super().__init__(*args, **kwargs)
+
+
 def emit(data: dict) -> None:
     """Write structured data to stdout."""
     print(json.dumps(data), file=sys.stdout)

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/_skills_check.py

@@ -91,7 +91,7 @@ def _find_installed_skills() -> dict[str, str]:
         from google.agents.cli._runner import run_resolved
 
         proc = run_resolved(
-            ["npx", "-y", "skills", "list", "--json"],
+            ["npx", "-y", SKILLS_NPX_PACKAGE, "list", "--json"],
             capture_output=True,
             text=True,
             encoding="utf-8",

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/_tools.py

@@ -47,7 +47,9 @@ DEFAULT_INSTALL_HINTS = {
     "gh": "Install the GitHub CLI (https://cli.github.com/) and ensure it is in your PATH.",
     "git": "Install Git (https://git-scm.com/downloads) and ensure it is in your PATH.",
     "uv": "Install uv (https://docs.astral.sh/uv/getting-started/installation/) and ensure it is in your PATH.",
-    "uvx": "Install uv (https://docs.astral.sh/uv/getting-started/installation/) and ensure it is in your PATH.",
+    # uvx is shipped by uv, so the install instructions are the same.
+    "uvx": "uvx is part of uv. Install uv (https://docs.astral.sh/uv/getting-started/installation/) and ensure it is in your PATH.",
+    "go": "Install Go (https://go.dev/doc/install) and ensure it is in your PATH.",
 }
 
 
@@ -81,7 +83,7 @@ def _get_cleaned_path() -> str:
     return os.pathsep.join(cleaned_parts)
 
 
-def _is_windows() -> bool:
+def is_windows() -> bool:
     """Returns True if the current operating system is Windows."""
     return os.name == "nt"
 
@@ -93,7 +95,7 @@ def _get_gcloud_fallback() -> str | None:
     typically happens if the user opted not to add gcloud to the PATH during
     installation.
     """
-    if not _is_windows():
+    if not is_windows():
         return None
 
     local_app_data = Path(
@@ -131,7 +133,7 @@ def require_tool(name: str, install_hint: str = "") -> str:
 
     path = shutil.which(name)
 
-    if path is None and _is_windows():
+    if path is None and is_windows():
         path = shutil.which(name, path=_get_cleaned_path())
 
     if path is None:

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/deploy/_utils.py

@@ -25,12 +25,16 @@ if TYPE_CHECKING:
     from google.agents.cli._project import ProjectConfig
 
 # Shared machine-shape defaults for the imperative deploy paths: the deploy
-# command (Cloud Run) and deploy_agent_runtime() both pull from here. The Cloud
-# Run Terraform (service.tf) duplicates these values and must be kept in sync by
-# hand — Terraform can't import them.
+# command (Cloud Run) and deploy_agent_runtime() both pull from here. The
+# generated Terraform (service.tf) duplicates these values and must be kept in
+# sync by hand, since Terraform can't import them.
 DEFAULT_CPU = "1"
 DEFAULT_MEMORY = "4Gi"
-DEFAULT_MIN_INSTANCES = 1
+# Scale to zero by default: `agents-cli deploy` is the iteration path, and idle
+# dev/demo agents holding a warm instance burn regional capacity for nothing.
+# Production deployments go through Terraform, whose service.tf pins
+# min_instances = 1 to avoid cold starts; users can also pass --min-instances.
+DEFAULT_MIN_INSTANCES = 0
 DEFAULT_MAX_INSTANCES = 10
 # Max in-flight requests per container. Conservative on purpose: the worker is
 # I/O-bound (CPU isn't the limit), but peak memory grows with concurrency and is

{google_agents_cli-1.4.0 → google_agents_cli-1.4.1}/src/google/agents/cli/deploy/cmd_deploy.py

@@ -1196,9 +1196,10 @@ def _list_agent_runtime_deployments(project: str | None, location: str) -> None:
         click.echo(f"No Agent Runtime deployments found in {project} ({location}).")
         return
 
-    from rich.console import Console
     from rich.table import Table
 
+    from google.agents.cli._output import Console
+
     table = Table(title=f"Agent Runtime Deployments — {project} ({location})")
     table.add_column("Display Name", style="bold")
     table.add_column("Resource Name", style="dim")
@@ -1250,9 +1251,10 @@ def _list_cloud_run_deployments(project: str | None, region: str | None) -> None
         click.echo(f"No Cloud Run services found{location_label}{project_label}.")
         return
 
-    from rich.console import Console
     from rich.table import Table
 
+    from google.agents.cli._output import Console
+
     title_parts = ["Cloud Run Services"]
     if project:
         title_parts.append(f"— {project}")
@@ -1312,9 +1314,10 @@ def _list_gke_deployments() -> None:
         click.echo("No GKE deployments found in the current cluster.")
         return
 
-    from rich.console import Console
     from rich.table import Table
 
+    from google.agents.cli._output import Console
+
     table = Table(title="GKE Deployments")
     table.add_column("Name", style="bold")
     table.add_column("Ready")

google_agents_cli-1.4.1/src/google/agents/cli/dev/cmd_build.py

@@ -0,0 +1,63 @@
+# 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.
+
+"""agents-cli build command — compile the agent."""
+
+import click
+
+from google.agents.cli._project import chdir_project_root, read_project_config
+from google.agents.cli._runner import run
+from google.agents.cli.scaffold.utils.language import dispatch_language
+
+DEFAULT_OUTPUT = "bin/agent"
+
+
+@click.command("build")
+@click.option(
+    "--output",
+    "-o",
+    default=DEFAULT_OUTPUT,
+    show_default=True,
+    help="Path for the compiled binary.",
+)
+def cmd_build(output: str):
+    """Build the agent binary."""
+    chdir_project_root()
+    handler = dispatch_language(
+        "build", LANGUAGE_HANDLERS, read_project_config().language
+    )
+    handler(output=output)
+
+
+def _build_python(*, output: str) -> None:
+    """Python has no compile step; point the user at install."""
+    click.echo(
+        "Nothing to build: Python projects have no compile step.\n"
+        "  Run `agents-cli install` to sync dependencies."
+    )
+
+
+def _build_go(*, output: str) -> None:
+    """Compile the Go agent to the given output path."""
+    run(["go", "build", "-o", output, "."], check_err_msg="Failed to build agent")
+    click.echo(f"Built binary: {output}")
+
+
+# `None` = not supported yet; dispatch_language raises a clear error.
+LANGUAGE_HANDLERS = {
+    "python": _build_python,
+    "go": _build_go,
+    "java": None,
+    "typescript": None,
+}