Практычныя прытамулі: Я створыў той самы агент трывацьма спосабамі: Interactions API, ADK і

У гэтым карыце парадоксальная дорага ад сыр'ёў да рабочай системы паказвае, як я створыў той жа агента трэмаю спосабамі: через Interactions API, ADK і Antigravity SDK. Акцэнт ставіцца на крокі, якія можна выконваць, чыстае перакананне і код, які можна проста падставіць у репазітарый без неабяснення меты. У стадзіі агульнага відгледу неабходна прадзефінаваць вхідныя даны, адпаведальную особу за крок і критэрыя завершэння пры перадзмене коду. Аперацыйныя працавнікі должны магчымае перадзначыць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Запісваць трэба час выконання і вартасць токена або запыту разам з функцыйнальнымі рэзултатамі. Відразувыя даны пра вартасць запобегаюць неспадзячым рахункам, калі дорага пераходзіць з дэмаверсіі ў спяльныя сераўы.

Настройка і адступленне за інструкцыямі

Калі вы працуеце над этапамі наладкі і адпаведнага выканання, спачатку запісайце умовы дагавору: неабяжлівыя даны, сигнал успеху і тое, што выходзіць у разе частковага невыканання. Такі список пераконтроўвае чыстасць пазнейшых змян у кодзе. Зберагаюце настройкі праза код аплікацыі. Файлы сераўнавання, хранільнікі секрэтных дадзеных і флагі функцый крануцца ў аднам месцы, дзе аператары можаць аудытаваць іх без неабяжлівага чытання всей структуры. Робіце пераконтроўкі пасля дорогіх крокаў. Функцыя вярнення працы не должна зноў выклікаць той самы вызов LLM, калі аператар перапрыяўляе выканання да наступнага элемента.

export GOOGLE_API_KEY="..."   # get this at aistudio.google.com
gcloud auth application-default login

Метод 1: API для взаімадзеяння, вы пішаце інструмент і цикл

Калі працуеце над стадзіяй API Interactions методу 1, спачатку запісайце умовы вярбунка: неабяжлівыя данні, сігнал успеху і тое, што выходзіць у разе частковага няўспэху. Такі список контроля дапамагае заліцьварыць чыстасцю пазнейшых змян у кодзе. Документавайце як шлях успеху, так і шлях вяселення. Перапрыбуткі, людзкіе перакрыцця і обробка некоректных паведамленняў ёсць частью продукту, а не пазнейшым дапрацоўкам. Зявляйце логі з назвай інструмента, хэшам аргументаў, часам затрымкі і рэзультатам кожнага вызову. Без такога следу дэбаггін агента губіць гадзіны.

def execute_sql(query: str) -> list[dict]:
    client = bigquery.Client()
    config = bigquery.QueryJobConfig(maximum_bytes_billed=20 * 10**9)
    rows = client.query_and_wait(query, job_config=config, max_results=50)
    return [{k: str(v) for k, v in dict(row).items()} for row in rows]

execute_sql_tool = {
    "type": "function",
    "name": "execute_sql",
    "description": (
        "Run a BigQuery Standard SQL SELECT query against "
        "`bigquery-public-data.hacker_news.full`, the public Hacker News "
        "dataset (stories and comments since 2006). Columns: id INT, "
        "type STRING (story/comment/job/poll), title STRING (stories only), "
        "text STRING (body, HTML-escaped), `by` STRING (username), score INT, "
        "parent INT, descendants INT, timestamp TIMESTAMP, url STRING, "
        "dead BOOL, deleted BOOL. Returns at most 50 rows."
    ),
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}

while True:
    calls = [s for s in interaction.steps if s.type == "function_call"]
    if not calls:
        break
    results = [{
        "type": "function_result",
        "name": step.name,
        "call_id": step.id,
        "result": [{"type": "text", "text": json.dumps(execute_sql(**step.arguments))}],
    } for step in calls]
    interaction = client.interactions.create(
        model=MODEL,
        input=results,
        system_instruction=INSTRUCTION,
        tools=[execute_sql_tool],
        previous_interaction_id=interaction.id,
    )

Метод 2: ADK, фрэймворк прыносіць інструменты

