> ## 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.

# AI Agents with Tools

> Learn how to create AI agents that can use tools to interact with external systems and perform actions.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "AI Agents with Tools"
        Request[📋 User Request] --> Process[⚙️ AI Agents with Tools]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as AI Agents with Tools

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

def search(query: str) -> str:
    return f"Results for {query}"

agent = Agent(name="Assistant", tools=[search])
agent.start("Search for Python 3.13 release notes")
```

The user assigns tools to an agent; the model chooses tool calls to complete the task.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
flowchart TB
    subgraph Tools
        direction TB
        T3[Internet Search]
        T1[Code Execution]
        T2[Formatting]
    end

    Input[Input] ---> Agents
    subgraph Agents
        direction LR
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent 3]
    end
    Agents ---> Output[Output]

    T3 --> A1
    T1 --> A2
    T2 --> A3

    style Tools fill:#189AB4,color:#fff
    style Agents fill:#8B0000,color:#fff
    style Input fill:#8B0000,color:#fff
    style Output fill:#8B0000,color:#fff

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

```

| Feature     | [Knowledge](/docs/docs/features/knowledge) | [Tools](/docs/docs/features/toolsets) |
| ----------- | ------------------------------------- | -------------------------------- |
| Purpose     | Static reference information          | Dynamic interaction capabilities |
| Access      | Read-only reference                   | Execute actions and commands     |
| Updates     | Manual through files                  | Real-time through tool calls     |
| Storage     | Knowledge base                        | Assigned to specific agents      |
| Persistence | Permanent until changed               | Available during agent execution |

## Quick Start

Tools are functions that agents can use to interact with external systems and perform actions. They are essential for creating agents that can do more than just process text.

<Steps>
  <Step title="Simple Usage">
    Use the Code tab below to attach a tool to an agent.
  </Step>

  <Step title="With Configuration">
    Combine multiple tools and providers — see the YAML and CLI tabs.
  </Step>
</Steps>

