Skip to main content

​
HTTP / REST

Make arbitrary HTTP requests from your agent. Call any REST API with configurable headers, base URL, timeout, and response truncation.

​
Quick Start

import { Agent, openai, HttpToolkit } from "@radaros/core";

const http = new HttpToolkit({
  baseUrl: "https://api.example.com",
  headers: { Authorization: "Bearer sk-..." },
});

const agent = new Agent({
  name: "api-agent",
  model: openai("gpt-4o"),
  instructions: "Call the API to fetch data and answer questions.",
  tools: [...http.getTools()],
});

const result = await agent.run("Get the list of users from the API");

​
Config

​
baseUrl
string
Base URL prepended to relative paths (e.g. "https://api.example.com").
​
headers
Record<string, string>
Default headers included in every request.
​
timeout
number
default:"30000"
Request timeout in milliseconds.
​
maxResponseSize
number
default:"20000"
Max response body characters to return. Larger responses are truncated.

​
Tools

ToolDescription
http_requestMake an HTTP request (GET, POST, PUT, PATCH, DELETE). Returns status, headers, and body.

​
Tool Usage Examples

​
GET Request

const result = await agent.run("Get the list of products from our API");

// The agent calls http_request with:
// { method: "GET", url: "/products?limit=20" }
//
// baseUrl is prepended: https://api.example.com/products?limit=20

​
POST Request

const result = await agent.run(
  "Create a new user with name 'Jane Doe' and email 'jane@example.com'"
);

// The agent calls http_request with:
// {
//   method: "POST",
//   url: "/users",
//   body: { name: "Jane Doe", email: "jane@example.com" },
//   headers: { "Content-Type": "application/json" }
// }

​
Error Handling

The tool returns the full HTTP response including status code, so the agent can interpret errors: 
const result = await agent.run("Delete user 999 from the API");

// The agent calls http_request with:
// { method: "DELETE", url: "/users/999" }
//
// If the API returns 404:
// "The user with ID 999 was not found. The API returned a 404 Not Found error."

​
Response Truncation

Large API responses are automatically truncated to maxResponseSize (default 20,000 characters). Combine with toolResultLimit for further control: 
const http = new HttpToolkit({
  baseUrl: "https://api.example.com",
  headers: { Authorization: "Bearer sk-..." },
  maxResponseSize: 10_000,
});

const agent = new Agent({
  name: "api-agent",
  model: openai("gpt-4o"),
  tools: [...http.getTools()],
  toolResultLimit: { maxChars: 20_000, strategy: "truncate" },
});