Практычныя прытамулі: Чаго ваша схема не можа сказаць вашам агенту, формат адкрытых ведоў

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

Адна запитанне, чатыры схованыя рашэнні

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

Чаму «дадзець больш контексту» не рашаяць проблемы

Калі працуеце над пытаннем «Чаму даць больш штоўкі», спачатку запісайце контракт: неабходныя даны, сігнал успеху і тое, што выходзіць пад частым неудачам. Такі список пераконтрацуючых пунктов дапамагае залічваць змяны ў кодзе чыста.

Формат адкрытых ведамасцей

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

Акт 1: стварэнне таго, што можа запісваць паловая машына

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

uv tool install git+https://github.com/GoogleCloudPlatform/open-knowledge-format

reference-agent enrich \
  --source bq \
  --dataset "$PROJECT_ID.marketplace" \
  --out bundles/generated \
  --no-web

Акт 2: запісваць рашэнні

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

---
type: Metric
title: Gross Merchandise Value (GMV)
description: Total settled transaction value for a period in IDR, excluding cancellations, reversals and returns.
tags: [metrics, finance, headline-metric]
generated: { by: human:analytics-lead@marketplace.example, at: 2026-09-01T09:00:00+07:00 }
verified:
  - { by: human:analytics-lead@marketplace.example, at: 2026-09-01T11:00:00+07:00 }
stale_after: 2027-01-31T00:00:00+07:00
---

Акт 3: агент, який іх чытае

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

def read_okf_concept(path: str) -> dict:
    """Read one OKF concept document from the local bundle.

    Args:
        path: Path relative to the bundle root, for example "metrics/gmv.md".
            Call this with "index.md" first to find which concepts exist.

    Returns:
        'status', and on success 'content' with the raw markdown and frontmatter.
    """
    doc = (OKF_BUNDLE / path.lstrip("/")).resolve()
    # `path` is model-controlled. Block anything that escapes the bundle.
    if not doc.is_relative_to(OKF_BUNDLE) or not doc.is_file():
        return {"status": "error", "error": f"no concept at {path}"}
    return {"status": "success", "content": doc.read_text(encoding="utf-8")}

bigquery_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://bigquery.googleapis.com/mcp",
        headers={
            "Content-Type": "application/json",
            "Accept": "application/json, text/event-stream",
        },
        sse_read_timeout=300.0,
    ),
    header_provider=_bigquery_auth_header,
    tool_filter=[
        "list_dataset_ids",
        "list_table_ids",
        "get_dataset_info",
        "get_table_info",
        "execute_sql_readonly",
    ],
)

root_agent = Agent(
    name="marketplace_analytics_agent",
    model="gemini-3.7-flash",
    instruction=(
        "Before writing any SQL: call read_okf_concept('index.md'), then read every "
        "concept the question touches: the metric, the payment status, the geography.\n"
        "Use only the filters, joins and period cuts those concepts define. "
        "Never invent a status value or a metric formula.\n"
        f"Run queries with execute_sql_readonly, passing projectId='{PROJECT_ID}'.\n"
        "Show the SQL you ran, and name the concepts you relied on."
    ),
    tools=[read_okf_concept, bigquery_mcp],
)

Што на самай працоўвало

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

Што гэта не вырашае

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

Ключавыя выводы

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

Чэк-ліст аператывання

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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