<Tabs>
  <Tab title="Code">
    <Steps>
      <Step title="Install PraisonAI">
        Install the core package:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonaiagents duckduckgo-search
        ```
      </Step>

      <Step title="Configure Environment">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY=your_openai_key
        ```

        Generate your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
        Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the [Models](/docs/models) for more information.
      </Step>

      <Step title="Create Agent with Tool">
        Create `app.py`

        <CodeGroup>
          ```python Single Agent theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          from praisonaiagents import Agent
          from duckduckgo_search import DDGS

          # 1. Define the tool
          def internet_search_tool(query: str):
              results = []
              ddgs = DDGS()
              for result in ddgs.text(keywords=query, max_results=5):
                  results.append({
                      "title": result.get("title", ""),
                      "url": result.get("href", ""),
                      "snippet": result.get("body", "")
                  })
              return results

          # 2. Assign the tool to an agent
          search_agent = Agent(
              instructions="Perform internet searches to collect relevant information.",
              tools=[internet_search_tool] # <--- Tool Assignment
          )

          # 3. Start Agent
          search_agent.start("Search about AI job trends in 2025")
          ```

          ```python Multiple Agents theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
          from praisonaiagents import Agent, AgentTeam
          from duckduckgo_search import DDGS

          # 1. Define the tool
          def internet_search_tool(query: str):
              results = []
              ddgs = DDGS()
              for result in ddgs.text(keywords=query, max_results=5):
                  results.append({
                      "title": result.get("title", ""),
                      "url": result.get("href", ""),
                      "snippet": result.get("body", "")
                  })
              return results

          # 2. Assign the tool to an agent
          search_agent = Agent(
              instructions="Search about AI job trends in 2025",
              tools=[internet_search_tool] # <--- Tool Assignment
          )

          blog_agent = Agent(
              instructions="Write a blog article based on the previous agent's search results."
          )

          # 3. Start Agents
          agents = AgentTeam(agents=[search_agent, blog_agent])
          agents.start()
          ```
        </CodeGroup>
      </Step>

      <Step title="Start Agents">
        Execute your script:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        python app.py
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="No Code">
    <Steps>
      <Step title="Install PraisonAI">
        Install the core package and duckduckgo\_search package:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonai duckduckgo_search
        ```
      </Step>

      <Step title="Create Custom Tool">
        <Info>
          To add additional tools/features you need some coding which can be generated using ChatGPT or any LLM
        </Info>

        Create a new file `tools.py` with the following content:

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        from duckduckgo_search import DDGS
        from typing import List, Dict

        # 1. Tool
        def internet_search_tool(query: str) -> List[Dict]:
            """
            Perform Internet Search
            """
            results = []
            ddgs = DDGS()
            for result in ddgs.text(keywords=query, max_results=5):
                results.append({
                    "title": result.get("title", ""),
                    "url": result.get("href", ""),
                    "snippet": result.get("body", "")
                })
            return results  
        ```
      </Step>

      <Step title="Create Agent">
        Create a new file `agents.yaml` with the following content:

        ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        framework: praisonai
        topic: create movie script about cat in mars
        agents:  # Canonical: use 'agents' instead of 'roles'
          scriptwriter:
            instructions: Expert in dialogue and script structure, translating concepts into
              scripts.  # Canonical: use 'instructions' instead of 'backstory'
            goal: Write a movie script about a cat in Mars
            role: Scriptwriter
            tools:
              - internet_search_tool # <-- Tool assigned to Agent here
            tasks:
              scriptwriting_task:
                description: Turn the story concept into a production-ready movie script,
                  including dialogue and scene details.
                expected_output: Final movie script with dialogue and scene details.
        ```
      </Step>

      <Step title="Start Agents">
        Execute your script:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        praisonai agents.yaml
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Creating Custom Tool

<Steps>
  <Step>
    Create any function that you want to use as a tool, that performs a specific task.

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from duckduckgo_search import DDGS

    def internet_search_tool(query: str):
        results = []
        ddgs = DDGS()
        for result in ddgs.text(keywords=query, max_results=5):
            results.append({
                "title": result.get("title", ""),
                "url": result.get("href", ""),
                "snippet": result.get("body", "")
            })
        return results
    ```
  </Step>

  <Step>
    Assign the tool to an agent

    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        data_agent = Agent(
            instructions="Search about AI job trends in 2025",
            tools=[internet_search_tool], # <-- Tool Assignment
        )
    ```
  </Step>
</Steps>

<Card title="That's it!">
  <Check>You have created a custom tool and assigned it to an agent.</Check>
</Card>

## Creating Custom Tool with Detailed Instructions

<Tabs>
  <Tab title="Code">
    <Steps>
      <Step title="Install PraisonAI">
        Install the core package:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonaiagents duckduckgo-search
        ```
      </Step>

      <Step title="Configure Environment">
        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        export OPENAI_API_KEY=your_openai_key
        ```

        Generate your OpenAI API key from [OpenAI](https://platform.openai.com/api-keys)
        Use other LLM providers like Ollama, Anthropic, Groq, Google, etc. Please refer to the [Models](/docs/models) for more information.
      </Step>

      <Step title="Create Agent with Tool">
        Create `app.py`

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        from praisonaiagents import Agent, Task, AgentTeam
        from duckduckgo_search import DDGS

        # 1. Tool Implementation
        def internet_search_tool(query: str):
            results = []
            ddgs = DDGS()
            for result in ddgs.text(keywords=query, max_results=5):
                results.append({
                    "title": result.get("title", ""),
                    "url": result.get("href", ""),
                    "snippet": result.get("body", "")
                })
            return results

        # 2. Assign the tool to an agent
        data_agent = Agent(
            name="DataCollector",
            role="Search Specialist",
            goal="Perform internet searches to collect relevant information.",
            backstory="Expert in finding and organising internet data.",
            tools=[internet_search_tool],
            reflection=False
        )

        # 3. Task Definition
        collect_task = Task(
            description="Perform an internet search using the query: 'AI job trends in 2024'. Return results as a list of title, URL, and snippet.",
            expected_output="List of search results with titles, URLs, and snippets.",
            agent=data_agent,
            name="collect_data",
        )

        # 4. Start Agents
        agents = AgentTeam(
            agents=[data_agent],
            tasks=[collect_task],
            process="sequential"
        )

        agents.start()
        ```
      </Step>

      <Step title="Start Agents">
        Execute your script:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        python app.py
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="No Code">
    <Steps>
      <Step title="Install PraisonAI">
        Install the core package and duckduckgo\_search package:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        pip install praisonai duckduckgo_search
        ```
      </Step>

      <Step title="Create Custom Tool">
        <Info>
          To add additional tools/features you need some coding which can be generated using ChatGPT or any LLM
        </Info>

        Create a new file `tools.py` with the following content:

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        from duckduckgo_search import DDGS
        from typing import List, Dict

        # 1. Tool
        def internet_search_tool(query: str) -> List[Dict]:
            """
            Perform Internet Search
            """
            results = []
            ddgs = DDGS()
            for result in ddgs.text(keywords=query, max_results=5):
                results.append({
                    "title": result.get("title", ""),
                    "url": result.get("href", ""),
                    "snippet": result.get("body", "")
                })
            return results  
        ```
      </Step>

      <Step title="Create Agent">
        Create a new file `agents.yaml` with the following content:

        ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        framework: praisonai
        topic: create movie script about cat in mars
        agents:  # Canonical: use 'agents' instead of 'roles'
          scriptwriter:
            instructions:  # Canonical: use 'instructions' instead of 'backstory' Expert in dialogue and script structure, translating concepts into
              scripts.
            goal: Write a movie script about a cat in Mars
            role: Scriptwriter
            tools:
              - internet_search_tool # <-- Tool assigned to Agent here
            tasks:
              scriptwriting_task:
                description: Turn the story concept into a production-ready movie script,
                  including dialogue and scene details.
                expected_output: Final movie script with dialogue and scene details.
        ```
      </Step>

      <Step title="Start Agents">
        Execute your script:

        ```bash Terminal theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        praisonai agents.yaml
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## MCP Tools (Model Context Protocol)

