Built-in Tools

OverviewCopy Anchor Link

Cogitator ships with 26 built-in tools covering math, data processing, the file system, network, databases, email and GitHub. Every tool has a Zod schema (the runtime validates the model's arguments against it) and returns structured results; most failures come back as { error } data the model can read instead of a thrown exception.

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

const assistant = new Agent({
  name: 'assistant',
  model: 'openai/gpt-6.1-sol',
  instructions: 'You are a helpful assistant.',
  tools: [calculator, fileRead, httpRequest],
});

const everything = new Agent({
  name: 'power-user',
  model: 'openai/gpt-6.1-sol',
  instructions: 'You are a helpful assistant.',
  tools: builtinTools,
});

builtinTools is a Tool[], so pass it as tools directly or spread it next to your own tools. Prefer picking the tools an agent needs: builtinTools includes exec, file_delete and send_email.

Environment VariablesCopy Anchor Link

Variables are read on each call. On runtimes without process.env (Cloudflare Workers without nodejs_compat, Deno without --allow-env) they count as unset.

Optional PackagesCopy Anchor Link

They are optional peer dependencies of @cogitator-ai/core; a tool that needs a missing one returns an error telling you what to install.

Math & UtilitiesCopy Anchor Link

calculatorCopy Anchor Link

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

uuidCopy Anchor Link

Generates UUID v4 identifiers with crypto.randomUUID.

random_numberCopy Anchor Link

Generates a random number within a range.

random_stringCopy Anchor Link

Generates a cryptographically secure random string using crypto.randomBytes.

hashCopy Anchor Link

Computes cryptographic hashes.

sleepCopy Anchor Link

Pauses execution for a specified duration. Maximum 60 seconds.

datetimeCopy Anchor Link

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

Data ProcessingCopy Anchor Link

json_parseCopy Anchor Link

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

json_stringifyCopy Anchor Link

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

base64_encode / base64_decodeCopy Anchor Link

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

regex_matchCopy Anchor Link

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

regex_replaceCopy Anchor Link

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

Both regex tools reject texts over 1,000,000 characters and stop matching after 5 seconds. They run on the host event loop; for untrusted patterns prefer the WASM regex tool, which runs in a worker that the timeout terminates.

File SystemCopy Anchor Link

file_write and file_delete declare sideEffects: ['filesystem']. None of the file tools restricts paths — they act with the permissions of your process, so give them only to agents you trust or put the agent behind approvals.

file_readCopy Anchor Link

Reads file contents. Use base64 encoding for binary files.

file_writeCopy Anchor Link

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

file_listCopy Anchor Link

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

file_existsCopy Anchor Link

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

file_deleteCopy Anchor Link

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

Network & WebCopy Anchor Link

http_requestCopy Anchor Link

Makes HTTP requests with custom headers, body, and timeout. Response bodies longer than 100,000 characters are truncated (truncated: true).

web_searchCopy Anchor Link

Searches the web via Tavily, Brave Search, or Serper. Without provider it uses the first of TAVILY_API_KEY, BRAVE_API_KEY, SERPER_API_KEY that is set.

The filters work on every provider, each through its own parameters: Tavily's topic, time_range, start_date, include_domains, country and language, the news endpoints, freshness, country and search_lang of Brave, and the news endpoint, tbs, gl and hl of Serper. Domain filters become site: operators for Brave and Serper. A filter a provider cannot apply comes back as an error instead of being dropped: Tavily has no result pages, and it favours a country only in general searches.

Results carry publishedAt (ISO 8601) when the provider reports a date, Serper's relative dates ("3 hours ago") resolved at the time of the search, source for Serper news, and content with includeRawContent.

createWebSearchTool({ provider, apiKeys }) builds the same tool with a default provider and keys passed in code instead of the environment:

import { createWebSearchTool } from '@cogitator-ai/core';

const search = createWebSearchTool({ provider: 'tavily', apiKeys: { tavily: config.tavilyKey } });

web_scrapeCopy Anchor Link

Fetches an HTML page and extracts its content as text, markdown or raw HTML, optionally limited to a CSS selector, with link and image collection.

Non-HTML responses return an error.

Database & SearchCopy Anchor Link

sql_queryCopy Anchor Link

Executes SQL queries against PostgreSQL (pg) or SQLite (better-sqlite3). Supports parameterized queries and is read-only by default.

In read-only mode the query must be a single SELECT/WITH/SHOW/DESCRIBE/EXPLAIN statement. On PostgreSQL it additionally runs inside a BEGIN TRANSACTION READ ONLY block that is always rolled back, so side-effecting functions (for example nextval()) are rejected by the database itself; SQLite databases are opened with readonly: true. With readOnly: false, statements that return no rows (INSERT, UPDATE, DELETE) return rows: [] and the number of affected rows in rowCount.

vector_searchCopy Anchor Link

Performs semantic similarity search with pgvector: embeds the query via OpenAI, Ollama, or Google, then finds similar rows in PostgreSQL.

The provider is auto-detected from OPENAI_API_KEY, then OLLAMA_BASE_URL/OLLAMA_URL/OLLAMA_HOST (the first one set is also the Ollama URL; default http://localhost:11434), then GOOGLE_API_KEY. Default models: text-embedding-3-small (OpenAI), nomic-embed-text (Ollama), gemini-embedding-001 (Google). The embedding dimension must match your pgvector column.

Communication & DevCopy Anchor Link

send_emailCopy Anchor Link

Sends email via the Resend API or SMTP (nodemailer). Declares sideEffects: ['network', 'external'].

Auto-detection picks Resend when RESEND_API_KEY is set, otherwise SMTP when SMTP_HOST and SMTP_USER are set. Resend sends from onboarding@resend.dev when no sender is configured. SMTP needs SMTP_PASS too, uses port SMTP_PORT (default 587, TLS on 465) and falls back to SMTP_USER as sender.

github_apiCopy Anchor Link

GitHub REST API access with GITHUB_TOKEN. One tool, 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.

import { Agent, githubApi } from '@cogitator-ai/core';

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

execCopy Anchor Link

Executes shell commands and returns stdout, stderr and the exit code. Declares sideEffects: ['process', 'filesystem', 'network'] and requiresApproval: true, so every call waits for a decision (see Approvals).

exec declares a Docker sandbox (cogitator/sandbox:base, 256 MB, 100 PIDs, no network). Inside a Cogitator the command runs in that container through @cogitator-ai/sandbox. When the sandbox package is not installed or Docker is unreachable, the runtime logs a warning and runs the command on the host, unless sandbox.allowNativeFallback: false on the Cogitator makes the call fail. See Sandbox.

Multimodal Tool FactoriesCopy Anchor Link

Image and audio tools are created with factories rather than shipped in builtinTools. See Vision & Audio for parameters and results.

Other Tool FactoriesCopy Anchor Link

These build tools around state you provide; they are not part of builtinTools.

Tools created with createSelfTools run with full Node.js access in your process.

Public hosts onlyCopy Anchor Link

A model chooses the URLs web_scrape and http_request fetch, and the audio URL transcribe_audio reads, so a page it read or a prompt it was given can point it at http://169.254.169.254/ (a cloud's credentials), http://localhost:8080/admin or a database on the internal network. These tools reach only the public internet: a URL on a loopback, private, link-local, carrier-grade NAT, multicast or documentation address, localhost, *.local, *.internal or a metadata host is refused, every redirect target is checked again, and a hostname is checked by the address it resolves to when the request connects, so a name that resolves elsewhere a moment later (DNS rebinding) is refused too. A refused URL comes back to the model as an error naming it.

An agent meant to work on a trusted network opts in, or brings its own client:

import { createHttpRequestTool, createWebScrapeTool } from '@cogitator-ai/core';

const intranet = createWebScrapeTool({ allowPrivateNetwork: true });
const api = createHttpRequestTool({ fetch: proxiedFetch });

A fetch of your own is trusted with every URL, so it should apply your network policy. createTranscribeAudioTool takes the same two options.

The guard is yours to use too: fetchPublic is a fetch for public hosts, createPublicFetch({ allowPrivateNetwork, maxRedirects, resolver, isBlocked }) builds one to your rules, assertPublicUrl(url) checks a URL up front, assertPublicHost(url) checks the addresses its host resolves to as well and isPrivateAddress(ip) classifies an address. They run on node:http, in Node and Bun alike, and a refusal throws a PrivateNetworkError.

With robots, the tool checks a URL and the addresses its host resolves to before it reads the site's robots.txt. RobotsPolicy reads robots.txt with the global fetch unless given another: new RobotsPolicy({ userAgent, fetch: fetchPublic }) keeps those reads on public hosts too.

Requests carry DEFAULT_USER_AGENT and Accept: */* unless the caller sets its own headers.

Polite crawling with robots.txtCopy Anchor Link

RobotsPolicy reads and caches a site's robots.txt and answers whether a URL may be fetched, by RFC 9309: the groups that name your product token (else *), longest match wins with * and $ patterns, a 4xx robots.txt allows everything, a 5xx or a network failure allows nothing until the cache (one hour by default) expires. It implements RobotsChecker, which WebLoader in @cogitator-ai/rag and BrowserSession in @cogitator-ai/browser take as robots:

import { RobotsPolicy } from '@cogitator-ai/core';

const robots = new RobotsPolicy({ userAgent: 'NewsBot/1.0 (+https://example.com/bot)' });
await robots.allows('https://example.com/news/today'); // true or false

The token defaults to the User-Agent's first word (NewsBot); pass token to match another. robotsRulesFor(text, token) and robotsAllowsPath(rules, path) expose the parser for robots.txt files you already have.

createWebScrapeTool({ userAgent, robots }) builds a web_scrape tool with your User-Agent and a robots.txt check on every hop, redirects included (a disallowed page comes back as an error). The plain webScrape keeps the default User-Agent and checks nothing.