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

Любой коннектор — REST или RPC — вызывается через одни и те же три инструмента. Они доступны как нативные инструменты агента и через MCP-сервер. Флоу всегда один: получить каталог, прочитать паспорт сервиса, выполнить вызов.

1

list_services — каталог

Возвращает каталог коннекторов: канонический key и однострочное summary на каждый сервис. Размером с рукопожатие (~2–5 КБ), поэтому любая сессия может начинаться отсюда. При подключённых аккаунтах каждая позиция помечается connected: true/false.

2

describe_service — паспорт

Возвращает структурированный паспорт одного сервиса: его модули, типовые рецепты (конкретные примеры VERB /path с шаблонами тела), лимиты, подсказки по полям и пагинации, enum'ы, примеры ответов и version/ttl для клиентского кэширования. Вызовите без module для индекса, затем с module — для полной спецификации модуля.

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

connector_execute — вызов

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

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

Параметры connector_execute

FieldTypeDescription
servicerequiredstringКлюч коннектора из list_services (например wildberries). Может нести суффикс аккаунта — см. адресацию нескольких аккаунтов ниже.
modulestringПодобласть коннектора (statistics, content, …), как указано в паспорте.
methodrequiredstringREST: HTTP-глагол (GET/POST/…). RPC: имя RPC-метода.
pathstringREST: путь запроса. RPC: оставьте пустым, имя метода передайте в method.
bodyobjectТело запроса для записывающих вызовов.
queryobjectПараметры строки запроса.
instance_idstringНацелиться на конкретный подключённый аккаунт, когда их несколько.

REST vs RPC

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

  • REST (большинство коннекторов) — передайте module, HTTP-method, path и body/query.
  • RPC (например bitrix24, семейство onec) — оставьте path пустым, а имя RPC-метода передайте в method.

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

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

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

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

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

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

  • Неизвестный module возвращает жёсткую ошибку с подсказками did_you_mean и списком known_modules.
  • Неизвестный или несовпавший path всё равно выполняется, но добавляет мягкую подсказку path_did_you_mean и меню available_paths в метаданных ответа.
  • Неизвестный аккаунт возвращает UNKNOWN_INSTANCE со списком candidates.

Ошибки

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

Была ли страница полезна?