Deployment

Deploy Agentor agents and MCP servers to production using self-hosted uvicorn or gunicorn servers, Docker containers, Kubernetes, or serverless platforms.

Overview

agent.serve() returns an ordinary ASGI app running under uvicorn, so anywhere you can run a Python web service will do:

1. Self-hosted Servers - uvicorn, gunicorn, or Docker
2. Kubernetes - a standard Deployment and Service
3. Serverless - AWS Lambda, Cloud Run, and similar
4. ASGI Servers - any ASGI-compatible platform

The app carries no authentication of its own. Put it behind whatever your infrastructure already uses.

Observability

Tracing is off unless you ask for it. A trace carries prompts, tool arguments and tool results, so nothing leaves your process by default:

agent = Agentor(
    name="Production Agent",
    model="gpt-4o",
    enable_tracing=True,   # needs CELESTO_API_KEY
)

You can also decide per run - agent.run("...", tracing=False) sends nothing for that call, and tracing=True traces one run without turning it on for the agent. See Tracing for the full picture.

Self-Hosted Deployment

Local Development

Run agents locally:

from agentor import Agentor

agent = Agentor(
    name="Weather Agent",
    model="gpt-5-mini",
    tools=["get_weather"]
)

agent.serve(
    host="0.0.0.0",
    port=8000,
    log_level="info",
    access_log=True
)

Access at http://localhost:8000.

Production Server

For production, use Gunicorn with uvicorn workers:

gunicorn server:app \
  -k uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000

Create server.py:

from agentor import Agentor

agent = Agentor(
    name="Production Agent",
    model="gpt-4o",
    tools=["get_weather"]
)

app = agent._create_app(host="0.0.0.0", port=8000)

uvicorn Deployment

Run with uvicorn directly:

uvicorn server:app \
  --host 0.0.0.0 \
  --port 8000 \
  --workers 4 \
  --log-level info

Docker Deployment

Dockerfile

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "server:app", "--host", "0.0.0.0", "--port", "8000"]

Build and Run

# Build image
docker build -t my-agent .

# Run container
docker run -p 8000:8000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  my-agent

Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  agent:
    build: .
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - CELESTO_API_KEY=${CELESTO_API_KEY}
    restart: unless-stopped

Run:

docker-compose up -d

Kubernetes Deployment

Deployment YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentor-agent
spec:
  replicas: 3
  selector:
    matchLabels:
      app: agentor-agent
  template:
    metadata:
      labels:
        app: agentor-agent
    spec:
      containers:
      - name: agent
        image: my-agent:latest
        ports:
        - containerPort: 8000
        env:
        - name: OPENAI_API_KEY
          valueFrom:
            secretKeyRef:
              name: agent-secrets
              key: openai-api-key
---
apiVersion: v1
kind: Service
metadata:
  name: agentor-agent
spec:
  selector:
    app: agentor-agent
  ports:
  - port: 80
    targetPort: 8000
  type: LoadBalancer

Deploy:

kubectl apply -f deployment.yaml

MCP Server Deployment

Deploy LiteMCP servers:

from agentor.mcp import LiteMCP

app = LiteMCP(
    name="production-mcp",
    version="1.0.0"
)

@app.tool()
def production_tool(param: str) -> str:
    return f"Result: {param}"

if __name__ == "__main__":
    app.serve(host="0.0.0.0", port=8000)

MCP with Gunicorn

gunicorn mcp_server:app \
  -k uvicorn.workers.UvicornWorker \
  --workers 4

MCP as ASGI App

LiteMCP is a full ASGI application:

# Use with any ASGI server
import uvicorn

app = LiteMCP(name="my-mcp")
uvicorn.run(app, host="0.0.0.0", port=8000)

Serverless Deployment

AWS Lambda

Use Mangum for Lambda compatibility:

pip install mangum

from agentor import Agentor
from mangum import Mangum

agent = Agentor(
    name="Lambda Agent",
    model="gpt-4o",
    tools=["get_weather"]
)

app = agent._create_app(host="0.0.0.0", port=8000)
handler = Mangum(app)

Google Cloud Run

Create app.yaml:

runtime: python311
entrypoint: gunicorn -k uvicorn.workers.UvicornWorker server:app

env_variables:
  OPENAI_API_KEY: "your-key"

Deploy:

gcloud run deploy my-agent \
  --source . \
  --platform managed \
  --region us-central1

Environment Configuration

Production Settings

Configure for production (src/agentor/config.py):

import os
from dataclasses import dataclass

@dataclass
class Config:
    base_url: str = os.getenv("CELESTO_BASE_URL", "https://api.celesto.ai")
    api_key: str | None = os.getenv("CELESTO_API_KEY")

Required Environment Variables

# LLM Provider (choose one)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."
export GEMINI_API_KEY="..."

# Celesto tracing (only needed if you pass enable_tracing=True)
export CELESTO_API_KEY="..."

# Tool-specific keys
export WEATHER_API_KEY="..."
export GITHUB_TOKEN="..."

Health Checks

Agents automatically include health endpoints:

@app.get("/health")
def health():
    return {"status": "ok"}

Test:

curl http://localhost:8000/health

Monitoring

Logging

Configure logging levels:

import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

agent.serve(log_level="info")

Tracing

Enable Celesto tracing (src/agentor/tracer.py):

from agentor.tracer import setup_celesto_tracing

setup_celesto_tracing(
    endpoint="https://api.celesto.ai/traces/ingest",
    token="your-celesto-key"
)

Metrics

Integrate with Prometheus:

from prometheus_client import Counter, Histogram
from fastapi import FastAPI

app = agent._create_app(host="0.0.0.0", port=8000)

request_count = Counter('requests_total', 'Total requests')
request_duration = Histogram('request_duration_seconds', 'Request duration')

Load Balancing

Nginx Configuration

upstream agentor_backend {
    server 127.0.0.1:8000;
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
}

server {
    listen 80;
    server_name agent.example.com;

    location / {
        proxy_pass http://agentor_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Security

API Authentication

Implement authentication middleware:

from fastapi import Header, HTTPException

async def verify_token(authorization: str = Header(None)):
    if not authorization or not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401)
    token = authorization.split(" ")[1]
    if token != "expected-token":
        raise HTTPException(status_code=403)

app = agent._create_app(host="0.0.0.0", port=8000)
app.add_middleware(verify_token)

HTTPS/TLS

Use a reverse proxy (Nginx, Caddy) or configure uvicorn with SSL:

uvicorn server:app \
  --ssl-keyfile ./key.pem \
  --ssl-certfile ./cert.pem

Performance Tuning

Worker Configuration

Optimal workers = (2 × CPU cores) + 1:

gunicorn server:app \
  -k uvicorn.workers.UvicornWorker \
  --workers 9 \
  --worker-connections 1000 \
  --max-requests 1000 \
  --max-requests-jitter 50

Concurrency Control

Limit concurrent requests:

results = await agent.arun(
    batch_prompts,
    limit_concurrency=10  # Max 10 concurrent tasks
)

Troubleshooting

Common Issues

Port already in use:

lsof -i :8000
kill -9 <PID>

Module not found:

pip install -e .

API key errors:

env | grep API_KEY

Debug Mode

Enable detailed logging:

agent.serve(
    log_level="debug",
    access_log=True
)

Next Steps

Agents

Learn about agent configuration

A2A Protocol

Deploy A2A-compatible agents

MCP Servers

Deploy MCP servers

Celesto AI

Deploy to Celesto platform