1. 概要
この Codelab では、Agents CLI を使用して AI エージェントのローカル開発ライフサイクル全体を管理する方法を学びます。既存の Gemini モデルをラップする場合でも、Agent Development Kit（ADK 2.0）を使用してカスタム エージェントをゼロから構築する場合でも、Agents CLI にはエージェントをローカルでスキャフォールディング、ビルド、リント、テストするためのツールが用意されています。
学習内容
agents-cliと関連するスキルをインストールして設定する方法。- 新しいエージェント プロジェクトをスキャフォールディングする方法。
- ADK 2.0 グラフ ワークフロー エージェント プロジェクトの構造とキーファイル。
- 自動リンティングとコード クリーンアップを実行する方法。
- 自動再読み込みによるインタラクティブ テスト用のローカル ウェブ プレイグラウンドを起動して使用する方法。
必要なもの
- Python 3.11 以降
- uv パッケージ マネージャー
- Node.js 18 以降（コーディング エージェント スキルを使用する場合）
- Antigravity IDE（Google Antigravity からインストールして構成）
前提条件
この Codelab は、次の内容を理解していることを前提としています。
- ターミナルとコマンドラインを使用する。
AI エージェントや ADK 2.0 の経験は不要です。
2. 認証と環境を設定する
エージェントが Gemini モデルを呼び出すための認証情報を指定します。
オプション 1: Gemini API キー（Google AI Studio）
標準の Gemini API キー（Google AI Studio から取得できます）を使用している場合は、IDE ターミナル セッションでエクスポートします。
export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE
オプション 2: Google Cloud アプリケーションのデフォルト認証情報
Google Cloud で Vertex AI を使用している場合は、Google Cloud アプリケーションのデフォルト認証情報（ADC）で認証し、アクティブな Google Cloud プロジェクトを設定します。
gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location
3. Agents CLI とスキルを設定する
最初の手順は、agents-cli ツールをインストールすることです。このツールは、エージェント プロジェクト管理の面倒な作業を処理します。
Antigravity をインストールしたら、ターミナルでセットアップ コマンドを直接実行します。
👉 ターミナルを開いて実行します。
uvx google-agents-cli setup
このコマンドを実行すると、次のものが自動的にインストールされます。
- システムのグローバルに Agents CLI ツール。
- Antigravity がエージェントの構築、スキャフォールディング、評価、デプロイに役立つ 7 つのドメイン固有のコーディング アシスタント スキル。これらのスキルは
~/.agents/skills/にグローバルに 1 回インストールされ、Antigravity によって自動的に検出されます。
注: スキルは ~/.agents/skills/ にインストールされ、Antigravity によって自動的に取得されます。これを確認するには、/skills コマンドまたは Antigravity の設定を使用します。
想定される出力（トリミング済み）:
█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`
`Your coding agent just got an upgrade.`
`1. Authentication`
`─────────────────`
`✓ Authenticated with Google Cloud`
`2. CLI Installation`
`───────────────────`
`▸ uv tool install google-agents-cli`
`✓ Installed google-agents-cli`
`3. Skills Installation`
`──────────────────────`
`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`
`◇ Found 7 skills`
`~/.agents/skills/google-agents-cli-adk-code`
`~/.agents/skills/google-agents-cli-deploy`
`~/.agents/skills/google-agents-cli-eval`
`~/.agents/skills/google-agents-cli-observability`
`~/.agents/skills/google-agents-cli-publish`
`~/.agents/skills/google-agents-cli-scaffold`
`~/.agents/skills/google-agents-cli-workflow`
4. エージェント プロジェクトを作成する
このセクションでは、プロトタイプ テンプレートを使用して、完全に構造化されたプロジェクト ディレクトリを作成します。
👉 プロンプト Antigravity:
Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.
Antigravity は、スキャフォールディング コマンド（agents-cli scaffold create customer-support-agent --prototype --yes）を自動的に実行し、プロジェクト ファイルを設定します。
5. エージェント コードを確認する
👉 生成されたコードの説明を Antigravity に依頼します。
Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.
Antigravity IDE では、新しく作成したプロジェクト ファイルとアーティファクトが補助ペイン（左側）に直接表示されます。app/agent.py を表示するか、IDE のファイル エクスプローラーから開いて、スキャフォールディングされたコードを確認できます。
# app/agent.py
from __future__ import annotations
from typing import Any, Literal
from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field
class InquiryCategory(BaseModel):
category: Literal['shipping', 'unrelated'] = Field(
description=(
'Determine if the user query is related to shipping (rates, tracking,'
' delivery times, returns) or unrelated.'
)
)
def save_query(node_input: str):
"""Saves user query in state for downstream nodes."""
yield Event(data=node_input, state={'user_query': node_input})
categorize_agent = LlmAgent(
name='categorize',
model='gemini-3.1-flash-lite',
instruction='You are an expert classifier. Categorize the user query.',
output_key='inquiry_category',
output_schema=InquiryCategory,
)
@node
def route_inquiry(ctx: Context, node_input: Any):
"""Routes the workflow based on the classified category."""
category_data = ctx.state.get('inquiry_category', {})
category = category_data.get('category', 'unrelated')
query = ctx.state.get('user_query', '')
yield Event(data=query, route=category)
faq_agent = LlmAgent(
name='shipping_faq',
model='gemini-3.1-flash-lite'',
instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
SHIPPING FAQ:
- Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
over $50 qualify for free standard shipping.
- Tracking: You can track your order by entering your tracking number on
our website's tracking page.
- Delivery Times: Standard delivery takes 3-5 business days. Express
delivery takes 1-2 business days.
- Returns: We offer free returns within 30 days of delivery. Please make
sure the item is in its original condition.
""",
)
@node
def handle_unrelated(ctx: Context, node_input: Any):
"""Handles unrelated inquiries politely."""
yield Event(
data=(
'I am sorry, I am a shipping customer support assistant and can only'
' answer questions related to our shipping FAQ.'
)
)
root_agent = Workflow(
name='customer_support_workflow',
edges=[
*Edge.chain('START', save_query, categorize_agent, route_inquiry),
(route_inquiry, faq_agent, 'shipping'),
(route_inquiry, handle_unrelated, 'unrelated'),
],
)
app = App(
name='customer_support_agent',
root_agent=root_agent,
)
主な概念
- ワークフローとエッジ: ADK 2.0 では、エージェント アプリケーションは
Workflowを使用してグラフとしてオーケストレートされます。edgesリストは実行フローを定義し、STARTからノードを連結して、ルートに基づく条件付き分岐を可能にします（例:"shipping"のfaq_agentまたは"unrelated"のhandle_unrelatedへのルーティング）。 - LlmAgent: 特定の指示、モデル、構造化された出力（
output_schema）を使用して LLM を活用したタスクを定義する宣言型ノード。 - ノードとコンテキスト:
@nodeで装飾された（または標準の）Python 関数。ロジックを実行し、Contextを介して実行状態にアクセスし、Eventオブジェクトを生成して、グラフに沿ってデータとルーティング シグナルを渡します。 - モデル: デフォルトの高速推論モデルとして `gemini-3.1-flash-lite` が使用されます。
- アプリ ラッパー: 最上位の
Appオブジェクトはルート ワークフローをラップします。ローカル プレイグラウンド、ADK 評価ハーネス、Agent Runtime などの外部ツールは、この標準化されたappインターフェースを介してワークフローを検出して実行します。
6. 自動リント
エージェントを実行またはテストする前に、コードがクリーンで、正しくフォーマットされていることを確認することをおすすめします。
👉 プロンプト Antigravity:
Run linting on my agent project to verify its health.
Antigravity は、バックグラウンドで agents-cli lint を実行して、事前構成されたチェックを実行し、ファイル全体でインポート、構文、形式の一貫性を検証します。
7. プレイグラウンドでのインタラクティブ テスト
ローカル ウェブ プレイグラウンドは、エージェントの動作を検証する最も速い方法です。エージェントとチャットしてツールの実行をリアルタイムで検査できるインタラクティブなチャット インターフェースが用意されています。
👉 プロンプト Antigravity:
Launch the local development playground for my agent.
Antigravity はローカル開発サーバー（agents-cli playground）を起動します。ウェブブラウザで指定された URL（通常は http://127.0.0.1:8080/dev-ui/?app=app）を開き、プルダウンからフォルダ app を選択して、エージェントとのチャットを開始します。
ウェブ インターフェースでエージェントとのチャットを開始します。配送に関する質問をしてみます。
How much is standard shipping?
ワークフローが faq_agent に分類して転送し、回答していることを確認します。また、無関係な質問をして、ワークフローが handle_unrelated に転送し、回答を正しく拒否していることを確認します。
What is the weather like?
リアルタイム自動再読み込みをテストする
エージェントに対するリアルタイム編集が Playground にどのように反映されるかを確認できます。
- Antigravity に次のように尋ねて、
app/agent.pyのfaq_agent命令を変更します。Modify the faq_agent instruction in app/agent.py to make the shipping rates response more playful and enthusiastic. Add some emojis and highlight the free shipping threshold. - playground でエージェントに新しいメッセージを送信して、自動再読み込みをテストします。
How much is standard shipping?
8. コマンドラインの実行
簡単なテスト、自動化、スクリプト作成の場合は、Antigravity にターミナルから直接エージェントを実行するようリクエストできます。
👉 プロンプト Antigravity:
Run a CLI query asking my agent how long standard delivery takes.
Antigravity はクエリ コマンド（agents-cli run "How long does standard delivery take?"）を実行します。これにより、1 回の推論が実行され、エージェントの最終的なレスポンスとツールの実行の詳細が出力されます。
9. クリーンアップ
ローカル環境に不要なリソースが残らないようにするには、次のクリーンアップ手順を行います。
- ローカル サーバーを停止する:
agents-cli playgroundサーバーがまだ実行中の場合は、ターミナルでCtrl + Cを押して停止します。 - ローカル プロジェクト ファイルを削除: スキャフォールディングされたエージェント プロジェクト ディレクトリをローカルマシンから削除します。
rm -rf customer-support-agent
10. まとめと次のステップ
おめでとうございます！Agents CLI と ADK 2.0 を使用して、AI エージェントのエンドツーエンドのローカル開発ライフサイクルを正常に管理しました。
学習した内容
- ツールを設定する: Agents CLI をインストールし、Antigravity のドメイン固有のワークフロー スキルを構成しました。
- プロジェクトをスキャフォールディング: 標準化されたテンプレートを使用して、完全に構造化された
customer-support-agentプロジェクトを作成しました。 - ADK 2.0 の構造を分析: グラフ ワークフロー、LLM エージェント、ノード、エッジ、条件付きルーティングについて説明しました。
- Managed Local Health:
agents-cli lintを使用してコード品質の自動チェックを実行しました。 - 検証済みの動作: プレイグラウンドでリアルタイムのホットリロードを使用してエージェントをインタラクティブにテストし、コマンドラインでクイック テストを実行しました。
次のステップ
ローカル開発ループを習得したので、エージェントを拡張して本番環境に移行する方法について説明します。
- 評価:
agents-cli eval runを使用して、evalset に対してエージェントをスコアリングし、精度を測定して回帰を見つけます。 - エンタープライズ クラウド スケール: デプロイとオブザーバビリティ:
agents-cli deployを使用して、エージェント ランタイムや Cloud Run などの本番環境にエージェントをパッケージ化してデプロイします。ログと実行トレースを Cloud Trace と BigQuery にストリーミングするように、本番環境のテレメトリーを設定します。