Od prototypu do produkcji za pomocą Agents CLI: Agent do zatwierdzania wydatków

Każdy, kto ostatnio próbował wysłać agenta AI, zna ten schemat. W fazie rozwoju zachowuje się tak: odpowiada na pytania, wykorzystuje odpowiednie narzędzia, podejmuje rozsądne decyzje. Potem ktoś pyta, kiedy może wejść do produkcji, a dni mija na konfiguracji Dockera, uwierzytelnianiu, monitorowaniu oraz procesach wdrażania.

Kod agenta został napisany w ciągu kilku godzin. Infrastruktura niezbędna do jego działania wymaga tygodni.

Poniżej znajduje się opis krok po kroku budowy i wdrażania agenta w stylu produkcyjnym za pomocą Agents CLI – narzędzia otwartego oprogramowania przeznaczonego do przejęcia tego procesu wdrażania. Przykładem jest agent do zatwierdzania wydatków, zawierający reguły biznesowe, mechanizmy oceny oraz rozwiązanie do wdrażania w chmurze; według informacji dostarczonych przez to narzędzie cały proces trwa w przybliżeniu pół godziny. Traktuj tę wartość jako najlepszy możliwy wynik w przypadku dobrze przygotowanego konta.

Luka wdrożeniowa

Budowa agenta za pomocą Agent Development Kit (ADK), LangChain lub LlamaIndex jest dość prosta. Prawdziwe wyzwanie pojawia się przy wprowadzeniu go do produkcji. Agent produkcyjny zazwyczaj wymaga wszystkich poniższych elementów.

Rozwój lokalny

• kod agenta, który stanowi najważniejszą część
• lokalne środowisko do testowania
• dane symulacyjne lub stuby API

Testowanie i ocena

• definicje przypadków testowych
• metryki i kryteria oceny
• konfiguracja wykorzystująca LLM jako sędziego
• zestaw testów regresji

Infrastruktura produkcyjna

• obraz kontenera
• konfiguracja wdrażania w chmurze, np. dla Cloud Run lub Kubernetes
• autoryzacja i uwierzytelnianie
• zarządzanie sekretami
• proces CI/CD

Obserwowalność

• śledzenie zapytań
• rejestracja promptów i odpowiedzi

Śledzenie kosztów i analiza danych

Nadzór wydajności

Ostrzeżenia o błędach

Każdy z tych elementów oznacza konieczność nauczenia się nowego narzędzia, przeczytania innego zestawu dokumentacji oraz połączenia oddzielnych systemów. Asystent do programowania może pomóc w logice agenta, ale ma trudności z jego wdrożeniem, ponieważ nie zna konwencji używanych w infrastrukturze, co skutkuje seriami debugowania.

Czym jest Agents CLI

Agents CLI to zestaw narzędzi oferujący jedną interfejs do całego cyklu życia rozwoju agentów w Google Cloud. Działa w dwóch trybach.

1. Tryb agenta. Instaluje się „umiejętności” w asystencie do programowania, takim jak Gemini CLI, Claude Code lub Cursor. Te umiejętności uczą asystenta wzorców wdrażania, dzięki czemu podejmuje on prawidłowe decyzje.

Tryb ręczny. Samodzielnie wykonywane są polecenia CLI. Każde polecenie działa niezależnie i nie jest potrzebny żaden asystent AI.

Główna idea polega na tym, że zamiast asystenta zgadującego co do konwencji wdrażania, otrzymuje się tekst czytelny przez maszynę, który informuje o tym, kiedy używać każdego celu wdrażania, jak strukturyzować oceny oraz które wzorce obserwowalności działają najlepiej.

Przykład: agent zatwierdzający wydatki

Agent przegląda raporty wydatków pracowników i decyduje o ich zatwierdzeniu zgodnie z polityką firmy. Do rozumowania wykorzystuje modele Gemini poprzez Vertex AI. Wymagania:

