> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Registry

> AI SDK Tools Registry - Built-in tools for PraisonAI agents

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> T[Tool]
    T --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
    class T tool
```

# AI SDK Tools Registry

PraisonAI provides a unified registry of AI SDK tools that can be used with agents. All tools are lazy-loaded and have optional dependencies.

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent, tools } from 'praisonai';

    const agent = new Agent({
      name: 'Assistant',
      tools: [
        tools.tavily(),      // Web search
        tools.exa(),         // Semantic search
        tools.firecrawl(),   // Web scraping
      ],
    });

    const result = await agent.run('Research the latest AI developments');
    ```
  </Step>

  <Step title="With Configuration">
    Adjust agent instructions, tool options, and provider settings for production — see the Configuration section below.
  </Step>
</Steps>

## Available Tools

| Tool                       | Package                      | Description                | Required Env         |
| -------------------------- | ---------------------------- | -------------------------- | -------------------- |
| **tavily**                 | `@tavily/ai-sdk`             | Web search, extract, crawl | `TAVILY_API_KEY`     |
| **exa**                    | `@exalabs/ai-sdk`            | Semantic web search        | `EXA_API_KEY`        |
| **perplexity**             | `@perplexity-ai/ai-sdk`      | Real-time search           | `PERPLEXITY_API_KEY` |
| **firecrawl**              | `@mendable/firecrawl-js`     | Web scraping & crawling    | `FIRECRAWL_API_KEY`  |
| **codeExecution**          | `ai-sdk-tool-code-execution` | Python code sandbox        | `VERCEL_OIDC_TOKEN`  |
| **guard**                  | `@superagent-ai/ai-sdk`      | Prompt injection detection | `SUPERAGENT_API_KEY` |
| **redact**                 | `@superagent-ai/ai-sdk`      | PII redaction              | `SUPERAGENT_API_KEY` |
| **verify**                 | `@superagent-ai/ai-sdk`      | Claim verification         | `SUPERAGENT_API_KEY` |
| **valyuWebSearch**         | `@valyu/ai-sdk`              | Domain-specific search     | `VALYU_API_KEY`      |
| **airweave**               | `@airweave/sdk`              | RAG/semantic search        | `AIRWEAVE_API_KEY`   |
| **bedrockCodeInterpreter** | `bedrock-agentcore`          | AWS code execution         | AWS credentials      |

## Installation

Install only the tools you need:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Web search tools
npm install @tavily/ai-sdk
npm install @exalabs/ai-sdk

# Security tools
npm install @superagent-ai/ai-sdk

# Code execution
npm install ai-sdk-tool-code-execution
```

## Using the Tools Facade

The `tools` object provides a simple API for all built-in tools:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { tools } from 'praisonai';

// Search tools
tools.tavily({ maxResults: 5 })
tools.exa({ highlights: true })
tools.perplexity()

// Content tools
tools.tavilyExtract()
tools.tavilyCrawl()
tools.firecrawl()
tools.firecrawlCrawl()

// Security tools
tools.guard()
tools.redact()
tools.verify()

// Code execution
tools.codeExecution()
tools.codeMode()

// Domain search (Valyu)
tools.valyuWebSearch()
tools.valyuFinanceSearch()
tools.valyuPaperSearch()
tools.valyuSecSearch()

// Custom tools
tools.custom({ name, description, parameters, execute })
```

## Registry API

Access the underlying registry for advanced use cases:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { getToolsRegistry, registerBuiltinTools } from 'praisonai';

// Register all built-in tools
registerBuiltinTools();

// Get the registry
const registry = getToolsRegistry();

// List all tools
const allTools = registry.list();

// Get tool metadata
const metadata = registry.getMetadata('tavily');

// Create a tool instance
const tool = registry.create('tavily', { maxResults: 10 });

// Check if a tool is registered
const exists = registry.has('tavily');
```

## Middleware

Add middleware to all tool executions:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { 
  getToolsRegistry,
  createLoggingMiddleware,
  createTimeoutMiddleware,
  createRedactionMiddleware 
} from 'praisonai';

const registry = getToolsRegistry();

// Add logging
registry.use(createLoggingMiddleware());

// Add 30-second timeout
registry.use(createTimeoutMiddleware(30000));

// Add PII redaction
registry.use(createRedactionMiddleware());
```

