Практычныя прытамулкі: Паўная энцыклапедыя прыладоў для агентаў (з кодам)

Наступныя прыміткі паказваюць практычны шлях для выкарыстоўвання кнігі “The Complete Guide to Agent Harnesses (With Code)”. Акцэнт ставіцца на контракты, перакананняя та месцы для падставлення коду, а не на мотывацыйныя аспекты. Калі працуеце на стадіі агледжэння, спачатку запісайце контракт: неабяжныя даны, сігнал успеху та тое, што выканаецца у разе частковага нявыпалення. Такі список дапамагае залишацца чыстаснаўным пад час пазнейшых змян у кодзе. Запісвайце час выканання та кост токеноў або запытаў разам з рэзультатамі функцыяналізму. Відразувая візуабельнасць костаў запобегае неспакойным рахункам, калі процес пераходзіць з дэмаверсіі ў спяльныя среды.

Што на самай працэ вы купіваеце за дапамогою гарнісу

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

while agent.turns < max_turns:
    call = agent.next_call(observations)
    if call is None:
        break
    result = execute(call)
    observations.append(result)

Перакладзіце правілу ў код

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

Слой 1: Межа выканання

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

SYSTEM_PROMPT = "IMPORTANT: never delete a file without asking the user first."

def execute(call):
    if call.name == "delete_file":
        FILES.pop(call.args["path"], None)
        return f"deleted {call.args['path']}"

def boundary(rules):
    def wrap(execute):
        def guarded(call):
            for name, deny_if, reason in rules:
                if deny_if(call):
                    return f"DENIED by {name}: {reason}"
            return execute(call)
        return guarded
    return wrap

NEEDS_APPROVAL = [(
    "delete-needs-approval",
    lambda c: c.name == "delete_file" and not c.args.get("approved_by_human"),
    "deletion requires an explicit human approval flag on the call",
)]

Роўнь 2: Сэндбоксінг

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

DENY = ["secrets/"]

def execute(call):
    path = call.args["path"]
    if any(path.startswith(d) for d in DENY):   # checks the spelling
        return "DENIED by deny-list"
    real = os.path.normpath(path)               # the ../ collapses HERE, after the check
    return DISK.get(real, "not found")

read('secrets/api_key')          -> DENIED by deny-list
read('work/../secrets/api_key')  -> sk-live-DO-NOT-LEAK

ALLOW_ROOTS = ["work"]

def resolve(path):
    real = os.path.normpath(path)               # resolve FIRST
    if not any(real == r or real.startswith(r + os.sep) for r in ALLOW_ROOTS):
        return None
    return real

3-й слой: Стойкасц памяці

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

CONVERSATION, DISK, HARNESS_CONFIG = [], {}, {}

def remember(kind, key, value):
    """'chat' dies with the session, 'disk' survives it,
    'config' shapes every session that follows."""
    {"chat": lambda: CONVERSATION.append(value),
     "disk": lambda: DISK.__setitem__(key, value),
     "config": lambda: HARNESS_CONFIG.__setitem__(key, value)}[kind]()

4-й шар: цыклы верыфікацыі

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

def execute(call):
    if call.name == "review":
        snapshot = dict(CODE)               # a copy, so the reviewer cannot write
        src = snapshot[call.args["path"]]
        return f"VERDICT: {'off-by-one' if '+ 1' in src else 'looks good'}"
    if call.name == "apply_fix":
        if call.args.get("dry_run", True):  # on by default, turned off on purpose
            return f"DRY RUN: would rewrite {call.args['path']}, nothing written"
        CODE[call.args["path"]] = call.args["new"]
        return f"wrote {call.args['path']}"

Слой 5: Каналы контексту

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

def subagent_search(query):
    """Its own window. The main thread never pays for this reading."""
    global subagent_tokens
    subagent_tokens += sum(len(v.split()) for v in CORPUS.values())
    return next(f"{n}: {b.split('ANSWER:')[1].strip()}"
                for n, b in CORPUS.items() if "ANSWER:" in b)
def execute(call):
    global main_tokens
    distilled = subagent_search(call.args["q"])
    main_tokens += len(distilled.split())    # the only line that bills you
    return distilled

Тое, чаго ўсе яшчэ не можаць вам сказаць

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

Repo

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

git clone https://github.com/paoloap-py/agent-harness-guide
cd agent-harness-guide

python3 run_all.py        # all five layers, guard off then on, side by side
python3 test_harness.py   # asserts every difference above, 10 checks

Куды це вас прыводзіць

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

Частае запытання

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

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

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

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

Автаналізавайцеся ў шлюзе і паўтарна автаналізавайцеся на роўні дадзенняў. Сам токен-носіцель не є межай арендаванага ресурсу.

Зрабіце перапактовку пасля дорогіх крокаў. Функцыя продакцыі не должна занова нарахоўваць плата за той самы вызыв LLM, калі аператар прабуе знова вызваць пазнейшы вузел.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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