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

# 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

<Steps>
  <Step title="Install Dependencies">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    pip install "praisonaiagents[os]"
    ```
  </Step>

  <Step title="Set API Key">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    export OPENAI_API_KEY="your-key"
    ```
  </Step>

  <Step title="Initialize Agents">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai --init "helpful assistant"
    ```
  </Step>

  <Step title="Start Server">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    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
    ```
  </Step>

  <Step title="Verify">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    curl http://localhost:8000/health
    ```
  </Step>
</Steps>

## Python - Single Agent

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```

<Note>
  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 (5s timeout).
</Note>

## agents.yaml

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai serve agents --port 8000 --host 0.0.0.0
```

## CLI Commands

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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
```

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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST http://localhost:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "What is AI?"}'
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "response": "Artificial intelligence (AI) refers to..."
}
```

## Remote Access

Use `host="0.0.0.0"` to allow remote connections:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST http://SERVER_IP:8000/ask \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello"}'
```

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

## Related

* [Agents API Reference](../api/agents-api) - Full API documentation
* [Agents MCP](./agents-mcp) - Deploy agents as MCP server
* [Tools MCP](./tools-mcp) - Deploy tools as MCP server
* [Deploy CLI](../cli/index) - Deploy using praisonai deploy