Перейти к содержимому
Команда ClaudexiaОбновлено ИНСТРУКЦИЯ

Как создать ИИ-агента: схема, код на Python и варианты без кода

Как создать ИИ-агента: модель, инструменты и цикл. Минимальный код на Python с Anthropic SDK через Claudexia, n8n, Claude Code, MCP, расходы и безопасность.

ИИ-агент это языковая модель, которой вы дали инструменты и поставили в цикл. Модель просит вызвать инструмент, ваш код его выполняет и возвращает результат, модель решает, что делать дальше, и так до итогового ответа. Чтобы сделать такого агента, нужны три вещи: модель с поддержкой вызова инструментов, описание одного-двух инструментов и цикл на несколько десятков строк. Ниже схема цикла, рабочий код на Python и способы получить то же без программирования.

Что такое ИИ-агент: модель, инструменты, цикл

Определение берём у самой Anthropic, из её статьи про построение агентов. Там различают два типа систем. В workflow модели и инструменты связаны заранее прописанным кодом: шаги и их порядок известны. В агенте модель сама направляет свой процесс и выбор инструментов. Коротко Anthropic сводит агента к модели, которая использует инструменты и получает обратную связь от среды в цикле.

ЧастьЧто этоКто за неё отвечает
МодельРешает, нужен ли инструмент и с какими аргументами, и пишет итоговый ответПровайдер модели
ИнструментыФункции с описанием входа: читать файл, искать в базе, отправлять запросВы: описываете схему и пишете код
ЦиклПередаёт результаты инструментов модели и останавливается на итоговом ответеВы: пишете сами или берёте готовый

Автономия не бесплатна. Anthropic предупреждает, что агентные системы часто обменивают задержку и стоимость на качество задачи, а самостоятельность модели означает более высокие расходы и накопление ошибок. Её совет: искать самое простое решение и усложнять, только когда нужно, а иногда это значит не строить агента вовсе. Если шаги известны заранее, хватит обычной цепочки вроде workflow в n8n, агент понадобится там, где путь к ответу заранее не известен.

Паттерны вроде ReAct и Plan-and-Execute мы разбирали в статье агентные паттерны Claude, а оценку качества агентов в материале про evals.

Как устроен цикл вызова инструментов

Документация Anthropic описывает цикл так (страница «How tool use works» на platform.claude.com). Модель не выполняет код. Она отвечает структурным запросом, ваше приложение запускает операцию, а результат возвращается в разговор. Канонический вид цикла: while по полю stop_reason.

запрос (messages + tools)  <------------------------------+
        |                                                  |
        v                                                  |
ответ: stop_reason == "tool_use"?                          |
   нет -> итоговый ответ, выходим                          |
   да  -> выполнить инструменты, собрать блоки tool_result |
        |                                                  |
        +----- добавить в историю и отправить снова -------+

По шагам:

  1. Вы отправляете запрос с массивом tools и сообщением пользователя.
  2. Модель отвечает с stop_reason: "tool_use" и одним или несколькими блоками tool_use. В блоке три поля: id, name и input с аргументами по вашей схеме.
  3. Вы запускаете инструмент и оформляете результат блоком tool_result с полем tool_use_id, равным id вызова. Необязательное поле is_error: true сообщает модели, что инструмент упал.
  4. Вы отправляете новый запрос: исходные сообщения, ответ модели и пользовательское сообщение с блоками tool_result.
  5. Цикл повторяется, пока stop_reason равен tool_use. Любое другое значение (end_turn, max_tokens, stop_sequence, refusal) выходит из цикла: либо ответ готов, либо модель остановилась по другой причине, и её надо обработать.

В документации выделены два правила формата. Блок tool_result должен идти сразу за сообщением с tool_use, между ними нельзя вставлять другие сообщения. И внутри пользовательского сообщения блоки tool_result стоят первыми, текст допустим только после них. При нарушении API отвечает ошибкой вроде «tool_use ids were found without tool_result blocks immediately after». Если ответ содержит сразу несколько блоков tool_use, результаты возвращают все вместе в одном сообщении. Подробности и примеры есть на страницах Anthropic «Handle tool calls» и «Define tools», а у нас на эту тему написаны Tool use на практике и Function calling и tool use в Claude.

Минимальный агент на Python

Пример читает текстовые файлы из папки docs и отвечает по ним. Два инструмента: list_files и read_file. В коде три защиты: лимит шагов, проверка пути и передача ошибки инструмента модели.

