HTTP-запросы

Инструмент http_request позволяет агентам PRX выполнять прямые HTTP-запросы к внешним API. Он предназначен для структурированного взаимодействия с API -- получение JSON-данных, вызов REST-эндпоинтов, отправка вебхуков -- а не для общего веб-сёрфинга. Инструмент применяет политику запрета по умолчанию: доступны только домены, явно указанные в allowed_domains.

HTTP-запрос защищён feature-гейтом и требует http_request.enabled = true в конфигурации. В отличие от инструмента браузера, который рендерит веб-страницы, инструмент HTTP-запросов работает на уровне протокола, что делает его быстрее и более подходящим для интеграций с API.

Инструмент поддерживает все стандартные HTTP-методы (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), пользовательские заголовки, тела запросов и настраиваемые таймауты. Тела ответов захватываются с ограничением настраиваемого максимального размера для предотвращения исчерпания памяти.

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

[http_request]
enabled = true
allowed_domains = [
  "api.github.com",
  "api.openai.com",
  "api.anthropic.com",
  "httpbin.org"
]
max_response_size = 1000000   # Максимальный размер тела ответа в байтах (1 МБ)
timeout_secs = 30             # Таймаут запроса в секундах

Белый список доменов

Список allowed_domains -- основной механизм безопасности инструмента HTTP-запросов. Разрешены только запросы к доменам из этого списка. Правила сопоставления доменов:

Паттерн	Пример	Совпадает с
Точный домен	"api.github.com"	только api.github.com
Подстановка поддомена	"*.github.com"	api.github.com, raw.github.com и т.д.
Домен верхнего уровня	"github.com"	только github.com (не поддомены по умолчанию)

WARNING

Пустой список allowed_domains означает, что HTTP-запросы запрещены, даже если инструмент включён. Это безопасная настройка по умолчанию.

Использование

GET-запрос

Получение данных из REST API:

{
  "name": "http_request",
  "arguments": {
    "method": "GET",
    "url": "https://api.github.com/repos/openprx/prx/releases/latest",
    "headers": {
      "Accept": "application/vnd.github+json",
      "Authorization": "Bearer ghp_xxxxxxxxxxxx"
    }
  }
}

POST-запрос

Отправка данных на эндпоинт API:

{
  "name": "http_request",
  "arguments": {
    "method": "POST",
    "url": "https://api.example.com/webhooks",
    "headers": {
      "Content-Type": "application/json"
    },
    "body": "{\"event\": \"task_completed\", \"data\": {\"task_id\": 42}}"
  }
}

PUT-запрос

Обновление ресурса:

{
  "name": "http_request",
  "arguments": {
    "method": "PUT",
    "url": "https://api.example.com/config/settings",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer token-here"
    },
    "body": "{\"theme\": \"dark\", \"language\": \"en\"}"
  }
}

DELETE-запрос

Удаление ресурса:

{
  "name": "http_request",
  "arguments": {
    "method": "DELETE",
    "url": "https://api.example.com/items/42",
    "headers": {
      "Authorization": "Bearer token-here"
    }
  }
}

Параметры

Параметр	Тип	Обязательный	По умолчанию	Описание
method	string	Нет	"GET"	HTTP-метод: "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"
url	string	Да	--	Полный URL запроса. Должен быть HTTPS или HTTP. Домен должен быть в allowed_domains.
headers	object	Нет	{}	Пары ключ-значение HTTP-заголовков для включения в запрос
body	string	Нет	--	Тело запроса (для методов POST, PUT, PATCH)
timeout_secs	integer	Нет	Значение из конфигурации (30)	Переопределение таймаута для конкретного запроса в секундах

Возвращает:

Поле	Тип	Описание
success	bool	true если запрос завершён (даже для не-2xx кодов статуса)
output	string	Тело ответа (текст), обрезанное до max_response_size. Включает код статуса и заголовки в структурированном выводе.
error	string?	Сообщение об ошибке при неудачном запросе (домен заблокирован, таймаут, ошибка соединения)

