Від прототипу до виробництва за допомогою Agents CLI: Агент для схвалення витрат

Кожен, хто нещодавно намагався розіслати AI-агента, знає цю схему. Під час розробки він поводиться так: відповідає на запитання, використовує потрібні інструменти, робить обґрунтовані вибори. Потім хтось запитує, коли він може почати працювати, і дні проходять у Docker, автентифікації, моніторингу та процесах розгортання.

Написання коду агента зайняло кілька годин. А інфраструктура навколо нього — кілька тижнів.

Далі йде пошагове опис створення та розгортання агента у продакшн-режимі за допомогою Agents CLI — інструментарію з відкритим кодом, призначеного для автоматизації цих процесів. Прикладом є агент для схвалення витрат із бізнес-правилами, оцінками та розгортанням у хмарі; за твердженням розробників інструментарію, весь процес займає приблизно півгодини. Вважайте це оптимальним результатом для підготовленого облікового запису.

Розрив у розгортанні

Створення агента за допомогою Agent Development Kit (ADK), LangChain чи LlamaIndex є досить простим. Справжня складність починається під час впровадження його у продакшн. Для роботи в продакшені агент зазвичай потребує всього наступного.

Локальна розробка

• код агента, який є найцікавішою частиною
• локальна налаштованість для тестування
• мок-дані чи штучні API

Тестування та оцінка

• визначення випадків тестування
• метрики та критерії оцінювання
• налаштування використання LLM як судді
• набір тестів на виявлення змін

Інфраструктура продакшену

• образ контейнера
• налаштування розгортання в хмарі, наприклад для Cloud Run чи Kubernetes
• автентифікація та авторизація
• керування секретами
• пайплайн CI/CD

Оперативне спостереження

• відстеження запитів
• логування запитів та відповідей

відстеження та аналіз витрат

моніторинг продуктивності

сповіщення про помилки

Кожен з цих елементів означає необхідність опанування ще одного інструменту, читання ще одного набору документації та поєднання окремих систем. Асистент для програмування може допомогти з логікою агента, але має труднощі з розгортанням, оскільки не знає стандартів вашої інфраструктури, що призводить до необхідності багатьох раундів виправлення помилок.

Що таке Agents CLI

Agents CLI — це набір інструментів, який пропонує єдиний інтерфейс для всього життєвого циклу розробки агентів у Google Cloud. Він працює у двох режимах.

1. Режим агента. Ви встановлюєте „навички“ у асистента для програмування, такого як Gemini CLI, Claude Code чи Cursor. Ці навички навчають асистента шаблонам розгортання, щоб він приймав правильні рішення.

Ручний режим. Ви самі виконуєте команди CLI. Кожна команда працює окремо, і жоден штучний інтелект не потрібен.

Основна ідея полягає у тому, що замість того, щоб асистент вгадував правила розгортання, він отримує машинночитабельний контекст про те, коли використовувати кожну мету розгортання, як структурувати оцінки та які шаблони спостережуваності є найефективнішими.

Приклад: агент для схвалення витрат

Агент переглядає звіти працівників про витрати та приймає рішення щодо схвалення відповідно до політики компанії. Для міркувань він використовує моделі Gemini через Vertex AI. Вимоги:

• автоматично схвалювати звичайні заявки на суму до 50 доларів
• виявляти дублікати заявок
• піднімати попередження у разі незвичайних ситуацій, таких як витрати на вихідних чи невідомі постачальники
• передавати сумнівні випадки на розгляд людських експертів

Одне суворе правило безпеки: ніколи не автоматично схвалюйте нічого на суму понад 50 доларів

Передумови

Переконайтеся, що це встановлено:

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

Вам також потрібен проєкт Google Cloud із увімкненим обліком, який можна створити в консолі Google Cloud.

Встановіть інструментальний набір:

uvx google-agents-cli setup

Потім автентифікуйтеся в Google Cloud, виберіть свій проект та увімкніть необхідні 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

Це налаштовує доступ Vertex AI для агента, який буде викликати моделі Gemini через API Vertex AI.

Крок 1: створення схеми проекту

Замість того, щоб вручну створювати каталоги та файли конфігурації, дозвольте CLI сформувати повну структуру проекту.

За допомогою асистента для програмування, такого як Gemini CLI, Claude чи Cursor, достатньо лише запиту:

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

