AI Agents · Lesson

Serving Agents Behind an API

Wrap your agent in FastAPI with auth, request validation, and streaming over SSE or WebSockets.

Serving Agents Behind an API is a free AI Agents lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Agents learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

From Notebook to Service

A working agent in a notebook is the start. To ship, wrap it in an HTTP API that other services can call.

FastAPI Skeleton

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class AgentRequest(BaseModel):
    query: str
    user_id: str

class AgentResponse(BaseModel):
    answer: str
    trace_id: str

@app.post('/agents/qa', response_model=AgentResponse)
def qa(req: AgentRequest):
    trace_id = run_agent(req.query, req.user_id)
    return AgentResponse(answer=result.answer, trace_id=trace_id)

Authentication

Every agent endpoint must authenticate. Use API keys or OAuth, depending on caller type:

from fastapi import Header, HTTPException

def require_api_key(api_key: str = Header(alias='X-API-Key')):
    if not is_valid(api_key):
        raise HTTPException(401, 'Invalid API key')
    return api_key

@app.post('/agents/qa')
def qa(req: AgentRequest, key=Depends(require_api_key)):
    ...

Streaming Responses

For chat UIs, stream tokens with SSE:

from fastapi.responses import StreamingResponse

@app.post('/agents/qa/stream')
def qa_stream(req: AgentRequest):
    def gen():
        for chunk in stream_agent(req.query):
            yield f'data: {chunk}\n\n'
        yield 'data: [DONE]\n\n'
    return StreamingResponse(gen(), media_type='text/event-stream')

Request Validation

Pydantic enforces types and basic validation. Add custom validation as needed:

from pydantic import Field

class AgentRequest(BaseModel):
    query: str = Field(min_length=1, max_length=10_000)
    user_id: str
    options: dict = {}

Error Handling

Map exceptions to clean HTTP responses:

from fastapi import HTTPException

@app.exception_handler(BudgetExceeded)
def budget_handler(req, exc):
    return JSONResponse({'error': 'budget-exceeded'}, status_code=429)

@app.exception_handler(Exception)
def catch_all(req, exc):
    log.exception('Unhandled')
    return JSONResponse({'error': 'internal', 'trace_id': get_trace_id()}, status_code=500)

Concurrency

FastAPI uses async by default. For CPU-bound agents (rare) or blocking SDKs, use the async clients:

from openai import AsyncOpenAI
client = AsyncOpenAI()

async def run_agent_async(query):
    return await client.chat.completions.create(...)

Health and Readiness Endpoints

@app.get('/healthz')
def healthz():
    return {'status': 'ok'}

@app.get('/readyz')
def readyz():
    if not vector_db.is_healthy():
        raise HTTPException(503)
    return {'status': 'ready'}

Containerise

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ['uvicorn', 'main:app', '--host', '0.0.0.0', '--port', '8080']

Run With Multiple Workers

Uvicorn + Gunicorn for production:

gunicorn -k uvicorn.workers.UvicornWorker -w 4 main:app

Reverse Proxy

Put Nginx or Caddy in front for TLS, gzip, and IP allowlisting.

Logging Structured Output

import structlog
log = structlog.get_logger()

@app.middleware('http')
async def log_requests(request, call_next):
    response = await call_next(request)
    log.info('http', method=request.method, path=request.url.path, status=response.status_code)
    return response

CORS for Browser Clients

from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=['https://app.example.com'],
    allow_methods=['*'], allow_headers=['*']
)

Production Checklist Item

Which is essential for any production agent API?

Recap

FastAPI + Pydantic + async client + streaming + auth + structured logs + health probes. That's the production minimum.

Frequently asked questions

Is the “Serving Agents Behind an API” lesson free?

Yes — the full text of “Serving Agents Behind an API” is free to read here on the web, and the AI Agents course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Agents course, upgrade to CoddyKit PRO.

What will I learn in “Serving Agents Behind an API”?

Wrap your agent in FastAPI with auth, request validation, and streaming over SSE or WebSockets. You practise AI Agents with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start AI Agents?

No prior experience is required. AI Agents on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “Serving Agents Behind an API” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this AI Agents lesson?

Yes. Every AI Agents lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

Serving Agents Behind an API
Async Workflows and Background Jobs
Rate Limiting and Quota Management
Blue-Green and Canary Deploys for Agents

← Back to AI Agents