Как собрать своего первого ИИ-агента: модель, несколько инструментов и цикл

«ИИ-агент» звучит так, будто для него нужны фреймворк, векторная база данных и выходные на настройку. Это не так. Собственное определение Anthropic приятно лаконично: агент — это LLM, автономно использующий инструменты в цикле. Как только вы увидите этот шаблон, вы сможете собрать полезного первого агента менее чем в сотне строк кода — и, что не менее важно, понять, когда этого делать не стоит.

Основной цикл

Любой агент, каким бы навороченным он ни был, — это один и тот же четырёхшаговый цикл:

1. Вы даёте модели цель и список инструментов, которые ей разрешено вызывать.
2. Модель решает, ответить напрямую или вызвать инструмент.
3. Ваш код выполняет инструмент и возвращает результат модели.
4. Повторяйте, пока модель не сообщит, что закончила.

Модель никогда сама не касается вашей файловой системы или сети. Она лишь просит запустить инструмент; ваш код решает, делать ли это и как именно. В этом зазоре и живёт вся ваша безопасность.

Конкретный пример

Вот минимальный агент, способный отвечать на вопросы с помощью инструмента-калькулятора. Важна именно структура — та же форма масштабируется до редактирования файлов, веб-поиска или запросов к базе данных.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

Этот цикл while и есть агент. Модель видит вопрос, просит вызвать calculator с "1894 * 37 + 12", ваш код выполняет это, возвращает 70090, и модель пишет итоговый ответ. Замените калькулятор на пару read_file/write_file — и у вас получится примитивный кодинг-агент.

Инструменты — это та часть, которая действительно важна

Модель ровно настолько способна, насколько способны инструменты, которые вы ей даёте, и именно на проектировании инструментов спотыкается большинство первых агентов. Рекомендации Anthropic по написанию инструментов для агентов сводятся к нескольким правилам:

• Называйте и описывайте инструменты так, будто пишете для нового коллеги. search_invoices(customer_id, date_range) лучше расплывчатого query(sql) — чем чётче контракт, тем меньше ошибочных вызовов.
• Возвращайте результаты с высоким сигналом, а не сырые свалки данных. Если инструмент возвращает 5000 строк JSON, вы только что потратили бюджет контекста модели на шум. Урежьте до полезного.
• Делайте ошибки поучительными. «File not found: did you mean config.yaml?» позволяет модели восстановиться; голый стек вызовов — обычно нет.

Ограничители — прежде чем дать ему запуститься

Поскольку именно ваш код выполняет каждый вызов инструмента, за безопасность отвечаете вы. Три ограничителя, которые стоит добавить до того, как агент коснётся чего-то реального:

• Ограничьте цикл. Добавьте лимит на число итераций, чтобы запутавшийся агент не крутился вечно (и не накрутил счёт).
• Поставьте барьер на разрушительные действия. Всё, что удаляет, отправляет или платит, должно требовать подтверждения или сначала выполняться в песочнице.
• Проверяйте входные данные инструментов. Никогда не применяйте eval() к недоверенным строкам и не передавайте вывод модели напрямую в shell. Относитесь к каждому аргументу инструмента как к недоверенному пользовательскому вводу — потому что по сути это он и есть.

Когда НЕ стоит строить агента

Самое полезное, что стоит усвоить пораньше: множество задач вообще не требуют агента. Если шаги известны заранее — получить данные, обобщить их, отправить сводку по почте, — обычный скрипт с одним-двумя вызовами модели дешевле, быстрее и проще в отладке. Anthropic называет это рабочими процессами (workflows) и рекомендует их всякий раз, когда путь предсказуем. Берите настоящего агента только тогда, когда модели действительно нужно решать, что делать дальше, исходя из того, что она обнаруживает.

Начните с четырёхшагового цикла выше, дайте ему один-два хорошо описанных инструмента, ограничьте число итераций и добавьте реальную задачу. Один работающий агент научит вас большему, чем любой объём документации по фреймворкам.