Motor de puerta y giro
El corazón de AiHummer es un único servicio de puerta de enlace. Es al mismo tiempo el plano de control (API de administración, configuraciones, conexión de canales, mercado) y el girar el motor (el bucle de llamada de funciones que produce una respuesta). Por lo tanto, una implementación típica es solo ese servicio más PostgreSQL; no hay un nivel de trabajador separado que se requiera ejecutar.
Un servicio, dos roles
La puerta de enlace escucha en el pública puerto :8780 por defecto, controlado por AIHUMMER_GATEWAY_ADDR — este puerto maneja todo el tráfico externo (API, emparejamiento, WS/SSE, webhooks entrantes, el proxy de la aplicación/bolsillo y sondas de salud). La interfaz web de administración se ejecuta en un separado, privado oyente (predeterminado :8781, AIHUMMER_WEBUI_ADDR), servido en la ruta raíz / y idealmente vinculado a una interfaz solo interna. De cualquier manera, el proceso siempre es el mismo servicio único.
# gateway.env — the only required setting
AIHUMMER_DATABASE_URL=postgres://user:pass@localhost:5432/aihummer?sslmode=disable
# Admin Web UI after start at http://localhost:8781/ (the private Web UI listener)la la única dependencia estricta es PostgreSQL. Postgres es la única fuente de verdad para agentes, configuraciones, conversaciones, memoria, estado de entrega y auditoría. Todo lo demás —servicios opcionales, un almacén vectorial y proveedores de modelos— se integra solo cuando lo configuras.
[!NOTE] Sin una base de datos, la puerta de enlace se inicia en modo solo salud: responde
GET /healthzasí que un orquestador o equilibrador de carga puede ver que el proceso está vivo, pero no servirá para nada.GET /readyzverifica PostgreSQL y devuelve503mientras la base de datos no esté accesible.
Qué sucede al iniciar
Al iniciar, la puerta de enlace realiza algunos pasos en un orden estricto:
- abre el grupo de conexiones de la base de datos,
- aplica cualquier migración pendiente bajo un bloqueo consultivo de Postgres,
- resuelve la configuración (valor de la base de datos → variable de entorno → incorporado) predeterminado), y
- conecta los servicios — enrutador, orquestador, canales, herramientas, memoria, entrega — en una puerta de enlace en funcionamiento.
La consecuencia importante es que la mayoría de las funciones son opcionales mediante una clave de configuración. Una capacidad que no está configurada simplemente no se activa, lo que mantiene el tiempo de ejecución predeterminado pequeño y predecible. Usted activa las cosas desde la interfaz de administración web o con un AIHUMMER_* variable, y la pasarela las resuelve en el próximo inicio (o en caliente, para los mandos que lo soportan).
El motor de giro
Cuando un mensaje llega a la puerta de enlace, el motor de turno se hace cargo. Funciona un bucle de llamadas a funciones: al modelo se le da el aviso del sistema y la conversación, puede llamar a herramientas (o generar sub-agentes), cada resultado de herramienta se retroalimenta, y el ciclo continúa hasta que el modelo produce una respuesta final. Esa respuesta luego se entrega a la capa de entrega.
inbound message
└─▶ turn engine
├─ assemble layered system prompt
├─ call model ──▶ tool calls / sub-agents ──▶ tool results ─┐
│ ▲ │
│ └────────────────────────────────────────────────-─┘
└─ final answer ─▶ reliable delivery ─▶ originating channelDebido a que el bucle es determinista respecto a de dónde proviene cada entrada, las respuestas se resuelven a partir del historial de la conversación y de los resultados de las herramientas, nunca mediante la inyección de texto no confiable en las instrucciones. Esa propiedad es lo que hace que la capa de prompts a continuación sea segura y rápida.
El aviso del sistema por capas y amigable con la caché
El aviso del sistema no es un solo bloque. Se ensambla en capas, ordenadas deliberadamente de manera que el las partes estables vienen primero y las partes volátiles vienen al final. Esto es importante porque los proveedores de modelos almacenan en caché un prompt por su prefijo: mientras el inicio del prompt sea idéntico byte por byte, se reutiliza el prefijo en caché y solo se vuelve a procesar la parte final.
| Zona | Capas (en orden) | Cambios… |
|---|---|---|
| Prefijo estable (cacheable) | identidad base + guía de herramienta/memoria → inquilino → persona → habilidades | raramente — por agente/inquilino |
| Cola volátil (adjunto al final) | estado de incorporación → hidratación de memoria → la fecha en vivo | cada giro |
El prefijo estable contiene todo lo que define quién es el agente: la identidad incorporada y la guía de cómo funcionan las herramientas y la memoria, luego la capa de inquilino, la persona del agente y el bloque de habilidades renderizado. Nada de eso cambia entre dos turnos consecutivos del mismo agente, por lo que forma un prefijo en caché reutilizable.
La cola volátil se adjunta después el prefijo estable precisamente para que nunca invalide la caché: el estado de incorporación, la memoria hidratada para esta conversación específica y la fecha actual cambian turno a turno, pero debido a que se encuentran al final solo cuestan lo que agregan.
[!TIP] Este ordenamiento es la razón por la cual pueden estar presentes datos en vivo, como la fecha de hoy, en cada turno sin pagar para volver a codificar toda la identidad cada vez. Mantener contenido personalizado por agente en las capas estables (personalidad, habilidades) y dejar que el el motor posee la cola volátil.
¿A dónde vamos ahora?
- Ve cómo los inquilinos están aislados en Multialojamiento e idempotencia.
- Aprende cómo se devuelven las respuestas en Entrega y recuperación confiables.
- Las capacidades opcionales se ejecutan como Sidecares.