MCP allows agents to use external tools via standardized protocols. This is the recommended way to add powerful tools to your agents.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, MCP

# Use MCP tools with environment variables
agent = Agent(
    instructions="Search the web for information",
    tools=MCP(
        command="npx",
        args=["-y", "@anthropic/mcp-server-brave-search"],
        env={"BRAVE_API_KEY": "your-api-key"}
    )
)

agent.start("Search for AI trends in 2025")
```

<CardGroup cols={2}>
  <Card title="MCP Overview" icon="plug" href="/docs/mcp/mcp">
    Introduction to Model Context Protocol
  </Card>

  <Card title="MCP Transports" icon="network-wired" href="/docs/docs/mcp/transports">
    stdio, HTTP, WebSocket, and SSE transports
  </Card>
</CardGroup>

## Built-in Search Tools

PraisonAI includes built-in search tools that work with multiple providers:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Tavily Search (recommended)
agent = Agent(
    instructions="Search and analyze information",
    tools=["tavily"]  # Requires TAVILY_API_KEY
)

# You.com Search
agent = Agent(
    instructions="Search the web",
    tools=["you"]  # Requires YOU_API_KEY
)

# Exa Search
agent = Agent(
    instructions="Find relevant content",
    tools=["exa"]  # Requires EXA_API_KEY
)
```

<CardGroup cols={2}>
  <Card title="Tavily" icon="magnifying-glass" href="/docs/docs/tools/tavily">
    AI-optimized search with web search, news, and content extraction
  </Card>

  <Card title="You.com" icon="globe" href="/docs/tools/you">
    Web search with AI-powered results
  </Card>

  <Card title="Exa" icon="search" href="/docs/docs/tools/exa">
    Neural search for finding similar content
  </Card>
