АІ-агенты для інжынераў будуччыны: памяць, інструменты та ціклы кантролю
Практычныя карточкі з элементаў агента — планаванне, інструменты, памяць і адзначэнне рэзультатаў — без зайвага термінолагічнага апылу, які мог бы замаскаваць сэрвіс дизайну.
У гэтым керавані перадаецца спосаб рэалізацыі для: «Усё, што інжынерам AI трэба знать пра агентаў AI». Акцэнт ставіцца на кантракты, пераконтроўкі і код, які можна падключыць у репазітарый без неабязковасці здогадвацца пра намеры. Для загальнага адгледжэння, перш чым зменяць код, неабходна задаць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аперацыёныя працоўнікі должны магчымае перадзеяць крок з вядомай точкі контролю, не здагадваючыся пра схованы стан. Валідзіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшоў, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны процес.
Як агенты выконваюць дзеяння
Жа тое, як агенты выкарыстоўваюць свае дзеяння, перад зменым коду неабходна задаць вхідныя даны, абавесця крока і критэрыі завершэння. Аператары должны магчымае запускать крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяйце цім этапу як кантракту межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даць назвы артыфактам, задаць перакананні на успех і адмовіцца ад тыхняе частковага завершэння без паведамлення. Строго адганяйце схемы інструментаў. Шырокія параметры у вільным тексте спрыяюць втручанню і робяць аудыты дорогімі.
import requests
def search_web(query: str) -> list[dict]:
response = requests.get(
"https://serpapi.com/search",
params={"q": query, "api_key": "YOUR_API_KEY", "num": 5},
)
results = response.json()["organic_results"]
return [
{"title": r["title"], "url": r["link"], "snippet": r["snippet"]}
for r in results
]
results = search_web("best sourdough recipe")
for r in results:
print(r["title"], "-", r["url"])
import anthropic
client = anthropic.Anthropic()
# The menu of tools the model can choose from
tools = [
{
"name": "web_search",
"description": "Search the web for current information.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query"}
},
"required": ["query"],
},
}
]
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "What's the weather in Seattle right now?"}],
)
print(response.content)
# [ToolUseBlock(name='web_search', input={'query': 'Seattle weather today'})]
# 1. Parse the LLM response to find the tools it wants to run
tool_calls = [block for block in response.content if block.type == "tool_use"]
# 2. Run the functions directly, OUTSIDE of the LLM
# (this is our search_web function from earlier -- plain Python,
# the model never sees this code)
tool_results = []
for call in tool_calls:
if call.name == "web_search":
output = search_web(call.input["query"])
tool_results.append(
{
"type": "tool_result",
"tool_use_id": call.id,
"content": str(output),
}
)
# 3. Hand the results back -- from the model's perspective,
# the answer just shows up in the chat
final = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "What's the weather in Seattle right now?"},
{"role": "assistant", "content": response.content},
{"role": "user", "content": tool_results},
],
)
print(final.content[0].text)
# "It's 62 and cloudy in Seattle."
Багатоэтапныя заданні
Для багатыякхэтных заданняў неабходна прадзефінаваць вхідныя даны, адпаведальную особу за кожны хэт і крытыяры завершэння працы перад змінайом коду. Аператары должны магчымае перзапускать хэт з вядомай точкі контролю, не прабуючы спадарацца пра схованы стан. Запісваюцься час выконання і витраты праза функцыйнальныя рэзултаты. Відразлівасць на ранніх этапах запобегае неспакоўным рахункам, калі процес пераходзіць з дэмовай среды ў спакульную.
# The ReAct loop
while True:
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
# If the model didn't ask for any tools, it's done -- that's its final answer
if response.stop_reason != "tool_use":
break
# Otherwise: run the tools, append the results, and go around again
tool_results = []
for block in response.content:
if block.type == "tool_use":
output = run_tool(block.name, block.input)
tool_results.append(
{"type": "tool_result", "tool_use_id": block.id, "content": str(output)}
)
messages.append({"role": "user", "content": tool_results})
print(response.content[0].text)
# "Booked it into your calendar -- cheapest flight was the 9:15am Alaska
# departure Friday at $138. Event added from 9:15am to 11:30am."
Надзеяныя рэзултаты
Для адказных рэзультатаў неабходна перад змянай коду задаць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння. Аператары должны магчымае перайсці на выкананне кроку з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Канфігурацыю трэба знаходзіць за межамі коду прыкладнення. Файлы сераўіса, хранальнікі секрэтных дадзеных і флагі функцыйяў должны быць у аднам месца, якое аператары можаць пераглядаць, не чытаючы весь ланцуг аперацый. Шэматы інструментаў трэба строго абмежыць. Шырокія параметры у вигляде вольнага тексту спрыяюць втручанню з боку зловераго і робяць аудыт даскладным. Для адказных рэзультатаў неабходна перад змянай коду задаць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння. Аператары должны магчымае перайсці на выкананне кроку з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Валідзіце маленькія, тэставаныя елементы замест большых скрыптаў. Калі крок не выкананы, прычына неудачы должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцуг аперацый.
system_prompt = """You have access to a web_search tool.
To use it, respond with JSON in this format:
{"name": "web_search", "input": {"query": "..."}}
CRITICAL: You MUST respond with ONLY valid JSON. NO other text.
NO markdown. NO code fences. NO explanations before or after.
Your ENTIRE response must be parseable by json.loads().
DO NOT FORGET THE COMMAS. CHECK YOUR BRACKETS.
If you output anything that is not valid JSON, the system WILL CRASH.
THIS IS EXTREMELY IMPORTANT. VALID JSON ONLY.
"""
Высокая якосць вхідных дадзеных
Для высокакалітэтных вхідных дадзенняў неабходна прадзефінаваць сэрвы вхідных дадзенняў, адпаведальнага за выкананне крока і крэтарыяў завершэння працы перад змінайом коду. Аператары должны магчыма было перзапускаць крок з вядомай точкі контролю, не падозрываючы прыхованы стан. Спрыяйце цэму этапу як кантракту межа вхіднымі дадзеннямі і пасвярджанымі выходнымі рэзультатамі. Даўце назвы артыфактам, прадзефінаваць перакананняя успеху і адмовіцеся ад беззвучнага частковага завершэння. Зробіце точку контролю пасля дорогіх вызоў модэлю, каб перапрыцёк не прабіў зноў за тую ж работу.
tools = [
{
"name": "web_search",
"description": "Search the web for current information.",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
{
"name": "add_calendar_event",
"description": "Add an event to the user's calendar.",
"input_schema": {
"type": "object",
"properties": {
"title": {"type": "string"},
"start_time": {"type": "string"},
},
"required": ["title", "start_time"],
},
},
# ...plus read_email, send_email, get_flights, book_flight,
# read_file, write_file, run_code, and 20 more
]
Даверлівасць да вашага агента
Ёнколі вы паверяеце свога агента, перад зменым коду неабяжна вызначыць параметры вводу, адпаведнага крока і критэрыі завершэння. Аператары должны магчымаць перапрыявленне крока з вядомай точкі контролю без неабяжнага адгадвання захаванога стану.
Чэк-ліст для эксплуатацыі
Для чэк-ліста для эксплуатацыі таксама неабяжна перад зменым коду вызначыць параметры вводу, адпаведнага крока і критэрыі завершэння. Аператары должны магчымаць перапрыявленне крока з вядомай точкі контролю без неабяжнага адгадвання захаванога стану.
Неабяжна задокументаваць як шлях успеху, так і шлях вярнення да нормальнага стану. Перапрыявленні, перакрыцця з боку адпаведных спецыялістаў і обработка некоректных паведамленняў є часткай продукту, а не чымс, што дадаецца пазней.
Пауза пасля дорогіх вызоў модэлі, каб перапрытак не практыкаваў зношчання за тую ж работу.
Як толькі дозволяе бюджет, дадзіце тэст на працягласць, які перабірае критычны шлях у CI з фіксатрамі.
Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі якісь крок не выйшаў, адказ за гэта павінен быць прызначаны для адной відпаведальнасці, а не для заплутанага ланцуга задач.
Пауза пасля дорогіх вызоў модэлі, каб перапрытак не практыкаваў зношчання за тую ж работу.
Перад апранаваным стэка заморозьце версіі, зафіксуйце ідеальны транскрыпт для критычнага шляху і паказваце крокі для адворачэння. У спадзяльных средах неабходны ліміты частоты вызоў, пераказкі прыналежнасці і чыстае ведамства для змены секрэтных даных. Валіце простую надзяйнасць замест крэатыўных, адзінразовых дэманстрацый.
Для захода паўжасткі №0 неабходна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры зміне коду. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю без неабясненняя схованага стану.
Запісваць час выконання і витраты разам з функцыйнальнымі рэзултатамі. Вочымае адстаўленне запобегае неспакою, калі процес пераходзіць з дэмовай среды ў спакульную.
Строго абмежыць схемы інструментаў. Шырокія параметры у вигляде вольнага тексту спрыяюць атакам і робяць аудыты дорогімі.
Для захода паўжасткі №1 таксама неабходна ўзначыць вхідныя даны, адпаведальнага за крок і крэтыяры завершэння пры зміне коду. Аператары должны магчымаць перзапуск кроку з вядомай точкі контролю без неабясненняя схованага стану.
Дакументаваць як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкія контрольныя пункты і обработка некоректных паведамленняў є часткай продукту, а не дадатковым элементам пасляўпрацоўкі.
Контрольныя пункты пасля дорогіх запытоў модэлю, ўбліж тое, каб павторны запуск не выкалецаваў дагэнь той ж самай роботы.
Для пункту 2 пра зміцненне захоўнасці неабходна перад змянай коду задаць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аперацыёныя працавнікі должны магчыма было павторна запусціць крок з вядомага контрольнага пункту, не спрабоўваючы здогадвацца пра схованы стан.
Спрыяйце цім этапу як даговору межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, задаць перакананні на успех і адмовіцеся ад беззвучнага частковага завершэння.
Раздзеліце планаванне ад выконання інструментам. Планавальнік прыметляе; выконаваць зменяе; пераканальнік пераканваецца ў рэзультатах па адносу да цялевай меты.
Для пункту 3 пра зміцненне захоўнасці неабходна перад змянай коду задаць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аперацыёныя працавнікі должны магчыма было павторна запусціць крок з вядомага контрольнага пункту, не спрабоўваючы здогадвацца пра схованы стан.
Зберагаюце канфігурацыю пазнаходзіцца за межама коду прыемліка. Файлы сяродавішчыны, хранальнікі секрэтных дадзеных і флагі функцыйяў должны быць у аднам месца, куды аператары можаць адбавляць аудыт без неабяжнага чытання всей структуры.
Строга абмежваюце схемы інструментаў. Шырокія параметры у виглядзе вольнага тексту спрыяюць втручанню з боку зловераго і робяць аудыт даскладным.
Для паўнейшага забезпечэння безпекі, як указана ў пункце 4, неабходна з’явіць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры перамены коду. Аператары должны магчымае паўтарна запускаць крок з вядомага пункта контролю, не прыпускаючы стану, які залишаецца нез’явным.
Валідзіце маленькія, тэставаныя елементы заместо вялікіх скрыптаў. Калі крок не выйшоў, прычына неудачы должна вказываць на адну конкрэтную прычыну, а не на заплутаную структуру процеса.
Ствараюце пункт контролю пасля даскладных вызоў модэлю, каб паўтарны запуск не веліў зарабляць плату знову за тую ж самую роботу.
Для прыткага зміцнення, пункт 5: перад зменшэнням коду неабяжна визначыць вхідныя даны, адміністратара крока і критэрыя завершэння. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан.
Запісваць час выконання і витраты разам з функцыйнальнымі рэзултатамі. Відразы ўчасна запобiegаюць неспакоўным рахункам, калі процес пераходзіць з дэмовай среды ў спакульную.
Раздзеляць планаванне і выконання знарядзяў. Планавальнік прымечае варыянты; выконавальнік іх рэалізуе; пераканальнік пераглядае рэзултаты за адносам да цялі.
Для прыткага зміцнення, пункт 6: перад зменшэнням коду неабяжна визначыць вхідныя даны, адміністратара крока і критэрыя завершэння. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан.
Документаваць як шлях успеху, так і шлях вярнення да нормы. Перапрыбуткі, людзкія контрольны пункты і обработка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней.
Шыматковыя схемы адзінакоў строго прыкреплены. Шырые параметры у вільным формате спрыяюць атакам на ін’екцыю данных і робяць аудыты дорогімі.
Па прыказу паўнейшай захоўкі 7, перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аператары должны магчымае перайсці канкрэтны крок з вядомага пункту контролю, не спрабоўваючы здагадвацца пра схованы стан.
Спрыяйце цім этапу як даговору межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Даць назвы артыфактам, задаць перакананні на успех і адмовіцца ад беззвучнага частковага завершэння.
Стварыце пункт контролю пасля дорогіх вызоў модэлю, каб перапрыцёк не прабаваў зноў абліковаць тую ж работу.
Па прыказу паўнейшай захоўкі 8, перад змянай коду неабходна задаць вхідныя даны, адпаведальнага за крок і критэрыя завершэння. Аператары должны магчымае перайсці канкрэтны крок з вядомага пункту контролю, не спрабоўваючы здагадвацца пра схованы стан.
Зберагаюце канфігурацыю праза ўнутрь коду прыемлі. Файлы сяродавішча, храненні секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавляць аудыт без неабяжнага чытання всей структуры.
Раздзеляйце планаванне ад выконання інструментаў. Планавальнік прымечвае варыянты; выконавальнік іх рэалізуе; пераканальнік пераглядае рынукты па адносу да цялевага рэзультата.
Для падышчы карыстаючыся прыказам 9, прайшліце заданнікі вхідных дадзеных, адпаведальнага за крок і крэтырыя завершэння пры перамены коду. Аператары павінны магчымаць перывыканне крока з вядомай точкі контролю без адгадванняя схованага стану.
Валіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшаў, прычына неудачы павінна вказываць на адну адпаведальнасць, а не на заплутаную лінію обработкі.
Строго абмежвайце схемы інструментаў. Шырокія аргументы у відкрытым формате спрыяюць втручанню і робяць аудыты дорогімі.
Для прыткага зміцнення, пункт 10: перад зменой коду неабяжна вызначыць параметры вводу, адміністратара крока і критэрыя завершэння. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан.
Запісваць час выконання і витраты разам з функцыйнальнымі рэзултатамі. Відразы ведаць дапамагае ухиліцца ад неспакою, калі процес пераходзіць з дэмовай среды ў спакульную.
Ствараць точку контролю пасля дорогіх вызоў модэлю, южы перзапуск не павярнуў бы плату за тую ж работу.
Для прыткага зміцнення, пункт 11: перад зменой коду неабяжна вызначыць параметры вводу, адміністратара крока і критэрыя завершэння. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не спрабоўваючы здагадвацца пра схованы стан.
Дакументаваць як шлях успеху, так і шлях вяснавання. Перзапускі, людскія контралі і обработка некоректных паведамленняў є часткай продукту, а не чымсь, што дадаецца пазней.
Раздзеліце планаванне ад выконання інструменту. Планавальнік прымеяе практыки; выконавальнік іх зменяе; пераканальнік пераглядае рэзультаты за адносамом да цялевай меты.
Для павышэння надзеі, прыметка 12: перад зменайом коду неабяжна визначыць вхідныя даны, адпаведальнага за крок і критэрыі завершэння. Аперацыйныя працавнікі должны магчымаць перапрыявленне крока з вядомай точкі контролю без неабяжнага адгадвання захаванага стану.
Спрытывайце гэты этап як даговор межа вхіднымі данымі і паверканымі рэзультатамі. Даеце назвы артыфактам, визначайце критэрыі успеху і адмовляйцеся ад тыхнага частковага завершэння без паведамлення.
Строго абмежвайце схемы інструменту. Шырокія аргументы у вигляде вольнага тэксту спрыяюць атакам і робяць аудыты дорогімі.
Для павышэння надзеі, прыметка 13: перад зменайом коду неабяжна визначыць вхідныя даны, адпаведальнага за крок і критэрыі завершэння. Аперацыйныя працавнікі должны магчымаць перапрыявленне крока з вядомай точкі контролю без неабяжнага адгадвання захаванага стану.
Зберагаюце канфігурацыю пазначкай за межамі коду прыемлі. Файлы сяродавішняе аб’ектаў, хранальнікі секрэтных дадзеных і флагі функцыйяў должны знаходзіцца ў аднам месцы, куды аператары можаць адбавіць аудыт без неабяжнага чытання всей структуры.
Ствараюце пункт перапытку пасля дорогіх вызоў модэлю, каб перапрыцёк не прабіў зноў абліковаць плату за тую ж работу.
Для зміцнення за прыказам 14 неабходна прадзефініраваць вхідныя даны, адпаведальнага за крок і критэрыя завершэння пры зміне коду. Аператары павінны магчымаць перзапуск крока з вядомага пункту перапытку, не спрабоўваючы здагадвацца пра схованы стан.
Валідзіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выйшоў, прычына неудачы павінна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаную лінію обробкі.
Раздзеляйце планаванне і выконання інструментаў. Планавальнік прыметляе варыянты; выконавальнік іх рэалізуе; пераканальнік пераглядае рынкі проты цялевых показначаў.
Для пункту 15 працы над зміцненням безпекі трэба пазначыць вхідныя даны, адміністратара крока і критэрыя завершэння пры перадзмене коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не прабуючы спадарацца прыватны стан.
Запісваюць час выконання і витраты праз адно з функцыйнальнымі рэзултатамі. Відразы ведаць дапамагае ухиліцца ад неспакоўных рахунков, калі процес пераходзіць з дэмаверсіі ў спяльныя среды.
Шаблоны інструментаў трэба строго абмежыць. Шырокія параметры у вільным формате спрыяюць атакам і робяць аудыты дорогімі.