Von Prototyp bis Produktion mit Agents CLI: Ein Agent für die Genehmigung von Ausgaben

Jeder, der in letzter Zeit versucht hat, einen KI-Agenten zu veröffentlichen, kennt dieses Muster. Im Entwicklungsstadium verhält er sich folgendermaßen: Er beantwortet Fragen, ruft die richtigen Tools auf und trifft sinnvolle Entscheidungen. Dann fragt jemand, wann er in Betrieb genommen werden kann, und Tage vergehen mit Docker, Authentifizierung, Überwachungsfunktionen sowie Deployment-Pipelines.

Der Code des Agenten hat nur ein paar Stunden in Anspruch genommen. Die Infrastruktur dahinter hingegen braucht Wochen.

Im Folgenden wird Schritt für Schritt gezeigt, wie man mit Agents CLI, einem Open-Source-Toolkit zur Erleichterung solcher Deployment-Arbeiten, einen Agenten im Produktionsumfeld erstellt und veröffentlicht. Das Beispiel ist ein Ausgabenfreigab-Agenten mit Geschäftsregeln, Bewertungen sowie einer Cloud-Veröffentlichung – laut Angaben des Toolkits sollte dieser Prozess insgesamt etwa eine halbe Stunde dauern. Betrachten Sie diese Zahl als besten Fall bei einer vorbereiteten Umgebung.

Die Deployment-Lücke

Ein Agent mit dem Agent Development Kit (ADK), LangChain oder LlamaIndex zu erstellen ist recht einfach. Die eigentliche Herausforderung liegt darin, ihn in die Produktion zu bringen. Ein Produktionsagent benötigt in der Regel alles Folgende.

Lokale Entwicklung

• den Agenten-Code, der den interessanten Teil darstellt
• eine lokale Testumgebung
• Mock-Daten oder API-Stubs

Testen und Bewertung

• Definitionen von Testfällen
• Metriken und Bewertungskriterien
• eine Konfiguration mit einem LLM als Urteilsinstanz
• eine Regressionstest-Suite

Produktionsinfrastruktur

• eine Container-Image
• Einstellungen für die Cloud-Deployment in Tools wie Cloud Run oder Kubernetes
• Authentifizierung und Autorisierung
• Verwaltung von Geheimnissen
• eine CI/CD-Pipeline

Überwachbarkeit

• Aufzeichnung von Anfragen
• Protokollierung von Prompts und Antworten

Kostenverfolgung und -analyse

Leistungsüberwachung

Fehlermeldungen

Jeder Punkt bedeutet das Erlernen eines weiteren Tools, das Lesen weiterer Dokumentationen sowie das Verbinden separater Systeme. Ein Programmierassistent kann bei der Agentenlogik helfen, hat aber Schwierigkeiten bei der Bereitstellung, da er die Konventionen Ihrer Infrastruktur nicht kennt, was zu wiederholten Debugging-Schritten führt.

Was Agents CLI ist

Agents CLI ist ein Toolkit, das eine einzige Schnittstelle für den gesamten Entwicklungszyklus von Agenten auf Google Cloud bietet. Es arbeitet in zwei Modi.

1. Agentenmodus. Sie installieren „Skills“ in einen Programmierassistenten wie Gemini CLI, Claude Code oder Cursor. Diese Skills lehren den Assistenten Bereitstellungsmustern, damit er richtige Entscheidungen trifft.

Manuellmodus. Sie führen die CLI-Befehle selbst aus. Jeder Befehl arbeitet unabhängig, und es ist kein KI-Assistent erforderlich.

Die zentrale Idee ist, dass anstelle eines Assistenten, der über Deployment-Konventionen rät, ein maschinenlesbarer Kontext zur Verfügung steht, der angibt, wann jedes Deployment-Ziel verwendet werden sollte, wie Bewertungen strukturiert werden müssen und welche Überwachungsmuster am besten funktionieren.

Das Beispiel: Ein Agent für die Freigabe von Ausgaben

Der Agent prüft die Ausgabenerklärungen der Mitarbeiter und entscheidet gemäß der Unternehmensrichtlinie über die Freigabe. Er nutzt Gemini-Modelle über Vertex AI zur Logikverarbeitung. Die Anforderungen sind:

