Provider, MCP и агентский клиент

Эта инструкция — для тех, кто подключает агентский клиент или свою интеграцию. Для обычной работы в браузере начните с первого результата в Studio; выбирать технические подключения для этого не нужно.

Provider подключает языковую модель для диалога и работы с кодом. MCP даёт клиенту инструменты Artillect для работы с моделями, файлами и генерациями. Можно подключить один из них или оба. Выбрать способ работы поможет техническая документация.

Подключение и права

Из карточки языковой модели откройте «Подключить через Artillect Provider». На странице настройки будут название и идентификатор выбранной модели. Создайте ключ Artillect, выберите своего клиента и следуйте его инструкции. Основную модель встроенного ассистента и модель внешнего клиента можно выбирать независимо.

Следуйте настройке Provider и подключению MCP. Provider требует provider:write/models:read. Для медиа нужны подходящие images:write/videos:write/projects:write; files:write нужен для загрузки медиа и текстовых документов в хранилище. MCP также поддерживает OAuth. Ключ не вставляют в промпт, репозиторий или публичный лог.

Порядок работы

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

Технические детали

Где кэшируется контекст Provider

Если вы подключили Artillect Provider к своему приложению, приложение хранит историю диалога и передаёт нужные сообщения в каждом запросе. Кэширование промпта (prompt caching) выполняется на стороне провайдера языковой модели через OpenRouter. Оно повторно использует обработанный префикс и может уменьшить стоимость и задержку; это не память диалога и не замена отправке истории.

В Chat Completions для моделей anthropic/* Artillect добавляет cache_control: {type:"ephemeral"}, если клиент не передал настройки кэширования на уровне запроса или текстовых блоков. Явные настройки сохраняются. Для native Anthropic Messages и Responses клиент передаёт параметры соответствующего протокола. Возможность, минимальный размер префикса, срок жизни и тариф кэша зависят от модели и провайдера; каждый запрос не гарантирует cache hit.

Стабильные системные инструкции и неизменный префикс повышают вероятность повторного использования. В Chat Completions session_id или заголовок X-Session-Id помогают OpenRouter направлять сессию тому же провайдеру, но не восстанавливают пропущенные сообщения. Смотрите usage.prompt_tokens_details.cached_tokens, cache_write_tokens и фактическую usage.cost; запись в кэш тоже может оплачиваться. Правила OpenRouter.

Практически: если вы подключаете готовый клиент к Artillect Provider, отдельный кэш-сервер, база кэша и ручная загрузка контекста в хранилище не нужны. Для своего приложения:

1. Сохраняйте историю у себя и отправляйте нужные сообщения в каждом запросе, включая результаты вызовов инструментов.
2. Держите постоянные инструкции, определения инструментов и документы в начале запроса. Новые сообщения добавляйте в конец. Случайный ID или текущее время в начале меняют префикс и могут помешать cache hit.
3. Для Chat Completions используйте одну модель и постоянный session_id в пределах диалога. Новый диалог получает новый ID; не генерируйте новый ID на каждый запрос.
4. Через Claude Chat Completions начните без собственного cache_control: Artillect добавит его автоматически. Если нужен явный срок жизни, маршрут принимает {"type":"ephemeral","ttl":"5m"} или "1h"; более длинная запись может стоить дороже. Не передавайте Anthropic-настройки кэша другим моделям без проверки их контракта.
5. Проверяйте usage.prompt_tokens_details.cached_tokens > 0 в последующих ответах с повторяющимся достаточно длинным префиксом. Ноль у первого или короткого запроса допустим. Для стриминга запросите stream_options: {"include_usage":true} и прочитайте usage в конце потока.

Пример тела запроса на POST /api/v1/provider/chat/completions/:

{
  "model": "anthropic/claude-sonnet-5.5",
  "session_id": "dialog-123",
  "messages": [
    { "role": "system", "content": "Постоянные инструкции приложения" },
    { "role": "user", "content": "Первый вопрос" },
    { "role": "assistant", "content": "Предыдущий ответ" },
    { "role": "user", "content": "Следующий вопрос" }
  ],
  "stream": true,
  "stream_options": { "include_usage": true }
}

Это пример структуры, а не достаточно длинный промпт для гарантированного cache hit. На следующем шаге сохраните префикс, тот же session_id и добавьте новые сообщения.

Скидка не вычисляется по догадке: Artillect использует фактическую usage.cost upstream, включая чтение и запись кэша. Предварительный резерв может быть выше окончательного списания. Статус и безопасная диагностика запроса доступны через GET /api/v1/provider/requests/?id=<X-Artillect-Request-Id> тому же пользователю и API-ключу; там видны held_tokens, charged_tokens, cost_usd и счётчики кэша, если их вернул upstream.

Хранение инструкций агентов и skills

Через хранилище можно загружать и скачивать инструкции агентов AGENTS.md, определения skills SKILL.md и другие Markdown/TXT-документы. Доступ есть через Public API, MCP и CLI. Клиент сам скачивает документ и подключает его к агенту; файл в хранилище не становится контекстом модели или записью prompt cache автоматически.

Provider возвращает текст, reasoning и предложения вызовов инструментов (tool calls). Агентский цикл и исполнение инструментов организует ваш клиент. MCP предоставляет catalog → estimate → submit → polling → delivery. Для генерации медиа сохраняйте task_id: идентификатор запроса Provider его не заменяет.

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

Дальше: полная инструкция и ограничения, файлы пользователя, стоимость.