Agents CLI 扩展：不改用 ADK，也能走同一套部署和评测

# First-party shorthand, which resolves to the google/agents-cli repository
agents-cli extension add <name>

# Any organization or repository on GitHub, including self-hosted Git servers
agents-cli extension add acme/platform-extensions
agents-cli extension add acme/platform-extensions#soc2-deploy

# A local path, which is typically used during extension development
agents-cli extension add local@../my-extension

Python 3.11 or later
uv package manager
Google Cloud SDK (gcloud)

uvx google-agents-cli setup

gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable aiplatform.googleapis.com run.googleapis.com artifactregistry.googleapis.com

agents-cli create my-agent \
    --agent google/agents-cli/extensions/langchain/template@v1.8.0 \
    -d cloud_run

cd my-agent && agents-cli install

Agents CLI v1.8.0
Fetching remote template: google/agents-cli/extensions/langchain/template@v1.8.0
> Verifying GCP credentials...
> ✓ Connected to project: your-project
✅ Success! Your agent project is ready.

my-agent/
├── agents-cli-extension.yaml      # auto-loaded project-scope overrides
├── agents-cli-manifest.yaml       # project configuration (deployment target, etc.)
├── GEMINI.md                      # project's coding-agent guide
├── langgraph.json                 # LangGraph dev-server configuration
├── pyproject.toml                 # langchain, langgraph, langchain-google-genai
├── Dockerfile                     # identical CMD to any ADK project
├── app/
│   ├── agent.py                   # exports root_agent: CompiledStateGraph
│   ├── fast_api_app.py            # exposes `app: FastAPI` on A2A
│   └── app_utils/
│       ├── a2a.py                 # LangGraphAgentExecutor and A2A routes
│       └── telemetry.py           # Cloud Trace and GenAI logging
├── scripts/
│   ├── run.py                     # drop-in replacement for `agents-cli run`
│   ├── eval_generate.py           # drop-in replacement for `agents-cli eval generate`
│   └── publish.py                 # Agent-Runtime-aware refusal wrapper
├── tests/
│   └── eval/datasets/basic-dataset.json
├── deployment/                    # Terraform infrastructure modules
├── uv.lock
└── .agents/skills/agents-cli-langchain/   # the project's own coding-agent skill

"""LangChain agent: a Gemini ReAct agent with a sample tool."""

import os
from dotenv import load_dotenv
from langchain.agents import create_agent
from langchain_google_genai import ChatGoogleGenerativeAI
from langgraph.graph.state import CompiledStateGraph

load_dotenv()

if not (os.environ.get("GOOGLE_API_KEY") or os.environ.get("GEMINI_API_KEY")):
    import google.auth
    _, project_id = google.auth.default()
    os.environ["GOOGLE_CLOUD_PROJECT"] = project_id
    os.environ["GOOGLE_CLOUD_LOCATION"] = "global"
    os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"

LLM = "gemini-3.8-flash"
llm = ChatGoogleGenerativeAI(model=LLM, temperature=0)


def get_weather(query: str) -> str:
    """Simulates a web search. Use it get information on weather."""
    if "sf" in query.lower() or "san francisco" in query.lower():
        return "It's 60 degrees and foggy."
    return "It's 90 degrees and sunny."


root_agent: CompiledStateGraph = create_agent(
    model=llm, tools=[get_weather], system_prompt="You are a helpful assistant"
)

$ grep -r "google.adk\|google-adk" pyproject.toml app/
$ echo "exit: $?"
exit: 1

agents-cli run "what's the weather in San Francisco?"

WARNING:root:agents-cli: applying 6 extension command(s): eval.dataset [langchain/project], eval.generate [langchain/project], eval.optimize [langchain/project], playground [langchain/project], publish.gemini-enterprise [langchain/project], run [langchain/project]
The weather in San Francisco is currently 60°F and foggy.

$ agents-cli --help | grep -E "playground|run "
  playground      Start the local LangGraph dev server.  [↑ langchain]
  run             Run the compiled agent graph with a single prompt.  [↑ langchain]