</CardGroup>

## Fast Context (Code Search)

Fast Context provides rapid parallel code search for AI agents - 10-20x faster than traditional methods:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, FastContext

# Create agent with context management
agent = Agent(
    instructions="You are a code assistant",
    context=True,  # Enable context management
)

# Use FastContext directly for code search
fc = FastContext(workspace_path="/path/to/codebase")
result = fc.search("find authentication handlers")
context = result.to_context_string() if result.files else None
```

<Card title="Fast Context" icon="bolt" href="/docs/docs/features/fast-context">
  Rapid parallel code search with caching and multi-language support
</Card>

## In-build Tools in PraisonAI

<CardGroup cols={2}>
  <Card title="Search Tools" icon="magnifying-glass" href="/docs/tools/search">
    Tools for searching and retrieving information from various sources
  </Card>

  <Card title="Tavily Tools" icon="magnifying-glass" href="/docs/docs/tools/tavily">
    AI-optimized web search, news, and content extraction
  </Card>

  <Card title="You.com Tools" icon="globe" href="/docs/tools/you">
    Web search with AI-powered results
  </Card>

  <Card title="Exa Tools" icon="search" href="/docs/docs/tools/exa">
    Neural search for finding similar content
  </Card>

  <Card title="Python Tools" icon="python" href="/docs/docs/tools/python_tools">
    Essential Python utilities for data manipulation and scripting
  </Card>

  <Card title="Spider Tools" icon="spider" href="/docs/docs/tools/spider_tools">
    Web crawling and scraping capabilities for data extraction
  </Card>

  <Card title="Arxiv Tools" icon="book" href="/docs/docs/tools/arxiv_tools">
    Access and search academic papers from arXiv repository
  </Card>

  <Card title="Newspaper Tools" icon="newspaper" href="/docs/docs/tools/newspaper_tools">
    Extract and parse content from news articles and websites
  </Card>

  <Card title="DuckDB Tools" icon="database" href="/docs/docs/tools/duckdb_tools">
    Fast analytical SQL database operations and queries
  </Card>

  <Card title="DuckDuckGo Tools" icon="duck" href="/docs/docs/tools/duckduckgo_tools">
    Web search functionality using DuckDuckGo's API
  </Card>

  <Card title="SearxNG Tools" icon="search" href="/docs/docs/tools/searxng">
    Privacy-focused web search using local SearxNG instance
  </Card>

  <Card title="Calculator Tools" icon="calculator" href="/docs/docs/tools/calculator_tools">
    Perform mathematical calculations and conversions
  </Card>

  <Card title="YAML Tools" icon="file-code" href="/docs/docs/tools/yaml_tools">
    Parse and manipulate YAML format data
  </Card>

  <Card title="JSON Tools" icon="brackets-curly" href="/docs/docs/tools/json_tools">
    Handle JSON data structures and operations
  </Card>

  <Card title="Pandas Tools" icon="table" href="/docs/docs/tools/pandas_tools">
    Data analysis and manipulation using Pandas
  </Card>

  <Card title="YFinance Tools" icon="chart-line" href="/docs/docs/tools/yfinance_tools">
    Fetch financial market data from Yahoo Finance
  </Card>

  <Card title="Shell Tools" icon="terminal" href="/docs/docs/tools/shell_tools">
    Execute shell commands and system operations
  </Card>

  <Card title="AST-Grep Tools" icon="code-branch" href="/docs/docs/tools/ast-grep-tools">
    AST-based structural code search and rewrite
  </Card>

  <Card title="LSP Tools" icon="compass" href="/docs/docs/tools/lsp_tools">
    Language-server-accurate go-to-definition, find-references, and symbol search
  </Card>

  <Card title="Search Tools (grep/glob)" icon="magnifying-glass" href="/docs/docs/tools/search-tools">
    Fast, capped grep and glob built-ins for code-searching agents
  </Card>

  <Card title="Computer Use Tools" icon="computer-mouse" href="/docs/docs/features/computer-use-tools">
    Agent-controlled screen: screenshots, mouse, keyboard, and scroll — gated by an approval callback
  </Card>

  <Card title="Wikipedia Tools" icon="book-open" href="/docs/docs/tools/wikipedia_tools">
    Access and search Wikipedia articles and data
  </Card>

  <Card title="XML Tools" icon="code" href="/docs/docs/tools/xml_tools">
    Process and manipulate XML format data
  </Card>

  <Card title="File Tools" icon="file" href="/docs/docs/tools/file_tools">
    File system operations and management utilities
  </Card>

  <Card title="Excel Tools" icon="file-excel" href="/docs/docs/tools/excel_tools">
    Work with Excel spreadsheets and workbooks
  </Card>

  <Card title="CSV Tools" icon="file-csv" href="/docs/docs/tools/csv_tools">
    Handle CSV file operations and transformations
  </Card>
</CardGroup>

## Tools Overview

<CardGroup cols={2}>
  <Card title="Search Tools" icon="magnifying-glass" iconType="solid">
    Tools for searching and retrieving information from various sources
  </Card>

  <Card title="File Tools" icon="file" iconType="solid">
    Tools for reading, writing, and manipulating files
  </Card>

  <Card title="API Tools" icon="code" iconType="solid">
    Tools for interacting with external APIs and services
  </Card>
</CardGroup>

## Advanced Tool Features

### Tool Configuration

<Frame>
  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  def configured_tool(
      query: str,
      max_results: int = 5,
      timeout: int = 10
  ) -> List[Dict]:
      """
      Example of a configurable tool
      
      Args:
          query (str): Search query
          max_results (int): Maximum number of results
          timeout (int): Request timeout in seconds
          
      Returns:
          List[Dict]: Search results
      """
      # Tool implementation
      pass
  ```
