DeepSeek Harness AI Agent: архитектура и задачи

Эта статья показывает, как последовательно собрать DeepSeek Harness AI Agent: сначала проверить минимальный цикл, затем подключить инструменты, сохранить состояние и подготовить среду для длительного выполнения. Мы отдельно разбираем границу между официально подтверждёнными возможностями API и функциями стороннего проекта.

Подходит: сначала соберите минимальный цикл DeepSeek Harness AI Agent, а затем добавляйте инструменты, память и параллельные задачи. Не подходит: начинать с многоагентной системы и широкими правами доступа — так сложнее понять, где именно возникает сбой.

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

Последнее обновление — 17 августа 2026 года. Мы сверили официальную документацию DeepSeek API, материалы организации DeepSeek и открытый репозиторий deepseek-harness. Возможности сторонних оболочек не считаются официальными возможностями API и требуют отдельной проверки в изолированной среде. В сентябре 2026 официальный репозиторий deepseek-ai/deepseek-harness и CLI dsh уже открыты; чтобы поставить официальный рантайм и прогнать Web / headless, читайте DeepSeek Harness dsh: установка. Этот текст по-прежнему про свой цикл и приёмку инструментов, он не заменяет официальную документацию CLI.

Эта статья рассчитана на три группы читателей:

• разработчиков, которые впервые знакомятся с DeepSeek Harness и хотят создать первого AI Agent;
• небольшие команды, переносящие локальный прототип в постоянно работающую среду;
• технических руководителей, которым нужно проверить корректность инструментов, восстановление после ошибок и реальную завершённость задач.

Подготовка минимальной задачи

До написания кода зафиксируйте границы первого сценария. Нам достаточно четырёх элементов:

1. входной запрос;
2. один разрешённый инструмент;
3. ожидаемый формат результата;
4. условие завершения.

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

Нужно также разделить два уровня системы. Официальный API DeepSeek поддерживает вызов функций: приложение передаёт модели описание инструмента, получает вызов с аргументами, самостоятельно выполняет функцию и отправляет результат обратно. Модель не получает прямого доступа к вашей файловой системе или командной оболочке. Это описано в официальном руководстве по вызову инструментов DeepSeek.

DeepSeek Harness следует рассматривать как сторонний слой оркестрации, пока конкретный репозиторий и его версия не проверены. В открытом проекте могут присутствовать CLI, MCP-интеграция, Skill-пакеты или собственный класс агента, но наличие этих компонентов не означает, что они входят в официальный API или имеют стабильный жизненный цикл.

Перед установкой полезно сверить общую структуру API в официальной документации DeepSeek. Для сторонних пакетов отдельно фиксируйте commit или релиз. README показывает заявленную модель использования, но не является гарантией совместимости с каждой версией клиента.

Официальное описание метода Chat Completions указывает, что функции передаются через параметр tools. API допускает до 128 функций в одном запросе, но это технический предел, а не практическая рекомендация. Для первого агента достаточно одного инструмента. Несколько похожих функций увеличивают вероятность ошибочного выбора и усложняют разбор журналов. Подробности параметров проверяйте в документации метода создания Chat Completion.

Первый час разработки

Минимальный AI Agent состоит из четырёх независимых частей.

Адаптер модели отправляет сообщения и возвращает ответ. Он не должен отвечать за права файлов, запуск команд или хранение артефактов.

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

История сообщений соединяет этапы выполнения. В ней сохраняются запрос пользователя, ответ ассистента с вызовом функции и сообщение с результатом инструмента.

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

Базовый поток можно представить так:

messages = [
    {
        "role": "user",
        "content": "Прочитайте config.json и верните значение ключа environment"
    }
]

response = client.chat.completions.create(
    model="выбранная_модель",
    messages=messages,
    tools=[read_config_tool],
    tool_choice="auto"
)

assistant_message = response.choices[0].message
messages.append(assistant_message)

if assistant_message.tool_calls:
    call = assistant_message.tool_calls[0]
    arguments = validate_arguments(call.function.arguments)
    result = read_config(arguments)

    messages.append({
        "role": "tool",
        "tool_call_id": call.id,
        "content": serialize_result(result)
    })

    final_response = client.chat.completions.create(
        model="выбранная_модель",
        messages=messages,
        tools=[read_config_tool]
    )

Это не production-реализация. В примере нет памяти, параллельных вызовов и автоматического исправления ошибок. Такая простота нужна намеренно: по журналу можно быстро определить, на каком этапе сломалась цепочка.

Для разбора ответа и безопасной обработки аргументов используйте стандартный парсер, а не ручное извлечение строк. Ограничения и поведение модуля описаны в официальной документации Python по работе с JSON. Схему параметров удобно сверять с официальной спецификацией JSON Schema для объектов.

За первый час мы проверяем пять условий:

• запрос действительно дошёл до API;
• ответ содержит корректный текст или вызов инструмента;
• аргументы можно разобрать как JSON;
• функция возвращает результат в ожидаемом формате;
• следующий ответ завершает задачу, а не создаёт бесконечное повторение.

Для сценария, где вызов заранее обязателен, можно использовать tool_choice="required" или выбрать конкретную функцию. В свободной задаче это ограничение способно заставить модель вызывать ненужный инструмент. Поэтому для общего агента безопаснее начинать с автоматического выбора и контролируемого списка функций.

