Documentation Index
Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
Use this file to discover all available pages before exploring further.
Deploy single or multi-agent systems as HTTP REST API servers.
Quick Start
Install Dependencies
pip install "praisonaiagents[os]"
Set API Key
export OPENAI_API_KEY="your-key"
Initialize Agents
praisonai --init "helpful assistant"
Start Server
praisonai serve agents --port 8000 --host 0.0.0.0
📄 Loading workflow from: agents.yaml
🚀 Starting PraisonAI API server...
Host: 0.0.0.0
Port: 8000
🚀 Multi-Agent HTTP API available at http://0.0.0.0:8000/agents
✅ FastAPI server started at http://0.0.0.0:8000
📚 API documentation available at http://0.0.0.0:8000/docs
Verify
curl http://localhost:8000/health
Python - Single Agent
from praisonaiagents import Agent
agent = Agent(
name="Assistant",
instructions="You are a helpful assistant.",
llm="gpt-4o-mini"
)
agent.launch(path="/ask", port=8000, host="0.0.0.0")
🚀 Agent 'Assistant' available at http://0.0.0.0:8000
✅ FastAPI server started at http://0.0.0.0:8000
📚 API documentation available at http://0.0.0.0:8000/docs
🔌 Available endpoints: /ask
Python - Multi-Agent
from praisonaiagents import Agent, AgentTeam
researcher = Agent(name="Researcher", instructions="Research topics", llm="gpt-4o-mini")
writer = Agent(name="Writer", instructions="Write content", llm="gpt-4o-mini")
agents = AgentTeam(agents=[researcher, writer])
agents.launch(path="/content", port=8000, host="0.0.0.0")
🚀 Multi-Agent HTTP API available at http://0.0.0.0:8000/content
📊 Available agents for this endpoint (2): Researcher, Writer
🔗 Per-agent endpoints: /content/researcher, /content/writer
✅ FastAPI server started at http://0.0.0.0:8000
📚 API documentation available at http://0.0.0.0:8000/docs
Multiple Agent / Agents instances may call .launch(port=N) concurrently from different threads — registration is atomic. If two launch calls use the same path on the same port, the second gets an auto-suffixed path (/path_abc123) and a warning is logged. Server readiness is signalled deterministically (no fixed sleep); .launch() returns only after the port is accepting connections. The wait defaults to 5 seconds and is configurable via the PRAISONAI_SERVER_READY_TIMEOUT environment variable. If the server doesn’t become ready in time, .launch() still returns and a warning is logged — check server logs for startup errors.
agents.yaml
framework: praisonai
topic: research and write content
roles:
researcher:
role: Researcher
goal: Research topics thoroughly
backstory: Expert researcher
tasks:
research_task:
description: Research the topic
expected_output: Research findings
writer:
role: Writer
goal: Write engaging content
backstory: Expert writer
tasks:
write_task:
description: Write based on research
expected_output: Written content
praisonai serve agents --port 8000 --host 0.0.0.0
CLI Commands
# Start agents server
praisonai serve agents --port 8000
# With custom host for remote access
praisonai serve agents --port 8000 --host 0.0.0.0
# With agents file
praisonai serve agents --file agents.yaml --port 8000
# Give the server more time on slow machines
export PRAISONAI_SERVER_READY_TIMEOUT=15
praisonai serve agents --port 8000
| Option | Default | Description |
|---|
--port | 8000 | Server port |
--host | 127.0.0.1 | Server host (use 0.0.0.0 for remote) |
--file | agents.yaml | Agents YAML file |
--reload | false | Enable hot reload |
--api-key | - | API key for authentication |
launch() Parameters
| Parameter | Type | Default | Description |
|---|
path | str | / | API endpoint path |
port | int | 8000 | Server port |
host | str | 0.0.0.0 | Server host |
debug | bool | False | Debug mode |
protocol | str | http | http or mcp |
Endpoints
| Endpoint | Method | Description |
|---|
/{path} | POST | Send query to agent(s) |
/{path}/list | GET | List available agents |
/{path}/{agent_id} | POST | Call specific agent |
/health | GET | Health check |
/docs | GET | Swagger UI |
Example Request/Response
Request:
curl -X POST http://localhost:8000/ask \
-H "Content-Type: application/json" \
-d '{"query": "What is AI?"}'
{
"response": "Artificial intelligence (AI) refers to..."
}
Remote Access
Use host="0.0.0.0" to allow remote connections:
# CLI
praisonai serve agents --port 8000 --host 0.0.0.0
# Python
agent.launch(path="/ask", port=8000, host="0.0.0.0")
curl -X POST http://SERVER_IP:8000/ask \
-H "Content-Type: application/json" \
-d '{"query": "Hello"}'
Environment Variables
| Variable | Default | Description |
|---|
PRAISONAI_SERVER_READY_TIMEOUT | 5.0 | Seconds to wait for the FastAPI server to become ready after .launch() / praisonai serve agents. A warning is logged if exceeded; startup continues. |
Troubleshooting
| Issue | Fix |
|---|
| Port in use | lsof -i :8000 then kill process |
| No agents.yaml | praisonai --init "topic" |
| Missing API key | export OPENAI_API_KEY="your-key" |
| Missing deps | pip install "praisonaiagents[os]" |
| Connection refused | Use host="0.0.0.0" for remote |
| Firewall blocking | Open port in firewall |
| Agent server slow to start / “did not become ready” warning | Set PRAISONAI_SERVER_READY_TIMEOUT=10 (seconds) before launching, or check server logs for the underlying startup error. |