</Frame>

### Tool Chaining

<Frame>
  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  def chain_tools(input_data: str) -> Dict:
      """
      Example of chaining multiple tools
      
      Args:
          input_data (str): Input data
          
      Returns:
          Dict: Processed results
      """
      # 1. Search for data
      search_results = internet_search_tool(input_data)
      
      # 2. Process results
      processed_data = process_tool(search_results)
      
      # 3. Format output
      return format_tool(processed_data)
  ```
</Frame>

### Tool Categories

<CardGroup cols={2}>
  <Card title="Data Collection Tools">
    * Web scraping
    * API integration
    * Database queries
  </Card>

  <Card title="Processing Tools">
    * Data transformation
    * Text analysis
    * Image processing
  </Card>

  <Card title="Output Tools">
    * File generation
    * Report creation
    * Data visualization
  </Card>
</CardGroup>

## Tool Integration

### Adding Tools to Agents

<Frame>
  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # Multiple tools
  agent = Agent(
      name="MultiTool Agent",
      tools=[
          internet_search_tool,
          file_processing_tool,
          api_integration_tool
      ]
  )
  ```
</Frame>

### Tool Dependencies

<Frame>
  ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  # Tool with dependencies
  def advanced_tool(data: Dict) -> Dict:
      """
      Tool that depends on external libraries
      
      Args:
          data (Dict): Input data
          
      Returns:
          Dict: Processed data
      """
      try:
          import required_library
          # Tool implementation
          return processed_result
      except ImportError:
          raise Exception("Required library not installed")
  ```
</Frame>

## Tool Guidelines

<CardGroup cols={2}>
  <Card title="Best Practices">
    1. **Type Hints**
       * Use Python type hints
       * Define clear input/output types
       * Document complex types

    2. **Documentation**
       * Write clear docstrings
       * Explain parameters
       * Provide usage examples

    3. **Error Handling**
       * Handle exceptions gracefully
       * Return meaningful errors
       * Validate inputs
  </Card>

  <Card title="Tool Types">
    1. **Search Tools**
       * Web search
       * Database queries
       * Document search

    2. **File Tools**
       * Read/write operations
       * File conversion
       * Data extraction

    3. **API Tools**
       * REST API calls
       * GraphQL queries
       * Service integration
  </Card>
</CardGroup>

## Best Practices Summary

<Note>
  Following these best practices will help you create robust, efficient, and secure tools in PraisonAI.
</Note>

<CardGroup cols={2}>
  <Card title="Design Principles" icon="compass-drafting" iconType="solid">
    <AccordionGroup>
      <Accordion title="Single Responsibility">
        Each tool should have one clear purpose and do it well. Avoid creating tools that try to do too many things.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # Good Example
        def process_image(image: np.array) -> np.array:
            return processed_image

        # Avoid
        def process_and_save_and_upload(image):
            # Too many responsibilities
            pass
        ```
      </Accordion>

      <Accordion title="Clear Interfaces">
        Define explicit input/output types and maintain consistent parameter naming.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        def search_tool(
            query: str,
            max_results: int = 10
        ) -> List[Dict[str, Any]]:
            """
            Search for information with clear parameters
            """
            pass
        ```
      </Accordion>

      <Accordion title="Documentation">
        Always include detailed docstrings and type hints.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        def analyze_text(
            text: str,
            language: str = "en"
        ) -> Dict[str, float]:
            """
            Analyze text sentiment and emotions.
            
            Args:
                text: Input text to analyze
                language: ISO language code
                
            Returns:
                Dict with sentiment scores
            """
            pass
        ```
      </Accordion>
    </AccordionGroup>
  </Card>
</CardGroup>

<br />

<CardGroup cols={2}>
  <Card title="Performance Optimization" icon="bolt" iconType="solid">
    <AccordionGroup>
      <Accordion title="Efficient Processing">
        Optimize resource usage and processing time.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # Use generators for large datasets
        def process_large_data():
            for chunk in data_generator():
                yield process_chunk(chunk)
        ```
      </Accordion>

      <Accordion title="Resource Management">
        Properly handle resource allocation and cleanup.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        async with aiohttp.ClientSession() as session:
            # Resource automatically managed
            await process_data(session)
        ```
      </Accordion>

      <Accordion title="Caching">
        Implement caching for frequently accessed data.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        @cache.memoize(timeout=300)
        def expensive_operation(data: str) -> Dict:
            return process_expensive(data)
        ```
      </Accordion>

      <Accordion title="Async Operations">
        Use async/await for I/O-bound operations.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        async def fetch_data(urls: List[str]):
            async with aiohttp.ClientSession() as session:
                tasks = [fetch_url(session, url) for url in urls]
                return await asyncio.gather(*tasks)
        ```
      </Accordion>
    </AccordionGroup>
  </Card>
</CardGroup>

<br />

<CardGroup cols={2}>
  <Card title="Security Best Practices" icon="shield-check" iconType="solid">
    <AccordionGroup>
      <Accordion title="Input Validation">
        Always validate and sanitize inputs to prevent security vulnerabilities.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        def process_user_input(data: str) -> str:
            if not isinstance(data, str):
                raise ValueError("Input must be string")
            return sanitize_input(data.strip())
        ```
      </Accordion>

      <Accordion title="Rate Limiting">
        Implement rate limiting for API calls to prevent abuse.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        @rate_limit(calls=100, period=60)
        async def api_call():
            return await make_request()
        ```
      </Accordion>

      <Accordion title="API Key Management">
        Securely handle API keys and credentials using environment variables.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        # Use environment variables
        api_key = os.getenv('API_KEY')
        if not api_key:
            raise ConfigError("API key not found")
        ```
      </Accordion>

      <Accordion title="Error Masking">
        Hide sensitive information in error messages to prevent information leakage.

        ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
        try:
            result = process_sensitive_data()
        except Exception as e:
            # Log detailed error internally
            logger.error(f"Detailed error: {str(e)}")
            # Return sanitized error to user
            raise PublicError("Processing failed")
        ```
      </Accordion>
    </AccordionGroup>
  </Card>