Нужен Python 3.10 или новее (так сказано в документации SDK). На 13 ноября 2026 актуальная версия пакета anthropic равна 2.8.0 по файлу версий в документации Anthropic.

pip install anthropic
export CLAUDEXIA_API_KEY="sk_cdx_..."
python agent.py

Сам agent.py:

import os
from pathlib import Path

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.claudexia.tech",
    api_key=os.environ["CLAUDEXIA_API_KEY"],
)

MODEL = "claude-sonnet-5"
ROOT = Path("docs").resolve()
MAX_STEPS = 8
SYSTEM = "Отвечай только по файлам из папки docs. Если ответа в файлах нет, так и скажи."

TOOLS = [
    {
        "name": "list_files",
        "description": "Вернуть имена файлов в папке docs.",
        "input_schema": {"type": "object", "properties": {}},
    },
    {
        "name": "read_file",
        "description": "Прочитать текстовый файл из папки docs по имени.",
        "input_schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}},
            "required": ["name"],
        },
    },
]


def run_tool(name, args):
    if name == "list_files":
        return "\n".join(p.name for p in ROOT.iterdir() if p.is_file())
    if name == "read_file":
        path = (ROOT / args["name"]).resolve()
        if path.parent != ROOT:
            raise ValueError("файл вне папки docs")
        return path.read_text(encoding="utf-8")[:20000]
    raise ValueError(f"неизвестный инструмент: {name}")


def ask(question):
    messages = [{"role": "user", "content": question}]
    for _ in range(MAX_STEPS):
        response = client.messages.create(
            model=MODEL,
            max_tokens=1024,
            system=SYSTEM,
            tools=TOOLS,
            messages=messages,
        )
        if response.stop_reason == "max_tokens":
            return "Остановился: ответ обрезан лимитом max_tokens."
        if response.stop_reason != "tool_use":
            return "".join(b.text for b in response.content if b.type == "text")

        messages.append({"role": "assistant", "content": response.content})
        results = []
        for block in response.content:
            if block.type != "tool_use":
                continue
            try:
                output = run_tool(block.name, block.input)
                results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": output}
                )
            except Exception as exc:
                results.append(
                    {
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": str(exc),
                        "is_error": True,
                    }
                )
        messages.append({"role": "user", "content": results})
    return "Остановился: исчерпан лимит шагов."


if __name__ == "__main__":
    print(ask(input("Вопрос: ")))

Адрес https://api.claudexia.tech указан без /v1: это Anthropic SDK, он сам дописывает путь. Ключ sk_cdx_... берут в кабинете Claudexia после регистрации: логин и пароль либо вход через Google, GitHub или Telegram, минимальное пополнение один доллар. Модель claude-sonnet-5 из примера есть только в канале Premium, для ключа Cheap поставьте claude-sonnet-5-5.

Что здесь происходит. client.messages.create отправляет историю и описания инструментов. Если модель вернула tool_use, в историю добавляется её ответ целиком (response.content), затем пользовательское сообщение с результатами всех вызванных инструментов. Исключение из инструмента превращается в tool_result с is_error, и модель сама решает, повторить вызов или объяснить, что не вышло. Проверка path.parent != ROOT не даёт прочитать файл за пределами папки, а MAX_STEPS обрывает цикл, если модель зациклилась.

Причину остановки max_tokens код разбирает отдельно. По документации Anthropic она значит, что ответ оборван лимитом, и тогда либо поднимают max_tokens, либо продолжают ответ, а оборванный вызов инструмента отправляют заново с большим лимитом. Пример этого не делает: он честно сообщает об обрезании, чтобы вы не приняли огрызок за готовый ответ. Лимит 1024 в коде небольшой, при длинных ответах поднимите его.

Что мы проверили и чего не проверяли

Настоящий запрос с этим кодом через шлюз Claudexia мы не отправляли. Вместо него подняли на локальной машине сервер-заглушку, который отвечает в формате Anthropic по заранее заданному сценарию: сначала просит list_files, затем два вызова read_file, один из них с попыткой выйти из папки, затем выдаёт итоговый текст. Код отработал за три запроса, а попытка выйти из папки ушла в следующий запрос как tool_result с is_error. Подменяли только адрес. Отдельным прогоном заглушка вернула stop_reason: "max_tokens": сначала с оборванным текстом, затем с вызовом read_file вместо текста. Оба раза функция вернула сообщение об обрезании и новых запросов не отправляла.

