@webneat/ai-tools

A library for creating AI agent tools with built-in Vercel AI SDK integration.

Installation

npm install @webneat/ai-tools
# or
pnpm add @webneat/ai-tools

Quick Start

import { z } from 'zod'
import { tool } from '@webneat/ai-tools'

// Define a simple tool
const greet = tool({
  name: 'greet',
  description: 'Greets a person by name',
  input: z.object({ name: z.string() }),
  output: z.object({ message: z.string() }),
  execute: async (input) => ({ message: `Hello, ${input.name}!` }),
})

// Get AI SDK compatible tool
const ai_tool = greet.ai_sdk()

Using Context

Tools can receive context for shared state or configuration:

import { z } from 'zod'
import { tool } from '@webneat/ai-tools'

type LogContext = { logs: string[] }

const log_message = tool<{ msg: string }, { logged: boolean }, LogContext>({
  name: 'log',
  description: 'Logs a message',
  input: z.object({ msg: z.string() }),
  output: z.object({ logged: z.boolean() }),
  execute: async (input, context) => {
    context.logs.push(input.msg)
    return { logged: true }
  },
})

// Create shared context
const context: LogContext = { logs: [] }

// Pass context when creating AI SDK tool
const ai_tool = log_message.ai_sdk(context)

Built-in Tools

Shell Tools

Execute shell commands with permission control and process management:

import { shell, type ShellContext } from '@webneat/ai-tools'

const context: ShellContext = {
  ask_permission: async (cmd) => true, // Implement your permission logic
  processes: new Map(),
  cwd: '/home/user',
  env: { PATH: process.env.PATH },
}

const tools = {
  start_process: shell.start_process.ai_sdk(context),
  check_process: shell.check_process.ai_sdk(context),
  kill_process: shell.kill_process.ai_sdk(context),
  wait_for_process: shell.wait_for_process.ai_sdk(context),
  list_processes: shell.list_processes.ai_sdk(context),
  delete_process: shell.delete_process.ai_sdk(context),
  write_stdin: shell.write_to_process_stdin.ai_sdk(context),
}

Context Tools

Get information about the execution environment:

import { context } from '@webneat/ai-tools'

const get_context_tool = context.get_context.ai_sdk()

API Reference

tool(definition)

Creates a tool factory from a definition.

Parameters:

• name: Tool name
• description: Tool description for the AI
• input: Zod schema for input validation
• output: Zod schema for output validation
• execute: Async function (input, context) => Promise<output>

Returns:

• ToolFactory with ai_sdk(context?) method

ToolFactory.ai_sdk(context?)

Returns an AI SDK compatible tool. Pass context if the tool requires it.

License

MIT