</CardGroup>

<br />

<Tip>
  **Pro Tip**: Start with these practices from the beginning of your project. It's easier to maintain good practices than to retrofit them later.
</Tip>

## Tool Packages Architecture

PraisonAI tools are organized into two packages for optimal performance and flexibility:

```
┌─────────────────────────────────────────────────┐
│                  YOUR CODE                       │
│  from praisonaiagents import Agent              │
│  from praisonai_tools import read_json          │  ← Extended Tools
│  from praisonaiagents import tavily             │  ← Core Tools
└─────────────────────────────────────────────────┘
                    │
       ┌────────────┴────────────┐
       ▼                         ▼
┌──────────────────┐    ┌──────────────────────┐
│  praisonaiagents │    │    praisonai-tools   │
│  (Core SDK)      │    │    (Extended Tools)  │
├──────────────────┤    ├──────────────────────┤
│ 21 Core Tools    │    │ 135+ Specialized     │
│ - Search         │    │ - JSON/YAML/XML/CSV  │
│ - Scraping       │    │ - Calculator         │
│ - File/Shell     │    │ - arXiv/Wikipedia    │
│ - Python Execute │    │ - YFinance/DuckDB    │
│ - Skill Tools    │    │ - Email/Slack/GitHub │
│ - CoT Training   │    │ - All heavy deps     │
└──────────────────┘    └──────────────────────┘
       │                         │
       │  Lightweight            │  Optional Install
       │  ~0.23s import time     │  pip install praisonai-tools
       ▼                         ▼
┌──────────────────────────────────────────────────┐
│              Agent(tools=[...])                   │
│  Unified tool interface - works with both        │
└──────────────────────────────────────────────────┘
```

### Package Installation