Extensions (experimental):
  eval.dataset  (override, project) <- langchain: uv run python scripts/unsupported.py eval dataset
  eval.generate  (override, project) <- langchain: uv run python scripts/eval_generate.py
  eval.optimize  (override, project) <- langchain: uv run python scripts/unsupported.py eval optimize
  playground  (override, project) <- langchain: uv run langgraph dev --no-browser --port 8080
  publish.gemini-enterprise  (override, project) <- langchain: uv run --with pyyaml python scripts/publish.py
  run  (override, project) <- langchain: uv run python scripts/run.py

agents-cli deploy

CMD ["uv", "run", "uvicorn", "app.fast_api_app:app", "--host", "0.0.0.0", "--port", "8080"]

agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json \
    -o tests/eval/output/
agents-cli eval grade --traces tests/eval/output/basic-dataset.json \
    --config tests/eval/eval_config.yaml
agents-cli eval compare tests/eval/output/run_1.json tests/eval/output/run_2.json

$ agents-cli eval dataset synthesize
agents-cli eval dataset is not supported by the langchain extension:
it runs the agent through ADK's user simulator, which needs google-adk
in this project's venv.

# agents-cli-extension.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/google/agents-cli/main/schemas/agents-cli-extension-v1alpha1.schema.json

schema: agents-cli-extension/v1alpha1
name: sbom-deploy
description: Scan the project SBOM, then run the native agents-cli deploy.
requires:
  agents_cli: ">=1.5,<2"
  on_incompatible: warn

commands:
  override:
    deploy:
      run: ["bash", "scripts/sbom_then_deploy.sh"]
      description: SBOM scan via syft+grype, then the built-in deploy.
  add:
    sbom-report:
      run: ["bash", "scripts/sbom_report.sh"]
      description: Produce an SBOM for the current project (no deploy).

#!/usr/bin/env bash
# scripts/sbom_then_deploy.sh
set -euo pipefail
cd "$(dirname "$0")/.."

echo "[sbom-deploy] generating SBOM..."
syft dir:. -o cyclonedx-json > /tmp/sbom.cdx.json

echo "[sbom-deploy] scanning for criticals..."
grype sbom:/tmp/sbom.cdx.json --fail-on critical

# AGENTS_CLI_DISABLE_OVERRIDES=1 is already set by the loader,
# so this call hits the built-in deploy. No infinite recursion.
echo "[sbom-deploy] SBOM clean; running native deploy..."
exec agents-cli deploy "$@"

$ agents-cli deploy --project foo
[sbom-deploy] (demo) would scan SBOM here...
[sbom-deploy] AGENTS_CLI_DISABLE_OVERRIDES=1
[sbom-deploy] would then shell to: agents-cli deploy --project foo

agents-cli extension add local@../my-sbom-extension

agents-cli extension add acme/platform-extensions#sbom-deploy --ref v1.0.0

$ agents-cli extension list
Extensions:
  langchain    project  (commands: eval.dataset, eval.generate, eval.optimize, playground, publish.gemini-enterprise, run)
  sbom-deploy  project  (commands: deploy, sbom-report)  requires: >=1.5,<2

$ agents-cli --help | grep -A1 -E "deploy|sbom-report"
  deploy          SBOM scan via syft+grype, then the built-in deploy.  [↑
                  sbom-deploy]
  sbom-report     Produce an SBOM for the current project (no deploy).  [↑
                  sbom-deploy]

$ agents-cli deploy --help
Usage: agents-cli deploy [OPTIONS] [EXTRA_ARGS]...

  Overrides `deploy` via extension 'sbom-deploy' (project scope).

  SBOM scan via syft+grype, then the built-in deploy.

  Runs: bash scripts/sbom_then_deploy.sh

  Argv after the command name passes through to the script verbatim.

  To bypass extension overrides and run the built-in:
  AGENTS_CLI_DISABLE_OVERRIDES=1 agents-cli deploy

# agents-cli-extensions.yaml  (lockfile; commit this to version control)
extensions:
- name: sbom-deploy
  source: acme/platform-extensions#sbom-deploy
  ref: v1.0.0
  sha: a1b2c3d4...
  scope: project

uvx google-agents-cli setup
agents-cli create my-agent --agent google/agents-cli/extensions/langchain/template@v1.8.0 -d cloud_run