Vibe Coding für KI-Agenten: Agentenlebenszyklus mit Agents CLI und ADK 2.0 verwalten

1. Übersicht

In diesem Codelab erfahren Sie, wie Sie mit der Agents CLI den gesamten lokalen Entwicklungszyklus eines KI-Agenten verwalten. Mit der Agents CLI können Sie Ihre Agenten lokal erstellen, linten und testen, unabhängig davon, ob Sie vorhandene Gemini-Modelle einbinden oder benutzerdefinierte Agenten mit dem Agent Development Kit (ADK 2.0) von Grund auf neu erstellen.

Lerninhalte

  • Installation und Einrichtung von agents-cli und den zugehörigen Skills
  • Erstellen eines neuen Agentenprojekts
  • Struktur und wichtige Dateien eines ADK 2.0-Projekts für einen Graph-Workflow-Agenten
  • Automatisches Linten und Bereinigen von Code
  • Starten und Verwenden der lokalen Web-Playground-Umgebung für interaktive Tests mit automatischem Neuladen

Voraussetzungen

  • Python 3.11 oder höher
  • uv-Paketmanager
  • Node.js 18+ (bei Verwendung von Coding-Agenten-Skills)
  • Antigravity IDE (Installation und Konfiguration über Google Antigravity)

Vorbereitung

Für dieses Codelab sind folgende Kenntnisse erforderlich:

  • Verwendung eines Terminals und der Befehlszeile

Vorkenntnisse zu KI-Agenten oder ADK 2.0 sind nicht erforderlich.

2. Authentifizierung und Umgebung einrichten

Geben Sie Ihre Anmeldedaten zur Authentifizierung an, damit der Agent Gemini-Modelle aufrufen kann.

Option 1: Gemini API-Schlüssel (Google AI Studio)

Wenn Sie einen Standard-Gemini API-Schlüssel verwenden (den Sie von Google AI Studio erhalten), exportieren Sie ihn in Ihrer IDE-Terminalsitzung:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Option 2: Standardanmeldedaten für Google Cloud-Anwendungen

Wenn Sie Vertex AI in Google Cloud verwenden, authentifizieren Sie sich mit den Standardanmeldedaten für Anwendungen (Application Default Credentials, ADC) und legen Sie Ihr aktives Google Cloud-Projekt fest:

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 und Skills einrichten

Der erste Schritt ist die Installation des Tools agents-cli. Dieses Tool übernimmt die anspruchsvolle Aufgabe der Verwaltung von Agentenprojekten.

Führen Sie nach der Installation von Antigravity den Einrichtungsbefehl direkt im Terminal aus.

👉 Öffnen Sie ein Terminal und führen Sie Folgendes aus :

uvx google-agents-cli setup

Mit diesem Befehl wird Folgendes automatisch installiert:

  1. Das Tool Agents CLI global auf Ihrem System.
  2. Sieben domänenspezifische Skills für den Coding-Assistenten, die Antigravity verwenden kann, um Sie beim Erstellen, Scaffolding, Bewerten und Bereitstellen von Agenten zu unterstützen. Diese Skills werden einmal global in ~/.agents/skills/ installiert und automatisch von Antigravity erkannt.

Hinweis: Skills werden in ~/.agents/skills/ installiert und automatisch von Antigravity erkannt. Sie können dies mit dem Befehl /skills oder in den Antigravity-Einstellungen überprüfen.