• automatyczne zatwierdzanie rutynowych wniosków o wartości poniżej 50 dolarów
• wykrywanie duplikatów wniosków
• sygnalizowanie nieprawidłowości, takich jak wydatki z weekendu lub nieznani dostawcy
• przekazywanie niepewnych przypadków do ludzkich recenzentów

jedna ścisła zasada bezpieczeństwa: nigdy nie zatwierdzaj automatycznie niczego powyżej 50 dolarów

Wymagania wstępne

Upewnij się, że są zainstalowane:

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

Potrzebujesz również projektu w Google Cloud z włączoną fakturacją, który można stworzyć w konsoli Google Cloud.

Zainstaluj zestaw narzędzi:

uvx google-agents-cli setup

Następnie zaloguj się do Google Cloud, ustaw swój projekt i włącz wymagane API:

# 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

To konfiguruje dostęp do Vertex AI dla agenta, który będzie wywoływał modele Gemini za pośrednictwem API Vertex AI.

Krok 1: stworzenie szkieletu projektu

Zamiast ręcznie tworzyć katalogi i pliki konfiguracyjne, niech CLI wygeneruje pełną strukturę projektu.

Z pomocą asystenta programistycznego takiego jak Gemini CLI, Claude lub Cursor wystarczy jedno polecenie:

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

Asystent czyta zainstalowane umiejętności i tworzy projekt o odpowiedniej strukturze. Ręczna metoda polega na użyciu trzech poleceń:

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

Flaga --prototype ma znaczenie. Generuje ona jedynie kod agenta oraz strukturę testów, pomijając elementy związane z wdrożeniem, takie jak Docker, Terraform i CI/CD, które są dodawane później. Wygenerowana struktura wygląda w ten sposób:

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

Krok 2: napisanie logiki biznesowej

Następnie zaimplementuj logikę zatwierdzania w pliku app/agent.py. W ADK, podobnie jak w większości frameworki agentowych, narzędzia to zwykłe funkcje w Pythonie. Dokumentacja jest kluczowa, ponieważ model czyta ją, aby zdecydować, kiedy i w jaki sposób wywołać każde narzędzie.

Narzędzie 1: sprawdzenie historii wydatków.

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"
    })

Narzędzie 2: pobrać politykę firmy.

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)

Narzędzie 3: skontaktuj się z pracownikiem.

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}"
    })

Następnie narzędzia są podłączane do agenta z jasnymi instrukcjami i ograniczeniami bezpieczeństwa:

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

Przyjrzyj się uważnie zasadom bezpieczeństwa podanym w instrukcjach. Nawet jeśli zasady pozwalają na zatwierdzenie posiłku do wartości 50 dolarów, obowiązuje sztywny limit: agent nigdy nie zatwierdza automatycznie żadnej transakcji przekraczającej 50 dolarów bez sprawdzenia przez człowieka. Dzięki temu unika się drogich błędów.

Krok 3: testowanie lokalnie

Rozpocznij środowisko ADK:

agents-cli playground

Otwiera interfejs internetowy na localhost pod portem 8080. Trzy przypadki obejmują podstawy.

Zwykła akceptacja.

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

Oczekiwane zachowanie: agent wywołuje get_company_policy(), widzi próg 50 dolarów, wywołuje check_expense_history(), nie znajduje żadnych duplikatów i zatwierdza transakcję.

Powyżej progu.

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

Oczekiwane zachowanie: agent przenosi sprawę na wyższy poziom, ponieważ kwota przekracza 50 dolarów.

Podwójne zgłoszenie.

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

Oczekiwane zachowanie: agent znajduje duplikat w symulowanej historii i przekazuje sprawę do wyższych instancji.

Testy ręczne potwierdzają poprawne funkcjonowanie w optymalnych warunkach. Gotowość do użycia w produkcji wymaga bardziej systematycznego podejścia.

Krok 4: strukturyzowane oceny

