Deployment Guide
Production deployment patterns for SpoonOS agents.
Deployment Options
| Method | Best For | Complexity |
|---|---|---|
| Docker | Portability, consistency | Low |
| AWS Lambda | Serverless, event-driven | Medium |
| GCP Cloud Run | Auto-scaling containers | Medium |
| Vercel | API endpoints | Low |
| VPS | Full control, cost-effective | Medium |
Docker Deployment
Dockerfile
# Dockerfile
FROM python:3.12-slim
WORKDIR /app
# Install system dependencies
RUN apt-get update && apt-get install -y \
gcc \
&& rm -rf /var/lib/apt/lists/*
# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
# Copy application
COPY . .
# Create non-root user
RUN useradd -m appuser && chown -R appuser:appuser /app
USER appuser
# Environment
ENV PYTHONUNBUFFERED=1
ENV PYTHONDONTWRITEBYTECODE=1
# Health check
HEALTHCHECK --interval=30s --timeout=10s \
CMD python -c "import spoon_ai; print('ok')" || exit 1
# Run
CMD ["python", "main.py"]
Docker Compose
# docker-compose.yml
version: '3.8'
services:
agent:
build: .
restart: unless-stopped
env_file:
- .env
environment:
- LOG_LEVEL=INFO
ports:
- "8000:8000"
volumes:
- ./data:/app/data
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
interval: 30s
timeout: 10s
retries: 3
redis:
image: redis:7-alpine
restart: unless-stopped
volumes:
- redis_data:/data
volumes:
redis_data:
Build and Run
# Build
docker build -t spoonos-agent .
# Run
docker run -d \
--name my-agent \
--env-file .env \
-p 8000:8000 \
spoonos-agent
# With compose
docker-compose up -d
AWS Lambda
Handler
# lambda_handler.py
import json
import os
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
# Initialize outside handler for warm starts
agent = None
def get_agent():
global agent
if agent is None:
agent = SpoonReactMCP(
name="lambda_agent",
llm=ChatBot(model_name="gpt-4o"),
tools=ToolManager([]),
max_steps=10
)
return agent
def handler(event, context):
"""Lambda handler."""
try:
body = json.loads(event.get('body', '{}'))
query = body.get('query', '')
if not query:
return {
'statusCode': 400,
'body': json.dumps({'error': 'Missing query'})
}
agent = get_agent()
# Run synchronously (Lambda doesn't support async directly)
import asyncio
loop = asyncio.get_event_loop()
response = loop.run_until_complete(agent.run(query))
return {
'statusCode': 200,
'headers': {'Content-Type': 'application/json'},
'body': json.dumps({'response': response})
}
except Exception as e:
return {
'statusCode': 500,
'body': json.dumps({'error': str(e)})
}
SAM Template
# template.yaml
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Globals:
Function:
Timeout: 300
MemorySize: 1024
Runtime: python3.12
Resources:
AgentFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: .
Handler: lambda_handler.handler
Environment:
Variables:
OPENAI_API_KEY: !Ref OpenAIKey
Events:
Api:
Type: Api
Properties:
Path: /query
Method: post
Parameters:
OpenAIKey:
Type: String
NoEcho: true
Outputs:
ApiEndpoint:
Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/query"
Deploy
# Install SAM CLI
pip install aws-sam-cli
# Build and deploy
sam build
sam deploy --guided
GCP Cloud Run
Dockerfile for Cloud Run
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# Cloud Run uses PORT env var
ENV PORT=8080
CMD exec uvicorn api:app --host 0.0.0.0 --port $PORT
API for Cloud Run
# api.py
from fastapi import FastAPI
from pydantic import BaseModel
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
app = FastAPI()
agent = SpoonReactMCP(
name="cloudrun_agent",
llm=ChatBot(model_name="gpt-4o"),
tools=ToolManager([])
)
class QueryRequest(BaseModel):
query: str
@app.post("/query")
async def query(request: QueryRequest):
response = await agent.run(request.query)
return {"response": response}
@app.get("/health")
async def health():
return {"status": "healthy"}
Deploy to Cloud Run
# Build and push
gcloud builds submit --tag gcr.io/PROJECT_ID/spoonos-agent
# Deploy
gcloud run deploy spoonos-agent \
--image gcr.io/PROJECT_ID/spoonos-agent \
--platform managed \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars "OPENAI_API_KEY=sk-..."
Vercel Deployment
API Route
# api/query.py
from http.server import BaseHTTPRequestHandler
import json
import asyncio
from spoon_ai.agents import SpoonReactMCP
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
agent = SpoonReactMCP(
name="vercel_agent",
llm=ChatBot(model_name="gpt-4o"),
tools=ToolManager([])
)
class handler(BaseHTTPRequestHandler):
def do_POST(self):
content_length = int(self.headers['Content-Length'])
body = json.loads(self.rfile.read(content_length))
query = body.get('query', '')
loop = asyncio.new_event_loop()
response = loop.run_until_complete(agent.run(query))
loop.close()
self.send_response(200)
self.send_header('Content-Type', 'application/json')
self.end_headers()
self.wfile.write(json.dumps({'response': response}).encode())
vercel.json
{
"version": 2,
"builds": [
{
"src": "api/*.py",
"use": "@vercel/python"
}
],
"routes": [
{
"src": "/api/(.*)",
"dest": "/api/$1"
}
]
}
Deploy
# Install Vercel CLI
npm i -g vercel
# Deploy
vercel --prod
Self-Hosted VPS
Setup Script
#!/bin/bash
# setup.sh
# Update system
sudo apt update && sudo apt upgrade -y
# Install Python 3.12
sudo add-apt-repository ppa:deadsnakes/ppa -y
sudo apt install python3.12 python3.12-venv -y
# Create app directory
sudo mkdir -p /opt/spoonos
sudo chown $USER:$USER /opt/spoonos
# Clone and setup
cd /opt/spoonos
git clone https://github.com/your-org/your-agent.git app
cd app
# Create virtual environment
python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# Copy environment file
cp .env.example .env
# Edit .env with your keys
Systemd Service
# /etc/systemd/system/spoonos-agent.service
[Unit]
Description=SpoonOS Agent
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/spoonos/app
Environment=PATH=/opt/spoonos/app/venv/bin
ExecStart=/opt/spoonos/app/venv/bin/python main.py
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
Enable and Start
sudo systemctl daemon-reload
sudo systemctl enable spoonos-agent
sudo systemctl start spoonos-agent
# Check status
sudo systemctl status spoonos-agent
# View logs
sudo journalctl -u spoonos-agent -f
Nginx Reverse Proxy
# /etc/nginx/sites-available/spoonos
server {
listen 80;
server_name agent.yourdomain.com;
location / {
proxy_pass http://127.0.0.1:8000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_cache_bypass $http_upgrade;
}
}
SSL with Certbot
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d agent.yourdomain.com
Environment Management
Production .env
# .env.production
NODE_ENV=production
LOG_LEVEL=INFO
# LLM (use secrets manager in production)
OPENAI_API_KEY=${OPENAI_API_KEY}
# Database
DATABASE_URL=postgresql://user:pass@host:5432/db
# Redis
REDIS_URL=redis://localhost:6379
# Monitoring
SENTRY_DSN=https://...
Secrets Management
# config.py
import os
from functools import lru_cache
# AWS Secrets Manager
def get_secret_aws(secret_name: str) -> str:
import boto3
client = boto3.client('secretsmanager')
response = client.get_secret_value(SecretId=secret_name)
return response['SecretString']
# GCP Secret Manager
def get_secret_gcp(secret_name: str) -> str:
from google.cloud import secretmanager
client = secretmanager.SecretManagerServiceClient()
name = f"projects/PROJECT_ID/secrets/{secret_name}/versions/latest"
response = client.access_secret_version(name=name)
return response.payload.data.decode()
@lru_cache
def get_config():
env = os.getenv("ENV", "development")
if env == "production":
return {
"openai_key": get_secret_aws("openai-api-key"),
"database_url": get_secret_aws("database-url"),
}
else:
return {
"openai_key": os.getenv("OPENAI_API_KEY"),
"database_url": os.getenv("DATABASE_URL"),
}
Monitoring
Health Check Endpoint
@app.get("/health")
async def health():
checks = {
"agent": "healthy",
"llm": "unknown",
"tools": "unknown"
}
# Check LLM connection
try:
# Quick test
checks["llm"] = "healthy"
except:
checks["llm"] = "unhealthy"
status = "healthy" if all(v == "healthy" for v in checks.values()) else "degraded"
return {"status": status, "checks": checks}
Logging Configuration
import logging
import json
from datetime import datetime
class JSONFormatter(logging.Formatter):
def format(self, record):
return json.dumps({
"timestamp": datetime.utcnow().isoformat(),
"level": record.levelname,
"message": record.getMessage(),
"module": record.module,
"function": record.funcName,
})
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
handler = logging.StreamHandler()
handler.setFormatter(JSONFormatter())
logger.addHandler(handler)
Deployment Checklist
- [ ] Environment variables configured
- [ ] Secrets in secure storage
- [ ] Health check endpoint working
- [ ] Logging configured
- [ ] Error tracking (Sentry) enabled
- [ ] SSL/TLS configured
- [ ] Rate limiting implemented
- [ ] Backup strategy in place
- [ ] Monitoring alerts configured
- [ ] Rollback procedure documented