<Tabs>
  <Tab title="Core Tools Only">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Lightweight - includes search, scraping, file/shell tools
    pip install praisonaiagents
    ```

    **Included Tools:**

    * Search: `tavily`, `exa`, `duckduckgo`, `searxng`, `web_search`
    * Scraping: `crawl4ai`, `spider_tools`
    * Utilities: `file_tools`, `shell_tools`, `python_tools`, `ast_grep_tools`, `computer_tools`, `lsp_definition`, `lsp_references`, `lsp_hover`, `lsp_document_symbols`, `lsp_workspace_symbols`
    * Training: `cot_save`, `cot_upload_to_huggingface`
  </Tab>

  <Tab title="Extended Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Full toolkit - includes all specialized tools
    pip install praisonaiagents praisonai-tools
    ```

    **Additional Tools:**

    * Data: `read_json`, `read_yaml`, `read_xml`, `read_csv`, `read_excel`
    * Research: `search_arxiv`, `wikipedia_search`
    * Finance: `yfinance`, `calculate`, `duckdb_query`
    * Integrations: `EmailTool`, `SlackTool`, `GitHubTool`, `NotionTool`
  </Tab>

  <Tab title="Wrapper with Tools">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    # Via wrapper (includes praisonai-tools automatically)
    pip install "praisonai-frameworks[crewai]"
    # or
    pip install "praisonai-frameworks[autogen]"
    ```
  </Tab>
</Tabs>

### Import Patterns

<CodeGroup>
  ```python Core Tools (from praisonaiagents) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from praisonaiagents import Agent
  from praisonaiagents import tavily, exa_search, duckduckgo
  from praisonaiagents import crawl4ai, spider_tools
  from praisonaiagents import read_file, write_file, execute_command
  from praisonaiagents import cot_save, cot_upload_to_huggingface

  agent = Agent(
      instructions="Search the web",
      tools=[tavily, crawl4ai]
  )
  ```

  ```python Extended Tools (from praisonai_tools) theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  from praisonaiagents import Agent
  from praisonai_tools import read_json, write_json, validate_json
  from praisonai_tools import read_csv, read_excel, read_yaml
  from praisonai_tools import search_arxiv, wikipedia_search
  from praisonai_tools import EmailTool, SlackTool, GitHubTool

  agent = Agent(
      instructions="Process JSON data",
      tools=[read_json, write_json]
  )
  ```
</CodeGroup>

### Core Tools Reference

<CardGroup cols={2}>
  <Card title="Search Tools" icon="magnifying-glass">
    **Package:** `praisonaiagents`

    * `tavily`, `tavily_search`, `tavily_extract`
    * `exa`, `exa_search`, `exa_search_contents`
    * `duckduckgo`, `internet_search`
    * `searxng_search`
    * `search_web` (auto-fallback)
  </Card>

  <Card title="Scraping Tools" icon="spider">
    **Package:** `praisonaiagents`

    * `crawl4ai`, `crawl4ai_extract`
    * `spider_tools`, `scrape_page`, `extract_links`
  </Card>

  <Card title="File/Shell Tools" icon="terminal">
    **Package:** `praisonaiagents`

    * `read_file`, `write_file`, `list_files`
    * `execute_command`, `list_processes`
    * `execute_code`, `analyze_code`
  </Card>

  <Card title="Training Tools" icon="graduation-cap">
    **Package:** `praisonaiagents`

    * `cot_save`, `cot_upload_to_huggingface`
    * `cot_generate`, `cot_improve`
  </Card>

  <Card title="Screen Control Tools" icon="computer-mouse">
    **Package:** `praisonaiagents`

    * `computer_screenshot`, `computer_screen_size`
    * `computer_move`, `computer_click`, `computer_scroll`
    * `computer_type`, `computer_key`
    * `set_computer_approval` (register the human-in-the-loop gate)
  </Card>
</CardGroup>

### Extended Tools Reference

<CardGroup cols={2}>
  <Card title="Data Format Tools" icon="brackets-curly" href="/docs/docs/tools/json_tools">
    **Package:** `praisonai-tools`

    * `read_json`, `write_json`, `validate_json`
    * `read_yaml`, `write_yaml`, `validate_yaml`
    * `read_xml`, `write_xml`, `transform_xml`
    * `read_csv`, `write_csv`, `merge_csv`
    * `read_excel`, `write_excel`, `merge_excel`
  </Card>

  <Card title="Research Tools" icon="book" href="/docs/docs/tools/arxiv_tools">
    **Package:** `praisonai-tools`

    * `search_arxiv`, `get_arxiv_paper`
    * `wikipedia_search`
    * `pubmed_search`
  </Card>

  <Card title="Finance/Analytics" icon="chart-line" href="/docs/docs/tools/yfinance_tools">
    **Package:** `praisonai-tools`

    * `get_stock_price` (YFinance)
    * `calculate`, `solve_equation`
    * `duckdb_query`, `pandas_read_csv`
  </Card>

  <Card title="Integration Tools" icon="plug" href="/docs/docs/tools/external/email">
    **Package:** `praisonai-tools`

    * `EmailTool`, `SlackTool`, `DiscordTool`
    * `GitHubTool`, `NotionTool`, `TrelloTool`
    * `PostgresTool`, `MongoDBTool`, `RedisTool`
  </Card>
</CardGroup>

## Tool Security & Collision Prevention

<Warning>
  **Tool Name Conflicts**: When multiple environments register tools with the same names (e.g., multiple `send_message` implementations), agents may pick the wrong tool. Use the [Allowed Tools](/docs/features/allowed-tools) feature to whitelist specific tools and prevent collisions.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Custom Tools" icon="wrench" href="/docs/docs/tools/custom">
    Build your own agent tools
  </Card>

  <Card title="Tools Overview" icon="toolbox" href="/docs/docs/tools/tools">
    Browse PraisonAI tool documentation
  </Card>
</CardGroup>