Większość programistów pomija ten krok, co jest główną przyczyną awarii agentów w środowisku produkcyjnym. Potrzebne są przypadki testowe z jasno określonymi kryteriami sukcesu lub niepowodzenia. Pytanie brzmi nie „czy to wydaje się słuszne?”, ale „czy spełnia to zasady?”

Zedytuj plik 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"]
    }
  ]
}

Rozpocznij ocenę:

agents-cli eval run

Przykład wyniku:

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

Ocena jest przeprowadzana przez model językowy działający jako sędzia, który korzysta z kryteriów określonych w pliku eval_config.json. Gdy jakiś przypadek nie zostanie przebrany, modyfikuje się instrukcje agenta lub logikę narzędzi, aż wszystkie przypadki zostaną przebrane.

Ten cykl to pętla eval-fix, klucz do niezawodnych agentów produkcyjnych. Bez ocen polega się na nadziei, że agent będzie działał poprawnie, natomiast dzięki nim ma się pewność.

Krok 5: wdrożenie

Agent działa poprawnie i przechodzi wszystkie oceny, więc nadszedł czas na jego wdrożenie. Najpierw należy dodać infrastrukturę niezbędną do wdrożenia:

agents-cli scaffold enhance --deployment-target cloud_run

To generuje plik Dockerfile, konfigurację wdrożenia Cloud Run oraz pliki Terraform. Następnie ustaw projekt i przeprowadź wdrożenie:

gcloud config set project YOUR_PROJECT_ID
agents-cli deploy

Oczekuj wyniku w takim kształcie:

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

Podobno całkowity czas od wywołania agents-cli create do uruchomienia usługi wynosi około 30 minut, chociaż czas pierwszego uruchomienia zależy od ustawień konta i uprawnień.

Krok 6: możliwości obserwacji

Cloud Trace jest włączany automatycznie, bez konieczności konfiguracji. Aby przetestować zainstalowany agent:

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"

Następnie otwórz Cloud Trace, aby zobaczyć:

• pełne ślady żądań wraz z podziałem na opóźnienia
• czas trwania każdej wywołania LLM
• CZasy wykonywania narzędzi
• horyzont czasowy od początku do końca dla każdej żądania

Dla debugowania i analizy włącz logowanie treści:

agents-cli infra single-project --project YOUR_PROJECT_ID

To zapewnia konto usługowe do rejestrowania, pojemnik Cloud Storage do przechowywania wiadomości i odpowiedzi, zestaw danych BigQuery do analiz oraz aktualizację umożliwiającą agentowi rejestrowanie każdej rozmowy. Następnie można przeprowadzać zapytania dotyczące zachowania w produkcji w BigQuery:

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;

To jest kluczowe przy debugowaniu. Gdy ktoś pyta, dlaczego agent awansował zamówienie o wartości 30 dolarów, sprawdzasz BigQuery i widzisz dokładnie, co zdecydował i dlaczego.

Co wyróżnia ten zestaw narzędzi

Cztery wybory projektowe wyróżniają się szczególnie.

1. Umiejętności jako kontekst czytelny dla maszyn. Agents CLI oferuje coś więcej niż tylko polecenia. Dostarcza umiejętności, które uczą twojego asystenta programistycznego ich prawidłowego używania. Uruchomienie agents-cli setup instaluje siedem z nich:

• google-agents-cli-workflow do cyklu życia rozwoju
• google-agents-cli-adk-code do wzorców API ADK w Pythonie
• google-agents-cli-scaffold do tworzenia szkieletów projektów
• google-agents-cli-eval do metodologii oceny
• google-agents-cli-deploy do celów implementacji

google-agents-cli-publish do rejestracji w Gemini Enterprise

google-agents-cli-observability do śledzenia i logowania

