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

1. Übersicht

In diesem Codelab erfahren Sie, wie Sie die Agents CLI verwenden, um den gesamten lokalen Entwicklungszyklus eines KI-Agenten zu steuern. Ganz gleich, ob Sie vorhandene Gemini-Modelle einbinden oder benutzerdefinierte Agents mit dem Agent Development Kit (ADK 2.0) von Grund auf neu erstellen – die Agents CLI bietet die Tools, mit denen Sie Ihre Agents lokal erstellen, linten und testen können.

Lerninhalte

  • So installieren und richten Sie agents-cli und die zugehörigen Skills ein.
  • So erstellen Sie ein neues Agent-Projekt.
  • Die Struktur und die wichtigsten Dateien eines ADK 2.0-Agentenprojekts für Graph-Workflows.
  • Automatisierte Linting- und Codebereinigungen ausführen
  • So starten und verwenden Sie die lokale 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 KI-Agenten-Skills)
  • Antigravity IDE (über Google Antigravity installieren und konfigurieren)

Vorbereitung

In diesem Codelab wird davon ausgegangen, dass Sie mit Folgendem vertraut sind:

  • Mit einem Terminal und einer Befehlszeile

Es sind keine Vorkenntnisse in Bezug auf KI-Agents oder ADK 2.0 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 in Google AI Studio erhalten können, exportieren Sie ihn in der 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

Installieren Sie zuerst das agents-cli-Tool. Dieses Tool übernimmt die anspruchsvolle Aufgabe der Verwaltung von Agent-Projekten.

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 Agents CLI-Tool global auf Ihrem System.
  2. Sieben domänenspezifische Fähigkeiten des Programmierassistenten, die Antigravity nutzen kann, um Sie beim Erstellen, Gerüstbau, Bewerten und Bereitstellen von Agents 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 prü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. Projekt für KI-Agenten erstellen

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

👉 Antigravity-Prompt:

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

5. Agent-Code ansehen

👉 Antigravity bitten, 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 generierten 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 Agent-Anwendungen als Diagramm mit Workflow orchestriert. Die Liste edges definiert den Ausführungsablauf, indem Knoten aus START verkettet 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-basierte Aufgaben mit spezifischen Anweisungen, Modellen und strukturierten Ausgaben (output_schema) definieren.
  • Knoten und Kontext: Mit @node dekorierte Python-Funktionen (oder Standardfunktionen), die Logik ausführen, über Context auf den Ausführungsstatus zugreifen und Event-Objekte ausgeben, um Daten und Routing-Signale entlang des Diagramms zu übergeben.
  • Modell: „gemini-3.1-flash-lite“ wird als schnelles Standardmodell für Schlussfolgerungen verwendet.
  • App-Wrapper: Das App-Objekt der obersten Ebene umschließt den Stamm-Workflow. 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. Automatisierte Linting-Funktion

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

👉 Antigravity-Prompt:

Run linting on my agent project to verify its health.

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

7. Interaktive Tests mit dem Playground

Die lokale Web-Playground ist die schnellste Möglichkeit, das Verhalten Ihres Agents zu überprüfen. Sie bietet eine interaktive Chat-Oberfläche, über die Sie mit Ihrem KI-Agenten chatten und Tool-Ausführungen in Echtzeit prüfen können.

👉 Antigravity-Prompt:

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 Ordner app aus, um mit Ihrem Agent zu chatten.

Chatten Sie mit Ihrem KI-Agenten über die Weboberfläche. Versuche es mit einer Frage zum Versand:

How much is standard shipping?

Der Workflow kategorisiert und leitet die Anfrage erfolgreich an faq_agent weiter, damit sie beantwortet werden kann. Stellen Sie außerdem eine Frage, die nicht mit dem Thema zusammenhängt, um zu prüfen, ob der Workflow zu handle_unrelated weitergeleitet wird und die Antwort korrekt abgelehnt wird:

What is the weather like?

Automatisches Aufladen in Echtzeit testen

Sie können sehen, wie sich Echtzeitbearbeitungen Ihres Agents im Playground auswirken.

  1. Ändern Sie die faq_agent-Anweisung in app/agent.py, indem Sie Antigravity fragen: 
    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 im Playground, um das automatische Neuladen zu testen: 
    How much is standard shipping?
    Die Playground-Umgebung wird automatisch neu geladen und der aktualisierte Code wird in Echtzeit ausgeführt, ohne dass ein Serverneustart erforderlich ist. In der Antwort sollten jetzt einige Emojis angezeigt werden.

8. Ausführung über die Befehlszeile

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

👉 Antigravity-Prompt:

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 in einem einzelnen Durchgang ausgeführt und die endgültige Antwort des Agents zusammen mit den Details zur Tool-Ausführung ausgegeben.

9. Bereinigen

So vermeiden Sie, dass unerwünschte Ressourcen in Ihrer lokalen Umgebung verbleiben: 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 Gerüstverzeichnis des Agent-Projekts 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 dem ADK 2.0 verwaltet.

Das haben Sie gelernt

  • Tools einrichten: Sie haben die Agents CLI installiert und domänenspezifische Workflow-Skills für Antigravity konfiguriert.
  • Projektgerüst erstellt: Ein vollständig strukturiertes customer-support-agent-Projekt mithilfe von standardisierten Vorlagen erstellt.
  • Analyzed ADK 2.0 Structure: Graph-Workflows, LLM-Agents, Knoten, Kanten und bedingtes Routing.
  • Managed Local Health: Es wurden automatisierte Codequalitätsprüfungen mit agents-cli lint durchgeführt.
  • Bestätigtes Verhalten: Der Agent wurde interaktiv mit Hot-Reloading in Echtzeit über die Playground-Umgebung getestet und es wurden Schnelltests ü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 Agent anhand eines Evalsets mit agents-cli eval run, um die Genauigkeit zu messen und Regressionen zu finden.
  • Enterprise Cloud Scale: Bereitstellung und Observability: agents-cli deploy ermöglicht es Ihnen, Ihren KI-Agenten in Produktionsumgebungen wie Agent Runtime oder Cloud Run zu verpacken und bereitzustellen. Richten Sie die Telemetrie für die Produktion ein, um Logs und Ausführungstraces an Cloud Trace und BigQuery zu streamen.

Zusätzliche Ressourcen