FastAPI Hello Agent

hello-agent/
  app/
    __init__.py
    main.py
    models.py
  requirements.txt
  Dockerfile
  README.md

from enum import Enum
from pydantic import BaseModel, Field


class RefusalCode(str, Enum):
    OUT_OF_SCOPE = "OUT_OF_SCOPE"
    UNAUTHORIZED = "UNAUTHORIZED"


class HelloRequest(BaseModel):
    name: str = Field(..., min_length=1, max_length=200)


class HelloResponse(BaseModel):
    message: str
    version: str = "0.1.0"


class RefusalResponse(BaseModel):
    refused: bool = True
    refusal_code: RefusalCode
    refusal_reason: str

import hmac
import os

from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse

from app.models import HelloRequest, HelloResponse, RefusalCode, RefusalResponse

APP_VERSION = os.getenv("APP_VERSION", "0.1.0")
AGENT_SECRET_KEY = os.getenv("AGENT_SECRET_KEY", "")  # optional

app = FastAPI(
    title="Hello Agent",
    version=APP_VERSION,
)


def verify_agent_secret(request: Request) -> JSONResponse | None:
    """Optional auth: verify X-Agent-Secret header if AGENT_SECRET_KEY is configured."""
    if not AGENT_SECRET_KEY:
        return None

    provided = request.headers.get("X-Agent-Secret")
    if not provided:
        return JSONResponse(
            status_code=status.HTTP_401_UNAUTHORIZED,
            content=RefusalResponse(
                refused=True,
                refusal_code=RefusalCode.UNAUTHORIZED,
                refusal_reason="Missing X-Agent-Secret header",
            ).model_dump(),
        )

    if not hmac.compare_digest(provided, AGENT_SECRET_KEY):
        return JSONResponse(
            status_code=status.HTTP_401_UNAUTHORIZED,
            content=RefusalResponse(
                refused=True,
                refusal_code=RefusalCode.UNAUTHORIZED,
                refusal_reason="Invalid X-Agent-Secret header",
            ).model_dump(),
        )

    return None


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


@app.post("/v1/hello", response_model=HelloResponse | RefusalResponse)
async def hello(request: Request, payload: HelloRequest):
    secret_check = verify_agent_secret(request)
    if secret_check is not None:
        return secret_check

    # Example scope boundary (optional): refuse certain names
    if payload.name.strip().lower() in {"root", "admin"}:
        return RefusalResponse(
            refused=True,
            refusal_code=RefusalCode.OUT_OF_SCOPE,
            refusal_reason="This agent will not greet privileged identities",
        )

    return HelloResponse(message=f"hello {payload.name}", version=APP_VERSION)

fastapi==0.115.6
uvicorn[standard]==0.30.6
pydantic==2.10.6

FROM python:3.11-slim

WORKDIR /app

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

COPY app ./app

ENV PORT=8000
EXPOSE 8000

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

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

curl -s -X POST http://localhost:8000/v1/hello \
  -H 'Content-Type: application/json' \
  -d '{"name":"Sean"}' | jq

export AGENT_SECRET_KEY='supersecret'

curl -s -X POST http://localhost:8000/v1/hello \
  -H 'Content-Type: application/json' \
  -H 'X-Agent-Secret: supersecret' \
  -d '{"name":"Sean"}' | jq