Asystent korzysta z nich w odpowiednich sytuacjach. Zamiast zgadywać, wie, kiedy wybrać Agent Runtime, Cloud Run lub GKE, a także jakie wzory z użyciem LLM-as-judge są skuteczne, dzięki czemu nie ma konieczności prób i błędów przy mierzeniu wyników.

2. Ocena jako standard. Każdy projekt zawiera od początku infrastrukturę do oceny: folder tests/eval/evalsets/ z przykładami przypadków, plik eval_config.json z kryteriami oceny oraz konfigurację LLM-as-judge. To odzwierciedla rzeczywistość, ponieważ agenci bez mechanizmów oceny rzadko trafiają do produkcji, a ustanowienie oceny jako standardowego kroku oznacza, że agenci są testowane przed wdrożeniem.

3. Obserwowalność jako standard. Cloud Trace jest automatycznie włączany na każdym zainstalowanym agencie. Naprawianie błędów w agencie używanym w produkcji bez śladów jest niemal niemożliwe. Logowanie treści oraz analizy w BigQuery są dostępne opcjonalnie za pomocą polecenia agents-cli infra single-project, ale podstawowe śledzenie jest obowiązkowe.

4. Infrastruktura za Ciebie. Logika agenta jest interesująca, natomiast konfiguracje Dockera, komponenty autoryzacji oraz pliki Terraform nie. Interfejs CLI zajmuje się infrastrukturą, dzięki czemu możesz poświęcić czas na ulepszenie funkcjonalności agenta.

Kroki dalej

Agent do zarządzania wydatkami spełnia podane wymagania, ale rzeczywista implementacja wymaga kilku dodatkowych elementów.

Dane w czasie rzeczywistym. Zastąp symulowaną historię zapytaniem do bazy danych z danymi o wydatkach:

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. Stwórz workflow w GitHub Actions dla środowiska staging i produkcyjnego:

agents-cli infra cicd --runner github-actions

Tworzy pipeline wielośrodowiskowy, w którym komitety do main są rozprzestrzeniane na środowisko staging, a wydania oznaczone tagami – na środowisko produkcyjne.

Zapis sesji. Dodaj Cloud SQL dla trwałych sesji:

agents-cli scaffold enhance --session-type cloud_sql

Systemy wieloagentowe. Szablon adk_a2a umożliwia specjalistycznym agentom współpracę, co jest przydatne w złożonych procesach pracy, takich jak reagowanie na incydenty czy migracje kodu:

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

Generowanie wzbogacone wydobywaniem informacji. Stwórz agenta przy użyciu wyszukiwania wektorowego:

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

To generuje kod do pobierania danych, integrację z wyszukiwaniem wektorowym oraz logikę odzyskiwania informacji.

Techniki w skrócie

Każda z tych technik jest przeznaczona do jednego etapu cyklu życia: tworzenie szkieletu z flagą prototypu umożliwiającą szybki start, narzędzia w postaci udokumentowanych funkcji Pythona, ścisłe ograniczenia bezpieczeństwa w instrukcjach, testy w lokalnym środowisku, strukturyzowane oceny z pętlą korygującą, generowana infrastruktura do wdrożenia oraz śledzenie i logowanie treści dla lepszej widoczności. Razem tworzą one ścieżkę od prototypu do produkcji.

Główny wniosek

Różnica wdrożeniowa jest rzeczywista. Wiele projektów agentów utyka nie dlatego, że sam agent jest słaby, ale dlatego, że jego wdrożenie wymaga zbyt dużo pracy nad infrastrukturą.

Agent CLI nie rozwiązuje wszystkiego. Nadal potrzebne są dobrze zaprojektowane polecenia, odpowiednie narzędzia oraz dokładne testy. To, co faktycznie eliminuje, to pracochłonne zadania związane z infrastrukturą, które utrzymują agenty w środowiskach rozwojowych. Celem jest, aby prace z agentami wyglądały jak uruchamianie create-react-app, a nie jak ręczne budowanie infrastruktury.