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

# API Vocabulary

> One word per concept — approval= and launch(protocol=...) across the whole SDK

One vocabulary spans the SDK: `approval=` gates tools and agents, and `launch(protocol=...)` serves them.

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

@tool(approval=True)
def refund_order(order_id: str) -> str:
    """Refund an order."""
    return f"Refunded {order_id}"

support = Agent(name="support", tools=[refund_order], approval="high")
billing = Agent(name="billing", instructions="Answer billing questions.")

PraisonAIAgents(agents=[support, billing]).launch(protocol="mcp", port=7777)
# → http://localhost:7777/mcp — same launch() you already know from protocol="http"
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    subgraph Approval["approval="]
        Tool["@tool(approval=…)"] --> Word1["🛡️ same word"]
        Agent1["Agent(approval=…)"] --> Word1
    end
    subgraph Launch["launch(protocol=…)"]
        A2["Agent.launch(protocol=…)"] --> Word2["🌐 same word"]
        Multi["PraisonAIAgents.launch(protocol=…)"] --> Word2
    end

    classDef api fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef word fill:#10B981,stroke:#7C90A0,color:#fff

    class Tool,Agent1,A2,Multi api
    class Word1,Word2 word
```

## Quick Start

**1. Gate a tool**

`approval=True` on `@tool` registers the tool at `"high"` risk.

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

@tool(approval=True)
def delete_account(user_id: str) -> str:
    """Delete a user account."""
    return f"Deleted {user_id}"
```

**2. Gate an agent**

The same word gates the agent — `approval="high"` asks before any high-risk tool.

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

agent = Agent(name="support", instructions="Help users.", approval="high")
```

**3. Serve over MCP**

`launch(protocol="mcp")` publishes the agent(s) over MCP — same `launch()` as `protocol="http"`.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent.launch(protocol="mcp", port=7777)
```

***

## The two words

| Concept | The word | Where it appears |
| - | - | - |
| Human sign-off before running | `approval=` | `@tool(approval=…)` and `Agent(approval=…)` |
| Serve over a protocol | `launch(protocol=…)` | `Agent.launch(protocol=…)` and `PraisonAIAgents.launch(protocol=…)` |

`launch(protocol="mcp")` delegates to `serve_agents(...)`, so single- and multi-agent serving share one endpoint (`/mcp`), one tool schema (`ask_{name}` + `list_agents`), and one session model.

***

## Deprecated spellings

Old spellings still work but are on the way out.

| Deprecated | Use instead | Note |
| - | - | - |
| `@tool(requires_approval=…)` | `@tool(approval=…)` | Still works, emits a `DeprecationWarning`. `.requires_approval` and `.approval` both hold the resolved value. |
| `serve_agents([...])` (free function) | `launch(protocol="mcp")` | Kept as a thin alias for a function-call idiom — identical behaviour. Not deprecated; use whichever fits your code. |

***

## Best Practices

> [accordion] Prefer approval= everywhere
>
> Write `approval=` on both `@tool` and `Agent`. One word means one mental model — no guessing which surface uses which spelling.

> [accordion] Pick the launch idiom that fits your code
>
> Hold an `Agent` or `PraisonAIAgents` object? Call `launch(protocol="mcp")`. Writing an imperative script? Call `serve_agents([...])`. Both resolve to the same server.

> [accordion] Migrate off requires\_approval
>
> `requires_approval=` warns on every use — including explicit `False`. Swap it for `approval=` to silence the `DeprecationWarning`.

***

## Related

> [card] [Tool Approval](https://praison.ai/docs/features/tool-requires-approval.md)
>
> `@tool(approval=…)` decorator reference

> [card] [Agent Approval](https://praison.ai/docs/features/approval.md)
>
> `Agent(approval=…)` config and the dangerous-tools registry

> [card] [Serve Agents](https://praison.ai/docs/features/serve-agents.md)
>
> `serve_agents([...])` — what `launch(protocol='mcp')` delegates to

> [card] [Agents MCP](https://praison.ai/docs/deploy/servers/agents-mcp.md)
>
> `launch(protocol='mcp')` ergonomics and Docker


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