Асистент читає встановлені навички та створює проект із правильною структурою. Ручний спосіб передбачає три команди:

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

Прапорець --prototype має велике значення. Він генерує лише код агента та структуру тестів, залишаючи без уваги елементи розгортання, такі як Docker, Terraform та CI/CD, які додаються пізніше. Структура, що генерується, виглядає ось так:

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

Крок 2: написати бізнес-логіку

Далі реалізуйте логіку схвалення у файлі app/agent.py. У ADK, як і в більшості фреймворків агентів, інструменти є звичайними функціями Python. Документація є критично важливою, оскільки модель читає її, щоб вирішити, коли та як викликати кожен інструмент.

Інструмент 1: перевірити історію витрат.

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

Інструмент 2: отримати політику компанії.

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)

Інструмент 3: звернутися до людини.

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

Потім інструменти підключаються до агента з чіткими інструкціями та обмеженнями щодо безпеки:

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

Уважно перегляньте правила безпеки в інструкції. Навіть якщо політика дозволяє схвалювати закупівлі на суму до 50 доларів, існує жорсткий ліміт: агент ніколи не схвалює автоматично щось понад 50 доларів без людського перегляду. Це запобігає дорогим помилкам.

Крок 3: тестування локально

Запустіть середовище ADK:

agents-cli playground

Він відкриває веб-інтерфейс на localhost порту 8080. Три варіанти охоплюють основи.

Стандартна затвердження.

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

Очікувана поведінка: агент викликає get_company_policy(), бачить поріг у 50 доларів, викликає check_expense_history(), не знаходить дублікатів та схвалює заявку.

Перевищено поріг.

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

Очікувана поведінка: агент піднімає справу на вищий рівень, оскільки сума перевищує 50 доларів.

Подано дублікат.

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

Очікувана поведінка: агент знаходить дублікат у штучній історії та піднімає ситуацію на вищий рівень.

Ручні тести підтверджують правильний хід роботи. Однак для готовності до експлуатації потрібні більш систематичні підходи.

Крок 4: структуровані оцінки

Більшість розробників пропускають цей крок, і це є однією з основних причин несправностей агентів у продакшені. Вам потрібні тест-кейси з чіткими критеріями успіху або невдачі. Питання полягає не у тому, „Чи здається це правильним?“, а у тому, „Чи відповідає це правилам?“

Виправте файл 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"]
    }
  ]
}

Запустіть оцінку:

agents-cli eval run

Приклад результату:

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

Оцінювання здійснюється ШІ, який виступає у ролі судді, керуючись критеріями з файлу eval_config.json. Коли якийсь випадок не проходить, потрібно коригувати інструкції агента чи логіку інструментів, поки всі випадки не будуть пройдені.

Цей цикл називається циклом оцінки та виправлення — ключем до надійних агентів у продакшені. Без оцінок ви лише сподіваєтесь, що агент працює, а з ними ви точно знаєте.

Крок 5: розгортання

Агент працює та проходить усі тести, тож настав час його розгортання. Спочатку додайте інфраструктуру для розгортання:

agents-cli scaffold enhance --deployment-target cloud_run

Це створює Dockerfile, конфігурацію розгортання Cloud Run та файли Terraform. Потім налаштовуйте проект та розгортайте його:

gcloud config set project YOUR_PROJECT_ID
agents-cli deploy

Очікуйте результат у такому форматі:

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

За даними, загальний час від виконання команди agents-cli create до запуску сервісу становить близько 30 хвилин, проте час першого запуску залежатиме від налаштувань облікового запису та прав доступу.

Крок 6: можливість спостереження

Cloud Trace увімкнутий автоматично без необхідності налаштувань. Щоб спробувати використати розгорнутого агента:

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"

Потім відкрийте Cloud Trace, щоб побачити:

• повні трекери запитів із розбивкою за затримками
• тривалість кожного виклику LLM
• час виконання інструментів
• горизонт часу від початку до кінця для кожного запиту

Для відлагодження та аналізу увімкніть журналювання контенту:

agents-cli infra single-project --project YOUR_PROJECT_ID

Це забезпечує обліковий запис сервісу для логування, бакет Cloud Storage для зберігання запитів та відповідей, набір даних BigQuery для аналітики, а також оновлення, яке змушує агента логувати кожну розмову. Після цього ви можете аналізувати поведінку системи у режимі продакшен у 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;