Регистрация инструмента и возврат результата

Схема пользовательской функции

Описание инструмента влияет на решение модели. Формулировка «работа с файлами» слишком широкая. Лучше указать конкретный файл, разрешённую операцию и запрет на изменение данных.

read_config_tool = {
    "type": "function",
    "function": {
        "name": "read_config",
        "description": (
            "Читает значение из config.json "
            "в разрешённом рабочем каталоге и не изменяет файл"
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "key": {
                    "type": "string",
                    "description": "Имя конфигурационного ключа"
                }
            },
            "required": ["key"],
            "additionalProperties": False
        }
    }
}

Для параметров используется JSON Schema. Даже хорошая схема не заменяет локальную проверку. Аргументы из ответа модели нужно разобрать, проверить типы, допустимые значения, существование пути и права операции. Нельзя передавать полученную строку напрямую в shell-команду или файловый API.

Особенно важно разделять функции с побочным эффектом:

• чтение данных;
• подготовка изменения;
• применение изменения;
• публикация результата.

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

Журнал вызова

Каждый вызов сохраняйте как отдельное событие. Минимальная запись содержит:

• идентификатор задачи;
• имя инструмента;
• исходные аргументы;
• аргументы после нормализации;
• время начала и окончания;
• результат или класс ошибки;
• номер итерации;
• решение о повторе.

Не ограничивайтесь строкой «инструмент завершён». Такая запись не объясняет, передала ли модель неправильный путь, вернула ли функция пустой результат или истёк тайм-аут.

Ошибки должны возвращаться в структурированном виде:

{
  "ok": false,
  "error_type": "validation_error",
  "message": "Ключ не найден",
  "retryable": false
}

Поле retryable помогает не запускать повторную попытку там, где проблема связана с неверным запросом. Сетевой сбой и временная недоступность сервиса могут быть повторяемыми. Отсутствующий файл или запрещённый путь обычно требуют изменения входных данных.

Состояние и длинные задачи

Хранить всю историю в одном контексте удобно только для короткой демонстрации. В рабочем агенте мы разделяем состояние на три слоя.

Краткосрочное состояние — сообщения текущего цикла и последние ответы инструментов. Оно нужно для принятия следующего решения.

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

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

Для длинной операции задайте явные стадии:

queued
  ↓
planning
  ↓
executing
  ↓
validating
  ├── completed
  ├── paused
  └── failed

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

Правила восстановления:

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

Условия выбора архитектуры

• Если задача длится недолго и не имеет побочных эффектов, достаточно истории сообщений и локального журнала.
• Если задача переживает перезапуск, добавьте постоянное хранилище состояния.
• Если создаются файлы или патчи, храните их как артефакты, а не только в prompt.
• Если участвуют разные разработчики, создавайте отдельный рабочий каталог для каждого запуска.
• Если требуется ручная проверка, добавьте состояние awaiting_confirmation, а не пытайтесь имитировать согласие пользователя внутри prompt.

Кодирующий агент и рабочая среда

DeepSeek Harness можно применять для экспериментального coding agent, если ограничить область действий. Подходящий набор операций:

1. прочитать структуру репозитория;
2. найти связанные файлы;
3. составить план;
4. подготовить патч;
5. запустить разрешённые тесты;
6. сформировать отчёт;
7. ожидать подтверждения.

Неподходящий вариант — выдать агенту полный доступ к домашнему каталогу, сети и оболочке, а затем рассчитывать на один системный prompt. Такой дизайн плохо восстанавливается, трудно проверяется и создаёт лишние риски при ошибочном вызове.

Постоянная среда для кодирующего агента должна включать:

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

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

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

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

Для таких случаев можно рассмотреть удалённую облачную среду Mac. Регион выбирайте по задержке, правилам доступа и расположению команды, а не только по названию площадки.

Деплой и приёмочная проверка

Перед переносом прототипа закрепите окружение:

1. Зафиксируйте версию Python или Node.
2. Зафиксируйте версии зависимостей.
3. Сохраните конкретный commit DeepSeek Harness.
4. Передавайте API-ключ через окружение, а не через код.
5. Создайте рабочий каталог на каждую задачу.
6. Разделите логи API, инструментов и приложения.
7. Установите общий тайм-аут и лимит итераций.
8. Ограничьте число одновременных запусков.
9. Проверьте остановку и восстановление процесса.
10. Удалите секреты из журналов и сообщений.

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

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

Завершение. Задача получает явный статус completed, failed или paused.

Параметры. Аргументы инструмента не только валидны как JSON, но и допустимы по смыслу: путь существует, значение разрешено, операция соответствует правам.

Восстановление. Тестируются ошибка API, тайм-аут, невалидный результат инструмента, остановка процесса и повторная доставка события.

Повторяемость. Одинаковый вход не создаёт повторный побочный эффект после безопасного восстановления.

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

Используйте следующий алгоритм решения:

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

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

Если агент будет месяцами выполнять стабильную тяжёлую нагрузку, работать с физическими интерфейсами или функционировать без сетевой зависимости, аренда не всегда окажется лучшим решением. Но для проверки DeepSeek Harness AI Agent, повторяемых экспериментов и изолированных задач сначала важнее управляемая среда, чем сложная постоянная инфраструктура.