Практычныя прытамулкі: Введэнне ў агентскія AI з Google ADK
Практычныя прыказкі: Введэнне ў агентскі ІІ з Google ADK: контракты, перакананні та слоты для коду для команд, якія використоўваюць гэты патэрн.
У гэтым карыце парадоксальнае шлях ад сыр'ёў да рабочай системы для: «Введэння ў агентныя AI з Google ADK». Акцэнт ставіцца на практычныя крокі, чысткія перакананні та код, які можна прыўязаць да репазітария без неабязковасці здогадвацца пра мету. У стадзіі агледжэння неабходна практычна визначыць інпуты, адпаведальную за крок особу та критэрыя завершэння пры перамены коду. Аперацыйныя працавнікі должны магчымае перадзваніць крок з вядомай точкі контролю без неабязковасці здагадвацца пра схованы стан. Спрыяйце гэтай стадзіі як даговор між інпутамі та практычна перакананымі выходамі. Дайце назву артыфактам, практычна визначыць перакананні на успех та адмовіцеся ад бяспечнага частковага завершэння.
Пераход з чатботаў да агентаў
Калі працюеце над стадзіяй «Пераход з чатботаў», спачатку запішыце угоду: неабходныя даны, сигнал успеху і тое, што выканаецца у разе частковага невыпалення. Такі список контроля дапамагае заліцвачыць змяны ў кодзе па-справжнему. Запісвайце час выканення і кост токенаў або запытаў праза функцыйнае рэзультат. Відкрытыя даны пра косцы запобегаюць неспакойным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя среды. Зробіце перапаконтрацю пасля дорогіх крокаў. Система вярнення не павінна знову нарахоўваць косты той самай вызову LLM, калі аператар перапрыямляе роботу да наступнага элемента.
Розумеўце основную ідею за агентным ІІ
Калі працуеце над стадзіяй «Розумэнне асновной ідеі», спачатку запішыце умовы кантракту: неабяжлівыя даны, сігнал успеху і тое, што выходзіць пад частыя неудачы. Такі список контроля дапамагае заліцвачыць змяны ў кодзе пазнейша. Храніце настройкі за межамі коду прыемліка. Файлы сераўіса, хранальнікі секрэтных данных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабяжлівага чытання всей структуры. Ставьце контрольныя пункты пасля дорогіх крокаў. Система вярнення праблемы не должна занова ставіць плату за той самы вызов LLM, калі аператар перапрыяўляе роботу да наступнага элемента.
from google.adk.agents import Agent
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
Наданне агенту рэальных можлівасцей за дапамогою інструментаў
Калі працуеце над стадзіяй «Даўчы агенту рэальнае выкананне», спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выканаецца у разе частковага нявыпання. Такі список перакладоў заходзіць да таго, каб пазнейшыя змены коду былі чыстымі. Документавайце як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў ёсць частью продукту, а не пазнейшым дапрацоўкам. Зявляйце логі з назвай інструмента, хэшам параметраў, часам адклікання і рэзультатам кожнага вызову. Без такога следу дэбагаванне цыклаў агента губіць гадзіны. Калі працуеце над стадзіяй «Даўчы агенту рэальнае выкананне», спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выканаецца у разе частковага нявыпання. Такі список перакладоў заходзіць да таго, каб пазнейшыя змены коду былі чыстымі. Спрыймайце гэтую стадзію як контракт межаў між вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даўце назвы элементам, задайце критэрыяі успеху і не падтрымвайце тыхню частковую завершэннасць.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise Exception("Cannot divide by zero")
return a / b
raise Exception("Unsupported operation")
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction=(
"You are a helpful assistant with calculator capabilities. "
"Use the calculator tool for arithmetic. "
"Supported operations are add, subtract, multiply, divide."
),
tools=[calculator]
)
Стварэнне агентаў з калькамі інструментаў
Этап агентаў з багатымі можлівасцямі для працы з будовам работае наўзярэджэй, калі яго спрыяваць як вимерную паверхню. Зафіксавайце адна ідеальная транскрыпцыю, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Запісвайце часы выконання і косты токеноў або запытак па боку функцыйнальных рэзультаатаў. Відразлівае відображэння костаў з самага пачатку запобегае неспакойным рахункам, калі процес пераходзіць з дэмаверсіі ў спяльныя сераўы. Адкройце інструменты з вузкімі схемамі і чыткімі пазначкамі пра побачныя эфекты. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым яны автаматычна схваляюць іх.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise ValueError("Cannot divide by zero.")
return a / b
raise ValueError("Unsupported operation.")
def convert_units(value: float, from_unit: str, to_unit: str) -> float:
from_unit = from_unit.lower()
to_unit = to_unit.lower()
if from_unit == "km" and to_unit == "miles":
return value * 0.621371
if from_unit == "miles" and to_unit == "km":
return value / 0.621371
if from_unit == "celsius" and to_unit == "fahrenheit":
return value * 9 / 5 + 32
if from_unit == "fahrenheit" and to_unit == "celsius":
return (value - 32) * 5 / 9
raise ValueError("Unsupported unit conversion.")
def get_weather_mock(city: str) -> dict:
weather_data = {
"bucharest": {
"temperature_celsius": 23,
"condition": "sunny",
"wind_speed_kmh": 10,
},
"london": {
"temperature_celsius": 16,
"condition": "rain",
"wind_speed_kmh": 18,
},
}
key = city.lower()
if key not in weather_data:
return {
"city": city,
"error": "Weather data not available."
}
return {
"city": city,
**weather_data[key],
}
root_agent = Agent(
name="multi_tool_agent",
model="gemini-2.5-flash",
instruction=(
"You are a practical assistant. "
"Use the available tools when the user asks for calculations, "
"unit conversions, or weather information."
),
tools=[
calculator,
convert_units,
get_weather_mock,
],
)
Сістэмы з калькамі агентаў: Агенты, якія выкарыстоўваюць іншых агентаў
Сістэмы з мнагае агентамі, якія выкарыстоўваюць стадыяны, працуюць наякша, калі іх спрыяглядаць як вимерную паверхню. Запісаўце адна «золатая» транскрыпцыю, адзін прыклад неудачы і прыметку па аброшчанні роботы перад расшырэнням масштаба. Зберагачыце настройкі праза код аплікацыі. Файлы сяродавішча, хранільнікі секрэтных дадзеных і флагі функций павінны знаходзіцца ў адном месцы, куды аператары можаць адбавляць без неабяжнага чытання всіх дадзеных. Зберагачыце стан графа ў простам і типаванам формате. Вярнутыя блокі маскуюць інфармацыю пра тое, який вузел запісаў якое поле, і спакоююць продажчыку роботы пасля перарываў.
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.adk.tools import google_maps_grounding
from google.adk.tools.agent_tool import AgentTool
routing_agent = LlmAgent(
name="routing_agent",
model="gemini-2.5-pro",
instruction="""
You are a routing agent.
Use google_maps_grounding to estimate routes and travel times.
""",
tools=[google_maps_grounding],
)
discovery_agent = LlmAgent(
name="discovery_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel discovery agent.
Use Google Search to find interesting places.
""",
tools=[google_search]
)
composer_agent = LlmAgent(
name="composer_agent",
model="gemini-2.5-pro",
instruction="""
Write a friendly travel itinerary based on the collected information.
""",
tools=[]
)
root_agent = LlmAgent(
name="travel_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel assistant.
Coordinate discovery, routing, and itinerary composition.
""",
tools=[
AgentTool(discovery_agent),
AgentTool(routing_agent),
AgentTool(composer_agent)
]
)
Парадныя рабочыя практыкі і дэтэрміністычная оркестрацыя
Парадыгма абоэтапных рабочых практык і детерміністычных процэсаў працюе наякша, калі яе розглядаць як мерыемую структуру. Зберагучы адна ідеальная версія даных, адзін прыклад неудачы і запіс працэсу вярнення да пачатковага стану, прычаму не трэба расшырваць сферу дзеяння. Дакументавацыя успішнага і восстанавліваючага падхода трэба выконваць разам. Перапрыбуткі, людзкі контроль і обработка некоректных паведамленняў є часткай самага продукту, а не наступным етапам його дапрацоўкі. Стан графа трэба падтрымваць у простам і типаваным формате. Вкладзеныя структуры даных маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакоююць працэс пасля перарываў. Парадыгма абоэтапных рабочых практык і детерміністычных процэсаў працюе наякша, калі яе розглядаць як мерыемую структуру. Зберагучы адна ідеальная версія даных, адзін прыклад неудачы і запіс працэсу вярнення да пачатковага стану, прычаму не трэба расшырваць сферу дзеяння. Разглядайце этап як кантракт між вхіднымі даннымі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаць критэрыя успеху і не падтрымвайце беззвучнае частковае завершэння задання.
from google.adk.agents import Agent, SequentialAgent
from google.adk.tools import AgentTool
planner_agent = Agent(
name="planner_agent",
model="gemini-2.5-flash",
instruction="""
Read the user request and create a short execution plan.
"""
)
executor_agent = Agent(
name="executor_agent",
model="gemini-2.5-flash",
instruction="""
Execute the plan and delegate specialist work.
""",
tools=[]
)
report_agent = Agent(
name="report_agent",
model="gemini-2.5-flash",
instruction="""
Produce the final report based on execution results.
"""
)
root_agent = SequentialAgent(
name="planner_executor_report_workflow",
sub_agents=[
planner_agent,
executor_agent,
report_agent,
],
)
Адкрытыяе запуск агента ADK локальна
Для стадіі запуску агента ADK неабяжна прадзеўдзіць вводныя даны, абавесцелівальніка крока і крэтыяры завершэння прычым змене коду. Аперацыйныя працавнікі павінны магчымаецца перапрыявляць крок з вядомага пункта контролю без неабяжнай адгадвання схованага стану. Запісваць час выконання і косць токена або запыту праза функцыйнальнымі рэзултатамі. Відразлівасць косца з самага пачатку запобегае неспакоўным рахункам, калі траекторыя пераходзіць з дэмавайнага режыма ў спяльныя среды. Заставіць людзкую апраўдку для тых крокаў, якія витрачаюць грошы або зменяюць даны прадукцыі. Прыўязка на час компілявання не ўзначае павноты бізнес-процэсу.
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True
adk web
Размешчэнне агента ў Google Cloud Run
Для разміщэння агента на певным этапе неабяжна ўзначыць параметры вводу, адпаведальнага за даны этап і крэтарыя завершэння працы перад змінайом коду. Аператары должны магчымаць перзапуск этапу з вядомай точкі контролю, не падозрываючы прыхованы стан. Конфігурацыю трэба знаходзіць пазначыльна ад коду прыкладнення. Файлы сераўнавання сяродовішча, храненні секрэтных данных і флагі функцый належыць у аднам месца, якое аператары можаць пераглядаць, не чытаяўшы весь ланцуг задач. Пры выконанні дзеянь, якія коштуюць грошы або зменяюць даны у працэйнай сістэме, неабяжна ўключыць людзкія празборы. Прыўязка на час компіляцыі не є гарантыяй полнай адпаведнасці да вимог бізнесу.
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["adk", "web", "--host", "0.0.0.0", "--port", "8080"]
gcloud run deploy simple-agent \
--source . \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
--set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \
--set-env-vars GOOGLE_CLOUD_LOCATION=us-central1
gcloud run services describe simple-agent \
--region us-central1 \
--format='value(status.url)'
Актывацыя агента через FastAPI
Для стадіі «Актывацыя агента» неабходна прадзеўжчае вызначэнне інпутаў, адпаведальнага за шаг і крэатарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі должны магчымае перзапускаць шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Неабходна аддзеўнаваць дакументацыю як па шляху успеху, так і па шляху вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обработка некоректных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Неабходна людзкая аправарэнне для тых крокаў, якія выкарыстоўваюць грошы або зміняюць даны працэсу. Компіляцыйныя налашчэнні не ўзроўнаўцуюцца з повнай адпаведальнасцю за бізнес. Для стадіі «Актывацыя агента» неабходна прадзеўжчае вызначэнне інпутаў, адпаведальнага за шаг і крэатарыяў завершэння працы перад зменым коду. Аперацыйныя працавнікі должны магчымае перзапускаць шаг з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяйце тэй стадіі як кантракту межа інпутамі і перакананымы выходнымі даннымі. Даўце назвы артыфактам, вызначыце крэатарыі успеху і адмовіцеся ад беззвучнага частковага завершэння.
import uuid
from fastapi import FastAPI
from pydantic import BaseModel
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from agent import root_agent
app = FastAPI()
session_service = InMemorySessionService()
runner = Runner(
agent=root_agent,
app_name="weather_agent_service",
session_service=session_service,
)
class QueryRequest(BaseModel):
message: str
@app.post("/weather")
async def weather(request: QueryRequest):
user_id = "api_user"
session_id = str(uuid.uuid4())
await session_service.create_session(
app_name="weather_agent_service",
user_id=user_id,
session_id=session_id,
)
content = types.Content(
role="user",
parts=[
types.Part(text=request.message)
],
)
final_answer = ""
async for event in runner.run_async(
user_id=user_id,
session_id=session_id,
new_message=content,
):
if event.is_final_response():
final_answer = event.content.parts[0].text
return {
"response": final_answer
}
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
Размешчэнне ў Agent Engine
Кал працуеце над этапам размешчэння ў Agent Engine, спачатку запісайце умовы викорыстання: неабяжлівыя данні, сигнал успеху і тое, што выканаецца у разы частковага невяліка. Такі список дапамагае залишыцца чыстым пад час пазнейшых змян у кодзе. Запісвайце час выканання і вартасць токена або запытку празаўсёды разам з рэзультатамі функцыянальнай працы. Візуабельнае паказанне вартасці з самага пачатку запобегае неспакою, калі праця пераходзіць з дэмовай среды ў спакульнаныя сераўеры. Зробіце контрольную пазнаку пасля дорогіх крокаў. Функцыя адновлення не должна зноў нарахоўваць тую ж самую плата за вызов LLM, калі аператар перапрыямляе роботу да наступнага вузла.
gcloud services enable \
aiplatform.googleapis.com \
storage.googleapis.com
export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"
gsutil mb -l us-central1 $STAGING_BUCKET
adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent
Заключныя меркі
Калі працюеце на стадыі «Заключныя заўважэнні», спачатку запісайце угоду: неабходныя даны, сігнал успеху і тое, што выходзіць па частым неудачам. Такі список пераканальвае ў тым, што пазнейшыя змены коду будуць чыстымі. Зберагайце настройкі парадульна ад коду прыемлі. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабходнасці чытання всей структуры. Стварайце контрольныя пункты пасля дорогіх крокаў. Система вярнення не должна занова ставіць плату за той самы вызыв LLM, калі аператар перапрыяўляе роботу да наступнага элемента.
Чек-ліст для эксплуатацыі
Стадыя чек-ліста для эксплуатацыі працюе найэфектывней, калі яе спрыяглядаць як мерыемую плошчу. Запісайце адну ідеальную транскрыпцыю, адзін прыклад неудачы і прыметкі па адвярненню роботы, прычым расшырюючы сферу дзеяння.
Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшаў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаную лінію обработкі.
Зберагаюць стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэзвалечэнне пасля перерываў.
Калі дозволяе бюджет, дадзіце тэст на перакананне, які працюе з критычным шляхам у CI за дапамою фіксатываў, а не з рэальнымі платнымі API.
Спрыяйце цэй стадзіі як кантракту межа вхіднымі дадзеннямі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задзержыце перакананні на успех і адмовіцеся ад беззвучнага частковага завершэння.
Зберагаюць стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэзвалечэнне пасля перерываў.
Перш чым апранаваць стэк, заморозьце версіі, зафіксуйце ідеальны транскрыпт для критычнага шляху і падтвердзіце крокі для абраткі. У спадзяльных сэрвісах патрабуецца наяўнасць лімітаваў швайна, перакананняў на прыналежнасць і чыстае відпаведальнае аб’екта для ротацыі секрэтных дадзенняў. Валіце надзейнасць працы над красавім разовым дэманстрацыйным прыкладам.
Запіскі для пакета 18b8374abe5a: не класты ключі прадаўцоў у репазітарыю, задаць максымальны ліміт токена на кожную сесію, а таксама зберагчы транскрыпціі празаўсюды з фікстурамі для ацэнкі, каб пазнейшыя замены моделей заставаліся порównанымі.