llm4s-core/org.llm4s/org.llm4s.toolapi/org.llm4s.toolapi.builtin

org.llm4s.toolapi.builtin

Built-in tools for common agent operations.

This package provides production-ready tools that can be used out of the box:

== Core Utilities (No API Keys Required) ==

import org.llm4s.toolapi.builtin.core._

val tools = new ToolRegistry(Seq(
 DateTimeTool.tool,
 CalculatorTool.tool,
 UUIDTool.tool,
 JSONTool.tool
))

== File System Tools ==

import org.llm4s.toolapi.builtin.filesystem._

val fileTools = new ToolRegistry(Seq(
 ReadFileTool.create(FileConfig(
   maxFileSize = 512 * 1024,
   allowedPaths = Some(Seq("/tmp"))
 )),
 ListDirectoryTool.tool,
 FileInfoTool.tool
))

== HTTP Tools ==

import org.llm4s.toolapi.builtin.http._

val httpTools = new ToolRegistry(Seq(
 HTTPTool.create(HttpConfig(
   timeoutMs = 10000,
   allowedDomains = Some(Seq("api.example.com"))
 ))
))

== Shell Tools ==

import org.llm4s.toolapi.builtin.shell._

// Read-only shell (safe commands)
val shellTools = new ToolRegistry(Seq(
 ShellTool.create(ShellConfig.readOnly())
))

// Development shell with common dev tools
val devShellTools = new ToolRegistry(Seq(
 ShellTool.create(ShellConfig.development())
))

== Search Tools ==

import org.llm4s.toolapi.builtin.search._

val searchTools = new ToolRegistry(Seq(
 DuckDuckGoSearchTool.tool
))

== All Built-in Tools ==

import org.llm4s.toolapi.builtin.BuiltinTools

// Get all safe tools (no shell, restricted filesystem)
val tools = BuiltinTools.withHttpSafe()

// Get all tools with custom config
val allTools = BuiltinTools.all(
 fileConfig = FileConfig(allowedPaths = Some(Seq("/tmp")))
)

Attributes

See also: org.llm4s.toolapi.builtin.core for core utility tools

org.llm4s.toolapi.builtin.filesystem for file system tools

org.llm4s.toolapi.builtin.http for HTTP tools

org.llm4s.toolapi.builtin.shell for shell tools

org.llm4s.toolapi.builtin.search for search tools

Members list

Packages

Core utility tools that require no external dependencies or API keys.

These tools provide common functionality for agent workflows:

DateTimeTool: Get current date/time in any timezone
CalculatorTool: Perform mathematical calculations
UUIDTool: Generate unique identifiers
JSONTool: Parse, format, and query JSON data

Attributes

Example

import org.llm4s.toolapi.builtin.core._
import org.llm4s.toolapi.ToolRegistry
// Recommended: Safe API returning Result
for {
 dateTime   <- DateTimeTool.toolSafe
 calculator <- CalculatorTool.toolSafe
 uuid       <- UUIDTool.toolSafe
 json       <- JSONTool.toolSafe
} yield new ToolRegistry(Seq(dateTime, calculator, uuid, json))
// Or use the convenience val
allToolsSafe.map(tools => new ToolRegistry(tools))

File system tools for reading, writing, and managing files.

These tools provide safe access to the file system with configurable path restrictions and size limits.

== Configuration ==

All file system tools accept FileConfig for read operations or WriteConfig for write operations. These configurations allow:

Path allowlists and blocklists for security
File size limits
Symbolic link handling

== Available Tools ==

ReadFileTool: Read file contents
WriteFileTool: Write content to files (requires explicit path allowlist)
ListDirectoryTool: List directory contents
FileInfoTool: Get file metadata

Attributes

Example

import org.llm4s.toolapi.builtin.filesystem._
import org.llm4s.toolapi.ToolRegistry
// Read-only tools with default config (blocked: /etc, /var, /sys, /proc, /dev)
for {
 readFile <- ReadFileTool.toolSafe
 listDir  <- ListDirectoryTool.toolSafe
 fileInfo <- FileInfoTool.toolSafe
} yield new ToolRegistry(Seq(readFile, listDir, fileInfo))
// Or use the convenience val
readOnlyToolsSafe.map(tools => new ToolRegistry(tools))
// Tools with custom restrictions
val config = FileConfig(
 maxFileSize = 512 * 1024,
 allowedPaths = Some(Seq("/tmp", "/home/user/workspace"))
)
for {
 readFile <- ReadFileTool.createSafe(config)
 listDir  <- ListDirectoryTool.createSafe(config)
} yield new ToolRegistry(Seq(readFile, listDir))
// Write tool with explicit allowlist
val writeConfig = WriteConfig(
 allowedPaths = Seq("/tmp/output"),
 allowOverwrite = true
)
for {
 writeTool <- WriteFileTool.createSafe(writeConfig)
} yield new ToolRegistry(Seq(writeTool))

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(
   timeoutMs = 60000,
   maxResponseSize = 50 * 1024 * 1024
 ))
} yield new ToolRegistry(Seq(fullTool))

Search tools for web searches and lookups.

