ИИ-агент на Python: практикум по циклу с инструментами
Цикл агента на Python соединяет планировщик, управляемый запуск инструментов, сохранение наблюдений и правило остановки. В практикуме детерминированный планировщик делает механику воспроизводимой без ключа API. Для подключения языковой модели замените функцию планирования через документированный интерфейс, сохранив проверки исполнения в приложении.
Нужны Python 3 и базовое знакомство с функциями и словарями. Скачиваемый пример использует стандартную библиотеку, условный каталог и вывод в консоль. Он не обращается к сети и не изменяет файлы. До изменения кода изучите журнал выполнения.
Главные идеи
- Начните с одного поиска и условных записей.
- До исполнения проверяйте имя инструмента и форму аргументов.
- Явно обозначайте отсутствующую запись.
- Лимит шагов храните вне функции планирования.
Подготовьте вход и критерий результата
Сохраните скачиваемый пример как ai-agent-lab.py и выполните python3 ai-agent-lab.py. Известный ключ 'ai' должен вернуть запись после одного поиска и финального решения. В журнале видны инструмент, проверенный вход и результат. Неизвестный ключ завершает работу со статусом unknown, без сгенерированного названия. Это ожидаемые исходы данного упражнения, а не сравнение качества языковых моделей. До запуска запишите, что именно хотите проверить, чтобы оценивать поведение программы по определённому критерию.
Разберитесь в детерминированном планировщике
Функция планирования сначала запрашивает поиск. После получения наблюдения она предлагает итог на основании этого наблюдения. Это симулятор для изучения исполняющего цикла. Его решения заданы кодом; пример не демонстрирует рассуждения модели или понимание естественного языка. Польза — воспроизводимость. Можно изменить запуск инструментов или состояние и увидеть последствия без изменяющихся ответов API. Так вы изучаете обязанности контроллера до добавления ещё одного источника неопределённости.
Сохраняйте узкий набор инструментов
Реестр содержит только lookup. Исполняющая часть проверяет тип действия, наличие имени в реестре и единственный разрешённый аргумент key. Поиск проверяет, что вход — короткая строка. Не заменяйте это функцией исполнения Python или команд оболочки, написанных моделью. Будущая модель может предложить структурированный поиск, но реестр и проверки продолжают определять, что запускается. Полезно изучить отклонённую операцию отдельно: корректно оформленный текст предложения ещё не выдаёт разрешения исполнить её.
Проверьте отсутствие данных и ограничения
Читайте статус вместе с ответом. done означает возвращённую запись, unknown — отсутствие такого ключа, stopped — исчерпание бюджета шагов. Попробуйте бюджет в один шаг: поиск выполняется, но на финальное решение планировщика уже нет шага. Исход должен остаться stopped. Это показывает, почему достижение лимита нельзя выдавать за успех только потому, что инструмент что-то вернул. Важно различать полученные промежуточные данные и завершённую исходную задачу.
Практикум на Python
"""VITON13 SCHOOL: a deterministic teaching loop, without a model or network."""
import json
CATALOGUE = {
"ai": {"title": "Applied AI", "topics": ["goals", "tools", "checks"]},
"design": {"title": "Design", "topics": ["brief", "prototype", "review"]},
}
def lookup(key):
if not isinstance(key, str) or not 0 < len(key) <= 32:
raise ValueError("key must be a string of 1-32 characters")
return CATALOGUE.get(key)
TOOLS = {"lookup": lookup}
def plan(state):
"""A simulator: replace this proposal function to study model integration."""
if not state["observations"]:
return {"type": "tool", "name": "lookup", "args": {"key": state["key"]}}
return {"type": "final", "answer": state["observations"][-1]["result"]}
def run(key, planner=plan, max_steps=3):
if type(max_steps) is not int or max_steps < 1:
raise ValueError("max_steps must be a positive integer")
state = {"key": key, "observations": []}
for _ in range(max_steps):
action = planner(state)
if not isinstance(action, dict):
raise ValueError("proposal must be an object")
if action.get("type") == "final":
if not state["observations"]:
raise ValueError("final result requires an observation")
result = state["observations"][-1]["result"]
if action.get("answer") != result:
raise ValueError("final answer must match the retrieved record")
return {
"status": "done" if result is not None else "unknown",
"answer": result, "trace": state["observations"],
}
if action.get("type") != "tool" or action.get("name") not in TOOLS:
raise ValueError("tool is not allowed")
args = action.get("args")
if not isinstance(args, dict) or set(args) != {"key"}:
raise ValueError("lookup requires exactly one key argument")
if args["key"] != state["key"]:
raise ValueError("lookup is outside the requested key")
result = TOOLS[action["name"]](**args)
state["observations"].append({
"tool": action["name"], "input": dict(args), "result": result,
})
return {"status": "stopped", "answer": None, "trace": state["observations"]}
if __name__ == "__main__":
print(json.dumps(run("ai"), indent=2))
Подключайте модель после проверки границ
Замените планирование адаптером, возвращающим ту же структуру действия через документированный интерфейс инструментов выбранного провайдера. Передавайте цель и нужные наблюдения, проверяйте предложение, исполняйте инструмент вне модели. Испытайте неверное имя, неправильные аргументы, отсутствующую запись и неподтверждённый итог. Адаптеру также нужна обработка ошибок провайдера и ограничений использования. Автономный учебный пример даёт основу управления; объединённую реализацию с моделью следует проверять отдельно, сохраняя критерии и результаты испытаний.
Простыми словами
Практикум — модель мастерской для изучения механики. Фиксированный планировщик заменяет компонент выбора действия. Вы видите работу инструмента, блокнота и остановки до подключения языковой модели, которая может предлагать разные действия.
Попробуйте сами
Запустите известный ключ, неизвестный ключ и бюджет в один шаг. Затем подставьте планировщик, запрашивающий незарегистрированный инструмент. Предскажите каждый исход до запуска и сравните ожидание с результатом.
Ожидаемый результат
Результат с источником, исход unknown, исход stopped и отклонённое предложение. Запрещённый инструмент не должен исполняться.
Проверьте себя: Что изменяется после подключения языковой модели?
Генерация предложения. Права инструментов, проверка входа, состояние и лимиты остаются обязанностями программы.
Вопросы и ответы
Для примера нужен платный API?
Нет. Учебный пример использует детерминированную функцию планирования и локальный словарь. Учётная запись и ключ API не требуются. Адаптер языковой модели — отдельное расширение: его доступ и стоимость зависят от провайдера, а поведение нужно проверять самостоятельно.
Пример можно использовать как производственного агента?
Практикум объясняет цикл на условных записях. Рабочему приложению нужны реальная интеграция модели, аутентификация, восстановление после ошибок, права доступа, наблюдаемость и проверки конкретной задачи. Проектируйте их отдельно: успешный учебный запуск ещё не подтверждает готовность системы к эксплуатации.
Запустите пример, изучите все статусы и испытайте запрещённое предложение. Сохраните проверки при подключении модели.
Источники и дальнейшее чтение
- Python documentation — Control flow ↗Источники проверены:
- Python documentation — Data structures ↗Источники проверены:
- Anthropic — Writing effective tools for agents ↗Источники проверены: