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.

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"

Quick Start

1. Gate a tool

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

   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.

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

   agent.launch(protocol="mcp", port=7777)

The two words

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.

Best Practices

Related