API и MCP

Адрес и авторизация

Адрес сервиса: https://api.extella.ai. Запросы ниже отправляются методом POST с JSON-телом.

Получите токен в своём аккаунте Extella: можно попросить агента «Создай API-токен для моего скрипта». Используйте ID агента и профиля, в области которых сохраняете программы. Не публикуйте токен и не вставляйте его в код страницы сайта.

Content-Type: application/json
X-Auth-Token: YOUR_TOKEN
X-Profile-Id: YOUR_PROFILE_ID
X-Agent-Id: YOUR_AGENT_ID

Храните токен на сервере или в локальном окружении. В примере на Python он запрашивается скрытым вводом.

POST/api/expert/save

Создаёт или заменяет сохранённую программу. Обязательны name, description, code. Укажите cspl явно.

{
  "name": "add_two_numbers_v1",
  "description": "Add two numbers a and b; return total.",
  "code": "def add_two_numbers_v1(a: float = 0, b: float = 0) -> dict:\n    return {\"total\": a + b}",
  "cspl": "fython",
  "kwargs": {},
  "global": false
}

Сначала проверьте имя. Сохранение поверх существующей записи заменяет её код.

POST/api/expert/get

Возвращает запись по имени. Проверяйте поля expert_name, expert_code, cspl и expert_params.

{"name": "add_two_numbers_v1"}

POST/api/expert/run

Передаёт параметры сохранённой программе. Для текущей схемы запроса имя задаётся полем expert_name.

{
  "expert_name": "add_two_numbers_v1",
  "params": {"a": 5, "b": 7},
  "targets": ["DEVICE_ID"],
  "wait": true
}

Проверьте status, затем содержимое result. При ошибке изучите execution_log. Наличие HTTP 200 ещё не доказывает, что программа завершилась успешно.

Отложенный результат

Если вызов вернул task_id, запросите состояние через POST /api/tasks/check с телом {"task_id":"TASK_ID"}. Дождитесь конечного статуса, прежде чем повторять действие, которое меняет данные.

Ограничивайте число повторов и общее время ожидания. Не выводите токен в журнал при разборе ошибки.

Разбор ошибок

Подключение через MCP

MCP даёт агенту доступ к инструментам Extella. В клиенте, который поддерживает Streamable HTTP и заголовки авторизации, добавьте подключение:

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

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