Калі працуеце з этапам методу 2 ADK, спачатку запісайце умовы виконання: неабяжлівыя даны, сигнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список дапамагае заліцвачваць пазнейшыя змены ў кодзе. Воліце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшае, прычына нявыполнення павінна вказываць на адзін конкрэтны элемент, а не на заплутаны ланцюг задач. Запісвайце назву інструмента, хэш параметраў, час адпаведзі і рынак кожнага вызову. Без такога журналу дэбаггін агента займае гадзіны. Калі працуеце з этапам методу 2 ADK, спачатку запісайце умовы виконання: неабяжлівыя даны, сигнал успеху і тое, што выканаецца у разе частковага нявыполнення. Такі список дапамагае заліцвачваць пазнейшыя змены ў кодзе. Запісвайце часы виконання і кост токенаў або запытаў разам з функцыйнальнымі рынакамі. Відразувая інформацыя пра косты запобегае неспакойным рахункам, калі праця пераходзіць з дэмаверсіі ў спакульнаныя сераўысы.

import google.auth
from google.adk import Agent
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode

credentials, _ = google.auth.default()
toolset = BigQueryToolset(
    credentials_config=BigQueryCredentialsConfig(credentials=credentials),
    bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED),
)
root_agent = Agent(name="hn_opinion_agent", model=..., instruction=..., tools=[toolset])

Метод 3: Antigravity SDK, прыжковы костюм плюс MCP

Этап Antigravity SDK з методам 3 працюе найкраща, калі яго розглядаць як вимерную паверхню. Зберагчыце адна «золатая» транскрыпція, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу прыемлівання. Конфігурацыю трэба залічыць пазначкай занята ўнутрь коду прыемлівання. Файлы сяродавішча, хранільнікі секрэтных дадзеных і пазначкі функцый должны знаходзіцца ў аднам месцы, куды аператары можаць адрабатваць без падчытання всіх дадзеных. Неабходна выклікаць інструменты з вузкімі схемамі та чысткімі пазначкамі пабочных эфектаў. Хостам неабходна знаты, якія вызовы мутуюць стан, перш чым яны автаматычна схваляюць іх.

from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStreamableHttpServer

bigquery_mcp = McpStreamableHttpServer(
    name="bigquery",
    type="http",
    url="https://bigquery.googleapis.com/mcp",
    headers={"Authorization": f"Bearer {token}",
             "x-goog-user-project": project},
    enabled_tools=["execute_sql_readonly", "get_table_info", ...],
)
config = LocalAgentConfig(system_instructions=..., mcp_servers=[bigquery_mcp])
async with Agent(config) as agent:
    response = await agent.chat(question)

Порэванне

Этап параболік працюе найэфектывней, калі яго розглядаць як вимерную паверхню. Зафіксавайце адны ідеальны прыклад, адну ситуацыю неудачы і прыметкі па вярнэнні да пачатковага стану пры расшырэнні масштаба. Дакументавайце як шлях успеху, так і шлях вярнэння. Перапрыбуткі, людзкія контраліны і обработка некоректных паведамленняў ёсць часткай продукту, а не элементамі пазнейшай дапрацоўкі. Храніце стан графа ў простам і типаваным формате. Вярнутыя структуры маскуюць інфармацыю пра тое, який вузел запісаў канкрэтны поле, і спакоююць працу пасля перарываў.

Яго выдача

Этап «Serving it» працюе найкраща, калі яго розглядаць як меркавыя плошча. Зберагучы адна ідеальная версія, адзин прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выходзіць, прычына неудачы павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцюг дзеяння. Рэжым графа павінен быць простым і з адазначанням типа. Вярнутыя структуры маскуюць інфармацію пра тое, який вузел запісаў канкрэтны поле, і спакоююць працу пасля перарываў. Этап «Serving it» працюе найкраща, калі яго розглядаць як меркавыя плошча. Зберагучы адна ідеальная версія, адзин прыклад неудачы і запіс пра вярнэнне да пачатковага стану, перш чым расширваць сферу дзеяння. Запісвайце час выканання і кост токенаў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівасць костаў з самага пачатку запобегае неспакойным рашчыткам, калі процес пераходзіць з дэмавайнага режыма ў спяльныя сераўы.

Запіс пра адказвальны рахунак

Для прыткай на сцэне, перад змінайом код неабяжна адзначыць вхідныя даны, власніка крока і критэрыя выходу. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не падозрюючы прыхованы стан. Конфігурацыю трэба захаваць пазірна ад коду прыкладнення. Файлы сераўнавання, сховішчы секрэтных дадзеных і флагі функций должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць, не чытаяўшы весь лянцуг. Прыехваленне ад чалавека патрэбна для ребер, якія витрачаюць грошы або зменяюць даны у працэйнай сістэме. Падключэння ў час компілявання не адпавядае пачатковай цэлесообразнасі бізнесу.

Каторы выбраць

