Штучні інтелектуальні агенти для майбутніх інженерів: пам’ять, інструменти та контрольні цикли
Практична карта складових елементів агента — планування, інструменти, пам’ять та оцінка — без зайвої термінології, яка б маскувала справжню структуру проектування.
У цьому посібнику створюється функціональний шлях для: «Усе, що майбутні інженери 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 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не здогадуючись про прихований стан.
Записуйте час виконання та витрати поруч із функціональними результатами. Чітка видимість на ранніх етапах запобігає несподіваним рахункам під час переходу з демо-середовища у спільні середовища.
Розділяйте планування та виконання за допомогою інструментів. Планувальник пропонує; виконавець здійснює зміни; перевіряючий порівнює результати з поставленими цілями.
Для примітки щодо посилення безпеки 6 також необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не здогадуючись про прихований стан.
Документуйте як оптимальний шлях виконання, так і шлях відновлення одночасно. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.
Щільно прив’язуйте схеми інструментів. Широкі параметри у вигляді вільного тексту сприяють втручанню ззовні та роблять аудити дорогими.
Згідно з порадою 7 щодо посилення безпеки, перед зміною коду необхідно визначити вхідні дані, власника кроку та критерії завершення. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Позначте елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення.
Створюйте точки контролю після дорогих викликів моделей, щоб повторна спроба не призводила до подвійного оплати однакової роботи.
Згідно з порадою 8 щодо посилення безпеки, перед зміною коду необхідно визначити вхідні дані, власника кроку та критерії завершення. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Зберігайте конфігурацію поза кодом додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код.
Розділяйте планування та виконання інструментів. Планувальник пропонує; виконавець здійснює зміни; перевіряючий порівнює результати з поставленими цілями.
Щодо пункту 9 щодо посилення безпеки, необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан.
Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних.
Суворо обмежуйте схеми інструментів. Широкі параметри у вигляді вільного тексту сприяють втручанню ззовні та ускладнюють перевірки.
Для примітки щодо посилення безпеки 10 необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Записуйте час виконання та витрати поруч із функціональними результатами. Чітка візуалізація заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні середовища.
Створюйте точку контролю після дорогих викликів моделей, щоб повторна спроба не призводила до подвійного оплати однакової роботи.
Для примітки щодо посилення безпеки 11 також необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Документуйте як успішний, так і відновлювальний сценарії роботи разом. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації.
Розділіть планування та виконання інструментом. Планувальник пропонує; виконавець здійснює зміни; перевіряючий порівнює результати з поставленими цілями.
Для заходів позиціонування №12 необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Розглядайте цю стадію як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення роботи.
Суворо обмежте схеми інструментів. Широкі параметри у вигляді вільного тексту сприяють втручанню ззовні та ускладнюють аудити.
Для заходів позиціонування №13 необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Зберігайте конфігурацію поза кодом додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код.
Створюйте контрольні точки після дорогих викликів моделей, щоб повторна спроба не призводила до подвійного обчислення того ж завдання.
Згідно з порадою 14 щодо посилення безпеки, перед зміною коду необхідно визначити вхідні дані, власника кроку та критерії завершення. Оператори мають мати можливість знову виконати крок, спираючись на відому контрольну точку, без необхідності здогадуватися про прихований стан.
Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану структуру обробки даних.
Розділяйте процес планування та виконання інструментів. Планувальник пропонує рішення; виконавець його реалізує; перевірювач порівнює результати з поставленими цілями.
Для заходів по зміцненню безпеки №15 необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан.
Записуйте час виконання та витрати поруч із функціональними результатами. Раннє відстеження допомагає уникнути несподіваних рахунків під час переходу з демо-середовища у спільні середовища.
Суворо обмежуйте схеми інструментів. Широкі параметри у вигляді вільного тексту сприяють втручанню ззовні та ускладнюють аудити.