Servire gli agenti tramite un'API
Avvolga l'agente in FastAPI con autenticazione, convalida delle richieste e streaming tramite SSE o WebSocket.
Servire gli agenti tramite un'API è una lezione AI Agents gratuita su CoddyKit. Questa è la lezione 1 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Agents, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Agents include 4 lezioni in totale.
Parti di questa lezione non sono ancora state tradotte e vengono mostrate in inglese.
Dal notebook al servizio
Un agente funzionante in un notebook è solo l'inizio. Per distribuirlo, lo avvolga in un'API HTTP che altri servizi possano chiamare.
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)Autenticazione
Ogni endpoint dell'agente deve autenticarsi. Utilizzi chiavi API o OAuth, a seconda del tipo di chiamante:
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)):
...Risposte in streaming
Per le interfacce chat, esegua lo streaming dei token con 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')Convalida delle richieste
Pydantic impone i tipi ed esegue la convalida di base. Aggiunga la convalida personalizzata quando necessario:
from pydantic import Field
class AgentRequest(BaseModel):
query: str = Field(min_length=1, max_length=10_000)
user_id: str
options: dict = {}Gestione degli errori
Associare le eccezioni a risposte HTTP chiare:
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)Concorrenza
FastAPI utilizza async come impostazione predefinita. Per gli agenti vincolati dalla CPU (caso raro) o per gli SDK bloccanti, utilizzi i client asincroni:
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']Esegua con più worker
Uvicorn + Gunicorn per la produzione:
gunicorn -k uvicorn.workers.UvicornWorker -w 4 main:appProxy inverso
Metta Nginx o Caddy davanti per TLS, gzip e l'allowlist degli IP.
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 responseCORS for Browser Clients
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=['https://app.example.com'],
allow_methods=['*'], allow_headers=['*']
)Voce della checklist di produzione
Che cosa è essenziale per qualsiasi API di agent in produzione?
Riepilogo
FastAPI + Pydantic + client asincrono + streaming + autenticazione + log strutturati + probe di integrità. Questo è il minimo indispensabile per la produzione.
Domande Frequenti
La lezione «Servire gli agenti tramite un'API» è gratuita?
Sì — il testo completo di «Servire gli agenti tramite un'API» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Agents, passa a CoddyKit PRO. Il corso AI Agents include 4 lezioni in totale.
Cosa imparerò in «Servire gli agenti tramite un'API»?
Avvolga l'agente in FastAPI con autenticazione, convalida delle richieste e streaming tramite SSE o WebSocket. Eserciti AI Agents con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Agents?
Non è richiesta alcuna esperienza precedente. AI Agents su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 1 di 4.
Quanto tempo richiede la lezione «Servire gli agenti tramite un'API»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Agents?
Sì. Ogni lezione AI Agents include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Servire gli agenti tramite un'API
- Workflow asincroni e processi in background
- Limitazione della frequenza e gestione delle quote
- Deploy blue-green e canary per gli agenti