Back to Details

google-agents-cli-adk-code

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ADK Cheatsheet

ADK速查表

Before using this skill, activate 
/google-agents-cli-workflow
first — it contains the required development phases and scaffolding steps.
使用本技能前，请先激活
/google-agents-cli-workflow
——它包含所需的开发阶段和脚手架步骤。

Prerequisites

前置条件

  1. Run 
    agents-cli info
    — if it shows project config, skip to the cheatsheet below
  2. If no project exists: run 
    agents-cli scaffold create <name>
  3. If user has existing code: run 
    agents-cli scaffold enhance .
Do NOT write agent code until a project is scaffolded.
Python only for now. This cheatsheet currently covers the Python ADK SDK. Support for other languages is coming soon.
  1. 运行
    agents-cli info
    ——如果显示项目配置，直接跳至下方速查表
  2. 若无项目存在：运行
    agents-cli scaffold create <name>
  3. 若用户已有代码：运行
    agents-cli scaffold enhance .
在完成项目脚手架搭建前，请勿编写Agent代码。
目前仅支持Python。本速查表当前覆盖Python ADK SDK。 其他语言的支持即将推出。

Quick Reference — Most Common Patterns

快速参考——最常用模式

Agent Creation

Agent创建

python
from google.adk.agents import Agent

root_agent = Agent(
    name="my_agent",
    model="gemini-flash-latest",
    instruction="You are a helpful assistant that ...",
    tools=[my_tool],
)
NEVER change an existing agent's 
model=
value unless the user explicitly asks. If a Gemini model returns a 404, it's almost always a 
GOOGLE_CLOUD_LOCATION
issue — run the listing command to verify availability before changing anything. For model docs, fetch 
https://adk.dev/agents/models/google-gemini/index.md
.
bash
uv run --with google-genai python -c "
from google import genai
client = genai.Client(vertexai=True, location='global')
for m in client.models.list(): print(m.name)
"
python
from google.adk.agents import Agent

root_agent = Agent(
    name="my_agent",
    model="gemini-flash-latest",
    instruction="You are a helpful assistant that ...",
    tools=[my_tool],
)
除非用户明确要求，否则绝不要修改现有Agent的
model=
值。如果Gemini模型返回404错误，几乎都是
GOOGLE_CLOUD_LOCATION
问题——在修改任何内容前，先运行列表命令验证可用性。如需模型文档，请获取
https://adk.dev/agents/models/google-gemini/index.md
。
bash
uv run --with google-genai python -c "
from google import genai
client = genai.Client(vertexai=True, location='global')
for m in client.models.list(): print(m.name)
"

Basic Tool

基础工具

python
from google.adk.tools import FunctionTool

def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    return {"city": city, "temp": "22°C", "condition": "sunny"}

weather_tool = FunctionTool(func=get_weather)
ADK built-in tool imports: Import the tool instance, not the module.
python
from google.adk.tools.load_web_page import load_web_page  # CORRECT
from google.adk.tools import load_web_page                 # WRONG
python
from google.adk.tools import FunctionTool

def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    return {"city": city, "temp": "22°C", "condition": "sunny"}

weather_tool = FunctionTool(func=get_weather)
ADK内置工具导入方式：导入工具实例，而非模块。
python
from google.adk.tools.load_web_page import load_web_page  # 正确
from google.adk.tools import load_web_page                 # 错误

Simple Callback

简单回调

python
from google.adk.agents.callback_context import CallbackContext

async def initialize_state(callback_context: CallbackContext) -> None:
    state = callback_context.state
    if "history" not in state:
        state["history"] = []

root_agent = Agent(
    name="my_agent",
    model="gemini-flash-latest",
    instruction="...",
    before_agent_callback=initialize_state,
)
python
from google.adk.agents.callback_context import CallbackContext

async def initialize_state(callback_context: CallbackContext) -> None:
    state = callback_context.state
    if "history" not in state:
        state["history"] = []

root_agent = Agent(
    name="my_agent",
    model="gemini-flash-latest",
    instruction="...",
    before_agent_callback=initialize_state,
)

Reference Files