У заглушки есть ещё одно наблюдение. Установленный SDK 2.8.0 по умолчанию отправил заголовок anthropic-version: 2026-10-21 и ключ в Authorization: Bearer, а не в x-api-key. Шлюз Claudexia принимает оба способа передачи ключа, а как он ведёт себя с версией API 2026-10-21, мы не проверяли. В этой версии Anthropic убрала параметры temperature, top_p и top_k: наш код их не передаёт. Работает ли выбранная вами модель с инструментами через шлюз, определит первый же запрос.

Короче через tool runner

SDK умеет сам вести цикл: функцию объявляют декоратором @beta_tool, схему он выводит из сигнатуры функции, а client.beta.messages.tool_runner(...).until_done() выполняет все витки, обработку ошибок и сборку результатов. Так устроен последний шаг в учебнике Anthropic «Build a tool-using agent». Мы этот вариант не запускали, поэтому в статье цикл записан вручную: так видно, что происходит.

Агент без кода: n8n, Claude Code, готовые агенты

n8n. В n8n агент собирается из узла AI Agent. Режим Tools Agent использует внешние инструменты и API и сам выбирает, какой вызвать. Среди поддерживаемых им моделей есть Anthropic Chat Model, а инструментом может быть, например, узел HTTP Request. Для диалога агента подключают Chat Trigger и узел памяти, при этом память не переносится между сессиями. У n8n есть и руководство по подтверждению человеком вызовов выбранных инструментов перед выполнением. Установку и первый workflow разбираем в статье n8n: установка и первый workflow.

Claude Code. Это готовый агент для работы с кодом: по описанию Anthropic, он понимает весь код проекта, работает с несколькими файлами и инструментами, подключает внешние системы через MCP и умеет запускать несколько агентов параллельно. Для собственных агентов у Anthropic есть Agent SDK, построенный на возможностях Claude Code. К Claudexia Claude Code подключается по адресу https://api.claudexia.tech без /v1, пошаговая настройка в статье как настроить Claude Code.

Готовые открытые агенты. Hermes Agent и OpenClaw ставятся одной командой и работают через мессенджеры, у каждого есть наша инструкция: Hermes Agent и OpenClaw. Обзор остальных вариантов, с ценами и бесплатными уровнями на 13 ноября, лежит в лучших ИИ-агентах 2026.

Агенты на стороне Anthropic. У платформы Anthropic есть Managed Agents: готовая настраиваемая оболочка агента, которая работает на управляемой инфраструктуре, для долгих и асинхронных задач. В документации у неё статус бета. Через шлюз Claudexia мы её не проверяли.

MCP: подключить инструменты, не писать их

MCP, Model Context Protocol, по определению его сайта это открытый стандарт подключения ИИ-приложений к внешним системам. Вместо того чтобы писать read_file или клиент для трекера самому, вы подключаете MCP-сервер, и его инструменты становятся доступны агенту. В Claude Code удалённый сервер добавляется командой по шаблону claude mcp add --transport http <имя> <адрес>. Как устроены такие серверы и как написать свой, объясняют статьи MCP сервер: что это и MCP-серверы для Claude.

Предупреждение из документации Claude Code стоит запомнить: прежде чем подключать сервер, убедитесь, что ему доверяете, потому что серверы, подтягивающие внешнее содержимое, открывают риск prompt injection.

Где подстерегают расходы

Источников расхода три.

Системный промпт инструментов. По таблице в документации Anthropic по ценам, при включённых tools API добавляет служебный системный промпт. Для Claude Sonnet 5 это 354 токена, для Claude Opus 5.5 286 токенов (режим tool_choice со значением auto). Описания самих инструментов тоже считаются входными токенами.

История, которая пересылается на каждом шаге. В учебнике Anthropic цикл ведёт общий список сообщений, и каждый новый запрос содержит весь предыдущий контекст. Поэтому входные токены суммируются по всем шагам, а не берутся один раз. Ниже иллюстрация на допущениях, это не замер: служебный промпт с описаниями инструментов 2000 токенов, каждый шаг добавляет в историю 1500 токенов, на каждый ответ модели уходит 300 выходных токенов. Цены Claudexia, канал Premium, прайс на 19 ноября 2026: claude-sonnet-5 стоит 0,62 доллара за миллион входных и 2,92 доллара за миллион выходных токенов.

