Обзор API-источников

API-источники предоставляют гибкий HTTP-инструмент, который позволяет вашим агентам подключаться к практически любому REST API. Если у сервиса есть API — ваш агент может им пользоваться. Никакой MCP-сервер не требуется.

Просто спросите своего агента. Самый простой способ подключить API — сообщить агенту, что вам нужно:

• «Подключи API JSONPlaceholder»
• «Добавь доступ к внутреннему API моей компании»
• «Настрой погодное API с моим ключом»

Агент сам обрабатывает конфигурацию, учётные данные и проверку.

Как это работает

Когда вы настраиваете API-источник, AIKraft Agents:

1. Создаёт гибкий HTTP-инструмент для выполнения запросов
2. Обрабатывает аутентификацию, безопасно хранит и подставляет учётные данные
3. Проверяет соединение с помощью тестового эндпоинта
4. Разрешает агенту выполнять любые запросы к базовому URL API

Результат: ваш агент может вызывать любой эндпоинт настроенного API.

Конфигурация

API-источники настраиваются с помощью JSON-файла:

{
  "type": "api",
  "name": "My API",
  "tagline": "Description of the API",
  "icon": "https://example.com/icon.png",
  "api": {
    "baseUrl": "https://api.example.com/",
    "testEndpoint": {
      "method": "GET",
      "path": "health"
    },
    "authType": "bearer"
  }
}

Поля конфигурации

Типы аутентификации

API-источники поддерживают шесть методов аутентификации:

Bearer-токен

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "bearer"
  }
}

Отправляет учётные данные как Authorization: Bearer {token}.

Аутентификация через заголовок

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "header",
    "headerName": "X-API-Key"
  }
}

Отправляет учётные данные в пользовательском заголовке: X-API-Key: {token}.

Аутентификация через параметр запроса

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "query",
    "queryParam": "api_key"
  }
}

Добавляет учётные данные как параметр запроса: ?api_key={token}.

OAuth 2.0

Два режима: авто-обнаружение (самый простой) и явная конфигурация (для провайдеров без стандартных метаданных).

Авто-обнаружение (рекомендуется)

Если API поддерживает RFC 9728 (OAuth Protected Resource Metadata), достаточно установить authType — эндпоинты и регистрация клиента обрабатываются автоматически:

{
  "api": {
    "baseUrl": "https://connect.craft.do/my/api/v1/",
    "authType": "oauth"
  }
}

AIKraft Agents отправит запрос на базовый URL, прочитает заголовок WWW-Authenticate, обнаружит метаданные OAuth, динамически зарегистрирует клиента и запустит поток авторизации. Блок конфигурации oauth не нужен.

Явная конфигурация

Для провайдеров, не предоставляющих стандартные метаданные OAuth (например, GitHub, Linear), укажите эндпоинты вручную:

{
  "api": {
    "baseUrl": "https://api.github.com/",
    "authType": "oauth",
    "oauth": {
      "authorizationUrl": "https://github.com/login/oauth/authorize",
      "tokenUrl": "https://github.com/login/oauth/access_token",
      "clientId": "your_client_id",
      "clientSecret": "your_client_secret",
      "scopes": ["repo", "read:user"]
    }
  }
}

Полный поток OAuth 2.0 с PKCE в обоих режимах. Токены автоматически обновляются и отправляются как Authorization: Bearer {token}.

Для Google, Microsoft и Slack API у AIKraft Agents встроена поддержка OAuth с предопределёнными сферами доступа — вам не нужно вручную настраивать блок oauth. Достаточно указать соответствующее поле provider.

Без аутентификации

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "none"
  }
}

Для публичных API, не требующих аутентификации.

Базовая аутентификация

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "basic"
  }
}

Отправляет учётные данные как Authorization: Basic {base64(username:password)}.

Многозаголовочная аутентификация

{
  "api": {
    "baseUrl": "https://api.example.com",
    "authType": "header",
    "headerNames": ["X-API-KEY", "X-APP-KEY"]
  }
}

Отправляет несколько учётных данных как отдельные заголовки. Каждое имя заголовка в массиве получает собственное поле ввода при аутентификации. Все заголовки включаются в каждый запрос API.

Используйте многозаголовочную аутентификацию, когда API требует двух или более заголовков аутентификации одновременно. Это часто встречается в сервисах, разделяющих идентичность и авторизацию, или требующих одновременно ключ API и секрет приложения.

Типичные сценарии использования:

• Datadog: DD-API-KEY + DD-APPLICATION-KEY
• API с ключами идентификации и подписи: отдельный ключ API и секрет
• Сервисы с учётными данными приложения и пользователя: ключ приложения и токен пользователя

Тестовый эндпоинт

Поле testEndpoint указывает эндпоинт для проверки работоспособности соединения. При проверке источника AIKraft Agents отправляет запрос на этот эндпоинт, чтобы подтвердить:

• Базовый URL доступен
• Учётные данные аутентификации действительны
• API отвечает корректно

Распространённые тестовые эндпоинты:

Выбирайте лёгкий эндпоинт, требующий аутентификации. Это одновременно проверяет доступность и действительность учётных данных.

Обновление токенов (опционально)

Для bearer-token API с собственным эндпоинтом обновления токена (не OAuth) можно настроить автоматическое обновление токена с помощью необязательного поля renewEndpoint. При истечении срока действия токена AIKraft Agents вызывает этот эндпоинт для получения нового токена — переаутентификация вручную не требуется.

{
  "api": {
    "baseUrl": "https://api.example.com/",
    "authType": "bearer",
    "renewEndpoint": {
      "path": "auth/refresh",
      "method": "POST",
      "tokenField": "access_token",
      "expiresInField": "expires_in"
    }
  }
}

Если поле body опущено, текущий токен отправляется через заголовок Authorization. Если поле body указано, заполнители {{token}} в строковых значениях заменяются текущим токеном (поддерживаются вложенные объекты).

Это для API с пользовательскими эндпоинтами обновления, а не для OAuth. Для OAuth-API используйте authType: "oauth" — токены обновляются автоматически через стандартный поток OAuth.

Почему использовать API-источники?

• Универсальная совместимость

  Любой сервис с REST API может быть интегрирован.

• Простая конфигурация

  Достаточно указать базовый URL и данные аутентификации.

• Гибкие запросы

  HTTP-инструмент может выполнять любые запросы к API — JSON-тела по умолчанию, с поддержкой сырых тел для текста, XML и других типов контента.

• Безопасные учётные данные

  Ключи API хранятся зашифрованными, а не в файлах конфигурации.

Сравнение: MCP vs API-источники

Используйте MCP-источники, когда они доступны, для более богатой интеграции с предопределёнными инструментами. Используйте API-источники для сервисов без поддержки MCP или когда требуется гибкий HTTP-доступ.

Нужен Google, Microsoft или Slack? У AIKraft Agents встроена поддержка OAuth для этих сервисов с предопределёнными сферами доступа. Просто спросите агента «подключи Google Calendar» или «добавь Slack», и он проведёт вас через поток OAuth.

Нужен любой другой OAuth-провайдер? Используйте authType: "oauth" с блоком конфигурации oauth, чтобы подключить GitHub, Linear, Notion, Spotify или любой другой сервис OAuth 2.0.

Дальнейшие шаги

Практические примеры

Реальные примеры конфигураций API-источников.