@tinyweb-agent-framework/tool

Built-in tool factories + FileStorage adapters. Every factory returns a tool ready to plug into defineAgent({ tools: { ... } }).

Quick start: builtinTools(config)

One-liner to wire the whole catalog. Returns Record<string, Tool> you can pass straight into defineAgent({ tools }).

import { builtinTools } from "@tinyweb-agent-framework/tool"

const tools = builtinTools({
  // Zero-config defaults are ON: time_now, weather, crypto_price,
  // vn_gold_price, vn_lottery. Pass `false` to opt out of any of them.
  // Opt-in (need an API key):
  perplexity: { apiKey: process.env.PERPLEXITY_API_KEY! },
  webSearch: { provider: "tavily", apiKey: process.env.TAVILY_API_KEY! },
})

See the full catalog + tier breakdown in the docs site guide.

Tools

Info / utility (zero-config)

• timeNow(config) — current time in any IANA timezone (default Asia/Ho_Chi_Minh).
• weather(config) — current weather snapshot via wttr.in (no API key).
• cryptoPrice(config) — Binance spot ticker, multi-symbol in one call.

Vietnam locale (zero-config, scrape-based)

• vnGoldPrice(config) — giá vàng nhẫn 24K (BTMC + Bảo Tín Mạnh Hải).
• vnLottery(config) — kết quả XSMB / XSMT / XSMN từ xoso.com.vn.

Both return warnings: [...] when the upstream layout drifts instead of throwing.

Search

• perplexitySearch(config) — Sonar API (OpenAI-compatible) answers with citations.
• webSearch(config) — Tavily / Brave / Exa / Serper unified.

webSearch(config)

import { webSearch } from "@tinyweb-agent-framework/tool"

const search = webSearch({ provider: "tavily", apiKey: process.env.TAVILY_API_KEY! })
// provider: "tavily" | "brave" | "exa" | "serper"

webFetch(config?)

Fetches a URL and returns plain-text content (regex HTML strip, no jsdom).

import { webFetch } from "@tinyweb-agent-framework/tool"
const fetcher = webFetch({ timeoutMs: 15_000, maxLength: 100_000 })

imageGenerate(config)

import { imageGenerate } from "@tinyweb-agent-framework/tool"
const gen = imageGenerate({
  provider: "openai",            // "openai" | "replicate"
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-image-1",          // optional
  storage,                       // optional FileStorage to persist output
})

imageDescribe(config) / imageEdit(config)

import { imageDescribe, imageEdit } from "@tinyweb-agent-framework/tool"
const describe = imageDescribe({ apiKey: process.env.OPENAI_API_KEY! })
const edit = imageEdit({ apiKey: process.env.OPENAI_API_KEY!, storage })

fileRead(config) / fileWrite(config)

import { fileRead, fileWrite, makeLocalFS } from "@tinyweb-agent-framework/tool"

const storage = makeLocalFS("./.agent-data")
const read = fileRead({ storage })
const write = fileWrite({ storage })

FileStorage adapters

• makeMemoryStore() — in-memory Map<string, Uint8Array>.
• makeLocalFS(basePath) — node:fs with path-traversal guard.
• makeS3Store(client, options) — duck-typed against @aws-sdk/client-s3 (peer dep).

import { S3Client, GetObjectCommand, PutObjectCommand, ListObjectsV2Command } from "@aws-sdk/client-s3"
import { makeS3Store } from "@tinyweb-agent-framework/tool"

const storage = makeS3Store(
  new S3Client({ region: "us-east-1" }),
  {
    bucket: "my-bucket",
    prefix: "agent/",
    commands: { GetObjectCommand, PutObjectCommand, ListObjectsV2Command },
    publicUrl: (key) => `https://cdn.example.com/${key}`,
  },
)

License

MIT