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

# Vendor Tools (PraisonAI-Tools)

> Install third-party API tools (Stripe, Slack, Jira, financial data, etc.) as pip plugins from PraisonAI-Tools

Vendor tools are third-party API integrations you add to an agent with one `pip install` and a name in `tools=[]`.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Agent] --> B["tools=['vendor_tool']"]
    B --> C[PraisonAI-Tools pip plugin]
    C --> D[Vendor API]

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef plugin fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef api fill:#10B981,stroke:#7C90A0,color:#fff

    class A agent
    class B tool
    class C plugin
    class D api
```

## Quick Start

**1. Install the plugin**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai-tools-stripe
```

**2. Use it in your agent**

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

agent = Agent(
    name="Finance Analyst",
    instructions="Analyze market data",
    tools=["stripe_balance"],
)

agent.start("What is our current Stripe balance?")
```

The tool is auto-discovered by name after install — no imports needed.

***

## How It Works

The agent resolves a tool name to a vendor plugin installed through pip, calls the vendor API, and replies with the result.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Plugin as PraisonAI-Tools Plugin
    participant Vendor as Vendor API

    User->>Agent: Ask a question
    Agent->>Plugin: Call tool by name
    Plugin->>Vendor: Request data
    Vendor-->>Plugin: Response
    Plugin-->>Agent: Result
    Agent-->>User: Answer
```