Erwartete Ausgabe (gekürzt) :

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`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. Agentenprojekt erstellen

In diesem Abschnitt erstellen Sie ein vollständig strukturiertes Projektverzeichnis mit der Prototypvorlage.

👉 Prompt für 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 führt automatisch den Scaffolding-Befehl (agents-cli scaffold create customer-support-agent --prototype --yes) aus und richtet die Projektdateien für Sie ein.

5. Agentencode ansehen

👉 Bitten Sie Antigravity, den generierten Code zu erklären:

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.

In der Antigravity IDE werden neu erstellte Projektdateien und Artefakte direkt im Hilfsbereich (links) angezeigt. Sie können app/agent.py dort ansehen oder über den Datei-Explorer der IDE öffnen, um den Code zu untersuchen.

# 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,
)

Schlüsselkonzepte

  • Workflow und Edges: In ADK 2.0 werden Agentenanwendungen als Graph mit Workflow orchestriert. Die Liste edges definiert den Ausführungsablauf, indem Knoten von START miteinander verknüpft werden und bedingte Verzweigungen basierend auf Routen ermöglicht werden (z.B. Routing zu faq_agent bei "shipping" oder handle_unrelated bei "unrelated").
  • LlmAgent: Deklarative Knoten, die LLM-gestützte Aufgaben mit bestimmten Anweisungen, Modellen und strukturierten Ausgaben (output_schema) definieren.
  • Knoten und Kontext: Python-Funktionen, die mit @node annotiert sind (oder Standardfunktionen), die Logik ausführen, über Context auf den Ausführungsstatus zugreifen und Event-Objekte erzeugen, um Daten und Routing-Signale im Graph weiterzugeben.
  • Modell: `gemini-3.1-flash-lite` wird als Standardmodell für schnelle Schlussfolgerungen verwendet.
  • App-Wrapper: Das Objekt der obersten Ebene umschließt den Root-Workflow.App Externe Tools wie die lokale Playground-Umgebung, ADK-Bewertungstools und die Agent Runtime erkennen und führen Ihren Workflow über diese standardisierte app-Schnittstelle aus.

6. Automatisches Linten

Bevor Sie Ihren Agenten ausführen oder testen, sollten Sie sicherstellen, dass Ihr Code sauber und korrekt formatiert ist.

👉 Prompt für Antigravity:

Run linting on my agent project to verify its health.

Antigravity führt im Hintergrund agents-cli lint aus, um vorkonfigurierte Prüfungen durchzuführen und Importe, Syntax und Formatierungskonsistenz in Ihren Dateien zu überprüfen.

7. Interaktive Tests mit der Playground-Umgebung

Die lokale Web-Playground-Umgebung ist die schnellste Möglichkeit, das Verhalten Ihres Agenten zu überprüfen. Sie bietet eine interaktive Chat-Oberfläche, auf der Sie mit Ihrem Agenten chatten und Toolausführungen in Echtzeit beobachten können.

👉 Prompt für Antigravity:

Launch the local development playground for my agent.

Antigravity startet den lokalen Entwicklungsserver (agents-cli playground). Öffnen Sie die angegebene URL (in der Regel http://127.0.0.1:8080/dev-ui/?app=app) in Ihrem Webbrowser und wählen Sie im Drop-down-Menü den Ord2er app aus, um mit Ihrem Agenten zu chatten.

Beginnen Sie in der Weboberfläche mit Ihrem Agenten zu chatten. Stellen Sie eine Frage zum Versand:

How much is standard shipping?

Beachten Sie, wie der Workflow die Frage erfolgreich kategorisiert und an faq_agent weiterleitet, um sie zu beantworten. Stellen Sie auch eine Frage, die nicht mit dem Thema zusammenhängt, um zu überprüfen, ob der Workflow an handle_unrelated weitergeleitet wird und die Antwort korrekt abgelehnt wird:

What is the weather like?

Automatische Neuladung in Echtzeit testen

Sie können sehen, wie sich Änderungen an Ihrem Agenten in Echtzeit in der Playground-Umgebung widerspiegeln.

  1. Ändern Sie die Anweisung für faq_agent in app/agent.py, indem Sie Antigravity auffordern: 
    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.
  2. Senden Sie eine neue Nachricht an den Agenten in der Playground-Umgebung, um die automatische Neuladung zu testen: 
    How much is standard shipping?
    Die Playground-Umgebung wird automatisch neu geladen und führt Ihren aktualisierten Code in Echtzeit aus, ohne dass ein Neustart des Servers erforderlich ist. In der Antwort sollten jetzt einige Emojis zu sehen sein.

8. Ausführung über die Befehlszeile

Für schnelle Tests, Automatisierung oder Scripting können Sie Antigravity auffordern, Ihren Agenten direkt über das Terminal auszuführen.

👉 Prompt für Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity führt den Abfragebefehl (agents-cli run "How long does standard delivery take?") aus. Dadurch wird eine schnelle Inferenz mit einer einzigen Runde ausgeführt und die endgültige Antwort des Agenten zusammen mit Details zur Toolausführung ausgegeben.

9. Bereinigen

So vermeiden Sie unerwünschte Ressourcen in Ihrer lokalen Umgebung, führen Sie die folgenden Bereinigungsschritte aus:

  1. Lokale Server beenden: Wenn Ihr agents-cli playground Server noch ausgeführt wird, beenden Sie ihn im Terminal, indem Sie Ctrl + C drücken.
  2. Lokale Projektdateien entfernen: Löschen Sie das Verzeichnis des Agentenprojekts von Ihrem lokalen Computer.
rm -rf customer-support-agent

10. Zusammenfassung und nächste Schritte

Glückwunsch! Sie haben den gesamten lokalen Entwicklungszyklus eines KI-Agenten mit der Agents CLI und ADK 2.0 erfolgreich verwaltet.

Das haben Sie gelernt

  • Tools einrichten: Sie haben die Agents CLI installiert und domänenspezifische Workflow-Skills für Antigravity konfiguriert.
  • Projekt erstellen: Sie haben ein vollständig strukturiertes customer-support-agent Projekt mit standardisierten Vorlagen erstellt.
  • ADK 2.0-Struktur analysieren: Sie haben Graph-Workflows, LLM-Agenten, Knoten, Edges und bedingtes Routing untersucht.
  • Lokale Systemdiagnose durchführen: Sie haben automatisierte Codequalitätsprüfungen mit agents-cli lint ausgeführt.
  • Verhalten überprüfen: Sie haben den Agenten interaktiv mit Hot-Reloading in Echtzeit über die Playground-Umgebung getestet und schnelle Tests über die Befehlszeile ausgeführt.

Wie geht es weiter?

Nachdem Sie den lokalen Entwicklungszyklus gemeistert haben, können Sie Ihren Agenten so erweitern und für die Produktion vorbereiten:

  • Bewertung: Bewerten Sie Ihren Agenten anhand eines Testdatensatzes mit agents-cli eval run, um die Genauigkeit zu messen und Regressionen zu finden.
  • Enterprise Cloud-Skalierung: Bereitstellung & Beobachtbarkeit: Packen Sie Ihren Agenten und stellen Sie ihn in Produktionsumgebungen wie Agent Runtime oder Cloud Run mit agents-cli deploy bereit. Richten Sie die Telemetrie für die Produktion ein, um Logs und Ausführungstraces an Cloud Trace und BigQuery zu streamen.

Zusätzliche Ressourcen