参考文件

FileWhen to read
references/adk-python.md
ADK Python API — agents, tools, callbacks, plugins, state, artifacts, context caching, session rewind
references/adk-2.0.md
ADK 2.0 Workflow API (experimental pre-GA, opt-in) — graph-based workflows, nodes, edges, HITL, parallel processing
文件阅读时机
references/adk-python.md
ADK Python API——agents、tools、callbacks、plugins、state、artifacts、context caching、session rewind
references/adk-2.0.md
ADK 2.0 Workflow API（实验性预GA版本，需手动启用）——基于图的工作流、节点、边、人机交互（HITL）、并行处理

ADK 2.0 Workflows — Opt-in

ADK 2.0工作流——需手动启用

The Workflow API is experimental, pre-GA (ADK 2.0). Do NOT recommend it by default.
Before suggesting workflow patterns, explain the following to the user and ask if they want to proceed:
  1. What it is: ADK 2.0 introduces a graph-based Workflow API — nodes (functions, LLM agents, tools) connected by edges with conditional routing, fan-out/fan-in parallelism, and human-in-the-loop interrupts.
  2. When it helps: Complex multi-step pipelines needing deterministic control flow, parallel processing of list items, structured approval gates, or retry logic — cases where SequentialAgent/ParallelAgent/LoopAgent feel limiting.
  3. Risks: Pre-GA — APIs may change before GA. Requires 
    google-adk >= 2.0.0
    and Python >= 3.11. Incompatible with Live Streaming. Scaffolded projects need 
    pyproject.toml
    changes before upgrade — see the reference file for step-by-step instructions.
Only read 
references/adk-2.0.md
after the user explicitly opts in. If they decline or are unsure, use the standard ADK 1.x orchestration patterns from 
references/adk-python.md
(SequentialAgent, ParallelAgent, LoopAgent, BaseAgent).
Workflow API为实验性预GA版本（ADK 2.0）。默认不推荐使用。
在推荐工作流模式前，请向用户解释以下内容并询问是否要继续：
  1. 是什么：ADK 2.0引入基于图的Workflow API——节点（函数、LLM agents、工具）通过带有条件路由、扇出/扇入并行处理和人机交互中断的边连接。
  2. 适用场景：需要确定性控制流、列表项并行处理、结构化审批 gate 或重试逻辑的复杂多步骤流水线——即SequentialAgent/ParallelAgent/LoopAgent无法满足需求的场景。
  3. 风险：预GA版本——API在正式发布前可能会变更。需要
    google-adk >= 2.0.0
    和Python >= 3.11。与Live Streaming不兼容。脚手架项目升级前需要修改
    pyproject.toml
    ——请查看参考文件获取分步说明。
仅在用户明确同意后，才可查阅
references/adk-2.0.md
。若用户拒绝或不确定，请使用
references/adk-python.md
中的标准ADK 1.x编排模式（SequentialAgent、ParallelAgent、LoopAgent、BaseAgent）。

ADK Documentation

ADK文档

For the ADK docs index (titles and URLs for fetching documentation pages), use 
curl https://adk.dev/llms.txt
.
如需ADK文档索引（可用于获取文档页面的标题和URL），请使用
curl https://adk.dev/llms.txt
。

Related Skills

相关技能

  • /google-agents-cli-workflow
    — Development workflow, coding guidelines, and operational rules
  • /google-agents-cli-scaffold
    — Project creation and enhancement with 
    agents-cli scaffold create
    / 
    scaffold enhance
  • /google-agents-cli-eval
    — Evaluation methodology, evalset schema, and the eval-fix loop
  • /google-agents-cli-deploy
    — Deployment targets, CI/CD pipelines, and production workflows
  • /google-agents-cli-workflow
    ——开发工作流、编码指南和操作规则
  • /google-agents-cli-scaffold
    ——使用
    agents-cli scaffold create
    /
    scaffold enhance
    创建和优化项目
  • /google-agents-cli-eval
    ——评估方法、评估集 schema 和 eval-fix循环
  • /google-agents-cli-deploy
    ——部署目标、CI/CD流水线和生产工作流