Disponibilizando agentes por trás de uma API
Envolva seu agente no FastAPI com autenticação, validação de solicitações e transmissão por SSE ou WebSockets.
Disponibilizando agentes por trás de uma API é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
Partes desta aula ainda não foram traduzidas e aparecem em inglês.
Do notebook ao serviço
Um agente funcionando em um notebook é apenas o começo. Para lançá-lo, envolva-o em uma API HTTP que outros serviços possam chamar.
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)Autenticação
Cada endpoint do agente deve autenticar as solicitações. Use chaves de API ou OAuth, dependendo do tipo de chamador:
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)):
...Respostas transmitidas em fluxo
Para interfaces de bate-papo, transmita tokens com 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')Validação de solicitações
O Pydantic impõe tipos e validações básicas. Adicione validações personalizadas conforme necessário:
from pydantic import Field
class AgentRequest(BaseModel):
query: str = Field(min_length=1, max_length=10_000)
user_id: str
options: dict = {}Tratamento de erros
Mapeie exceções para respostas HTTP claras:
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)Concorrência
O FastAPI usa operações assíncronas por padrão. Para agentes limitados pela CPU (raros) ou SDKs bloqueantes, use os clientes assíncronos:
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']Execute com vários processos de trabalho
Uvicorn + Gunicorn para produção:
gunicorn -k uvicorn.workers.UvicornWorker -w 4 main:appProxy reverso
Coloque Nginx ou Caddy na frente para TLS, gzip e criação de uma lista de permissões de 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=['*']
)Item da Lista de Verificação de Produção
O que é essencial para qualquer API de agente em produção?
Recapitulação
FastAPI + Pydantic + cliente assíncrono + transmissão contínua + autenticação + registros estruturados + sondas de integridade. Essa é a base mínima para produção.
Perguntas Frequentes
A aula “Disponibilizando agentes por trás de uma API” é grátis?
Sim — o texto completo de “Disponibilizando agentes por trás de uma API” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Disponibilizando agentes por trás de uma API”?
Envolva seu agente no FastAPI com autenticação, validação de solicitações e transmissão por SSE ou WebSockets. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.
Quanto tempo leva a aula “Disponibilizando agentes por trás de uma API”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Disponibilizando agentes por trás de uma API
- Fluxos de trabalho assíncronos e tarefas em segundo plano
- Limitação de taxa e gerenciamento de cotas
- Implantações blue-green e canário para agentes