Built-in Tools

Overview

Cogitator ships with 26 built-in tools covering math, data processing, file system operations, network, databases, and more. Every tool is type-safe with Zod schemas and returns structured results.

import { builtinTools, calculator, fileRead, httpRequest } from '@cogitator-ai/core';

const agent = new Agent({
  name: 'assistant',
  model: 'openai/gpt-4o',
  tools: builtinTools,
});

You can also pick individual tools instead of loading the full set.

Math & Utilities

calculator

Evaluates mathematical expressions safely without eval. Supports +, -, *, /, ^ (power), parentheses, and functions: sqrt, sin, cos, tan, log, abs, round, floor, ceil. Constants: pi, e.

uuid

Generates one or more UUID v4 identifiers using Node's crypto.randomUUID.

random_number

Generates a random number within a range.

random_string

Generates a cryptographically secure random string using crypto.randomBytes.

hash

Computes cryptographic hashes. Supports md5, sha1, sha256, sha512.

sleep

Pauses execution for a specified duration. Maximum 60 seconds.

datetime

Returns the current date and time in various formats and timezones.

Data Processing

json_parse

Parses a JSON string into an object. Returns { result, valid: true } on success, { error, valid: false } on failure.

json_stringify

Converts a value to a JSON string with optional pretty-printing.

base64_encode / base64_decode

Encode strings to Base64 or decode Base64 back to plain text. Both support URL-safe variants.

regex_match

Finds all matches of a regular expression in text, returning match strings, indices, and named groups.

regex_replace

Replaces regex matches in text. Supports $1, $2 capture group references.

File System

All file system tools declare sideEffects: ['filesystem'] where applicable.

file_read

Reads file contents. Use base64 encoding for binary files.

file_write

Writes content to a file. Creates parent directories by default.

file_list

Lists directory contents with file names, paths, types, and sizes.

file_exists

Checks if a file or directory exists and returns its type and size.

file_delete

Deletes a file or directory. Use recursive: true for non-empty directories.

Network & Web

http_request

Makes HTTP requests with custom headers, body, and timeout. Responses larger than 100 KB are truncated.

web_search

Searches the web via Tavily, Brave Search, or Serper APIs. Auto-detects the provider from environment variables (TAVILY_API_KEY, BRAVE_API_KEY, SERPER_API_KEY).

web_scrape

Fetches and extracts content from web pages. Supports text, markdown, or raw HTML output, CSS selector extraction, and link/image collection.

Database & Search

sql_query

Executes SQL queries against PostgreSQL or SQLite. Supports parameterized queries and read-only mode by default for safety.

vector_search

Performs semantic similarity search using pgvector. Converts queries to embeddings via OpenAI, Ollama, or Google, then finds similar documents in PostgreSQL.

Communication & Dev

send_email

Sends email via Resend API or SMTP. Supports HTML body, CC/BCC, and reply-to.

github_api

Full GitHub API integration. Supports 12 actions: get_repo, list_issues, get_issue, create_issue, update_issue, list_prs, get_pr, create_pr, get_file, list_commits, search_code, search_issues. Requires GITHUB_TOKEN.

const agent = new Agent({
  name: 'github-bot',
  model: 'openai/gpt-4o',
  tools: [githubApi],
  instructions: 'You help manage GitHub repositories.',
});

exec

Executes shell commands. Declares side effects for process, filesystem, and network. Configured with requiresApproval: true and a Docker sandbox by default.