Практический запуск: от нуля до первого работающего AI-агента

AI-Агенты
Содержимое страницы

Теория об агентских системах убедительна. Но с чего начать на практике? В этой статье — конкретные шаги от выбора платформы до первого результата работы агента.

Что нам понадобится

Прежде чем писать первую строку кода, определимся с инструментарием. Для запуска минимального агента нужно:

  1. Языковая модель — «мозг» агента
  2. Среда выполнения — место, где агент запускается
  3. Инструменты — что агент умеет делать
  4. Оркестратор задач — как агент получает и отдаёт работу

Рассмотрим варианты на каждом уровне.

Выбор языковой модели

Основные провайдеры LLM для агентов:

Anthropic Claude

Лучший выбор для агентов-исполнителей. Модели семейства Claude (Sonnet, Opus, Haiku) отличаются:

  • Высокой точностью следования инструкциям
  • Надёжным использованием инструментов (tool use / function calling)
  • Большим контекстным окном (до 200 000 токенов у Claude 3.5)
  • Хорошим пониманием русского языка

Актуальные модели: claude-sonnet-4-6 (баланс качества и скорости), claude-opus-4-6 (максимальное качество).

OpenAI GPT

Широко используется, хорошая экосистема инструментов. GPT-4o подходит для агентов с необходимостью обрабатывать изображения.

Google Gemini

Сильные стороны: работа с документами, интеграция с Google Workspace, мультимодальность.

Рекомендация для старта

Начните с Claude Sonnet через API Anthropic. Хорошая документация, предсказуемое поведение, разумная стоимость.

Минимальный агент без фреймворка

Самый быстрый способ почувствовать, что такое агент — написать его напрямую через API. Вот пример на Python:

import anthropic
import json

client = anthropic.Anthropic()

# Определяем инструменты агента
tools = [
    {
        "name": "search_web",
        "description": "Поиск информации в интернете",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Поисковый запрос"
                }
            },
            "required": ["query"]
        }
    },
    {
        "name": "save_to_file",
        "description": "Сохранить текст в файл",
        "input_schema": {
            "type": "object",
            "properties": {
                "filename": {"type": "string"},
                "content": {"type": "string"}
            },
            "required": ["filename", "content"]
        }
    }
]

def run_tool(tool_name, tool_input):
    """Заглушка для выполнения инструментов"""
    if tool_name == "search_web":
        # Здесь был бы реальный поиск
        return f"Результаты поиска по запросу: {tool_input['query']}"
    elif tool_name == "save_to_file":
        with open(tool_input['filename'], 'w') as f:
            f.write(tool_input['content'])
        return f"Файл {tool_input['filename']} сохранён"

def run_agent(task: str):
    messages = [{"role": "user", "content": task}]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=4096,
            tools=tools,
            messages=messages
        )

        # Агент завершил работу
        if response.stop_reason == "end_turn":
            return response.content[0].text

        # Агент хочет использовать инструмент
        if response.stop_reason == "tool_use":
            messages.append({"role": "assistant", "content": response.content})

            tool_results = []
            for block in response.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})

# Запускаем агента
result = run_agent("Найди информацию об AI-агентах и сохрани краткое резюме в файл summary.txt")
print(result)

Это работающий минимальный агент. Он:

  1. Получает задачу
  2. Решает, нужен ли инструмент
  3. Вызывает инструмент
  4. Получает результат
  5. Продолжает до завершения

Фреймворки для агентов

Прямой API — хорошо для обучения, но неудобно для продакшна. Фреймворки берут на себя шаблонный код.

Claude Code (Anthropic)

Специализация: работа с кодовыми базами, файлами, командной строкой.

Claude Code — это агент, встроенный в среду разработки. Он умеет читать файлы, выполнять команды, создавать и редактировать код. Идеален для технических задач: рефакторинг, написание тестов, разбор ошибок.

Запуск: npx claude-code в директории проекта.

LangChain / LangGraph

Специализация: сложные цепочки обработки, RAG (поиск по своим данным), оркестрация.

LangGraph особенно хорош для агентов с циклическими потоками работы — когда агент должен итеративно уточнять свои действия.

from langgraph.graph import StateGraph
# Более сложная оркестрация, но и больше контроля

AutoGen (Microsoft)

Специализация: мультиагентные разговоры, где несколько агентов обсуждают задачу.

Подходит для задач, где нужна дискуссия: один агент предлагает, другой критикует, третий принимает решение.

Paperclip

Специализация: полноценная система управления командой агентов с задачами, бюджетами, аудитом.

Paperclip не просто запускает агентов — он управляет организацией агентов. Здесь есть роли, очереди задач, heartbeat-расписание, бюджетирование. Подходит, когда нужна не одна автоматизация, а целая команда.

