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

Эта инструкция — для тех, кто подключает агентский клиент или свою интеграцию. Для обычной работы в браузере начните с [первого результата в Studio](/docs/knowledge/start/first-result.md); выбирать технические подключения для этого не нужно.

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

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

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

Следуйте [настройке Provider](/provider/) и [подключению MCP](/docs/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](https://openrouter.ai/docs/guides/best-practices/prompt-caching).

Практически: если вы подключаете готовый клиент к 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/`:

```json
{
  "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` и добавьте новые сообщения.

| Протокол           | Что передавать для кэширования                                                                                                                                                                                                                                                                                              |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chat Completions   | Для Claude Artillect добавляет автоматический `cache_control`, если его не задал клиент. Для поддерживающих неявное кэширование моделей используется механизм провайдера. `session_id` или `X-Session-Id` помогают маршрутизации.                                                                                           |
| Anthropic Messages | Клиент сам помечает повторяемые текстовые блоки `system` или сообщений через `cache_control: {"type":"ephemeral"}`. Автоматическую настройку Chat Completions этот маршрут не добавляет; отдельного `session_id` в его JSON-контракте нет.                                                                                  |
| Responses          | Используйте неявный кэш выбранной модели и стабильный `prompt_cache_key`, если клиент его поддерживает. Anthropic-поле `cache_control` и `session_id` в JSON этого маршрута не принимаются. Историю передавайте в `input`; `store` поддерживается только как `false`, восстановление по `previous_response_id` отсутствует. |

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

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

Через [хранилище](/docs/knowledge/guides/storage-and-privacy.md) можно загружать и скачивать инструкции агентов `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. Перед скачиванием проверьте возможности своего клиента: [файлы и доставка результата](/docs/knowledge/guides/user-files-and-delivery.md).

Дальше: [полная инструкция и ограничения](/docs/artillect-provider.md), [файлы пользователя](/docs/knowledge/guides/user-files-and-delivery.md), [стоимость](/docs/knowledge/guides/pricing-and-reserve.md).