Формат ответа

Инструмент возвращает структурированный вывод, содержащий:

Status: 200 OK
Content-Type: application/json

{
  "name": "prx",
  "version": "0.8.0",
  ...
}

Для нетекстовых ответов (бинарные данные) инструмент сообщает размер ответа и тип содержимого без включения тела.

Типичные паттерны

Интеграция с API

Инструмент HTTP-запросов обычно используется для интеграции с внешними сервисами:

Агент размышляет: Пользователь хочет проверить статус CI своего PR.
  1. [http_request] GET https://api.github.com/repos/owner/repo/pulls/42/checks
  2. [парсит JSON-ответ]
  3. [сообщает статус пользователю]

Доставка вебхуков

Отправка уведомлений во внешние системы:

Агент размышляет: Задача завершена, нужно уведомить вебхук.
  1. [http_request] POST https://hooks.slack.com/services/T.../B.../xxx
     body: {"text": "Task #42 completed successfully"}

Получение данных

Извлечение структурированных данных для анализа:

Агент размышляет: Нужно найти метаданные пакета.
  1. [http_request] GET https://crates.io/api/v1/crates/tokio
  2. [извлекает версию, количество загрузок, зависимости]

Безопасность

Запрет по умолчанию

Инструмент HTTP-запросов использует модель безопасности с запретом по умолчанию. Если домен не указан явно в allowed_domains, запрос блокируется до установления сетевого соединения. Это предотвращает:

• Подделку запросов на стороне сервера (SSRF): Агент не может отправлять запросы к внутренним сетевым адресам (localhost, 10.x.x.x, 192.168.x.x), если это не разрешено явно
• Утечку данных: Агент не может отправлять данные на произвольные внешние серверы
• DNS rebinding: Домен проверяется в момент запроса, а не только при DNS-разрешении

Обработка учётных данных

Инструмент HTTP-запросов не внедряет учётные данные автоматически. Если агенту нужно аутентифицироваться в API, он должен явно включить заголовки аутентификации в аргументы вызова инструмента. Это означает:

• API-ключи видны в вызове инструмента (и журнале аудита)
• Агент может использовать только учётные данные, которые ему предоставлены или получены из памяти
• Утечка учётных данных на неавторизованные домены предотвращается белым списком доменов

Рассмотрите использование [security.tool_policy] для пометки http_request как supervised для чувствительных API-вызовов:

[security.tool_policy.tools]
http_request = "supervised"

Ограничения размера ответа

Настройка max_response_size (по умолчанию: 1 МБ) предотвращает исчерпание памяти от неожиданно больших ответов. Ответы, превышающие этот лимит, обрезаются с добавлением примечания.

Защита таймаутом

Настройка timeout_secs (по умолчанию: 30 секунд) предотвращает зависание агента на медленных или неответающих серверах. Таймауты применяются на уровне соединения.

Поддержка прокси

При настроенном [proxy] HTTP-запросы маршрутизируются через указанный прокси:

[proxy]
enabled = true
https_proxy = "socks5://127.0.0.1:1080"
no_proxy = ["localhost", "127.0.0.1"]

Журнал аудита

Все HTTP-запросы логируются в журнал аудита при его включении, включая:

• Метод и URL запроса
• Заголовки запроса (с редактированием конфиденциальных значений)
• Код статуса ответа
• Размер ответа
• Статус успешности/неудачи

Связанные разделы

• Веб-поиск -- поиск в интернете и получение содержимого страниц
• Инструмент браузера -- полная автоматизация браузера для веб-страниц
• Интеграция MCP -- подключение к внешним инструментам через протокол MCP
• Справочник конфигурации -- поля конфигурации [http_request]
• Настройка прокси -- настройки исходящего прокси
• Обзор инструментов -- все инструменты и система реестра