mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
eliasecchig
979a8fa9db
* Add Agents CLI quickstart to Get Started Agents CLI is currently explained only under Deploy > Agent Runtime and in the Coding with AI tutorial, so readers reach it either not at all or with the impression that it only configures AI coding assistants. Add a quickstart alongside the language quickstarts, and a card on the Get Started index so the choice is made up front. * Rework the quickstart around the coding agent path Lead with the coding agent as the intended way to use Agents CLI, add the lifecycle diagram and the seven skills, and say the CLI has more than 25 commands so the skills do not read as the whole product. Name the real Phase 0 questions (tools, inputs and outputs, success criteria) and close the loop in Next steps, where evaluation grades against those criteria. Drop the manual command section in favour of the upstream manual workflow tutorial, drop the playground production warning, and use Antigravity rather than Antigravity CLI to match the rest of the docs. * Address review feedback on Agents CLI quickstart - Tighten intro to 3-4 sentences; drop the coding-agent-path paragraph, the "optional / ordinary ADK agents" paragraph, and the seven-skills table (kept the lifecycle diagram) - Installation: state clearly that setup also installs the ADK Python packages, not just the CLI - Authenticate: swap the default to the Gemini API key path; move Google Cloud into a linked note pointing to the Google Cloud setup guide - Build your agent: replace prose in each tab with a command block containing verification steps as comments; move "Any other agent" out of the tabs into a note; "tell it" -> "tell the coding agent" - Add explanatory sentence before the scaffold command block clarifying that the coding agent runs the commands (and the reader can too) - Get Started index: drop the language-quickstarts-vs-Agents-CLI framing paragraph (unlikely to be read in that position) * Update agents-cli.md * Update agents-cli.md * Delete docs/assets/agents-cli-lifecycle.png --------- Co-authored-by: pierpaolo28 <pierpaolo28@users.noreply.github.com> Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
186 lines
6.4 KiB
Markdown
186 lines
6.4 KiB
Markdown
# Agents CLI Quickstart for ADK
|
|
|
|
This guide shows you how to get up and running with Agent Development Kit (ADK) using
|
|
Agents CLI. You can use the Agents CLI tool set with coding agents like Antigravity,
|
|
Claude Code, and Codex to build, evaluate, and deploy ADK agents. For more information,
|
|
see the [Agents CLI](https://google.github.io/agents-cli/) documentation.
|
|
Before you start, make sure you have the following installed:
|
|
|
|
* Python 3.11 or later: Agents CLI supports ADK agents in Python
|
|
* The [`uv`](https://docs.astral.sh/uv/getting-started/installation/) tool
|
|
to manage environments and dependencies
|
|
* [Node.js](https://nodejs.org/en/download), for installing the skills
|
|
* Coding agent such as [Antigravity](https://antigravity.google/),
|
|
[Claude Code](https://docs.anthropic.com/en/docs/claude-code), or
|
|
[Codex](https://github.com/openai/codex)
|
|
|
|
If you want to deploy ADK agents to services like Google Cloud, make sure
|
|
the following tools are also installed:
|
|
|
|
* [Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
|
|
* [Terraform](https://developer.hashicorp.com/terraform/downloads)
|
|
|
|
|
|
## Installation
|
|
|
|
Install Agents CLI by running the following command. This step installs the
|
|
`agents-cli` command, the ADK Python packages, and the ADK skills into any
|
|
coding agents already on your machine:
|
|
|
|
```shell
|
|
uvx google-agents-cli setup
|
|
```
|
|
|
|
??? tip "Alternative installation methods"
|
|
|
|
**pipx:**
|
|
|
|
```shell
|
|
pipx install google-agents-cli && agents-cli setup
|
|
```
|
|
|
|
**pip:**
|
|
|
|
```shell
|
|
pip install google-agents-cli && agents-cli setup
|
|
```
|
|
|
|
**Skills only:**
|
|
|
|
```shell
|
|
npx skills add google/agents-cli
|
|
```
|
|
|
|
The installation command is the only one you have to run yourself. Once
|
|
installed, you can use your coding agent to build and run an ADK agent.
|
|
|
|
## Authenticate
|
|
|
|
Agents CLI needs credentials for a generative AI API to run your agents. The
|
|
simplest option is a Gemini API key from Google AI Studio. Create a key on the
|
|
[API Keys](https://aistudio.google.com/app/apikey) page, then after you
|
|
scaffold a project in the next step, open its `.env` file and set:
|
|
|
|
```env title="Update: .env"
|
|
GEMINI_API_KEY=YOUR_API_KEY
|
|
```
|
|
|
|
Comment out the three `GOOGLE_CLOUD_*` lines in the same file so the SDK uses
|
|
your key instead of Vertex AI.
|
|
|
|
??? note "Using Google Cloud Agent Platform instead"
|
|
|
|
If you already have a Google Cloud project, Agents CLI picks up your
|
|
Application Default Credentials:
|
|
|
|
```shell
|
|
gcloud auth application-default login
|
|
```
|
|
|
|
Make sure the `GOOGLE_CLOUD_*` lines in the generated `.env` file are
|
|
uncommented and set them to your project identifiers. For more information
|
|
on connecting to Google Cloud services and projects with ADK, see the
|
|
[Google Cloud setup guide](/get-started/google-cloud/) for ADK.
|
|
|
|
## Build your agent
|
|
|
|
Open your coding agent and confirm it can see the skills:
|
|
|
|
=== "Antigravity"
|
|
|
|
```shell
|
|
antigravity # launch from your IDE or terminal
|
|
# then verify the Agents CLI skills are listed in your environment
|
|
```
|
|
|
|
=== "Claude Code"
|
|
|
|
```shell
|
|
claude
|
|
/skills # expect google-agents-cli-* entries in the list
|
|
```
|
|
|
|
=== "Codex"
|
|
|
|
```shell
|
|
codex
|
|
/skills # expect google-agents-cli-* entries in the list
|
|
```
|
|
|
|
??? note "Using other coding agents"
|
|
|
|
Agents CLI works with any coding agent that supports
|
|
[skills](https://agentskills.io/what-are-skills). Most agents list them
|
|
through a `/skills` command or a settings panel.
|
|
|
|
Then tell the coding agent what you want to build:
|
|
|
|
```shell title="Coding agent prompt"
|
|
Use agents-cli to build an agent that turns long text into short
|
|
bullet-point summaries
|
|
```
|
|
|
|
Your coding agent activates the `google-agents-cli-workflow` and
|
|
`google-agents-cli-scaffold` skills, asks clarifying questions about the
|
|
tools your agent calls, the inputs and outputs you expect, and the success
|
|
criteria to evaluate against, and then scaffolds the project.
|
|
|
|
Next, your coding agent uses the `google-agents-cli-adk-code` skill to write
|
|
your agent into `app/agent.py`. You end up with a working project with the
|
|
agent code, tests, and an eval dataset in the following file structure:
|
|
|
|
```none
|
|
my-agent/
|
|
app/
|
|
agent.py # main agent code
|
|
fast_api_app.py # server, telemetry, and routes
|
|
app_utils/ # session and artifact services
|
|
tests/
|
|
eval/ # evaluation datasets and metrics
|
|
integration/ # end-to-end agent tests
|
|
unit/
|
|
pyproject.toml # project config and dependencies
|
|
agents-cli-manifest.yaml # Agents CLI configuration
|
|
Dockerfile # container image for deployment
|
|
GEMINI.md # project guidance for coding agents
|
|
.env # API keys or project IDs
|
|
```
|
|
|
|
Use this project structure when you plan to test, evaluate, and deploy an agent.
|
|
If you want a create single-file agent for learning ADK, use the `adk create`
|
|
command instead.
|
|
|
|
## Run your agent
|
|
|
|
Ask your coding agent to start the local playground, or run it yourself:
|
|
|
|
```console
|
|
agents-cli playground
|
|
```
|
|
|
|
This command starts the ADK web interface with hot reload, so your changes
|
|
are reflected in the project as you edit. You can access the playground at
|
|
(http://localhost:8080). Select the agent at the upper left corner and paste
|
|
in a few paragraphs of text. The agent replies with a short bullet-point summary.
|
|
|
|
## Next: Evaluate and deploy your agent
|
|
|
|
Now that you have Agents CLI installed and your first agent running, you can
|
|
evaluate and deploy it with your coding agent using instructions like the
|
|
following:
|
|
|
|
* ***"Write evals for this agent and run them"*** to
|
|
[evaluate your agent](https://google.github.io/agents-cli/guide/evaluation/)
|
|
against the success criteria you set when you scoped it. Your coding agent
|
|
grades the results, groups the failures by cause, and tunes the agent's
|
|
instructions until it passes
|
|
* ***"Deploy this to Cloud Run"*** to
|
|
[deploy your agent](/deploy/agent-runtime/agents-cli/) to Agent Runtime,
|
|
Cloud Run, or GKE.
|
|
* ***"Set up observability infrastructure for my agent"*** to add prompt-response
|
|
logging and content logs.
|
|
|
|
For the full walkthrough, including evaluation, deployment, and observability,
|
|
see the Agents CLI
|
|
[Tutorial: Build your first agent](https://google.github.io/agents-cli/guide/quickstart-tutorial/).
|