Практичні поради: Створення кваліфікованих агентів
Покрокове керівництво з практичних порад: створення кваліфікованих агентів: контракти, перевірки та слоти для коду для команд, які використовують цю схему.
Використовуйте це як оновлену версію ідей з книги «Створення кваліфікованих агентів», орієнтовану на операторів: чіткі етапи, впорядковані блоки коду та примітки щодо відновлення, які зберігаються після передачі обов’язків. Етап Огляду найкраще функціонує, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний запис роботи, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-версії до спільних середовищ.
Що насправді є навичкою?
На етапі «Що таке навичка» необхідно визначити вхідні дані, відповідального за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Необхідно передбачити людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.
Аналогія
На етапі аналогії необхідно визначити вхідні дані, відповідального за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Необхідно встановити людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення під час компіляції не є гарантією повності функціоналу продукту.
У коді
На етапі попереднього написання коду необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, перевірювані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну структуру процесу. Встановлюйте людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення елементів під час компіляції не є гарантією повноти бізнес-функціоналу. На етапі попереднього написання коду необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість знову виконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-середовищ до спільних середовищ.
skills/
└── weather-skill/
├── SKILL.md # frontmatter + instructions
---
name: weather-skill
description: Get current weather for a location. Use when the user
asks about weather, temperature, or conditions anywhere.
---
# Get weather skill
.... {other instructions here}
Давайте створимо систему кріплення освітлення
Під час роботи над проектом «Давайте створимо сцену» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та наслідки часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевіряти, не читаючи весь код. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування займає години.
from dotenv import find_dotenv, load_dotenv
from langchain.agents import create_agent
from langchain.tools import tool
from langchain_openai import ChatOpenAI
_ = load_dotenv(find_dotenv())
llm = ChatOpenAI(
model="gpt-5.6-luna",
use_responses_api=True,
reasoning={"effort": "low"}, #The reasoning is medium by default so set this to l
)
@tool
def get_weather(location: str) -> str:
"""
Get the weather for a given location
"""
return f"The weather in {location} is sunny"
@tool
def get_exchange_rate(currency_from: str, currency_to: str) -> str:
"""
Get the exchange rate between two currencies
"""
return f"The exchange rate for {currency_from} to {currency_to} is 1.00"
Використання навичок для керування інструментами
Під час роботи над розділом «Використання навичок для керування процесом» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Фіксуйте назву інструменту, хеш аргументів, час відгуку та результат кожного виклику. Без цих записів дебагування агента може займати години.
skills/
└── weather-skill/
├── SKILL.md
└── forex-skill/
├── SKILL.md
---
name: forex-skill
description: Get live exchange rates between two currencies. Use this whenever the user asks about currency conversion, exchange rates, how much something costs in another currency, or comparisons like "is the dollar strong right now" — even if they don't use the words "forex" or "exchange rate" explicitly (e.g. "how much is 500 SGD in yen", "should I exchange money now or wait"). Always use this instead of guessing from memory, since exchange rates move constantly and Claude's training data has no visibility into current rates.
---
# Forex Skill
Fetches the live exchange rate between two currencies and reports it back in a clear, practical format.
## Instructions
1. **Identify both currencies.** Convert casual references to standard 3-letter ISO codes before calling the tool (e.g. "dollars" → ask which dollar: USD, SGD, AUD, etc.; "yen" → JPY; "pounds" → GBP).
2. **Handle ambiguous currency names.** If the user says something like "dollars" or "pounds" without specifying which country, ask them to clarify before calling the tool — don't assume USD/GBP by default.
3. **Call the `get_exchange_rate` tool**, passing both currency codes:
```python
get_exchange_rate(currency_from="<code>", currency_to="<code>")
```
4. **If the tool call fails or returns an error**, tell the user plainly that the rate lookup failed — don't fall back to guessing a rate from memory.
5. **Call once per currency pair.** For multi-currency questions (e.g. "compare SGD to USD, EUR, and JPY"), call the tool separately for each pair.
6. **Do the math for the user.** If they gave an amount ("convert 500 SGD to JPY"), multiply it out yourself using the returned rate — don't just hand back the raw rate and leave them to calculate it.
## Output format
...
## Examples
...
Експеримент 1: Навички у файлах
Під час виконання етапу «Навички Експерименту 1» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну функцію, а не на складну послідовність операцій. Робіть контрольні пункти після дорогих кроків. Система повторного запуску не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор намагається виконати наступний етап. Під час виконання етапу «Навички Експерименту 1» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ.
from deepagents.backends import FilesystemBackend
from deepagents.middleware import FilesystemMiddleware, SkillsMiddleware
backend = FilesystemBackend(root_dir="../", virtual_mode=True)
agent = create_agent(
model=llm,
tools=[get_weather, get_exchange_rate],
middleware=[
SkillsMiddleware(backend=backend, sources=["./skills/"]),
FilesystemMiddleware(
backend=backend,
tools=["read_file"], # read_file and nothing else
system_prompt=None,
),
],
)
Спробуйте самі
Етап «Спробуйте це» найкраще функціонує, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний результат, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф. Тримайте стан графа простим та типованим. Вкладені блоки приховують інформацію про те, який вузол записав яке поле, і ускладнюють продовження роботи після перерв.
>>> agent.invoke({"messages": [HumanMessage("What is the weather in Singapore?")]})
Singapore is currently **sunny**. It's a good time for outdoor plans.
Експеримент 2: Віддалені навички
Етап віддалених навичок Експерименту 2 працює найкраще, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний результат, один випадок невдачі та примітку про скасування змін перед розширенням обсягу. Документуйте як успішний, так і відновлювальний шляхи. Повторні спроби, людські контролі та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Зберігайте стан графа у простому та типованому вигляді. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють відновлення після перерв.
from urllib.request import urlopen
from deepagents.backends import StateBackend
from deepagents.backends.utils import create_file_data
backend = StateBackend()
skill_url = "https://raw.githubusercontent.com/.../langgraph-docs/SKILL.md"
with urlopen(skill_url) as response:
skill_content = response.read().decode('utf-8')
skills_files = {
"/skills/langgraph-docs/SKILL.md": create_file_data(skill_content),
}
agent = create_agent(
model= llm
middleware=[
SkillsMiddleware(
backend=backend,
sources=["./skills/"]
),
FilesystemMiddleware(backend=backend)
]
)
result = agent.invoke(
{
"messages": [{"role": "user", "content": "What is langgraph?"}],
# seeded into the in-state filesystem. needed for the first run
"files": skills_files,
},
)
Експеримент 3: Без інструментів
Етап інструментів Experiment 3 Zero працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям перед складними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій. Використовуйте інструменти з вузькими схемами та чіткими позначеннями побічних ефектів. Хостам потрібно знати, які виклики змінюють стан, перш ніж вони автоматично схвалять їх. Етап інструментів Experiment 3 Zero працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ.
---
name: weather-skill
description: Get current weather for a location. Use when the user asks
about weather, temperature, or conditions anywhere.
---
# Get weather skill
To get the weather of a location, run:
```bash
python skills/weather-skill/scripts/get_weather.py "<location>"
```
Returns JSON with weather condition. Parse and present naturally.
Run this script on each location the user asked for, one at a time.
#skills/weather-skill/get_weather.py
def main():
location = sys.argv[1] if len(sys.argv) > 1 else None
if not location:
print(json.dumps({"error": "location argument required"}))
sys.exit(1)
print(json.dumps({"location": location, "weather": "sunny"}))
if __name__ == “__main__”:
main()
from deepagents.backend import LocalShellBackend
backend = LocalShellBackend(
root_dir=str(Path.cwd()),
virtual_mode=False,
inherit_env=True,
)
middleware = [
FilesystemMiddleware(
backend=backend,
tools=["read_file", "ls", "glob", "execute"],
system_prompt=None,
),
SkillsMiddleware(backend=backend, sources=["./skills/"]),
]
agent = create_agent(model=llm, middleware=middleware) # no tools=
Зачекайте. Чи справді це виконалося?
Для етапу «Зачекайте, чи виконалося?» необхідно спочатку визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перевиконати крок з відомої точки контролю, не намагаючись вгадати прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, яке оператори можуть перевірити, не читаючи весь алгоритм. Встановіть людське схвалення для кроків, які спричиняють витрати грошей або змінюють дані в продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функцій.
Today's weather:
**Sydney:** Sunny
- **Melbourne:** Sunny
Рішення полягає у логуванні – але не у stdout.
Щоб виправити ситуацію на етапі логування, необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Необхідно встановити людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повності функціоналу продукту.
from pathlib import Path
import logging
LOG = Path(__file__).resolve().parent.parent / "skill.log"
logging.basicConfig(
filename=LOG, level=logging.INFO,
format="%(asctime)s [pid=%(process)d] %(message)s",
)
logging.info("invoked argv=%r cwd=%s", sys.argv, os.getcwd())
22:29:55,316 [pid=45724] invoked argv=[...get_weather.py, 'Sydney'] cwd=.../notebooks
22:29:55,316 [pid=45724] resolved location=Sydney
22:29:56,795 [pid=45725] invoked argv=[...get_weather.py, 'Melbourne'] cwd=.../notebooks
22:29:56,795 [pid=45725] resolved location=Melbourne
Баг, який пояснив увесь дизайн
Для етапу, який пояснює наявність бага, необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Краще використовувати невеликі, тестовані одиниці коду замість об’ємних скриптів. Коли крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну структуру процесу. Встановлюйте людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Компіляційна налаштування не є гарантією повноти бізнес-функціоналу. Для етапу, який пояснює наявність бага, необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-середовищ до спільних.
.Що таке virtual_mode?
Під час роботи над етапом «Що таке virtual_mode» спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допоможе зберегти чесність подальших змін у коді. Зберігайте конфігурацію окремо від коду додатку. Файли середовища, бази зберігання секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Створюйте контрольні точки після дорогих операцій. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор перезапускає пізнішу ланку.
Випадковий аргумент для всієї конструкції
Під час роботи над проектом «The accidental argument for stage» спочатку запишіть умови виконання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Одночасно задокументуйте шлях успішного виконання та шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.
То який з них вам слід створити?
Під час розробки алгоритму визначення того, яку частину потрібно запустити, спочатку запишіть „контракт“: необхідні вхідні дані, сигнал про успіх та що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на складну послідовність операцій. Робіть перевірки після дорогих кроків. Система повторного запуску не повинна знову стягувати плату за один і той самий виклик ШІ, коли оператор намагається запустити наступний етап. Під час розробки алгоритму визначення того, яку частину потрібно запустити, спочатку запишіть „контракт“: необхідні вхідні дані, сигнал про успіх та що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-режиму до спільних середовищ.
Але чи справді вам потрібні ці навички?
Але чи справді робота з проектами найкраще ведеться, якщо її розглядати як вимірювану поверхню? Запишіть один ідеальний приклад виконання, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, щоб оператори могли їх перевіряти, не читаючи весь граф. Зберігайте стан графа у вигляді простих структур із чіткими типами даних. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють продовження роботи після перерв.
Висновки
Етап „Заключні міркування“ працює найкраще, якщо його розглядати як вимірювану поверхню. Запишіть один ідеальний приклад виконання, один випадок невдачі та примітку про скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Зберігайте стан графа простим та типованим; вкладені структури приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють продовження роботи після перерв.
Чек-лист операцій
Під час роботи над етапом чек-листу операцій спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та наслідки часткової невдачі. Цей чек-лист забезпечує прозорість подальших змін у коді. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте мовчазного часткового завершення роботи.
Пункт перевірки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.
Забезпечте фіксацію версій залежностей та зафіксуйте дайджест зображення, яке використовувалося під час демонстрації. Відтворюваність краща за індивідуальні знання.
Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу від демонстрації до спільних середовищ.
Пункт перевірки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за той самий виклик LLM, коли оператор намагається знову виконати пізніший етап.
Перш ніж підвищувати рівень стека, заморозьте версії, зафіксуйте ідеальний запис для критичного шляху та підтвердьте кроки скасування змін. Спільні середовища потребують обмежень на кількість запитів, перевірок прав доступу та чіткого власника для зміни секретів. Краще надійність, навіть якщо вона здається нудною, ніж кмітливі одноразові демонстрації.
Примітка до пакету для 835597b38be4: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на кожну сесію та зберігайте транскрипції поруч із фіксами для оцінки, щоб подальша заміна моделей залишалася порівнянною.
Під час роботи над етапом 0 примітки щодо посилення безпеки спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Віддавайте перевагу малим, тестованим одиницям коду перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.
Деталь посилення безпеки 0/781: вимірюйте час виконання, клас помилки та кількість витрачених токенів для цієї примітки, а потім вирішуйте, чи залишити зміни, ґрунтуючись на фіксованому наборі питань, а не на індивідуальних спостереженнях.
Етап 1 процедури зміцнення найкраще функціонує, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний зразок роботи, один випадок збою та запис про скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам під час переходу від демо-середовища до спільних середовищ.
Деталь 1/781 процедури зміцнення: виміряйте час виконання, клас помилки та витрати на токени для цієї деталі, а потім вирішіть, чи залишити зміни, ґрунтуючись на фіксованому наборі питань, а не на окремих прикладах.