Agente LLM con streaming con fastapi-llm-agent
Construye un backend de chat que transmite los tokens a medida que se
generan y que puede hacer cosas de verdad — llamar a herramientas, leer
sus resultados y seguir adelante. Este tutorial recorre la plantilla
fastapi-llm-agent: el protocolo de eventos SSE, el bucle de llamadas a
herramientas y su límite de iteraciones, la memoria de conversación detrás
de una interfaz y una suite de tests que nunca toca la red.
Qué vas a aprender
- Generar un proyecto con
fastkit startdemo fastapi-llm-agent - Los tipos de eventos SSE que un cliente tiene que manejar y qué significa cada uno
- Cómo funciona, paso a paso, un turno del bucle de llamadas a herramientas
- Añadir tu propia herramienta
- Sustituir el almacén de conversaciones en proceso por uno real
- Por qué los tests son deterministas y gratuitos de ejecutar
Requisitos previos
- Python 3.12+
- FastAPI-fastkit instalado (
pip install fastapi-fastkit) - Una API key de Anthropic — solo para hablar con un modelo real. La suite de tests generada se ejecuta sin ella.
- Familiaridad con
async/awaity con los generadores asíncronos
Paso 1: Generar y configurar
$ fastkit startdemo fastapi-llm-agent
Enter the project name: support-agent
Enter the author name: Developer Kim
Enter the author email: developer@example.com
Enter the project description: Streaming support assistant
Select package manager (pip, uv, pdm, poetry) [uv]: uv
Do you want to proceed with project creation? [y/N]: y
Pon tu clave en .env antes de la primera ejecución:
pydantic-settings lee la clave y se la pasa al cliente al construirlo. Nunca se escribe en el código fuente ni se incrusta en la imagen de Docker.
Usar un gateway en lugar de la API de Anthropic
Define LLM_BASE_URL (y LLM_AUTH_TOKEN si el gateway usa
autenticación bearer) para apuntar a LiteLLM, a un proxy interno o a un
servidor local. El formato de transmisión sigue siendo la Messages API de
Anthropic; traducir para otros proveedores es tarea del gateway, no de
la app.
Paso 2: El árbol generado
support-agent/
├── pyproject.toml # Metadatos PEP 621 + [tool.fastapi-fastkit]
├── requirements.txt
├── Dockerfile
├── .env
├── scripts/
│ ├── chat.sh # envía un mensaje a un servidor en ejecución
│ ├── format.sh lint.sh run-server.sh test.sh
├── src/
│ └── app/
│ ├── main.py # app FastAPI + lifespan
│ ├── core/config.py # pydantic-settings (aquí vive la API key)
│ ├── llm/
│ │ ├── client.py # fábrica de AsyncAnthropic
│ │ ├── tools.py # esquemas de herramientas + handlers
│ │ └── agent.py # agente con streaming + bucle de herramientas
│ ├── memory/
│ │ ├── base.py # interfaz ConversationStore
│ │ └── in_memory.py # implementación local al proceso
│ ├── schemas/chat.py # cuerpos de petición + envoltorio de eventos SSE
│ └── api/
│ ├── router.py # agrega health + chat
│ ├── deps.py # dependencias de store / agente
│ ├── health.py # GET /health
│ └── chat.py # POST /chat (SSE), historial de conversación
└── tests/
├── conftest.py # cliente Anthropic falso con guion
├── test_health.py test_chat.py test_tools.py test_memory.py
Conviene fijarse desde el principio en tres fronteras: el cliente se crea con una fábrica (para que los tests puedan sustituirlo), la memoria es una interfaz con una implementación trivial (para que producción pueda sustituirla) y las herramientas son una lista de esquemas más un diccionario de handlers (para que añadir una solo toque un archivo).
Paso 3: Los endpoints
| Método | Endpoint | Descripción |
|---|---|---|
| GET | /api/v1/health |
Probe de liveness |
| POST | /api/v1/chat |
Transmite una respuesta por SSE |
| GET | /api/v1/conversations/{id} |
Leer el historial guardado |
| DELETE | /api/v1/conversations/{id} |
Olvidar una conversación |
POST /api/v1/chat recibe {"message": "...", "conversation_id": "..."}.
Omite conversation_id para empezar una conversación nueva y lee el id
asignado en el evento final done.
Paso 4: El protocolo de streaming
Cada mensaje SSE lleva su tipo en el campo event: y un envoltorio JSON en
data:. Un cliente tiene que manejar cinco de ellos además de los errores:
| Evento | Campos | Significado |
|---|---|---|
token |
text |
Un fragmento de la respuesta del asistente |
tool_use |
tool_name, tool_input |
Claude ha pedido una herramienta |
tool_result |
tool_name, tool_output |
La herramienta se ha ejecutado |
usage |
input_tokens, output_tokens |
Consumo de tokens por turno |
done |
conversation_id |
El turno ha terminado |
error |
detail |
Algo falló a mitad del stream |
tool_use y tool_result no son decoración — son lo que permite que una
interfaz muestre "buscando…" en lugar de una pausa sin explicación mientras
se ejecuta una herramienta.
El uso de tokens también se escribe en el logger app.agent en cada turno,
así que el consumo es visible en los logs del servidor sin instrumentar un
cliente.
Paso 5: Un turno del bucle
ChatAgent.stream en src/app/llm/agent.py es todo el motor. Un turno
transcurre así:
- Cargar el historial de la conversación desde el store.
- Abrir una petición en streaming con el historial, el nuevo mensaje del usuario y los esquemas de las herramientas.
- Emitir cada fragmento de texto como evento
tokenen cuanto llega. - Cuando termina el stream, leer el mensaje final; emitir un evento
usagey registrar en el log el recuento de tokens. - Si
stop_reason != "tool_use", el asistente ha terminado: guardar el turno, emitirdoney volver. - En caso contrario, para cada bloque
tool_use: emitirtool_use, ejecutar el handler, emitirtool_resulty recoger la salida. - Enviar todos los resultados de herramientas de vuelta en un único
mensaje
user— es lo que exige la Messages API — y repetir desde el paso 2.
El bucle está limitado por MAX_TOOL_ITERATIONS (5 por defecto). Si Claude
sigue pidiendo herramientas más allá del límite, el turno se guarda, se
registra una advertencia y se emite un evento error en lugar de dejar el
servidor dando vueltas:
yield AgentEvent(
type="error",
detail=(
"The assistant exceeded the tool-call limit of "
f"{self._max_tool_iterations} iterations."
),
)
Un límite así no es opcional en un bucle de agente. Sin él, un modelo que malinterpreta el resultado de una herramienta puede generarte costes de forma indefinida.
Paso 6: Las herramientas incluidas
| Herramienta | Propósito |
|---|---|
calculator |
Aritmética, analizada como AST con lista blanca — no eval |
current_time |
Hora actual en una zona horaria IANA |
La calculator merece una segunda mirada. Analiza la expresión con ast y
solo recorre tipos de nodo de una lista blanca, así que un argumento de
herramienta que viene de un modelo no puede ejecutar Python arbitrario.
Cualquier herramienta que acepte entrada generada por el modelo necesita la
misma disciplina: la salida del modelo es entrada no confiable.
Añadir una herramienta
Todo vive en src/app/llm/tools.py:
- Añade un esquema a
TOOL_SCHEMAS—name,descriptiony uninput_schemaen JSON Schema. - Registra el handler en
TOOL_HANDLERScon el mismo nombre.
Dos cosas que hay que hacer bien:
- La descripción es toda la instrucción que recibe Claude sobre cuándo recurrir a la herramienta. Es prompt engineering, no documentación — las descripciones vagas producen herramientas que nunca se llaman o que se llaman constantemente.
- Los handlers deben devolver una cadena y convertir sus propios fallos en un mensaje legible en lugar de lanzar una excepción. El bucle devuelve ese texto directamente al modelo, así que "no city named X was found" permite que el modelo se recupere, mientras que una excepción termina el turno.
Paso 7: Memoria de conversación
ConversationStore (src/app/memory/base.py) es la interfaz; el
in_memory.py incluido la implementa con un diccionario. Eso sirve para un
único proceso y es incorrecto para cualquier otra cosa — un reinicio lo
olvida todo y dos workers discrepan sobre el historial.
Para hacerlo real: implementa la misma interfaz sobre Redis o una base de
datos y devuélvela desde get_store() en src/app/api/deps.py. No cambia
nada en el agente ni en los routers, porque ninguno de los dos nombra nunca
la clase concreta.
Paso 8: Los tests
tests/conftest.py reproduce turnos con guion a través de un objeto falso
que imita AsyncAnthropic.messages.stream. Así, la suite es determinista,
se ejecuta sin conexión, no cuesta nada y aun así cubre los caminos que
importan: el camino de streaming y el bucle completo de herramientas,
incluido un turno en el que se llama a una herramienta y después el modelo
responde.
Este es el patrón que conviene mantener a medida que amplíes el agente. Probar una integración LLM contra el modelo real te da una suite lenta, inestable y cara que, aun así, no puede afirmar lo que dirá el modelo. Probar el bucle contra un cliente con guion afirma exactamente lo que tú escribiste.
Paso 9: Puntos de extensión
- Historial persistente — implementa
ConversationStoresobre Redis o una base de datos (Paso 7). - RAG — la recuperación queda deliberadamente fuera del alcance de la
plantilla. El punto de unión natural es
ChatAgent.stream: obtén el contexto antes de la primera petición y antepónlo al system prompt, o expón tu índice como una herramienta más y deja que el modelo decida cuándo buscar. - Autenticación y rate limiting —
POST /chatviene sin autenticación. Añade una dependencia al router antes de exponerlo públicamente; el tutorial de Autenticación JWT tiene los guards que reutilizarías.
Resumen
- Generación:
fastkit startdemo fastapi-llm-agent, defineANTHROPIC_API_KEY,bash scripts/run-server.sh. - Streaming: SSE con eventos
token/tool_use/tool_result/usage/done/error. - Bucle: stream → llamadas a herramientas → resultados de vuelta en un
único mensaje de usuario → repetir, limitado por
MAX_TOOL_ITERATIONS. - Herramientas: un esquema en
TOOL_SCHEMASy un handler enTOOL_HANDLERS; trata la entrada de las herramientas como no confiable. - Memoria: interfaz
ConversationStore, implementación con diccionario, sustitúyela enget_store(). - Tests: un cliente falso con guion, así que la suite funciona sin conexión y es determinista.
Siguientes pasos
- Integración con MCP — si necesitas un servidor MCP en lugar de un agente de chat.
- Autenticación JWT — poner cuentas delante del endpoint de chat.
- ¿Qué starter elegir?