Ад прататыпа да прадакшну з Agents CLI: агент пацвярджэння выдаткаў
Ствараем каркас, тэстуем, ацэньваем і разгортваем агента ADK у Cloud Run праз Agents CLI, з трасіроўкай, лагаваннем у BigQuery, CI/CD і пашырэннямі RAG.
Крыніцы: Building AI Agents in 30 Minutes from Prototype to Production
Кожны, хто нешта часам працаваў над апрабоўкай АІ-агента, ведае такі патэрны. У этапы розработкі ён дзейнаў так: адпавядае на запытанні, выклікае неабходныя інструменты, прымеўа разумныя рашэнні. Потым хтось запытаеся, калі ён зможа пачаць працаваць, і дні прыходзяць у вартас Docker, аутантыкацыі, мэтрыкі працы і працэсаў развярнення.
Напісанне коду агента зайняло каля калькі гадзін. А інфраструктура, якая яго падтрымлівае, — каля некалькі хвілін.
Далей паказана інструкцыя па стварэнні і развярненні агента у прыметнасці продакшну з выкарыстоўванням Agents CLI — адкрытага інструментарыя, які прагчыцца перадзеўсці такую працу з развярнення. Прыкладам ёст агент для затверджэння віткоў, які включае бізнес-правіла, аналізы і развярненне ў воблаку; за тверджэнням самага інструментарыя, весь гэты працэс займае працэйна палову гадзіны. Вважайце гэтыя цыфры оптымальным рэзультатам для падготавленага акаунта.
Разлік у працэсе развярнення
Стварэнне агента за дапамою Agent Development Kit (ADK), LangChain чыра LlamaIndex ўсё ж такі досыта проста. Але справжняя праца почынаецца тады, калі трэба запусціць яго у працэйнай асяроддзі. Для працы ў працэйной асяроддзі агенту зазвычай патрабуюцца всі наступныя элементы.
Локальная разработка
- код агента, які ўтварае галоўную частку
- локальная наладка для тэставання
- мак-даныя чыра API-стабы
Тэставанне і ацэнка
- вызначэння кейсаў тэставання
- метрыкі чыра крытэрыя оцэнкі
- наладка з вікорыстанням LLM як суддзі
- набор для тэставання на рэгрэсію
Інфраструктура для працэйной асяроддзя
- образ кантэйнера
- наладкі для розмешчэння ў воблаку, напрыклад Cloud Run чыра Kubernetes
- аўтэнтыфікацыя чыра автарызацыя
- каральнік секрэтных дадзенняў
- пайплайн CI/CD
Візуабельнасць
- тракарынг запытаў
- логаванне запытанняў чыра адпаведзей
Кожны пункт значыць неабходнасць выучэння ўтолькі новага інструмента, чытання ўтолькі новых інструкцый і сувязвання разлучных сістэм. Памагчык для кодавання можа дапамогць з логікаю агента, але ён мае труднасці з розгортанням, таму што не ведае прыемоў вашай інфраструктуры, што прыводзіць да паўторных спроб дыбаггавання.
Што такое Agents CLI
Agents CLI — гэта набор інструментаў, які прысвячаны цэламу жыцёвым цыклу разработкі агентаў у Google Cloud і праставляе з сабою ўніверсальны інтэрфейс. Ён працуе у двух рэжымах.
- Рэжым агента. Вы інсталюеце "умянення" у памагчык для кодавання, такі як Gemini CLI, Claude Code або Cursor. Шэрыя умянення навучаюць памагчыка шаблонам розгортання, каб ён могаў прымець правільныя рашэнні.
Основна ідэя полягае у тому, што замест того, шчоб асістэнт вгадував правіла розгортання, сістэма отрымуе машынно-чытабельній кантэкст шчодо того, колі вікорыстовуваты кожну мету розгортання, як структуруваты оцінкі і які шаблоні спостэрэжуваносты ёсць найефектывнішымі.
Прыклад: агент для схвалення вітрат
Агент перэглядае справаздачы працівніків про вітраты і прыймае рышэння шчодо схвалення відповідно до політыкі компаніі. Для апрацоўкі ён вікорыстовуе мадэлі Gemini праз Vertex AI. Вімогі:
- автоматычно схвалюваты звічайні запіты на суму до 50 доларыв
- віявляты подвійні заявкі
- підніматы поперэджэння шчодо незвічайніх сітуацій, такіх як заявкі на вітраты у віхідні або ад невідоміх постачальніків
- перэдаваты сумнівні віпадкі на розгляд людськімі рэцензентамі
Пярэшкоды
Убедзіцеся, што гэтыя элементы ўстановлены:
# Required tools
Python 3.11+
uv package manager
Node.js (for skills installation)
Google Cloud SDK (gcloud)
Табе таксэклікава пярэтка з Google Cloud, якае мяне калікавае падключыцься да Google Cloud консэле.
Заўдзеўкія пісьменныя назвы тагаў, атрыбутаў і URL-адзяроўкіхсьлягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя пераводзіць, якімі ёны ўказаныяў у вахадзе. Назвы тагоў, атрыбутаў і URL-адзяроўкіхслягаў не трэбя перав
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
Атлікаванне выканаецца за дапоможчыю LLM, які выступае як суддзя, на адказе крэтыкаў з файла eval_config.json. Калі якісь кейс не праходзіць, неабходна перэглядаць інструкцыі агента чыста логіку інструментаў, пакуль усе кейсы не працююць.
Гэты цыкл — гэта цыкл eval-fix, ключ да надзеяных агентаў у працэсе вырабоцтва. Без атлікаванняя вы толькі спадзяецеся, што агент будзе працаваць, а з яго вы знаеце.
Шаг 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 Python ADKgoogle-agents-cli-scaffoldдля стварэння каркаса праектаgoogle-agents-cli-evalдля методалагіі ацэнкіgoogle-agents-cli-deployдля цэлей развяртання
google-agents-cli-publish — для рэгістрацыі Gemini Enterprisegoogle-agents-cli-observability — для трэйсінгу і лагіранняАсістэнт выкарыстоўвае іх, калі гэта неабходна. У звязку з тым, што ён ведае, калі выбраць Agent Runtime, Cloud Run чы GKE, а таксама якія патэрны LLM-as-judge працуюць, не трэба пробаваць і спылучваць з метрыкамі ацэнкі.
2. Ацэнка як стандарт. Кожны праект з падтрымкай включае інфраструктуру ацэнкі з самага пачатку: папку tests/eval/evalsets/ для тэставання, файл eval_config.json з правіламі ацэнкі і налаштавання LLM-as-judge. Гэта адпраўдае рэальнасць, адколі агенты без процедуры ацэнкі рэдка калі прабываюць у прыменненні, а стандартным падходам зроблена ацэнка, таму агенты перавераняюцца прычынамі перад размешчэнням.
3. Абляцыя налогавых вітраў як стандарт. Cloud Trace ўвімкнуцься аўтаматычна на кожным размешаным агенце. Дыягнастыка агента, які працуе ў рэальных умовах, без абляцаў практычна немагчыма. Логаванне контэнту і аналітыка за дапамогою BigQuery ўвімкнуцься толькі праз agents-cli infra single-project, але базовая абляцыя ёсць обавязковай.
4. Інфраструктура адбываецца за вас. Логіка агента ёсць важлівай часткай, але конфігурацыі Docker, прыемнікі аўтэнтыфікацыі і файлы Terraform — няўажлівыя. Командна лінія берэ на сябе адпаведальнасць за інфраструктуру, ўжо таму, каб вы моглі сфокусавацца на розвіцці агента.
Далейшыя крокі
Агент для контролю вітраў падпараджаецца зазначаным трэбаванням, але рэальная размешчэнне выкалічвае ўсё ж дадатковыя элементы.
Рэальныя даны. Заменіце штучную історыю на запыт да вашай базы дадзеных з відомасцямі пра вітраты:
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, строгія правіла безпекі ў інструкціях, тэставанне ў локальных умовах, структураваныя ацэнкі з ціклам выправлення, створаная інфраструктура для развяртання, а таксама трэйсінг і логаванне кантэнту для контролю. Разам яны ствараюць шлях ад пратотыпа да практычнага выкорыстання.
Вывык
Разлік у працэсе развяртання ёсць рэальным. Багатыя праекты агентаў застаюць на месцы не таму, што самі агенты ўжо неефектывныя, а таму, што ўпрацоўкі для ўпрабавання ўсёлякія інфраструктурныя задачы займаюць занадта многа часу.
Агенты CLI не рашваюць усё. Вам яшчэ патрэбны добра спраектаваные запіты, прыдатныя інструменты і рэштычныя тэсты. Што жа ён здолвае, так гэта інфраструктурныя рутынгі, якія трывожуць агентаў у срэдах разработкі. Мета — каб рабочыя працэсы агентаў былі схожы на запуск create-react-app, а не на ручную нарабатку інфраструктуры.