AGENT SKILL

google-adk-setup

Bootstrap a Google ADK (Agent Development Kit) project from zero to a running local dev UI. Use when setting up a new ADK agent project, configuring Vertex AI credentials, scaffolding the agent folder, or troubleshooting ADK environment issues. Trigger on: adk setup, adk init, google-adk, vertex ai agent, uv run adk, adk web.

License 许可
Unlicense
所属仓库
saski/arnesto
最近更新
2026-11-12
Stars
★ 6
Forks
0

01 前言 Front Matter

name
google-adk-setup
description
Bootstrap a Google ADK (Agent Development Kit) project from zero to a running local dev UI. Use when setting up a new ADK agent project, configuring Vertex AI credentials, scaffolding the agent folder, or troubleshooting ADK environment issues. Trigger on: adk setup, adk init, google-adk, vertex ai agent, uv run adk, adk web.

02 资源文件 1

03 SKILL.md 正文

Google ADK Setup

When to Use / When Not to Use

Use this skill when:

  • Starting a new ADK project from scratch.
  • Configuring GCP credentials and environment variables for ADK.
  • Scaffolding an agent folder with adk create agent.
  • Launching the ADK dev UI or CLI runner.
  • Troubleshooting missing .env or Vertex AI auth errors.

Do not use this skill when:

  • Designing agent logic, tools, or multi-agent systems (use google-adk-agent-patterns).
  • Deploying to Cloud Run (deployment commands are in the references).

Prerequisites

  1. GCP project with billing enabled.
  2. gcloud CLI installed and authenticated: gcloud auth application-default login.
  3. uv installed (see using-uv skill).
  4. Vertex AI API enabled in your GCP project.

Enable the API:

gcloud services enable aiplatform.googleapis.com

Workflow

1. Create the project

uv init agent-project
cd agent-project
uv add google-adk

2. Scaffold the agent

uv run adk create agent

Interactive prompts:

  • Model: gemini-2.5-flash (recommended starting point)
  • Backend: Vertex AI
  • GCP Project ID: your project id
  • Location: global

Generated files:

agent/
├── __init__.py     # exposes root_agent
├── agent.py        # Agent definition
└── .env            # Vertex AI credentials (co-located with the package)

3. Verify the .env file

The .env lives inside the agent/ directory (not the project root):

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=global

4. Run the dev UI

uv run adk web --reload_agents

Opens at http://localhost:8000.

For Cloud Shell or remote environments, add --allow_origins="*".

5. Run in CLI mode

uv run adk run agent

Key Facts

  • GOOGLE_CLOUD_LOCATION=global routes to the global Vertex AI endpoint; use a regional value (e.g. us-central1) only if global is unavailable.
  • .adk/session.db (SQLite) stores conversation session state between runs. Delete it to reset sessions.
  • --reload_agents hot-reloads agent code on file changes; omit in production.

Troubleshooting

Symptom Fix
DefaultCredentialsError Run gcloud auth application-default login
Permission denied: aiplatform.googleapis.com Enable API: gcloud services enable aiplatform.googleapis.com
Agent changes not reflected Ensure --reload_agents flag is set
Sessions persist unexpectedly Delete agent/.adk/session.db

See references/cli-commands.md for the full CLI reference.

04 同仓库更多 Skills