Це має вирішальне значення для виправлення помилок. Коли хтось запитує, чому агент підвищив вартість обіду до 30 доларів, ви запитуєте BigQuery та бачите точно, що він вирішив та чому.

Що робить цей набір інструментів унікальним

Чотири підходи до проектування вирізняються серед інших.

1. Навички як контекст, зрозумілий машинам. Agents CLI пропонує не лише команди. Він надає навички, які навчають вашого асистента з програмування правильно ними користуватися. Виконання команди agents-cli setup встановлює сім з них:

• google-agents-cli-workflow для життєвого циклу розробки
• google-agents-cli-adk-code для шаблонів API ADK Python
• google-agents-cli-scaffold для створення основи проекту
• google-agents-cli-eval для методології оцінки
• google-agents-cli-deploy для цілей розгортання

google-agents-cli-publish для реєстрації Gemini Enterprise

google-agents-cli-observability для відстеження та логування

Асистент звертається до них у відповідних ситуаціях. Замість припущень він знає, коли обирати Agent Runtime, Cloud Run чи GKE, а також які схеми використання LLM як судді є ефективними, тому не виникає ситуацій проб і помилок під час оцінки показників.

2. Оцінка за замовчуванням. Кожен проект містить інфраструктуру для оцінки з самого початку: папку tests/eval/evalsets/ для прикладів, файл eval_config.json з критеріями оцінювання та налаштування LLM як судді. Це відповідає реальності, адже агенти без процедури оцінки рідко потрапляють у продакшн, а зроблення оцінки стандартною процедурою означає, що агенти проходять тестування перед розгортанням.

3. Спостережливість за замовчуванням. Cloud Trace автоматично увімкнений на кожному розгорнутому агенті. Виправлення помилок у продакшн-агенті без запису трекінгу майже неможливе. Логування контенту та аналітика в BigQuery доступні за допомогою команди agents-cli infra single-project, але базовий трекінг є обов’язковим.

4. Інфраструктура обробляється за вас. Логіка агента є цікавою. Конфігурації Docker, проміжки автентифікації та файли Terraform — ні. CLI бере на себе обробку інфраструктури, щоб ви могли присвятити час розробці розумних функцій агента.

Продовження

Агент для обліку витрат відповідає зазначеним вимогам, але для справжнього розгортання потрібні ще деякі елементи.

Живі дані. Замініть штучну історію на запит до вашої бази даних витрат:

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. Створіть workflow GitHub Actions для стейджингу та продакшну:

agents-cli infra cicd --runner github-actions

Він створює конвеєр з кількома середовищами, у якому комітти до main розгортаються у стадійному середовищі, а релізи з позначками — у продакшн-середовищі.

Зберігання сеансів. Додайте Cloud SQL для постійних сеансів:

agents-cli scaffold enhance --session-type cloud_sql

Системи з кількома агентами. Шаблон adk_a2a дозволяє спеціалізованим агентам координувати свої дії, що підходить для складних робочих процесів, таких як реагування на інциденти чи міграція коду:

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

Генерація з підсиленням за допомогою пошуку. Створіть агента з векторним пошуком:

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

Це створює код для обробки даних, інтеграцію векторного пошуку та логіку отримання інформації.

Коротко про методи

Кожен з цих методів спрямований на певну стадію життєвого циклу: створення основи з прапорцем прототипу для швидкого початку роботи, інструменти у вигляді задокументованих функцій Python, суворі обмеження безпеки в інструкціях, тестування у локальному середовищі, структурована оцінка з циклом виправлень, інфраструктура для розгортання та відстеження плюс журналування контенту для прозорості. Разом вони утворюють шлях від прототипу до продакшну.

Висновок

Проблема розгортання існує насправді. Багато проектів з агентами застрягають не через слабкість самого агента, а тому що його розгортання вимагає занадто багато роботи з інфраструктурою.

Agent CLI не вирішує всього. Вам все одно потрібні добре спроєктовані запити, відповідні інструменти та ретельне тестування. Те, що він справді усуває, — це обтяжливі завдання з інфраструктури, які тримають агентів у середовищах розробки. Мета полягає у тому, щоб робочі процеси агентів були схожі на виконання команди create-react-app, а не на ручне створення інфраструктури.