Практические примеры конфигурации API-источников

Реальные конфигурации и шаблоны использования API-источников для популярных сервисов.

Это руководство предоставляет практические примеры настройки API-источников для популярных сервисов и типовых шаблонов использования.

Примеры конфигурации

GitHub API

{
  "type": "api",
  "name": "GitHub",
  "tagline": "Access GitHub repositories, issues, and pull requests",
  "icon": "https://github.githubassets.com/favicons/favicon.svg",
  "api": {
    "baseUrl": "https://api.github.com",
    "testEndpoint": "/user",
    "authType": "bearer"
  }
}

Примеры запросов, которые может выполнять агент:

# List repositories
GET /user/repos

# Create an issue
POST /repos/{owner}/{repo}/issues
{"title": "Bug report", "body": "Description"}

# Get pull request
GET /repos/{owner}/{repo}/pulls/{pull_number}

OpenAI API

{
  "type": "api",
  "name": "OpenAI",
  "tagline": "Generate text and embeddings with GPT models",
  "icon": "https://openai.com/favicon.ico",
  "api": {
    "baseUrl": "https://api.openai.com/v1",
    "testEndpoint": "/models",
    "authType": "bearer"
  }
}

Stripe API

{
  "type": "api",
  "name": "Stripe",
  "tagline": "Manage payments, customers, and subscriptions",
  "icon": "https://stripe.com/favicon.ico",
  "api": {
    "baseUrl": "https://api.stripe.com/v1",
    "testEndpoint": "/customers?limit=1",
    "authType": "bearer"
  }
}

SendGrid API

{
  "type": "api",
  "name": "SendGrid",
  "tagline": "Send transactional and marketing emails",
  "icon": "https://sendgrid.com/favicon.ico",
  "api": {
    "baseUrl": "https://api.sendgrid.com/v3",
    "testEndpoint": "/user/profile",
    "authType": "bearer"
  }
}

Twilio API

{
  "type": "api",
  "name": "Twilio",
  "tagline": "Send SMS and make voice calls",
  "icon": "https://www.twilio.com/favicon.ico",
  "api": {
    "baseUrl": "https://api.twilio.com/2010-04-01",
    "testEndpoint": "/Accounts/{AccountSid}.json",
    "authType": "basic"
  }
}

Twilio использует базовую аутентификацию с вашим Account SID в качестве имени пользователя и Auth Token в качестве пароля.

Шаблоны аутентификации

Bearer Token (Самый распространённый)

Используется большинством современных API:

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

Сервисы, использующие bearer-токены:

• GitHub
• OpenAI
• Stripe
• SendGrid
• Slack

Пользовательский заголовок

Некоторые API используют пользовательские имена заголовков:

{
  "api": {
    "baseUrl": "https://api.exa.ai",
    "authType": "header",
    "headerName": "x-api-key"
  }
}

Сервисы, использующие пользовательские заголовки:

• Exa (x-api-key)
• Anthropic (x-api-key)
• AWS services (various)

Параметр запроса

Устаревшие API часто используют аутентификацию через параметр запроса:

{
  "api": {
    "baseUrl": "https://api.weatherapi.com/v1",
    "authType": "query",
    "queryParam": "key"
  }
}

Это добавляет `?key={your_api_key}` к запросам.

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

Для API, требующих имя пользователя/пароль:

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

Вы будете запрошены для ввода имени пользователя и пароля.

Типовые шаблоны

API с версионированными базовыми URL

Включите версию в базовый URL:

{
  "api": {
    "baseUrl": "https://api.example.com/v1"
  }
}

API с URL, зависящими от租户

Для многоклиентских API:

{
  "api": {
    "baseUrl": "https://your-tenant.api.example.com"
  }
}

Самохозяйственные API

Для внутренних или самохозяйственных сервисов:

{
  "api": {
    "baseUrl": "https://internal-api.yourcompany.com",
    "testEndpoint": "/health"
  }
}

Выбор тестового эндпоинта

Выберите эндпоинт, который:

• Требует аутентификации (проверяет учётные данные)
• Возвращает быстро (лёгкий ответ)
• Всегда доступен (не подвержен ограничению скорости)

Избегайте использования эндпоинтов, которые изменяют данные, в качестве тестовых. Ограничьтесь GET-запросами, которые только читают информацию.

Работа с API-источниками

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

Формат запроса

Агент использует HTTP-инструмент для выполнения запросов:

Make a GET request to /users/123

POST to /messages with body: {"text": "Hello", "channel": "general"}

Заголовки и тело

Агент может указывать:

• HTTP-метод (GET, POST, PUT, DELETE, PATCH)
• Путь (относительно базового URL)
• Параметры запроса
• Тело запроса (JSON по умолчанию)
• Дополнительные заголовки

Заголовки аутентификации добавляются автоматически.

Сырые (не JSON) тела запросов

По умолчанию параметры тела запроса кодируются в JSON. Для эндпоинтов, ожидающих plain text, XML или другие не JSON-типы контента, агент может использовать параметр _rawBody:

POST to /documents/review with params: { "_rawBody": "approved", "_contentType": "text/plain" }

Используйте _rawBody, когда эндпоинт API ожидает plain string, XML-полезную нагрузку или любое другое не JSON-тело. Значение отправляется точно так, как предоставлено — без сериализации.

Обработка ответов

Ответы API обрабатываются интеллектуально:

• JSON-ответы разбираются и представляются понятно
• Большие ответы могут быть свернуты
• Ошибки сообщаются с кодами статуса и сообщениями
• Ограничения скорости отображаются для помощи в отладке

Устранение неполадок

Тест подключения завершается ошибкой

• Проверьте правильность и доступность базового URL
• Убедитесь, что тестовый эндпоинт существует и правильно написан
• Убедитесь, что учётные данные действительны и имеют необходимые разрешения
• Некоторые API требуют определённых заголовков — проверьте документацию

Аутентификация не работает

• Убедитесь, что вы используете правильный тип аутентификации
• Для bearer-токенов убедитесь, что токен не истёк
• Для базовой аутентификации проверьте правильность имени пользователя и пароля
• Проверьте, требует ли API дополнительных заголовков

Запросы возвращают ошибки

• Проверьте документацию API на наличие обязательных параметров
• Убедитесь, что путь эндпоинта указан правильно
• Убедитесь, что формат тела запроса соответствует ожиданиям
• Проверьте ограничения скорости или квоты

Неправильный заголовок аутентификации

• Используйте headerName, чтобы указать пользовательские имена заголовков для типа аутентификации header
• Используйте queryParam, чтобы указать имя параметра запроса для типа аутентификации query
• Используйте authScheme, чтобы настроить префикс bearer (по умолчанию: "Bearer")