• Routinemäßige Ansprüche unter 50 Dollar automatisch freigeben
• Doppelte Einreichungen erkennen
• Auf ungewöhnliche Muster wie Ausgaben am Wochenende oder unbekannte Lieferanten hinweisen
• Unsichere Fälle an menschliche Prüfer weiterleiten

eine strenge Sicherheitsregel: Genehmigen Sie niemals automatisch etwas im Wert von über 50 $

Voraussetzungen

Stellen Sie sicher, dass Folgendes installiert ist:

# Required tools
Python 3.11+
uv package manager
Node.js (for skills installation)
Google Cloud SDK (gcloud)

Sie benötigen außerdem ein Google Cloud-Projekt mit aktivierter Rechnungsfunktion, das Sie in der Google Cloud-Konsole erstellen können.

Installieren Sie das Toolkit:

uvx google-agents-cli setup

Dann melden Sie sich bei Google Cloud an, legen Sie Ihr Projekt fest und aktivieren Sie die erforderlichen APIs:

# Authenticate with Google Cloud
gcloud auth application-default login
# Set your project ID
gcloud config set project YOUR_PROJECT_ID
# Enable required APIs
gcloud services enable aiplatform.googleapis.com
gcloud services enable run.googleapis.com
gcloud services enable artifactregistry.googleapis.com

Dadurch wird der Zugriff von Vertex AI für den Agenten konfiguriert, der die Gemini-Modelle über die Vertex AI API aufrufen wird.

Schritt 1: Projektstruktur erstellen

Anstatt Verzeichnisse und Konfigurationsdateien manuell zu erstellen, lässt sich die vollständige Projektstruktur durch die CLI generieren.

Mit einem Programmierassistenten wie Gemini CLI, Claude oder Cursor reicht bereits eine Anfrage aus:

Build an expense approval agent using agents-cli.
Auto-approve under $50, flag duplicates, escalate suspicious cases.
Start with a prototype.

Der Assistent liest die installierten Fähigkeiten und erstellt ein Projekt mit der richtigen Struktur. Der manuelle Weg besteht aus drei Befehlen:

agents-cli create expense-agent --prototype --yes
cd expense-agent
agents-cli install

Die Flagge --prototype ist wichtig. Sie erzeugt nur den Agenten-Code sowie die Teststruktur und lässt Deployment-Elemente wie Docker, Terraform und CI/CD aus, die später hinzukommen. Die erzeugte Struktur sieht so aus:

expense-agent/
├── app/
│   ├── agent.py          # Agent definition
│   └── app_utils/        # Telemetry helpers
├── tests/
│   ├── eval/
│   │   ├── evalsets/     # Test cases for LLM-as-judge
│   │   └── eval_config.json
│   ├── integration/
│   └── unit/
├── pyproject.toml        # Dependencies managed by uv
└── GEMINI.md             # Guidance for coding agents

Schritt 2: Die Geschäftslogik schreiben

Danach implementieren Sie die Freigabelogik in app/agent.py. In ADK, wie auch in den meisten Agentenframeworks, sind die Tools einfache Python-Funktionen. Die Dokumentation ist entscheidend, da das Modell sie liest, um zu bestimmen, wann und wie jedes Tool aufgerufen werden soll.

Tool 1: Ausgabenhistorie überprüfen.

import json
from adk.models import Gemini
from adk.agents import Agent

def check_expense_history(
    employee_id: str,
    vendor: str,
    date: str,
    amount: float
) -> str:
    """Check if this expense was already submitted.
    Args:
        employee_id: Employee identifier
        vendor: Vendor name
        date: Expense date (YYYY-MM-DD)
        amount: Expense amount in USD
    Returns:
        JSON string with duplicate check results
    """
    # In production, this would query your expense database
    # Using mock data for demonstration
    mock_history = [
        {"date": "2026-04-15", "vendor": "Coffee Shop", "amount": 8.50},
        {"date": "2026-04-15", "vendor": "Uber", "amount": 24.00},
    ]
    for past in mock_history:
        if (past["vendor"].lower() == vendor.lower() and
            past["date"] == date and
            abs(past["amount"] - amount) < 0.01):
            return json.dumps({
                "is_duplicate": True,
                "message": f"Duplicate found: ${amount} at {vendor} on {date}"
            })
    return json.dumps({
        "is_duplicate": False,
        "message": "No duplicate found"
    })

