Server: Agents HTTP

Deploy agents as HTTP API servers using praisonai —serve or Agent.launch()

Deploy single or multi-agent systems as HTTP REST API servers.

Quick Start

1. Install Dependencies

   pip install "praisonaiagents[os]"
   
2. Set API Key

   export OPENAI_API_KEY="your-key"
   
3. Initialize Agents

   praisonai --init "helpful assistant"
   
4. Start Server

   praisonai serve agents --port 8000 --host 0.0.0.0
   

   Expected Output:

   📄 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
   
5. 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")

Expected Output:

🚀 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")

Expected Output:

🚀 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:

{
  "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")

Connect from remote:

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.

Related

• Agents API Reference - Full API documentation
• Agents MCP - Deploy agents as MCP server
• Tools MCP - Deploy tools as MCP server
• Deploy CLI - Deploy using praisonai deploy