Skip to main content

Agent Launch API

Deploy PraisonAI agents as HTTP API endpoints using the launch() method.

Base URL

http://localhost:{port}
Default port is 8000 for single agents, 3030 commonly used in examples.

Starting the Server

Single Agent

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant."
)

agent.launch(path="/ask", port=8000)

Multiple Agents

from praisonaiagents import Agent, Agents

research = Agent(name="Research", instructions="Research topics")
writer = Agent(name="Writer", instructions="Write content")

agents = Agents(agents=[research, writer])
agents.launch(path="/agents", port=8000)

Endpoints

POST /

Send a message to the agent and receive a response. Request
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"message": "What is AI?"}'
Request Body
FieldTypeRequiredDescription
messagestringYesThe message to send to the agent
Response
{
  "response": "Artificial intelligence (AI) refers to..."
}
Response Fields
FieldTypeDescription
responsestringThe agent’s response

Configuration Options

agent.launch(
    path="/custom-endpoint",  # API endpoint path
    port=8080,                # Port number
    host="0.0.0.0",           # Host address
    debug=True,               # Enable debug mode
    cors_origins=["*"],       # CORS configuration
    api_key="your-api-key"    # Optional API key authentication
)
ParameterTypeDefaultDescription
pathstr/URL path for the endpoint
portint8000Port to listen on
hoststr0.0.0.0Host address to bind
debugboolFalseEnable debug logging
cors_originslistNoneAllowed CORS origins
api_keystrNoneAPI key for authentication
protocolstrhttpProtocol: http or mcp

Multiple Endpoints

Deploy multiple agents on the same server:
weather_agent.launch(path="/weather", port=3030)
stock_agent.launch(path="/stock", port=3030)
travel_agent.launch(path="/travel", port=3030)
All agents share the same FastAPI application when using the same port.

Authentication

When api_key is set, include it in requests:
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"message": "Hello"}'

Error Responses

StatusDescription
400Bad request - invalid JSON or missing message
401Unauthorized - invalid or missing API key
500Internal server error
Error Response Format
{
  "detail": "Error message describing the issue"
}

Python Client Example

import requests

response = requests.post(
    "http://localhost:8000/ask",
    json={"message": "What is machine learning?"},
    headers={"Content-Type": "application/json"}
)

print(response.json()["response"])

See Also