Werkzeug 2: Unternehmensrichtlinien abrufen.

def get_company_policy(category: str) -> str:
    """Retrieve expense policy for a given category.Args:
        category: Expense category (meals, transport, lodging, etc.)
    Returns:
        JSON string with policy rules
    """
    policies = {
        "meals": {"auto_approve_threshold": 50.00},
        "transport": {"auto_approve_threshold": 50.00},
        "lodging": {"auto_approve_threshold": 0.00},  # Always escalate
        "default": {"auto_approve_threshold": 25.00}
    }
    policy = policies.get(category.lower(), policies["default"])
    return json.dumps(policy)

Werkzeug 3: An einen Menschen weiterleiten.

def escalate_to_human(
    expense_id: str,
    reason: str,
    context: str
) -> str:
    """Route expense to human approval queue.Args:
        expense_id: Unique expense identifier
        reason: Why this needs human review
        context: Additional context for reviewer
    Returns:
        Confirmation message
    """
    # In production, this creates a ticket or notification
    print(f"\n🚨 ESCALATED: {expense_id}")
    print(f"Reason: {reason}\n")
    return json.dumps({
        "status": "escalated",
        "ticket_id": f"REVIEW-{expense_id}"
    })

Dann werden die Werkzeuge an einen Agenten angeschlossen, der klare Anweisungen sowie Sicherheitsbeschränkungen erhält:

root_agent = Agent(
    name="expense_approval_agent",
    model=Gemini(model="gemini-3.1-pro-preview"),  # Using Vertex AI
    instruction="""You are an expense approval agent. Review expenses and make
    approval decisions based on company policy.
    Process for every expense:
    1. Call get_company_policy() to check the category threshold
    2. Call check_expense_history() to verify no duplicate exists
    3. Make a decision: AUTO_APPROVE, ESCALATE, or REJECT
    Auto-approve only if ALL of these conditions are true:
    - Amount is under the threshold for that category
    - No duplicate found in expense history
    - Expense is from a business day (Monday-Friday)
    - Vendor appears legitimate
    Escalate to human if ANY of these conditions are true:
    - Amount is over the category threshold
    - Duplicate submission detected
    - Weekend expense without clear business justification
    - Uncertain about vendor legitimacy
    - Category is "lodging" (always requires human review)
    Safety rules (NEVER violate these):
    - NEVER auto-approve any expense over $50
    - NEVER approve without checking for duplicates first
    - ALWAYS provide clear reasoning for your decision
    - When in doubt, ESCALATE (false escalation is better than false approval)
    Response format:
    Decision: [AUTO_APPROVE | ESCALATE | REJECT]
    Reasoning: [Clear explanation of why you made this decision]
    Tools called: [Which tools you used]
    """,
    tools=[check_expense_history, get_company_policy, escalate_to_human],
)

Achten Sie genau auf die Sicherheitsregeln in den Anweisungen. Auch wenn die Richtlinien eine Freigabe von Mahlzeiten bis zu 50 Dollar zulassen würden, gilt eine feste Obergrenze: Der Agent genehmigt niemals automatisch etwas über 50 Dollar ohne menschliche Überprüfung. Dadurch werden teure Fehler verhindert.

Schritt 3: lokal testen

Starten Sie das ADK Playground:

agents-cli playground

Es öffnet eine Web-Oberfläche auf localhost Port 8080. Drei Fälle behandeln die Grundlagen.

Routinemäßige Freigabe.

Review this expense:
Employee: emp-123
Category: meals
Vendor: Coffee Shop
Date: 2026-04-18
Amount: $12.50

Erwartetes Verhalten: Der Agent ruft get_company_policy() auf, erkennt eine Schwellenwert von 50 $, ruft check_expense_history() auf, findet keine Duplikate und genehmigt die Ausgabe.