Для стадіі «Каторы ўжываць» неабходна прадзефінаваць вхідныя даны, адпаведальную особу за крок і критэрыя завершэння пры перадзеўранні коду. Аператары должны магчымае перайсці на гэты крок з вядомага пункта контролю, не спрабоўваючы здогадвацца пра схованы стан. Неабходна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія пераказы і обробка некоректных паведамленняў є частью продукту, а не дадатковым элементам пасляўпрацоўкі. Неабходна застаўляць людзкую затверджэнняе для тых крокоў, якія ведуць да выдаткаў грошэй або змяні дадзеных у працы. Працэс кампілявання не є гарантыяй полнай адпаведнасці продукту бізнес-трэбованням.

Чек-ліст для эксплуатацыі

Стадія чек-ліста для эксплуатацыі працюе наякшэ, калі яе спрыямаць як мерыемую структуру. Перш чым расширваць сферу дзеяння, неабходна зафіксаваць адны ідеальны прыклад роботы, адзін прыклад неудачы і прыметкі ўсування змян.

Спрыяваць гэтую стадію як даговор межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Назваць всі неабходныя элементы, прадзефінаваць критэрыя успеху і адмовіцца ад мовчанкавага частковага завершэння працы.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэз виконання пасля перерываў.

Калі дозволяе бюджет, дадзіце тэст на перакананне, які працюе над критычным шляхам у системе CI з викорыстаннем фіксатываў, а не рэальных платных API.

Запісвайце час виконання адпаведна да вартасці токена чытае запита разам з функцыйнальнымі рэзултатамі. Відразы вартасці з самага пачатку запобегае неспакою, калі шлях пераходзіць з дэмаверсіі ў спакульнаныя сераўсы.

Зберагаюце стан графа ў простам і типаваным формате. Вкладаныя блобы маскуюць інфармацію пра тое, який вузел запісаў якое поле, і спакоююць працэз виконання пасля перерываў.

Перш чым апранаваць стак, заморозьце версіі, зафіксуйце ідеальны транскрыпт для критычнага шляху і паказвайце крокі для адворачэння змян. У спакульных сераўсы неабходны ліміты на колькасць запытоў, перакананні ў прыналежнасці і чысткі власнік для змены секрэтных даных. Валіце надзейнасць працы над красавімі разовымі дэмамі.

Запіска параграфу 016bc4c24234: не кластыць ключы прадаўцаў у репазітары, задаць максымальную кантэнцыю токена на адна сесія і зберагчыць транскрыпты праза фіксатуры адлічэння, ўпынку празмена моделей застаўся можна пораўняваць.

Калі працуеце над пунктам 0 запіскі аб ужыцку захоўніх мера, спачатку запісайце контракт: неабходныя вхідныя даны, сігнал успеху і што выходзіць у разе частковага невыпання. Такі список контролю дапамагае заставаць пазнейшыя змены коду чыстымі. Спрыятлівайце гэтаму пункту як контракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Назвайце артыфакты, задаць перакананні успеху і адмовіцеся ад тыхоўскага частковага завершэння.

Дзеянне аб ужыцку захоўніх мера 0/754: замерыце час выканання, класію паказакоў і выкарыстаны токен для гэтай запіскі, а потым вынікніце, чы хацяць застаўці змену на адной фіксованай сэтке пытанняў, а не на адной лягкай інформацыі.

Этап 0 пры падготовцы да захісту працюе найкраща, калі яго спрыяваць як меравальную паверхню. Зберагчыце адна «золатая» транскрыпцыя, адзін прыклад неудачы і запіс пра вярненне да пачатковага стану, перш чым расширваць сферу дзеяння. Дакументавайце як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыбуткі, людзкія контралі і обработка некоректных паведамленняў ёсць часткаю продукту, а не чымсь, што дадаецца пазней.

Дзялей 0/773 пры падготовцы да захісту: змерьце час выканання, класыя ошибакі і колькасць викорыстоўваных ресурсаў для гэтага запісу, а пасля, на аднойчынных крэтарыях, аблікавайце, чы хацеце застаўіць змяну, а не на аднойчынах спогадах.

Для этапу 1 пры падготовцы да захісту, перш чым зменяць код, аблікавайце вхідныя даны, адпаведальнага за крок і крэтарыі завершэння. Аперацыйныя працавнікі павінны магчымае перазваляць крок з вядомай точкі контролю, не спадзяваючыся на скрыты стан. Спрыявайце гэтаму этапу як на даговор між вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, аблікавайце крэтарыі успеху і не прымайце тыхню частковую завершэннасць.

Дэталі зміцнення 1/773: звярніце увагу на час працы, клас памялкі і колькасць токенав, які былі выкарыстоўаны для гэтай памялкі, а потым вынікніце, чы хацяце застаўіць гэтыя змены, спынюючыся на фіксаванай сэтце пытанняў, а не на індывідуальных прыкладах.