Шагов в циклеВходных токенов всегоВыходных токеновСтоимость по прайсу
525 0001 500около 0,020 доллара
1087 5003 000около 0,063 доллара
20325 0006 000около 0,219 доллара

Шагов в четыре раза больше (с 5 до 20), а стоимость выросла примерно в одиннадцать. Если результаты ваших инструментов длиннее допущенных 1500 токенов, цифры выйдут выше. Снижает счёт кэширование промпта: чтение из кэша на Claudexia для этой модели стоит 0,08 доллара за миллион токенов.

Многие экземпляры и долгие сессии. В документации Claude Code про стоимость сказано, что при оплате по токенам средний расход по корпоративным развёртываниям составляет около 13 долларов на разработчика за активный день и 150-250 долларов в месяц, причём у 90% пользователей он ниже 30 долларов за активный день. Команды агентов в Claude Code запускают несколько экземпляров, у каждого своё окно контекста, и расход растёт с числом участников и временем их работы. Про то, как счета по агентам взлетают и как ставить потолок, мы писали отдельно: счета за ИИ-агентов.

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

Безопасность: что нельзя отдавать агенту

  • Секреты и персональные данные. Ключи, пароли, данные клиентов и чужой код под NDA не должны попадать ни в промпт, ни в ответы инструментов: всё, что агент прочитал, уходит провайдеру модели. Список и разбор в статье что нельзя отправлять в языковую модель.
  • Права на запись и удаление. Начинайте с инструментов только на чтение, как в примере выше. Опасные действия (отправить письмо, удалить, оплатить) пускайте через подтверждение человеком: в n8n такое подтверждение вызова инструмента описано в документации.
  • Содержимое из внешнего мира как команды. Результаты инструментов часто содержат внешний текст: веб-страницы, письма, загруженные файлы, ответы чужих API. Документация Anthropic называет это косвенной prompt injection: злоумышленник прячет в тексте инструкции, которые пытаются перенаправить модель. Anthropic советует держать такое содержимое внутри блоков tool_result, а не в системном промпте.
  • Свободный выход в сеть. В справке Claude про создание файлов Anthropic прямо пишет, что модель можно обмануть так, чтобы она отправила данные из контекста на чужой сервер, и поэтому сетевой доступ там можно отключить. Для своего агента вывод тот же: не давайте инструменту больше сети и файловой системы, чем нужно задаче.
  • Непроверенные MCP-серверы. См. предупреждение выше.

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

Источники

Страницы открыты 13 ноября 2026.

Частые вопросы

Что нужно, чтобы создать ИИ-агента?

Модель с поддержкой инструментов, описание хотя бы одного инструмента и цикл, который возвращает модели результаты вызовов до итогового ответа. Для обучения хватит кода из этой статьи, для работы без программирования подойдёт n8n или готовый Claude Code.

Чем агент отличается от обычного workflow?

В workflow порядок шагов задан заранее, в агенте шаги выбирает модель. По определению Anthropic, workflow это системы, где модели и инструменты связаны заранее прописанными путями кода, а агент сам направляет свой процесс.

Какую модель взять для агента?

Начните с самой дешёвой, которая справляется с вашей задачей, и поднимайтесь вверх, если ответы слабые. На 19 ноября 2026 в канале Premium Claudexia claude-haiku-5-5 стоит 0,10 и 0,36 доллара за миллион входных и выходных токенов, claude-sonnet-5 0,62 и 2,92, claude-opus-5-5 0,88 и 4,40. Как подобрать модель под задачу, написано в статье выбор модели под задачу. Sonnet 5 в Claudexia есть только в канале Premium, а Haiku 5.5 (claude-haiku-5-5) и Sonnet 5.5 (claude-sonnet-5-5) есть в обоих каналах: в Cheap Haiku 5.5 стоит 0,08 и 0,30 доллара, Sonnet 5.5 стоит 0,54 и 2,00 доллара.

Почему счёт растёт быстрее, чем число шагов?

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

Безопасно ли давать агенту доступ к файлам и почте?

Безопасность определяют права, которые вы выдали. Начинайте с чтения, ограничивайте пути и сеть, подтверждайте необратимые действия вручную и не передавайте секреты. Гарантий безопасности и законности способа мы не даём: условия вендора читаете и принимаете вы.