llm4s-docs/org.llm4s/org.llm4s.toolapi/org.llm4s.toolapi.builtin/org.llm4s.toolapi.builtin.http

org.llm4s.toolapi.builtin.http

package org.llm4s.toolapi.builtin.http

HTTP tools for making web requests.

These tools provide safe HTTP access with configurable domain restrictions and method limitations.

== Configuration ==

All HTTP tools accept HttpConfig for request configuration:

Domain allowlists and blocklists for security
Allowed HTTP methods
Response size limits
Timeout configuration

== Available Tools ==

HTTPTool: Make HTTP requests (GET, POST, PUT, DELETE, etc.)

Attributes

Example

import org.llm4s.toolapi.builtin.http._
import org.llm4s.toolapi.ToolRegistry
// Read-only HTTP tool (GET/HEAD only)
for {
 readOnlyTool <- HTTPTool.createSafe(HttpConfig.readOnly())
} yield new ToolRegistry(Seq(readOnlyTool))
// Restricted to specific domains
for {
 restrictedTool <- HTTPTool.createSafe(HttpConfig.restricted(
   Seq("api.example.com", "data.example.org")
 ))
} yield new ToolRegistry(Seq(restrictedTool))
// Full access with custom timeout
for {
 fullTool <- HTTPTool.createSafe(HttpConfig(
   timeout = 60.seconds,
   maxResponseSize = 50 * 1024 * 1024
 ))
} yield new ToolRegistry(Seq(fullTool))

Members list

Type members

Classlikes

HTTP response result.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: HTTPResult.type

Tool for making HTTP requests.

Features:

Support for GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
Request headers and body
Domain allowlist/blocklist for security
Response size limits
Configurable timeout, bounding the whole call (connect, every redirect hop and the body read)
Run as an agent's call, a POST, PUT, PATCH or DELETE carries the call's idempotency key as an Idempotency-Key header, so a server that honours it does the write once however often the agent runs the call; a header of that name set in the call's headers is kept instead

Attributes

Example

{
import org.llm4s.toolapi.builtin.http._
val httpTool = HTTPTool.create(HttpConfig(
 allowedDomains = Some(Seq("api.example.com")),
 allowedMethods = Seq("GET", "POST")
))
val tools = new ToolRegistry(Seq(httpTool))
agent.run("Fetch data from https://api.example.com/data", tools)

}

Supertypes

class Object

trait Matchable

class Any

Self type

HTTPTool.type

Configuration for HTTP tool.

== Security == By default, HTTPTool is configured with safe defaults:

Only GET and HEAD methods are allowed (read-only)
Internal IP ranges are blocked (10.x, 172.16-31.x, 192.168.x, IPv6 unique-local fc00::/7, ...)
Cloud metadata endpoints are blocked (169.254.169.254)
Localhost and loopback addresses are blocked

Value parameters

allowedDomains: Optional list of allowed domains. If None, all domains are allowed. A leading www. is ignored.
allowedMethods: HTTP methods that are allowed (default: GET, HEAD for safety).
blockInternalIPs: Whether to block requests to internal/private IP ranges (default: true).
blockedDomains: List of domains that are always blocked. A leading www. is ignored.
followRedirects: Whether to follow HTTP redirects. Defaults to false; when true each redirect hop is re-validated against the SSRF filter before the next request is issued (open-redirect bypass prevention).
maxRedirects: Maximum number of redirects to follow.
maxResponseSize: Maximum number of response body bytes read; the rest is never read, and the result's truncated is true.
redirectSafeHeaders: The caller-set headers a redirect may carry to another origin (matched in any case). Once a hop leaves the original request's origin - its scheme, host and port, so a downgrade from https to http counts - every other header the caller set is dropped, on that hop and every later one, including one that comes back. The default is Accept, Accept-Language, Accept-Encoding, User-Agent and Content-Type, the last only on a hop that re-sends the body (a 307 or 308). A header that names a credential (Authorization, Cookie, Proxy-Authorization, any name core's redaction treats as sensitive, such as X-Api-Key or X-Client-Secret, and any name ending in token or key) is dropped even if listed here. Seq.empty forwards no caller-set header.
timeout: Deadline for the whole call: connecting, every redirect hop and reading the body must all finish within it (the SSRF check's name resolution too), so a server that sends slowly cannot hold the call longer. A call that runs out of time fails with a TIMEOUT: error. A zero or negative timeout fails every call; one beyond 100 years is treated as 100 years. A TIMEOUT: releases the caller, not the request: one already sent may still be delivered and acted on by the server (a write is not rolled back), and a DNS lookup cannot be interrupted, so the worker thread may outlive the deadline by up to the resolver's own timeout (#1734).
userAgent: User-Agent header to use.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

Attributes

Companion: class
Supertypes: trait Product

trait Mirror

class Object

trait Matchable

class Any
Self type: HttpConfig.type

Value members

Concrete fields

All HTTP tools with default configuration, returning a Result for safe error handling.

Attributes

In this article

Generated with