Написание эффективного системного промпта

Системный промпт — это инструкции, которые определяют поведение агента. От его качества зависит 80% результата.

Структура хорошего промпта

# Роль и контекст
Ты — Content Analyst для сайта contributor.pw...

# Специализация
Твои задачи: аудит контента, SEO-анализ, написание статей...

# Правила работы
- Всегда читай существующие файлы перед редактированием
- Следуй формату из PUBLISHING-RULES.md
- Пиши на русском языке...

# Ограничения
- Не создавай файлы, если они уже существуют
- Не пуши в git без явного разрешения...

# Формат ответов
Отвечай кратко. Для кода используй блоки ```...

Принципы эффективного промпта

Конкретность: «Напиши статью ≥ 800 слов» лучше, чем «Напиши хорошую статью».

Ограничения вместо возможностей: Легче написать, что агент НЕ должен делать, чем перечислить всё, что должен.

Примеры: Если у агента есть доступ к примерам правильного поведения — он будет лучше их воспроизводить.

Эскалация: Явно укажите, когда агент должен остановиться и спросить, а не действовать самостоятельно.

Настройка инструментов

Инструменты — это функции, которые агент может вызывать. Стандартный набор:

Файловая система

tools = [
    {"name": "read_file", "description": "Читать содержимое файла"},
    {"name": "write_file", "description": "Записать содержимое в файл"},
    {"name": "list_directory", "description": "Список файлов в директории"},
]

Поиск

tools = [
    {"name": "web_search", "description": "Поиск в интернете"},
    {"name": "search_codebase", "description": "Поиск по кодовой базе"},
]

Выполнение кода

tools = [
    {"name": "run_bash", "description": "Выполнить команду в терминале"},
    {"name": "run_python", "description": "Выполнить Python-код"},
]

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

Первая задача: практический пример

Запустим реальный сценарий: агент анализирует директорию с markdown-файлами и создаёт отчёт о качестве контента.

Задача для агента:

Проанализируй все .md файлы в директории content/article/.
Для каждого файла проверь:
1. Наличие обязательных полей в front matter (title, description, date, tags)
2. Длину текста (минимум 500 слов)
3. Наличие тега <!--more-->

Сформируй отчёт в формате Markdown с таблицей результатов.
Сохрани отчёт в файл content-audit.md.

Что сделает агент:

  1. Вызовет list_directory("content/article")
  2. Для каждого файла вызовет read_file(filename)
  3. Проанализирует front matter и текст
  4. Составит таблицу
  5. Вызовет write_file("content-audit.md", report)

Это типичный агентский сценарий: итерация по данным, анализ, создание отчёта.

Отладка и улучшение агента

Первый запуск редко бывает идеальным. Что смотреть при отладке:

Логирование вызовов инструментов

Записывайте каждый вызов инструмента: что агент запросил, что получил. Это помогает понять логику принятия решений.

Промежуточные результаты

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

Итеративное улучшение промпта

Типичный цикл улучшения:

  1. Запустить агента на тестовой задаче
  2. Найти место, где поведение нежелательное
  3. Добавить в промпт явное правило для этого случая
  4. Повторить

Обычно 5–10 итераций дают стабильно работающего агента.

Безопасность: принцип наименьших привилегий

Агент с широкими правами — это риск. Несколько правил безопасности:

Изолируйте окружение: агент должен работать в директории без доступа к системным файлам, ключам API, и т.д.

Ограничьте инструменты: не давайте агенту инструмент delete_file, если задача только читать и анализировать.

Добавьте подтверждение: для необратимых действий (удаление, отправка email, деплой) требуйте явного подтверждения человека.

Логируйте всё: полный лог позволяет расследовать инциденты и восстановить хронологию.

Следующие шаги после первого агента

Когда первый агент работает стабильно, можно двигаться дальше:

  1. Добавить второго агента с другой специализацией
  2. Настроить передачу задач между агентами
  3. Подключить систему управления задачами (Paperclip, Linear, Jira)
  4. Настроить расписание для регулярных задач
  5. Добавить мониторинг производительности и стоимости

Итого

Запуск первого агента занимает несколько часов, но даёт ценный опыт:

  • Выбор модели: Claude Sonnet — хороший баланс для большинства задач
  • Прямой API подходит для прототипа, фреймворки — для продакшна
  • Системный промпт — важнейший инструмент управления поведением агента
  • Инструменты давать минимальный необходимый набор
  • Отладка — итеративный процесс уточнения промпта

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

Ссылки

Обсудите с предпринимателями

Присоединяйтесь к Telegram-чату — здесь предприниматели обсуждают автоматизацию, AI-агентов и рост бизнеса.

→ Войти в чат