De Cero a Agente Conversacional en Menos de 1 Hora

¿Necesitas lanzar un agente conversacional en producción pero no quieres empezar desde cero? Construir agentes de IA listos para escalar requiere una base sólida: arquitectura limpia, tests automatizados y la posibilidad de cambiar proveedores de LLM sin reescribir el código. py-hexagonal-langgraph es un scaffold open source que combina arquitectura hexagonal, LangGraph y FastAPI para que tengas tu primer agente funcionando en menos de una hora.

¿Qué es py-hexagonal-langgraph?

Es un proyecto en Python 3.11+ que ofrece una estructura profesional desde el primer día. El dominio permanece puro (sin dependencias externas), los nodos de LangGraph se comunican con el mundo exterior a través de puertos inyectados, y la calidad está integrada con Ruff, Mypy y Pytest.

Tecnologías usadas

El scaffold se apoya en Python 3.11+ para aprovechar tipado moderno (Annotated, Protocol) y mejoras de rendimiento. LangGraph aporta grafos de estado para orquestar agentes: StateGraph, AgentState y checkpointer para mantener el historial de conversaciones. LangChain y LangChain-OpenAI se encargan de la integración con los LLMs: mensajes BaseMessage e invocación del modelo.

En la capa de API, FastAPI expone los endpoints /chat y /health con validación automática. Pydantic modela el dominio (DomainMessage, ToolResult), define los schemas de la API y gestiona la configuración con pydantic-settings. La arquitectura hexagonal mantiene el dominio puro mediante puertos (LLMPort, RepositoryPort) y adaptadores inyectables.

Para calidad de código, el proyecto incluye Ruff (linting y formateo), Mypy (verificación de tipos estricta) y Pytest para tests unitarios e integración, usando MockLLMAdapter para evitar consumir tokens en cada ejecución.

Por qué arquitectura hexagonal

• Dominio puro: Los modelos y puertos no dependen de LangChain, OpenAI ni ninguna librería externa.
• Fácil de testear: Los tests usan un MockLLMAdapter que devuelve respuestas fijas, sin consumir tokens.
• Flexible: Cambia OpenAI por Anthropic, Ollama u otro proveedor implementando el mismo LLMPort.

Características principales

• AgentState con Annotated y operator.add para el historial de mensajes.
• Inyección de dependencias en el builder del grafo y en los casos de uso.
• FastAPI con endpoints /chat y /health.
• Prompts desacoplados en archivos .txt cargados por un PromptService.

¿Qué puedes construir con esto?

• Chatbots y asistentes conversacionales: Atención al cliente, soporte interno o FAQs inteligentes. El historial por thread_id permite conversaciones coherentes y contextuales.

• Agentes con herramientas (tools): Extiende el grafo con nodos que llamen APIs externas, bases de datos o motores de búsqueda. El patrón de puertos facilita añadir nuevas capacidades sin contaminar el dominio.

• RAG (Retrieval Augmented Generation): Conecta el RepositoryPort a un vector store para que el agente responda basándose en tus documentos. Ideal para conocimiento interno, manuales o documentación técnica.

• Orquestación de procesos: Diseña flujos con ramas condicionales, aprobaciones humanas o integración con sistemas legacy. LangGraph te permite modelar workflows complejos de forma clara.

• Multi-LLM: Cambia OpenAI por Anthropic, Ollama o modelos locales implementando el mismo LLMPort. El dominio no cambia; solo el adaptador inyectado.

• Integración con frontends: La API FastAPI se conecta fácilmente a React, Vue, apps móviles o cualquier cliente HTTP. Ideal para productos SaaS o dashboards con chat integrado.

Quick Start

git clone https://github.com/sstuardo/py-hexagonal-langgraph.git
cd py-hexagonal-langgraph
pip install -e ".[dev]"
cp .env.example .env
# Añadir OPENAI_API_KEY en .env
uvicorn py_hexagonal_langgraph.infrastructure.api.app:app --reload

Probar el chat:

curl -X POST http://localhost:8000/chat -H "Content-Type: application/json" \
  -d '{"message": "Hola", "thread_id": "test"}'

Conclusión

py-hexagonal-langgraph ofrece una base profesional para construir agentes de IA con arquitectura limpia, tests automatizados y la flexibilidad para escalar y cambiar proveedores según las necesidades del proyecto.

---

¿Quieres implementar agentes de IA con arquitectura limpia? Contáctanos o explora el repositorio en GitHub.