Tool System - PraisonAI

Tools give your Agents the ability to take actions beyond just generating text. Agents can call APIs, search the web, perform calculations, and interact with external systems.

Quick Start

Simple Usage

import { Agent } from 'praisonai';

// Define tools as simple functions
const getWeather = (city: string) => `Weather in ${city}: 22°C, sunny`;
const calculate = (expression: string) => eval(expression).toString();

// Agent automatically generates tool schemas from functions
const agent = new Agent({
  name: 'Assistant',
  instructions: 'You help users with weather and calculations.',
  tools: [getWeather, calculate]
});

await agent.chat('What is the weather in Paris?');
// Agent calls getWeather("Paris") → "Weather in Paris: 22°C, sunny"

await agent.chat('What is 15 * 7?');
// Agent calls calculate("15 * 7") → "105"

With Configuration

Use tool registries and categories — see sections below.

Agent with Simple Function Tools

The easiest way to give an Agent tools — just pass plain functions directly:

import { Agent } from 'praisonai';

function getWeather(city: string) {
  return { city, temperature: 22, condition: 'sunny' };
}

const agent = new Agent({
  instructions: 'Report the weather using the tool.',
  tools: [getWeather],
});

await agent.chat('Weather in Paris?');
// The tool receives city="Paris" (named args mapped positionally)

Plain-function tools now work as advertised. The model returns tool arguments as a named object; the runtime maps them onto your function’s positional parameters — so getWeather receives "Paris", not "[object Object]". Tool return values are serialised as JSON (no more .toString()), and your tools array is never mutated — the constructor iterates a snapshot.

Agent with Typed Tools

For more control, define tools with explicit schemas:

import { Agent, createTool } from 'praisonai';

const searchTool = createTool({
  name: 'web_search',
  description: 'Search the web for information',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query' },
      limit: { type: 'number', description: 'Max results' }
    },
    required: ['query']
  },
  execute: async ({ query, limit = 5 }) => {
    // Perform actual search
    return `Found ${limit} results for: ${query}`;
  }
});

const agent = new Agent({
  name: 'Research Agent',
  instructions: 'You research topics using web search.',
  tools: [searchTool]
});

await agent.chat('Find information about TypeScript 5.0 features');

Share tools across multiple Agents:

import { Agent, Agents, createTool } from 'praisonai';

// Shared tools
const databaseTool = createTool({
  name: 'query_database',
  description: 'Query the product database',
  parameters: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query']
  },
  execute: async ({ query }) => `Database results for: ${query}`
});

const emailTool = createTool({
  name: 'send_email',
  description: 'Send an email notification',
  parameters: {
    type: 'object',
    properties: { 
      to: { type: 'string' },
      subject: { type: 'string' },
      body: { type: 'string' }
    },
    required: ['to', 'subject', 'body']
  },
  execute: async ({ to, subject, body }) => `Email sent to ${to}`
});

// Agents with different tool sets
const analyst = new Agent({
  name: 'Data Analyst',
  instructions: 'Analyze data from the database.',
  tools: [databaseTool]
});

const notifier = new Agent({
  name: 'Notifier',
  instructions: 'Send notifications based on analysis.',
  tools: [emailTool]
});

const agents = new AgentTeam([analyst, notifier]);
await agents.start();

Agent with Context-Aware Tools

Tools can access Agent context:

import { Agent, createTool } from 'praisonai';

const auditTool = createTool({
  name: 'audit_log',
  description: 'Log an action for audit purposes',
  parameters: {
    type: 'object',
    properties: { action: { type: 'string' } },
    required: ['action']
  },
  execute: async ({ action }, context) => {
    // Access Agent context
    const log = {
      action,
      agent: context?.agentName,
      session: context?.sessionId,
      timestamp: new Date().toISOString()
    };
    console.log('Audit:', log);
    return `Logged: ${action}`;
  }
});

const agent = new Agent({
  name: 'Secure Agent',
  instructions: 'You perform secure operations with audit logging.',
  tools: [auditTool],
  sessionId: 'secure-session-123'
});

await agent.chat('Log that user requested a password reset');

Tool Registry for Agent Teams

Organize tools for complex Agent systems:

import { Agent, ToolRegistry, createTool } from 'praisonai';

const registry = new ToolRegistry();

// Register categorized tools
registry.register(createTool({
  name: 'calculator',
  category: 'math',
  description: 'Perform calculations',
  execute: async ({ expr }) => eval(expr).toString()
}));

registry.register(createTool({
  name: 'translator',
  category: 'language',
  description: 'Translate text',
  execute: async ({ text, lang }) => `[${lang}] ${text}`
}));

// Create Agents with tools from registry
const mathAgent = new Agent({
  name: 'Math Agent',
  instructions: 'You solve math problems.',
  tools: registry.getByCategory('math')
});

const langAgent = new Agent({
  name: 'Language Agent',
  instructions: 'You translate text.',
  tools: registry.getByCategory('language')
});

await mathAgent.chat('Calculate 25 * 4');
await langAgent.chat('Translate "Hello" to Spanish');

Custom Tools

Build custom tools

MCP Tools

MCP integration

​Quick Start

​Agent with Simple Function Tools

​Agent with Typed Tools

​Multi-Agent Tool Sharing

​Agent with Context-Aware Tools

​Tool Registry for Agent Teams

​Related

Custom Tools

MCP Tools

Quick Start

Agent with Simple Function Tools

Agent with Typed Tools

Multi-Agent Tool Sharing

Agent with Context-Aware Tools

Tool Registry for Agent Teams

Related