Вызов коннектора

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

list_services: каталог

Возвращает каталог коннекторов. По MCP это статический реестр services: [{name, summary, transport}] (около 16 000 символов) без признака подключённости. Нативный инструмент агента отдаёт items (подключённые сервисы с кабинетами и статусом на момент as_of) и available (имена всего каталога). Имя в available значит «сервис существует», а не «не подключён».

describe_service: паспорт

Возвращает структурированный паспорт одного сервиса. В индексе есть модули, call_template, critical_hints и заголовки рецептов. Укажите module, чтобы получить его методы, шаблоны запросов, лимиты, пагинацию и примеры ответов. Неизвестный модуль возвращает индекс и _module_filter_warning со списком допустимых.

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

describe_service(service="wildberries") describe_service(service="wildberries", module="statistics")

connector_execute: вызов

Единый исполнитель для любого коннектора. Аргументы валидируются по схеме сервиса до любого исходящего HTTP-запроса.

connector_execute( service="wildberries", method="GET", path="/api/v1/supplier/orders", query={"dateFrom": "2026-04-15"} )

В повторяющемся сценарии вызывайте готовую функцию навыка, если она есть. В чате агента с песочницей cw.connect() позволяет читать страницы, фильтровать их и считать итог в одной ячейке Python. Сначала примените фильтры или пакетные запросы, которые поддерживает API вендора, а из ячейки верните запрошенный результат и полноту обработки.

Параметры connector_execute

Field	Type	Description
servicerequired	string	Ключ коннектора из list_services (например wildberries). Аккаунт называется суффиксом в этой же строке (`ozon:2`, `ozon:Top Zip`), отдельного поля для него нет; см. адресацию нескольких аккаунтов ниже.
module	string	REST: обычно не нужен, модуль выводится из path; укажите, только если пути нет среди рецептов. RPC: обязателен (пространство методов, например crm).
methodrequired	string	REST: HTTP-глагол (GET/POST/…). RPC: имя метода (crm.deal.list). Глагол и путь всегда в разных полях.
path	string	REST: путь с подставленными значениями (/api/v3/stocks/12); адрес объекта из ответа (meta.href) принимается как есть. RPC: пустая строка.
body	object \| array	Тело POST/PUT/PATCH или именованные аргументы RPC-метода.
query	object	Параметры строки запроса; массивы сериализуются автоматически.
files	object	Только у нативного инструмента агента. Файлы для загрузки по имени поля вендора: id вложения или артефакта, путь в песочнице. Адрес, а не base64: кодирует платформа.

REST vs RPC

Коннекторы бывают двух форм, и connector_execute обрабатывает обе:

REST (большинство коннекторов): HTTP-method, path и body/query; module выводится из пути.
RPC (например bitrix24): module (пространство методов, например crm), имя метода в method (crm.deal.list), аргументы в body, path пустой.

Точную форму показывают call_template и рецепты паспорта. HTTP-глагол с путём у RPC-сервиса отклоняется с TOOL_VALIDATION_FAILED и меню available_recipes.

Адресация нескольких аккаунтов

Когда у организации подключено больше одного аккаунта для сервиса (несколько кабинетов Ozon, например), адресуйте конкретный. Голое имя сервиса распределяет чтения по всем подключённым аккаунтам (кроме сервисов, где свод по кабинетам не складывается, например onec и moysklad: там и чтение называет один); записи должны указывать один суффиксом к сервису (id кабинета или его название), в той же строке service:

connector_execute(service="ozon:Top Zip", method="POST", path="/v1/product/import", body={ ... })

Подсказки did-you-mean

Вызовы не падают молча при почти-попадании. Рецепты служат примерами, а не белым списком, поэтому:

Неизвестный service возвращает отказ с похожими ключами в details.suggestions.
Неизвестный module возвращает TOOL_VALIDATION_FAILED со списками known_modules и suggestions, и то же даёт пропущенный там, где он нужен (RPC), с тем же списком. У REST-вызова модуль выводится из пути, и неверная метка вызов не ломает.
Path, которого нет среди рецептов, всё равно выполняется, а в метаданные ответа (и в ошибку, например 404) ложится меню available_paths. Глагол, которого нет у рецептов этого пути, не отказывает и подсказки не добавляет: какие глаголы принимает путь, решает таблица глаголов коннектора, а где она не закрыта, отвечает сам сервис.
Неизвестное подключение возвращает UNKNOWN_INSTANCE со списком candidates (connection, label), и то же самое возвращает запись, не назвавшая подключение при нескольких: код и список те же, потому что и выход тот же: взять готовый адрес connection из candidates и передать его в service целиком (service="ozon:2"). Через MCP код тот же, а какой из двух случаев это был, называет details.connector_code.

Ошибки

Вызовы коннекторов возвращают стандартный контракт ошибки инструмента: code, message, retryable, опциональные hint и details. Вызовы через MCP не несут HTTP-статуса. См. таблицу ошибок MCP и Ошибки и лимиты. Случаи, которые стоит различать:

Нет прав на путь (403). AUTH_SCOPE_MISSING: ключу или токену не хватает прав, их можно выдать новым подключением. AUTH_SCOPE_NOT_GRANTABLE: права приложения фиксированы, повтор не поможет. details называют путь, на котором отказали.
Авторизация кабинета умерла. В чате ход встаёт на паузу с карточкой переподключения и продолжается, когда аккаунт подключат заново.
Метод снят вендором. Если Wildberries или Ozon сами объявили метод выключенным (заголовок Sunset с прошедшей датой или «this method is deprecated» в теле), подсказка велит больше не звать этот путь и искать преемника в describe_service.