Über der Schwellenwertgrenze.

Review this expense:
Employee: emp-456
Category: meals
Vendor: Restaurant
Date: 2026-04-18
Amount: $85.00

Erwartetes Verhalten: Der Agent leitet die Angelegenheit weiter, da der Betrag 50 $ überschreitet.

Doppelte Einreichung.

Review this expense:
Employee: emp-789
Category: transport
Vendor: Uber
Date: 2026-04-15
Amount: $24.00

Erwartetes Verhalten: Der Agent findet die Duplikate in der Simulationshistorie und leitet sie weiter.

Manuelle Tests belegen den erfolgreichen Ablauf. Für die Einsatzbereitschaft in der Produktion ist etwas Systematischeres erforderlich.

Schritt 4: strukturierte Bewertungen

Die meisten Entwickler überspringen diesen Schritt, was ein Hauptgrund dafür ist, dass Agenten in der Produktion versagen. Es sind Testfälle mit klaren Bestehens- oder Scheiterrichtlinien notwendig. Die Frage lautet nicht „Fühlt sich das richtig an?“, sondern „Erfüllt es die Richtlinien?“

Ändern Sie tests/eval/evalsets/basic.evalset.json:

{
  "eval_set_id": "expense_approval_eval",
  "name": "Expense Policy Validation",
  "eval_cases": [
    {
      "eval_id": "routine_approval",
      "conversation": [
        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-101, meals, Coffee Shop, 2026-04-18, $15.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["get_company_policy", "check_expense_history"],
      "expected_output_keywords": ["approve", "approved"]
    },
    {
      "eval_id": "escalate_over_threshold",
      "conversation": [
        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-102, meals, Restaurant, 2026-04-18, $85.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["get_company_policy", "escalate_to_human"],
      "expected_output_keywords": ["escalate", "human review"]
    },
    {
      "eval_id": "reject_duplicate",
      "conversation": [
        {
          "user_content": {
            "parts": [{
              "text": "Review: emp-103, transport, Uber, 2026-04-15, $24.00"
            }]
          }
        }
      ],
      "session_input": {
        "app_name": "app",
        "user_id": "eval_user",
        "state": {}
      },
      "expected_tool_calls": ["check_expense_history"],
      "expected_output_keywords": ["duplicate", "escalate"]
    }
  ]
}

Führen Sie die Bewertung aus:

agents-cli eval run

Beispielausgabe:

Running expense_approval_eval...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ routine_approval       policy_compliance: 1.0  safety: 1.0  tool_usage: 1.0
✓ escalate_over_threshold   policy_compliance: 1.0  safety: 1.0  tool_usage: 1.0
✓ reject_duplicate       policy_compliance: 0.9  safety: 1.0  tool_usage: 0.9
Overall Pass Rate: 100% (3/3 cases)
Average Scores: policy_compliance=0.97, safety=1.0, tool_usage=0.97

Die Bewertung wird von einem LLM durchgeführt, das als Richter fungiert und dabei die Kriterien aus eval_config.json verwendet. Wenn ein Fall fehlschlägt, wird die Anweisung des Agenten oder die Logik der Tools so lange angepasst, bis alle Fälle bestehen.

Dieser Zyklus ist die eval-fix-Schleife – der Schlüssel zu zuverlässigen Produktionsagenten. Ohne Bewertungen hofft man nur, dass der Agent funktioniert; mit ihnen weiß man es.

Schritt 5: Bereitstellung

Der Agent funktioniert und bestehen alle Bewertungen, daher ist es Zeit für die Bereitstellung. Zuerst fügen Sie die Bereitstellungsinfrastruktur hinzu:

agents-cli scaffold enhance --deployment-target cloud_run

Dadurch wird ein Dockerfile, eine Cloud Run-Deployment-Konfiguration sowie Terraform-Dateien erzeugt. Anschließend wird das Projekt festgelegt und bereitgestellt:

gcloud config set project YOUR_PROJECT_ID
agents-cli deploy

Erwarten Sie eine Ausgabe in dieser Art:

Building container image...
Pushing to us-central1-docker.pkg.dev/your-project/agents/expense-agent...
Deploying to Cloud Run...
✓ Deployment successful!
Service URL: https://expense-agent-xyz123-uc.a.run.app
Logs: https://console.cloud.google.com/run/detail/.../logs

Die angegebene Gesamtzeit von agents-cli create bis zur Verfügbarkeit des Services beträgt etwa 30 Minuten, wobei Ihre erste Ausführung von der Kontoeinrichtung und den Berechtigungen abhängt.

Schritt 6: Überwachbarkeit

Cloud Trace wird ohne weitere Konfiguration automatisch aktiviert. Um den bereitgestellten Agenten auszuprobieren:

agents-cli run "Review expense: emp-501, transport, Uber, 2026-04-18, $15.00"
agents-cli run "Review expense: emp-502, meals, Restaurant, 2026-04-18, $95.00"
agents-cli run "Review expense: emp-503, lodging, Hilton, 2026-04-18, $200.00"

Dann öffnen Sie Cloud Trace, um Folgendes zu sehen:

• vollständige Anfragenverläufe mit einer Aufschlüsselung der Latenz
• die Dauer jeder LLM-Aufruf
• die Ausführungszeiten der Tools
• eine End-to-End-Zeitlinie für jede Anfrage

Zur Fehlersuche und Analyse schalten Sie das Protokollieren von Inhalten ein:

agents-cli infra single-project --project YOUR_PROJECT_ID

Dies stellt ein Service-Konto für das Protokollieren, einen Cloud Storage-Container für die Speicherung von Eingaben und Antworten, ein BigQuery-Datensatz für Analysen sowie eine Funktion bereit, damit der Agent jede Konversation protokolliert. Anschließend können Sie das Produktivverhalten in BigQuery abfragen:

SELECT
  timestamp,
  JSON_EXTRACT_SCALAR(request_data, '$.user_content.parts[0].text') as request,
  JSON_EXTRACT_SCALAR(response_data, '$.decision') as decision,
  latency_ms
FROM `your-project.agent_analytics.conversations`
WHERE service_name = 'expense-agent'
ORDER BY timestamp DESC
LIMIT 10;

Dies ist für das Debuggen von entscheidender Bedeutung. Wenn jemand fragt, warum der Agent eine Mahlzeit im Wert von 30 Dollar priorisiert hat, können Sie BigQuery abfragen, um genau zu erfahren, was es entschieden hat und warum.

Was das Toolset auszeichnet

Vier Gestaltungsentscheidungen heben sich hervor.

1. Fähigkeiten als maschinenlesbarer Kontext. Agents CLI bietet mehr als nur Befehle. Es stellt Fähigkeiten bereit, die Ihrem Programmierassistenten beibringen, sie richtig zu verwenden. Durch Ausführung von agents-cli setup werden sieben davon installiert:

• google-agents-cli-workflow für den Entwicklungslebenszyklus
• google-agents-cli-adk-code für ADK Python API-Muster
• google-agents-cli-scaffold für Projekt-Scaffolding
• google-agents-cli-eval für Evaluierungsmethoden
• google-agents-cli-deploy für Bereitstellungsziele

google-agents-cli-publish zur Registrierung in Gemini Enterprise

google-agents-cli-observability für Tracing und Logging

Der Assistent wendet sie bei Bedarf an. Anstatt zu raten, weiß er, wann Agent Runtime, Cloud Run oder GKE gewählt werden sollen, und er kennt die geeigneten Muster mit LLM als Urteilsinstanz, sodass es keine Versuche und Fehler bei den Bewertungsmetriken gibt.

2. Bewertung standardmäßig. Jedes vorgefertigte Projekt enthält von Anfang an Infrastruktur für die Bewertung: ein Verzeichnis tests/eval/evalsets/ für Testfälle, eval_config.json für Bewertungskriterien sowie eine Einrichtung mit LLM als Urteilsinstanz. Das spiegelt die Realität wider, da Agenten ohne Bewertung selten in die Produktion gelangen, und indem die Bewertung zum Standardweg wird, werden die Agenten vor dem Deployment getestet.

3. Beobachtbarkeit standardmäßig aktiviert. Cloud Trace wird automatisch auf jedem bereitgestellten Agenten eingeschaltet. Das Debuggen eines Produktionsagenten ohne Aufzeichnungen ist nahezu unmöglich. Die Inhaltsprotokollierung sowie die Analyse mit BigQuery sind über agents-cli infra single-project optional, doch die grundlegende Trace-Funktion ist zwingend erforderlich.

4. Die Infrastruktur wird für Sie erledigt. Die Logik des Agenten ist interessant – Docker-Konfigurationen, Authentifizierungs-Middleware sowie Terraform-Dateien hingegen nicht. Die CLI übernimmt die Infrastruktur, sodass Sie sich auf die Optimierung des Agenten konzentrieren können.

Weiterführende Informationen

Der Ausgabenagent erfüllt die genannten Anforderungen, doch eine echte Bereitstellung erfordert noch einige weitere Komponenten.

Live-Daten. Ersetzen Sie die künstlich erzeugte Historie durch Abfragen in Ihrer Ausgaben-Datenbank:

import psycopg2

def check_expense_history(employee_id, vendor, date, amount):
    conn = psycopg2.connect(DATABASE_URL)
    cursor = conn.cursor()
    cursor.execute("""
        SELECT * FROM expenses
        WHERE employee_id = %s
        AND vendor = %s
        AND date = %s
        AND amount = %s
    """, (employee_id, vendor, date, amount))
    # Process results...

CI/CD. Erstellen Sie einen GitHub Actions Workflow für die Staging- und Produktivumgebung:

agents-cli infra cicd --runner github-actions

Es erstellt ein Mehrumgebungs-Pipeline-System, bei dem Committs an main in die Staging-Umgebung bereitgestellt werden und mit Tags versehene Veröffentlichungen in die Produktionsumgebung.

Sitzungsspeicherung. Fügen Sie Cloud SQL hinzu, um dauerhafte Sitzungen zu ermöglichen:

agents-cli scaffold enhance --session-type cloud_sql

Mehre-Agenten-Systeme. Das adk_a2a-Template ermöglicht es spezialisierten Agenten, sich zu koordinieren – was für komplexe Arbeitsabläufe wie die Incidentsuche oder Code-Migrationen geeignet ist:

agents-cli create coordinator-agent --agent-type adk_a2a

Retrieval-augmented Generation. Erstellen Sie einen Agenten mit Vektorsuche:

agents-cli create docs-agent \
  --agent-type agentic_rag \
  --datastore agent_platform_vector_search

Das erzeugt Code zur Dateneingabe, Integration einer Vektorsuche sowie Logik zur Datenabrufung.

Kurze Übersicht der Techniken

Jede der hier beschriebenen Techniken bezieht sich auf eine bestimmte Phase des Lebenszyklus: ein Gerüst mit einem Prototypen-Flag für schnelles Starten, Tools als dokumentierte Python-Funktionen, strenge Sicherheitsbeschränkungen in den Anweisungen, Tests in einem lokalen Umfeld, strukturierte Bewertungen mit einer Korrekturlaufschleife, generierte Infrastruktur für die Bereitstellung sowie Trace-Logging und Inhaltserfassung zur Überwachbarkeit. Zusammen bilden sie einen Weg vom Prototypen bis zur Produktion.

Fazit

Die Lücke bei der Bereitstellung ist real. Viele Agentenprojekte stocken nicht, weil die Agenten selbst schlecht sind, sondern weil ihre Veröffentlichung zu viel Infrastrukturarbeit erfordert.

Agents CLI löst nicht alles. Man benötigt weiterhin gut gestaltete Anfragen, geeignete Tools sowie gründliche Tests. Was es jedoch beseitigt, ist die infrastrukturelle Aufwandarbeit, die Agenten in Entwicklungsumgebungen gefangen hält. Das Ziel ist es, dass Agentenworkflows sich wie das Ausführen von create-react-app anfühlen und nicht wie das manuelle Aufbauen von Infrastruktur.