### Available Middleware

| Middleware                                 | Description                |
| ------------------------------------------ | -------------------------- |
| `createLoggingMiddleware()`                | Log tool calls and results |
| `createTimeoutMiddleware(ms)`              | Timeout long operations    |
| `createRedactionMiddleware()`              | Redact PII from results    |
| `createRateLimitMiddleware(limit, window)` | Rate limit tool calls      |
| `createRetryMiddleware(attempts, delay)`   | Retry failed calls         |
| `createTracingMiddleware()`                | Add tracing context        |
| `createValidationMiddleware()`             | Validate inputs            |

## Hooks

Set hooks for monitoring:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
registry.setHooks({
  beforeToolCall: (name, input, ctx) => {
    console.log(`Starting: ${name}`);
  },
  afterToolCall: (name, input, output, ctx) => {
    console.log(`Completed: ${name}`);
  },
  onError: (name, error, ctx) => {
    console.error(`Error in ${name}:`, error);
  },
});
```

## Custom Tools

Register your own tools:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { tools } from 'praisonai';

const calculator = tools.custom({
  id: 'calculator',
  name: 'calculator',
  description: 'Perform arithmetic calculations',
  parameters: {
    type: 'object',
    properties: {
      expression: {
        type: 'string',
        description: 'Math expression to evaluate',
      },
    },
    required: ['expression'],
  },
  execute: async (input) => {
    const result = eval(input.expression); // Use a proper math parser
    return { result };
  },
});

const agent = new Agent({
  tools: [calculator],
});
```

## CLI Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all tools
praisonai-ts tools list

# Get tool info
praisonai-ts tools info tavily

# Check dependencies
praisonai-ts tools doctor

# Show example
praisonai-ts tools example tavily

# Test a tool
praisonai-ts tools test tavily --live

# Register npm tool
praisonai-ts tools add @my-org/my-tool
```

## Tool Categories

### Search Tools

* **tavily** - General web search with AI answers
* **exa** - Semantic/neural search
* **perplexity** - Real-time search with citations
* **parallel** - Multi-source parallel search

### Content Tools

* **tavilyExtract** - Extract content from URLs
* **tavilyCrawl** - Crawl websites
* **firecrawl** - Advanced web scraping
* **airweave** - RAG/semantic search

### Security Tools

* **guard** - Detect prompt injection
* **redact** - Remove PII
* **verify** - Verify claims

### Code Execution

* **codeExecution** - Vercel sandbox (Python)
* **codeMode** - Custom sandboxed execution
* **bedrockCodeInterpreter** - AWS sandbox

### Domain Search (Valyu)

* **valyuWebSearch** - General web
* **valyuFinanceSearch** - Financial data
* **valyuPaperSearch** - Academic papers
* **valyuBioSearch** - Biology/medical
* **valyuPatentSearch** - Patents
* **valyuSecSearch** - SEC filings
* **valyuEconomicsSearch** - Economic data
* **valyuCompanyResearch** - Company info

## Error Handling

Tools throw specific errors for common issues:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { MissingDependencyError, MissingEnvVarError } from 'praisonai';

try {
  const tool = tools.tavily();
  await tool.execute({ query: 'test' });
} catch (error) {
  if (error instanceof MissingDependencyError) {
    console.log('Install:', error.installHints.npm);
  } else if (error instanceof MissingEnvVarError) {
    console.log('Set env var:', error.envVar);
  }
}
```

## Related

<CardGroup cols={2}>
  <Card title="Tavily" icon="book" href="/js/tools/tavily">
    Web search tool
  </Card>

  <Card title="Exa" icon="book" href="/js/tools/exa">
    Semantic search tool
  </Card>

  <Card title="Custom Tools" icon="book" href="/js/customtools">
    Creating custom tools
  </Card>

  <Card title="CLI Reference" icon="book" href="/js/cli">
    Command-line interface
  </Card>
</CardGroup>