Tool System

Give Agents tools to take actions and access external data

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.

Long-running tools receive ctx.signal on ToolExecutionContext — check it to stop early when cancelled. See Cancellation.

Tools work on every provider the TS SDK supports — openai/..., anthropic/..., google/..., groq/..., mistral/..., ollama/..., and more. The same tools: [...] you set on the Agent is formatted once and translated per-provider by the AI SDK backend, matching the Python SDK’s litellm-backed contract. Cross-provider tool support landed in PraisonAI PR #4412.

Quick Start

1. 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"
   
2. 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.

The same tools run on any provider — only the llm string changes:

// Same tools, different provider — no code change beyond `llm`.
const claudeAgent = new Agent({
  instructions: 'Report the weather using the tool.',
  llm: 'anthropic/claude-3-5-sonnet-latest',
  tools: [getWeather],
});

await claudeAgent.start('Weather in Paris?');

Tools + Structured Output on any provider

Combine tools and outputSchema — the agent runs the tool loop first, then returns JSON matching your schema. This works on every provider:

// Tools + structured output on a non-OpenAI provider — works from PraisonAI PR #4412 onward.
import { Agent } from 'praisonai';

const getWeather = (city: string) => ({ city, tempC: 20, condition: 'sunny' });

const agent = new Agent({
  instructions: 'Use the tool to answer, then return the result as JSON.',
  llm: 'anthropic/claude-3-5-sonnet-latest',
  tools: [getWeather],
  outputSchema: {
    type: 'object',
    properties: {
      city: { type: 'string' },
      tempC: { type: 'number' },
      condition: { type: 'string' },
    },
    required: ['city', 'tempC', 'condition'],
  },
});

const json = await agent.start('Weather in Paris?');
console.log(JSON.parse(json));
// { city: "Paris", tempC: 20, condition: "sunny" }

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');

Multi-Agent Tool Sharing

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');

Global Tool Registry

For the common case, register tools by name on the global registry and look them up with the Python-style register_tool / get_tool — no registry instance to pass around.

import { Agent, register_tool, get_tool, tool } from 'praisonai';

register_tool(tool({
  name: 'calculator',
  description: 'Perform calculations',
  execute: async ({ expr }: { expr: string }) => eval(expr).toString(),
}));

const mathAgent = new Agent({
  name: 'Math Agent',
  instructions: 'You solve math problems.',
  tools: [get_tool('calculator')!],
});

await mathAgent.chat('Calculate 25 * 4');

The global register_tool skips a name that is already registered (Python parity) — pass { overwrite: true } to replace it. The class method ToolRegistry.register below throws on a duplicate instead.

register options

register_tool(tool, options) and ToolRegistry.register(tool, options) share one options shape:

Option	Type	Description
name	string	Register under this name instead of the tool’s own
overwrite	boolean	Replace an existing registration under the same name
trustLevel	'trusted' | 'external'	Where the tool came from — invalid values throw
dynamicSchemaOverrides	(schema) => schema	Reshape the parameter schema at registration time

Scoped Registry for Agent Teams

Use a new ToolRegistry() only when you genuinely need a scoped, categorised registry — for example to split tools across an agent team.

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

const registry = new ToolRegistry();

// Register categorized tools — the class method throws on duplicate names.
registry.register(tool({
  name: 'calculator',
  category: 'math',
  description: 'Perform calculations',
  execute: async ({ expr }: { expr: string }) => eval(expr).toString(),
}));

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

// Create Agents with tools from the scoped 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');

Model definitions advertise the registration key, so a tool registered under { name: 'renamed' } dispatches correctly. Inspect a registry with registry.listTools(), registry.getAll(), registry.getTrustLevel(name), and registry.size.

Related

Custom Tools

Build custom tools

Factory Registry

Build instances from config

Tool Errors

Missing vs broken tools

MCP Tools

MCP integration