These tools provide web search capabilities using various search engines. All search tools follow the "config at the edge" pattern where configuration is loaded at the application boundary via org.llm4s.config.Llm4sConfig and passed to the tool's create() method.

== Available Tools ==

DuckDuckGoSearchTool: Search using DuckDuckGo Instant Answer API
Best for definitions, facts, quick lookups
No API key required
Returns abstracts, related topics, and infobox data
Configuration: API URL
BraveSearchTool: Search using Brave Search API
Comprehensive web search results
Requires API key (paid service)
Returns web pages, snippets, and metadata
Configuration: API key, URL, result count, safe search settings
ExaSearchTool: Search using Exa (formerly Metaphor) API
AI-powered semantic search engine
Requires API key (paid service)
Supports multiple search types: auto, neural, fast, deep
Returns rich content with text, highlights, summaries, and metadata
Configuration: API key, URL, result count, search type, max characters, max age

== Usage Pattern ==

All search tools follow the Result-based error handling pattern. Use for-comprehensions to chain operations and handle errors gracefully:

Attributes

Example

import org.llm4s.config.Llm4sConfig
import org.llm4s.toolapi.builtin.search._
import org.llm4s.toolapi.ToolRegistry
import org.llm4s.types.Result
// Load and create all search tools using Result
val toolsResult: Result[ToolRegistry] = for {
 // Load DuckDuckGo configuration and create tool
 duckDuckGoConfig <- Llm4sConfig.loadDuckDuckGoSearchTool()
 duckDuckGoTool   <- DuckDuckGoSearchTool.create(duckDuckGoConfig)
 // Load Brave Search configuration and create tool
 braveConfig <- Llm4sConfig.loadBraveSearchTool()
 braveTool   <- BraveSearchTool.create(braveConfig)
 // Load Exa Search configuration and create tool
 exaConfig <- Llm4sConfig.loadExaSearchTool()
 exaTool   <- ExaSearchTool.create(exaConfig)
 // Register all tools
 tools = new ToolRegistry(Seq(duckDuckGoTool, braveTool, exaTool))
} yield tools
// Handle the result
toolsResult match {
 case Right(tools) =>
   // Use tools with agent
   println(s"Successfully loaded $${tools.tools.size} search tools")
 case Left(error) =>
   // Handle configuration or validation errors
   println(s"Failed to load search tools: $${error.message}")
}

== Individual Tool Usage == You can also load and use tools individually:

import org.llm4s.toolapi.builtin.search.ExaSearchTool
// Load just Exa Search
val exaToolResult = for {
 config <- Llm4sConfig.loadExaSearchTool()
 tool   <- ExaSearchTool.create(config)
} yield tool
exaToolResult match {
 case Right(tool) => // Use tool
 case Left(error) => // Handle error
}

== Configuration == Configure search tools in your application.conf:

llm4s {
 tools {
   duckduckgo {
     apiUrl = "https://api.duckduckgo.com"
   }
   brave {
     apiKey = "your-api-key"
     apiUrl = "https://api.search.brave.com/res/v1"
     count = 10
     safeSearch = "moderate"
   }
   exa {
     apiKey = "your-exa-api-key"
     apiUrl = "https://api.exa.ai"
     numResults = 10
     searchType = "auto"        # Options: auto, neural, fast, deep
     maxCharacters = 500
   }
 }
}

Shell tools for executing system commands.

These tools provide safe shell access with configurable command allowlists and execution limits.

== Configuration ==

All shell tools require explicit command allowlisting via ShellConfig:

Allowed commands list (required for any execution)
Working directory configuration
Timeout limits
Output size limits

== Available Tools ==

ShellTool: Execute shell commands (requires explicit allowlist)

Attributes

Example

import org.llm4s.toolapi.builtin.shell._
import org.llm4s.toolapi.ToolRegistry
// Read-only shell (ls, cat, etc.)
val readOnlyShell = ShellTool.create(ShellConfig.readOnly())
// Development shell with common dev tools
val devShell = ShellTool.create(ShellConfig.development(
 workingDirectory = Some("/path/to/project")
))
// Custom restricted shell
val customShell = ShellTool.create(ShellConfig(
 allowedCommands = Seq("git", "npm"),
 timeoutMs = 60000
))
val tools = new ToolRegistry(Seq(devShell))

Type members

Classlikes

Aggregator for built-in tools with convenient factory methods.

Provides pre-configured tool sets for common use cases:

safe(): Core utilities, web search, and read-only HTTP (no file or shell access)
withFiles(): Safe tools plus read-only file system access
development(): All tools including shell with common dev commands

Attributes

Example

import org.llm4s.toolapi.ToolRegistry
import org.llm4s.toolapi.builtin.BuiltinTools
// Safe tools for production use
for {
 tools <- BuiltinTools.withHttpSafe()
} yield new ToolRegistry(tools)
// Development tools with file and shell access
for {
 tools <- BuiltinTools.developmentSafe(
   workingDirectory = Some("/home/user/project")
 )
} yield new ToolRegistry(tools)

Supertypes

class Object

trait Matchable

class Any

Self type

BuiltinTools.type

In this article

Generated with