Installed plugins register under the `praisonai.tools` entry-point group and become available by name — the same mechanism documented in [Custom Tools](https://praison.ai/docs/tools/custom.md).

***

## Three-Tier Tool Ecosystem

PraisonAI tools live in three places. Pick the tier that matches where your tool belongs.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph Tier1["Tier 1 - Core Legacy Bundled"]
        T1["Tavily, Exa, You.com, DuckDuckGo, Python, Shell, File"]
    end
    subgraph Tier2["Tier 2 - PraisonAI-Tools Pip Plugins"]
        T2["Stripe, Slack, Jira, SaaS and dataset wrappers"]
    end
    subgraph Tier3["Tier 3 - Custom / Single-File"]
        T3["@tool decorator, .praison/plugins/*.py"]
    end

    classDef core fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef plugin fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef custom fill:#189AB4,stroke:#7C90A0,color:#fff

    class T1 core
    class T2 plugin
    class T3 custom
```

| Tier | Where it lives | Use for |
| - | - | - |
| Core legacy bundled | `praisonaiagents.tools` (e.g. `tavily_tools.py`, `exa_tools.py`, `github_tools.py`, `duckduckgo_tools.py`, `searxng_tools.py`, `spider_tools.py`, `crawl4ai_tools.py`, `youdotcom_tools.py`, `jira_tools.py`, `email_tools.py`) | Backward-compat only — not a template for new modules |
| PraisonAI-Tools pip plugins | [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools) | All new vendor / third-party API integrations |
| Custom / single-file | Your project | Your own project-local logic |

> [!WARNING]
>
> "Same shape as Tavily/Exa" is a *consistency* check, not a *routing* one. Do not propose a new connector for core on precedent alone.

***

## Keep in Core or Route Out?

A tool only stays in `praisonaiagents.tools` if **both** left-column conditions hold. **Any** right-column condition routes it to PraisonAI-Tools.

| Keep in core `praisonaiagents.tools` | Route to PraisonAI-Tools |
| - | - |
| Local-state only — filesystem, shell, Python, AST, todo, schedule — **or** framework plumbing (delegation, subagent, session, artifact, memory, clarify) | Calls a third-party / remote API or SaaS |
| Uses only stdlib or already-required core deps | Needs service-specific auth or SDK; is a vendor connector (search, data, CRM, DB, messaging) |

> [!TIP]
>
> A macro / FX data client that uses only `urllib` still routes to PraisonAI-Tools. The dependency is the **external service plus credentials**, not the HTTP library.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Does the tool call a remote service<br/>or need service-specific credentials?}
    Q -->|No - local state / framework plumbing only| Core[Keep in praisonaiagents.tools]
    Q -->|Yes| Stdlib{Only uses stdlib HTTP?}
    Stdlib -->|Doesn't matter| Route[Route to PraisonAI-Tools]

    classDef q fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef core fill:#10B981,stroke:#7C90A0,color:#fff
    classDef route fill:#6366F1,stroke:#7C90A0,color:#fff

    class Q,Stdlib q
    class Core core
    class Route route
```

Your own project logic? Use a [custom tool or single-file plugin](https://praison.ai/docs/tools/custom.md) instead.

***

## Install Flow

Install one or more vendor plugins, then reference each by name.

**1. Install plugins**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonai-tools-stripe
```

**2. Add tool names to your agent**

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

agent = Agent(
    name="Finance Analyst",
    instructions="Analyze market data",
    tools=["yfinance", "stripe_balance"],
)

agent.start("Summarise AAPL year-to-date and our Stripe balance")
```

***

## How Auto-Discovery Works

Plugins declare a `praisonai.tools` entry point in their `pyproject.toml`; PraisonAI scans these on first use and registers each tool by name.

```toml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
[project.entry-points."praisonai.tools"]
stripe_balance = "praisonai_tools_stripe:StripeBalanceTool"
```

See the [Creating a Pip-Installable Tool Package](https://praison.ai/docs/tools/custom.md#creating-a-pip-installable-tool-package) section for the full publish flow.

***

## Routing is Not Fencing

Installing a vendor plugin decides **where the code lives**. It does **not** decide **how the LLM treats its results**.

A vendor result is only fenced (wrapped in `<external_tool_result>` safety markers) when **one of these** is true:

* the tool name is in the module-level `EXTERNAL_TOOL_NAMES` set, or
* it was registered with `ToolTrustLevel.EXTERNAL`.

Register your vendor tool for fencing at startup:

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

add_external_tool("stripe_balance")

agent = Agent(
    name="Finance Analyst",
    instructions="Analyze market data",
    tools=["stripe_balance"],
)
agent.start("What is our current Stripe balance?")
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[📦 Install plugin] --> B[🛡️ add_external_tool]
    B --> C[✅ Fenced result]

    classDef step fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef reg fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef ok fill:#10B981,stroke:#7C90A0,color:#fff

    class A step
    class B reg
    class C ok
```

See [Prompt Injection Protection](https://praison.ai/docs/features/prompt-injection-protection.md) for the full trust layer.

***

## Contributing a New Vendor Tool

> [!NOTE]
>
> New vendor integrations belong in [PraisonAI-Tools](https://github.com/MervinPraison/PraisonAI-Tools), not in the core SDK. A PR that adds a new `*_tools.py` module to `MervinPraison/PraisonAI` core is flagged **Repo routing ❌** by the merge gate and redirected. Matching an existing connector pattern (Tavily / Exa / You.com) does **not** exempt it.

Publish your plugin to PraisonAI-Tools and users install it with a single `pip install`.

***

## Best Practices

> **Prefer pip plugins for vendor APIs**
>
> Any public third-party API or SaaS integration goes in PraisonAI-Tools as an installable plugin, not in core.

> **Reference tools by name**
>
> After `pip install`, add the tool name to `tools=[]` — no import line is required.

> **Keep secrets in the environment**
>
> Read API keys from environment variables inside the plugin; never hard-code credentials.

> **Use custom tools for internal logic**
>
> Project-specific logic belongs in a custom tool or single-file plugin, not a published vendor package.

***

## Related

> **[Custom Tools](https://praison.ai/docs/tools/custom.md)**
>
> Build and publish your own tools

> **[Single-File Plugins](https://praison.ai/docs/tools/single-file-plugins.md)**
>
> Drop-in local Python plugins

> **[Tools Overview](https://praison.ai/docs/tools/tools.md)**
>
> Browse PraisonAI tool documentation

> **[MCP](https://praison.ai/docs/features/mcp.md)**
>
> Connect external tool servers


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.