La parte 6 puso required_scopes=[\"mcp:invoke\"] en el\nverificador de JWT y dio por autorizado el servidor. Lo está, en el sentido de que quien llama\nsin autenticarse no obtiene nada. No lo está, en el sentido que importa: mcp:invoke abre todas\nlas herramientas del servidor. El mismo token que deja a un agente ejecutar find_customer le\ndeja ejecutar issue_refund.
Ese es todo el hueco. Un agente de solo lectura y un agente que emite reembolsos tienen\ncredenciales idénticas, y lo único que se interpone entre \"busca a Maria\" y \"reembolsa la factura\n2\" es que nadie lo pidió.
\nEste post lo cierra, primero mal y luego bien, porque el \"mal\" es lo que la mayoría despliega y la\ndiferencia solo se nota en lo que el cliente puede hacer ante un rechazo.
\nAmbas versiones rechazan la misma llamada — un token de solo lectura pidiendo issue_refund. Se\ndiferencian en dónde se comprueba el ámbito, y esa única decisión determina lo que recibe el\ncliente:
Las partes 5 y 6, en concreto:
\nagent-tools\n(parte 5)~/mcp-auth/token.sh, que recibe una cadena de ámbitos y devuelve un token de accesoEl servidor de la parte 6 se queda en :8770 todo el rato. Las dos versiones de abajo corren en\n:8771 y :8772 para que puedas comparar las tres sin parar nada.
Los ámbitos son Property Mappings en Authentik. Customization → Property Mappings → New Property\nMapping → Scope Mapping, dos veces:
\n| Nombre | Nombre del ámbito | Descripción |
|---|---|---|
office-read | office:read | Consultar clientes y facturas |
office-refund | office:refund | Emitir reembolsos |
![\"Dos](\"https://development-wec.wiline.com/docs/es/assets/images/h10-scope-mappings-c80d52648d4347ac31467ecd7bfbc924.png\")
Crearlos no basta. Un proveedor solo emitirá un ámbito que se le haya asignado, así que abre\nApplications → Providers → agent-tools → Edit y mueve ambos a Selected Scopes.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h10-provider-scopes-845343ec44444c00ad1c5931086ff83c.png\")
Fíjate en la línea bajo el selector: \"Select which scopes can be used by the client. The client\nstill has to specify the scope to access the data.\" Las dos mitades importan. Seleccionar un\námbito aquí no lo mete en todos los tokens — permite que el cliente lo pida. Un cliente que no pide\nnada no obtiene nada, y por eso cada llamada a token.sh de abajo pasa una cadena de ámbitos\nexplícita.
Confirma que el token lleva de verdad lo que pediste:
\n~/mcp-auth/token.sh \"mcp:invoke office:read\" \\
| cut -d. -f2 | base64 -d 2>/dev/null | jq .scope
\"mcp:invoke office:read\"
Si eso vuelve sin office:read, el ámbito no está en el proveedor — arréglalo antes de escribir\nuna línea de código de servidor, o te pasarás una hora depurando una aplicación de permisos que\nfunciona perfectamente sobre un token al que nunca se le asignó el ámbito.
Mantén required_scopes=[\"mcp:invoke\"] en el verificador como precio de entrada, y luego pregunta\npor herramienta si quien llama tiene lo que esa operación necesita. FastMCP expone el token ya\nverificado a través de get_access_token(), así que un decorador puede leer los claims que el\nverificador ya comprobó:
from fastmcp.exceptions import ToolError
from fastmcp.server.dependencies import get_access_token
def requires(scope: str):
def decorate(fn):
@functools.wraps(fn)
async def wrapper(*args, **kwargs):
token = get_access_token()
held = set(getattr(token, \"scopes\", None) or [])
if scope not in held:
raise ToolError(
f'insufficient_scope: this tool requires \"{scope}\"; '
f'token carries {sorted(held) or \"nothing\"}'
)
return await fn(*args, **kwargs)
return wrapper
return decorate
Y luego una línea por herramienta:
\n@mcp.tool
@requires(\"office:read\")
async def find_customer(query: str) -> list[dict]: ...
@mcp.tool
@requires(\"office:refund\")
async def issue_refund(invoice_id: int) -> str: ...
Lánzalo en :8771 y prueba ambas herramientas con ambos tokens:
![\"Dos](\"https://development-wec.wiline.com/docs/es/assets/images/h10-per-tool-enforcement-36365bd959bc324dd447cfdbe681525c.png\")
--- token: mcp:invoke + office:read ---
find_customer : ALLOWED -> [{'id': 1, 'name': 'Maria Alvarez', ...}]
issue_refund : REFUSED -> insufficient_scope: this tool requires \"office:refund\"
--- token: mcp:invoke + office:refund ---
find_customer : REFUSED -> insufficient_scope: this tool requires \"office:read\"
issue_refund : ALLOWED -> Refunded 80.00 on invoice 2.
Eso es aplicación real de permisos. El token de reembolso no puede leer, el de lectura no puede\nreembolsar, y el rechazo nombra el ámbito que falta. Para muchos despliegues, aquí es donde se\npara.
\nMira la capa HTTP en lugar de la librería cliente.
\nTOK=$(~/mcp-auth/token.sh \"mcp:invoke office:read\")
curl -sS -i -X POST http://127.0.0.1:8771/mcp \\
-H \"Authorization: Bearer $TOK\" \\
-H \"Content-Type: application/json\" \\
-H \"Accept: application/json, text/event-stream\" \\
-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"issue_refund\",\"arguments\":{\"invoice_id\":2}}}'
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h10-200-no-challenge-ec64c16f2444a9ed7bcacaed0d917f3e.png\")
HTTP/1.1 200 OK
content-type: text/event-stream
data: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"content\":[{\"text\":\"insufficient_scope: this tool
requires \\\"office:refund\\\"; token carries ['mcp:invoke', 'office:read']\",\"type\":\"text\"},
\"isError\":true}}
HTTP 200. La petición tuvo éxito; la que declinó fue la herramienta. Esa es la semántica\ncorrecta de JSON-RPC y es inútil para un cliente OAuth.
\nUn cliente OAuth que quiere escalar — volver al servidor de autorización y pedir office:refund —\nestá atento a un 401 o 403 con una cabecera WWW-Authenticate que le diga qué solicitar. No\nse pone a extraer inglés de un resultado de herramienta. Así que el rechazo es legible para un\nhumano que lee logs e invisible para la maquinaria diseñada para manejar justo este caso.
Y además llega tarde. El cuerpo de la herramienta corre después del enrutado, después de montar la\nsesión, después de que el servidor se ha comprometido a una respuesta con éxito. Para entonces ya\nno queda línea de estado que cambiar.
\nConseguir un 403 significa comprobar los ámbitos antes de que responda la capa JSON-RPC, lo\nque significa un middleware ASGI envolviendo la app de FastMCP:
class ScopeChallengeMiddleware:
def __init__(self, app):
self.app = app
async def __call__(self, scope, receive, send):
if scope[\"type\"] != \"http\" or scope[\"method\"] != \"POST\":
return await self.app(scope, receive, send)
# Buffer the body so we can inspect it and still pass it on.
chunks, more = [], True
while more:
msg = await receive()
chunks.append(msg.get(\"body\", b\"\"))
more = msg.get(\"more_body\", False)
body = b\"\".join(chunks)
needed = None
try:
rpc = json.loads(body)
if rpc.get(\"method\") == \"tools/call\":
needed = TOOL_SCOPES.get((rpc.get(\"params\") or {}).get(\"name\"))
except Exception:
pass
if needed and needed not in token_scopes(dict(scope.get(\"headers\") or [])):
challenge = (
f'Bearer error=\"insufficient_scope\", scope=\"{needed}\", '
f'resource_metadata=\"{RESOURCE_METADATA}\", '
f'error_description=\"This operation requires the {needed} scope\"'
)
await send({\"type\": \"http.response.start\", \"status\": 403,
\"headers\": [(b\"content-type\", b\"application/json\"),
(b\"www-authenticate\", challenge.encode())]})
await send({\"type\": \"http.response.body\",
\"body\": json.dumps({\"error\": \"insufficient_scope\",
\"scope\": needed}).encode()})
return
# Replay the buffered body downstream.
replayed = False
async def replay():
nonlocal replayed
if not replayed:
replayed = True
return {\"type\": \"http.request\", \"body\": body, \"more_body\": False}
return await receive()
await self.app(scope, replay, send)
app = ScopeChallengeMiddleware(mcp.http_app(stateless_http=True))
La misma petición, contra :8772:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h10-403-challenge-2a8d3ff52be96195ff042471605c0c4e.png\")
HTTP/1.1 403 Forbidden
www-authenticate: Bearer error=\"insufficient_scope\", scope=\"office:refund\",
resource_metadata=\"http://127.0.0.1:8772/.well-known/oauth-protected-resource\",
error_description=\"This operation requires the office:refund scope\"
Ahora el cliente tiene algo sobre lo que actuar: el estado dice rechazado, scope= dice qué\npedir, y resource_metadata dice dónde averiguar cómo. Eso es autorización escalada como\nprotocolo, no como mensaje de log.
El middleware funciona. También es peor código que el decorador, de tres formas concretas, y\nfingir lo contrario sería deshonesto.
\nNo sabe qué es una herramienta. El middleware ASGI ve bytes y cabeceras. Para averiguar qué\nherramienta se está llamando, parsea él mismo el sobre JSON-RPC y busca el nombre en una tabla que\ntiene que mantener:
\nTOOL_SCOPES = {
\"find_customer\": \"office:read\",
\"open_invoices\": \"office:read\",
\"issue_refund\": \"office:refund\",
}
Esa tabla es una segunda fuente de verdad. Añade una herramienta y olvida la entrada y queda sin\nproteger — en silencio, porque el middleware simplemente deja pasar cualquier cosa que no\nreconoce. El decorador no podía tener ese fallo: el requisito estaba sobre la función.
\nDecodifica el token sin verificarlo. El middleware corre antes del verificador, así que los\nclaims verificados todavía no existen. Parte el JWT y decodifica en base64 el payload sin\ncomprobar la firma:
\npayload = auth.split(None, 1)[1].split(\".\")[1]
claims = json.loads(base64.urlsafe_b64decode(payload + \"=\" * (-len(payload) % 4)))
Esto no es el agujero que parece — el verificador sigue corriendo después y sigue rechazando un\ntoken falsificado, así que nada llega a una herramienta con una firma mala. Pero la decisión de\námbito se toma sobre bytes no autenticados, y la única razón por la que eso es sobrevivible es la\nsegunda comprobación detrás. Es una verruga, no una vulnerabilidad, y es de esas cosas que vale la\npena dejar escritas antes de que alguien más tarde quite el verificador \"redundante\".
\nAlmacena en memoria cada cuerpo de petición. Para leer el sobre y aun así pasarlo hacia abajo,\nel middleware vacía receive() en memoria y lo reproduce. Bien para llamadas JSON-RPC; piénsalo\nmejor antes de poner esto delante de subidas grandes.
insufficient_scope en una herramienta que sí concedisteRevisa el token, no el servidor:
\n~/mcp-auth/token.sh \"mcp:invoke office:refund\" | cut -d. -f2 | base64 -d 2>/dev/null | jq .scope
Si falta office:refund, el ámbito existe como Property Mapping pero nunca se movió a los\nSelected Scopes del proveedor. Authentik descarta en silencio los ámbitos que un cliente no\ntiene permitido solicitar en lugar de dar error, así que el token vuelve válido y corto.
Solo inspecciona POST. Los clientes MCP abren primero un GET para el flujo de eventos, y esa\npetición no lleva sobre JSON-RPC — si estás mirando la petición equivocada concluirás que el\nmiddleware está muerto. Confírmalo con el curl de arriba, que es un único POST.
TOOL_SCOPES está indexado por el nombre registrado de la herramienta, que es el nombre de la\nfunción, no la etiqueta decorada. Renombra una función y la tabla deja de coincidir. El caso de\npaso libre es la dirección peligrosa (sin proteger), pero un error tipográfico en la tabla produce\neste otro.
El desafío vive en la cabecera WWW-Authenticate. Los clientes que solo registran el cuerpo\nde la respuesta te mostrarán {\"error\":\"insufficient_scope\"} y nada sobre qué ámbito. Usa\ncurl -i.
Te dio autorización por herramienta de verdad: dos tokens que se diferencian en un ámbito,\ncada uno capaz de ejecutar exactamente una de dos herramientas, demostrado en la capa HTTP en\nlugar de afirmado. Y con el middleware, un rechazo del que un cliente puede recuperarse de forma\nprogramática.
\nNo te dio un diseño limpio. Ambas implementaciones son concesiones que apuntan en direcciones\nopuestas:
\ndecorador de herramienta (:8771) | middleware ASGI (:8772) | |
|---|---|---|
| El requisito de ámbito vive | en la función | en una tabla aparte |
| Lee claims verificados | sí | no — decodifica sin verificar, el verificador corre después |
| Rechazo | HTTP 200, isError: true | HTTP 403 + WWW-Authenticate |
| El cliente puede escalar | no | sí |
| Herramienta nueva sin proteger por defecto | no | sí |
El resumen honesto es que el comportamiento correcto del protocolo requiere salir de la\nabstracción que te da el framework, y la versión ergonómica no puede producirlo. Si tus clientes\nno implementan escalado — y la mayoría de los clientes de agentes hoy no lo hacen — el decorador es\nel mejor trato. Si lo hacen, lo pagas con una tabla que tienes que acordarte de actualizar.
\nTampoco te dio una autorización que sobreviva a que la herramienta haga otra cosa.\nissue_refund está protegido por office:refund; nada impide que un futuro find_customer se\nedite para escribir. Los ámbitos controlan la entrada, no el comportamiento — que es el mismo\nlímite que la parte 4 trazó alrededor de la\npolítica-en-la-herramienta.
El hueco evidente que queda es que ambas versiones confían en la lista de ámbitos del token y en\nnada más. Ninguna pregunta quién es quien llama ni sobre qué está actuando — un token con\noffice:refund reembolsa cualquier factura, de cualquier cliente, por cualquier importe. Eso es\nautorización a nivel de objeto, y no vive en los ámbitos de OAuth en absoluto.
WWW-Authenticate challengeTodas las partes de esta serie hasta ahora le han dado al modelo herramientas: funciones que\nescribiste tú, con argumentos que definiste tú. Este post va sobre la otra cosa que hacen los\nagentes, que es escribir código y después ejecutarlo.
\nEs un riesgo distinto, y vale la pena ser preciso sobre la diferencia. Una llamada a herramienta\nes el modelo eligiendo de un menú que tú controlas. Ejecutar código generado es el modelo\npasándote algo que nadie ha leído nunca, y que tú ejecutas en tu máquina.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB de RAM, Ubuntu 22.04, kernel 5.15, systemd 249.\nDocker rootless 29.8.1 de la Parte 8, corriendo\njunto al demonio del sistema. La imagen de prueba es python:3.12-alpine. El host mantuvo 20\ncontenedores en marcha durante todo el proceso.
Todas las cifras y mensajes de error de abajo provienen de esa ejecución.
La industria tiene un nombre para esto. El riesgo\nLLM05:2025 Improper Output Handling\nde OWASP lo lista como ejemplo de vulnerabilidad, con estas palabras:
\n\n\nLLM output is entered directly into a system shell or similar function such as exec or eval,\nresulting in remote code execution.
\n
Y su consejo sobre cómo pensar en el modelo es exactamente el correcto:
\n\n\nTreat the model as any other user, adopting a zero-trust approach
\n
Pero aquí está lo que hace que esa página merezca una lectura atenta. Te dice que trates la\nsalida del modelo como no confiable, nombra la ejecución de código como la consecuencia, y\ndespués su sección de prevención habla únicamente de validar texto: codificación de salida,\nconsultas parametrizadas, políticas de seguridad de contenido, monitoreo.
\nBusca en esa página sandbox, container, least privilege o isolation y obtienes\ncero resultados. No pocos. Ninguno.
\nNo es una crítica a OWASP; el riesgo trata sobre el manejo de la salida, y validar es la\nrespuesta correcta para una salida que se convierte en HTML o SQL. Pero cuando la salida es un\nprograma que estás a punto de ejecutar, validar deja de ser posible. No puedes averiguar con una\nexpresión regular si cien líneas de Python son seguras.
\nAsí que la guía nombra el problema y se detiene una capa por encima del arreglo. Este post es esa\ncapa.
\nLa implementación ingenua es la que casi todo el mundo despliega primero, y parece responsable\n— al fin y al cabo el código corre en un contenedor:
\ndocker -c rootless run --rm python:3.12-alpine python -c \"<el código del modelo>\"
Preguntémosle a ese contenedor hasta dónde llega.
\ndocker -c rootless run --rm python:3.12-alpine python -c \"
import os, urllib.request
print('uid inside :', os.getuid())
print('can see host / :', sorted(os.listdir('/'))[:10])
try:
r = urllib.request.urlopen('https://api.github.com', timeout=5)
print('internet : REACHED', r.status)
except Exception as e:
print('internet : blocked', type(e).__name__)
\"
docker -c rootless run --rm python:3.12-alpine sh -c '
echo \"memory limit : $(cat /sys/fs/cgroup/memory.max)\"
echo \"pids limit : $(cat /sys/fs/cgroup/pids.max)\"
echo \"cpus visible : $(nproc)\"
echo \"writable fs : $(touch /proc-test 2>/dev/null && echo yes || echo no)\"
'
![\"Un](\"https://development-wec.wiline.com/docs/es/assets/images/h9-naive-sandbox-06b5b3907235d86115ef158babda8df0.png\")
internet : REACHED 200
memory limit : max
pids limit : 19136
cpus visible : 8
writable fs : yes
Léelo como la lista de lo que el código generado tiene permitido hacer en tu máquina:
\nmax significa sin límite. En este host son 15 GB, y el\nkernel empezará a matar otras cosas para proporcionarlos.La Parte 8 sacó al demonio de root, así que este código ya no puede quedarse con el host.\nAquello valía la pena y aquí no ayuda en absoluto. Ninguno de los cinco puntos de arriba requiere\nser root.
\nDocker tiene flags para cada uno de estos. No son vistosas y son el arreglo entero:
\ndocker -c rootless run --rm \\
--network none --memory 256m --pids-limit 64 --cpus 0.5 \\
--read-only --tmpfs /tmp:size=16m \\
--cap-drop=ALL --security-opt no-new-privileges \\
python:3.12-alpine <comando>
En palabras llanas:
\n| Flag | Qué impide |
|---|---|
--network none | Sin red en absoluto — no se puede enviar nada a ninguna parte |
--memory 256m | Si usa más de 256 MB, el kernel lo mata a él, no a tus otros servicios |
--pids-limit 64 | Una bomba fork llega a 64 y se para |
--cpus 0.5 | Un bucle infinito se queda con medio núcleo |
--read-only | No se puede escribir nada en el sistema de archivos del contenedor |
--tmpfs /tmp:size=16m | Salvo un área pequeña de trabajo, limitada y en memoria |
--cap-drop=ALL | Sin privilegios de kernel — nada de montar, ni sockets crudos, nada |
--security-opt no-new-privileges | Nada de dentro puede ganar más privilegios de los que tenía |
Ejecútalo, y falla antes incluso de arrancar el contenedor:
\n![\"Docker](\"https://development-wec.wiline.com/docs/es/assets/images/h9-cpus-refused-0a8c67fa115c08d21d53054814b86f30.png\")
docker: Error response from daemon: NanoCPUs can not be set, as your kernel does not
support CPU CFS scheduler or the cgroup is not mounted
Retén ese mensaje, porque induce a error. El kernel soporta límites de CPU perfectamente — este\nhost ejecuta otros 20 contenedores con ellos disponibles. Volveremos a qué está mal de verdad.
\nQuita --cpus y todo lo demás se aplica:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h9-hardened-holds-e5ed1f26eadb61b1c097d1438eae1520.png\")
memory limit : 268435456 <- exactamente 256 MiB
pids limit : 64
cpus visible : 8
writable fs : no
tmp writable : yes
internet : blocked URLError
Cinco de seis controles funcionando. Y cpus visible: 8, porque no nos dejaron poner uno.
Un límite de CPU que falta suena leve al lado de \"memoria sin límite\". No lo es, porque un bucle\ninfinito es lo más probable que hace el código generado sin querer.
\nEsto lanza ocho bucles ocupados dentro del sandbox por lo demás completamente cerrado, durante\nocho segundos:
\ndocker -c rootless run -d --name burn \\
--network none --memory 256m --pids-limit 64 \\
--read-only --tmpfs /tmp:size=16m \\
--cap-drop=ALL --security-opt no-new-privileges \\
python:3.12-alpine sh -c 'for i in $(seq 8); do (while :; do :; done) & done; sleep 8'
sleep 3
docker -c rootless stats --no-stream burn
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/h9-burn-605-a829703726df3283acc0afa12d391696.png\")
NAME CPU % MEM USAGE / LIMIT NET I/O PIDS
burn 605.19% 1.23MiB / 256MiB 0B / 0B 9
605% de una CPU. Seis de los ocho núcleos del host, tomados por código dentro de un sandbox\ndonde la memoria está limitada a 256 MB (usó 1,23), los procesos a 64 (usó 9) y la red está\ncompletamente bloqueada.
\nTodos los controles que pusimos funcionan. El único que no pudimos poner es el que se está\nabusando.
\nEl mensaje de error culpaba al kernel. El kernel está bien. La respuesta real es un archivo.
\nCuando Docker corre en modo rootless no gestiona recursos directamente: solo puede usar lo que el\nsistema le haya entregado a tu cuenta de usuario. En Linux moderno esa entrega se llama\ndelegación de cgroups, y quien decide qué se delega es systemd.
\ncat /sys/fs/cgroup/user.slice/user-1000.slice/cgroup.controllers
memory pids
Dos cosas. Esa es la explicación entera:
\n\nEl demonio lo sabía desde el principio. Lo dijo al arrancar, diez veces, en líneas que nadie lee:
\njournalctl --user -u docker.service | grep -i \"no .* support\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h9-delegation-root-cause-801bd67d214cce22c58da71540cddebb.png\")
WARNING: No cpu cfs quota support
WARNING: No cpu cfs period support
WARNING: No cpu shares support
WARNING: No cpuset support
WARNING: No io.weight support
WARNING: No io.max (rbps) support
...
Esto también explica algo que la Parte 8 reportó como\nuna limitación sin más del modo rootless: que los límites de rendimiento de disco no funcionan.\nMisma causa. No es una propiedad de rootless, sino de lo que systemd delegó.
\nNo en la documentación rootless de Docker. Busqué en la página: cero apariciones de\n\"delegate\". La guía está río arriba, en el\nsitio de rootless containers, que\nlo dice directamente:
\n\n\nBy default, a non-root user can only get memory controller and pids controller to be delegated.
\n
Un archivo drop-in que le dice a systemd que entregue más:
\nsudo mkdir -p /etc/systemd/system/user@.service.d
cat <<EOF | sudo tee /etc/systemd/system/user@.service.d/delegate.conf
[Service]
Delegate=cpu cpuset io memory pids
EOF
sudo systemctl daemon-reload
La misma página advierte:
\n\n\nAfter changing the systemd configuration, you need to re-login or reboot the host. Rebooting\nthe host is recommended.
\n
Con systemd 249 resultó no hacer falta. Solo con daemon-reload:
cat /sys/fs/cgroup/user.slice/user-1000.slice/cgroup.controllers
cpuset cpu io memory pids
El demonio sí hay que reiniciarlo, porque lee sus capacidades una sola vez al arrancar. Reinicia\nsolo el demonio rootless, no toda tu sesión de usuario, que en este host habría tumbado\nademás un servicio sin relación:
\nsystemctl --user restart docker.service
journalctl --user -u docker.service --since \"-1min\" | grep -ci \"no cpu\\|no io\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h9-delegate-fix-1f7414c6361fa1fc13be57138940d1f5.png\")
0
Cero advertencias, donde había diez.
\nComando idéntico al anterior. Una flag añadida:
\ndocker -c rootless run -d --name burn2 \\
--network none --memory 256m --pids-limit 64 --cpus 0.5 \\
--read-only --tmpfs /tmp:size=16m \\
--cap-drop=ALL --security-opt no-new-privileges \\
python:3.12-alpine sh -c 'for i in $(seq 8); do (while :; do :; done) & done; sleep 8'
sleep 3
docker -c rootless stats --no-stream burn2
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/h9-burn-capped-7dff3d60a38ee6b89cb8667301faea0f.png\")
NAME CPU % MEM USAGE / LIMIT NET I/O PIDS
burn2 52.82% 1.242MiB / 256MiB 0B / 0B 9
605,19% → 52,82%. Los mismos ocho bucles infinitos, la misma imagen, todo igual. Medio\nnúcleo, como se pidió.
\nUn contenedor no es un sandbox hasta que dices qué puede usar. El valor por defecto es\ngeneroso en todas las dimensiones que importan, y nada te avisa, porque un contenedor sin\nrestricciones es algo completamente normal de ejecutar.
\nComprueba que tus límites se aplican, en lugar de darlo por hecho. Todo este post existe\nporque una flag que estaba silenciosamente no disponible se veía idéntica a una flag que\nfuncionaba. docker stats bajo una carga deliberada tarda un minuto y te dice la verdad.
Los mensajes de error apuntan a la capa equivocada. \"your kernel does not support CPU CFS\nscheduler\" describía un kernel que lo soporta perfectamente. La causa real era un valor por\ndefecto de systemd, dos capas más allá, documentado en otra web.
\nY el límite honesto: este sandbox contiene recursos. No vuelve seguro el código. No sabe\ndistinguir un script útil de uno hostil, y un programa que haga algo dañino dentro de 256 MB,\nmedio núcleo y sin red se ejecutará exactamente como está escrito. La contención te compra un\nradio de daño, no un criterio.
\nsystemd.resource-control(5) — Delegate=Esta es la parte que nadie dice en voz alta cuando te recomiendan añadirte al grupo docker\npara dejar de escribir sudo.
Ese grupo es root. No \"casi root\", ni \"root para cosas de Docker\". Si puedes ejecutar un\ncontenedor, puedes leer, modificar o borrar cualquier archivo de la máquina — incluido el\narchivo de contraseñas, los directorios personales de otras personas y los archivos que el\nadministrador apartó deliberadamente de ti.
\nNo hace falta ningún exploit. Es un comando, y tarda unos cuatro segundos.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB de RAM, Ubuntu 22.04, kernel 5.15. El demonio del\nsistema es el docker.io de Ubuntu 29.1.3; el demonio rootless instalado aquí es 29.8.1\ncon rootlesskit 3.1.0. La imagen de prueba es alpine:3.20. El host mantuvo 20 contenedores\nen marcha bajo el demonio del sistema durante todo el proceso, y ninguno se detuvo.
Todas las salidas y tiempos de abajo provienen de esa ejecución.
Ejecuta esto como usuario normal. No hay ningún sudo dentro.
docker run --rm -v /:/host alpine:3.20 \\
sh -c 'touch /host/root/rootless-demo && echo WROTE as uid $(id -u)'
sudo ls -l /root/rootless-demo
![\"Un](\"https://development-wec.wiline.com/docs/es/assets/images/h8-docker-group-is-root-8007f44ffccf255e2de1e18d9bf1ca00.png\")
WROTE as uid 0
-rw-r--r-- 1 root root 0 Sep 16 20:58 /root/rootless-demo
Un usuario que ni siquiera puede listar /root acaba de crear un archivo dentro, propiedad de\nroot.
Nada falló. Eso es el diseño. El demonio corre como root, le pediste montar el sistema de\narchivos completo, y lo hizo — porque un proceso root tiene permiso para ello. El \"root\" del\ncontenedor y el root del host son la misma cosa.
\nDocker lo documenta con claridad, y conviene leer sus palabras antes que las mías. De\nDocker daemon attack surface:
\n\n\nonly trusted users should be allowed to control your Docker daemon
\n
y, en la misma página:
\n\n\nDocker allows you to share a directory between the Docker host and a guest container; and it\nallows you to do so without limiting the access rights of the container.
\n
Eso no es una advertencia sobre un fallo. Es la descripción de la función que acabamos de usar.
\nLímpialo antes de seguir:
\nsudo rm -f /root/rootless-demo
Un agente de IA que ejecuta código que él mismo generó es, en términos de seguridad, ejecución\nremota de código que instalaste a propósito. No es una crítica a los agentes — es para lo que\nsirven.
\nAsí que la pregunta deja de ser \"¿podría un atacante ejecutar código aquí?\" — algo ya lo hace,\nconstantemente — y pasa a ser \"¿hasta dónde llega ese código?\".
\nSi llega al socket de Docker, la respuesta es \"a todo\", mediante el comando de arriba. Tus\nclaves de API. Tus claves SSH. El volumen de la base de datos. Todo, por muy cuidadosamente\nque hayas configurado el contenedor del propio agente.
\nLa Parte 2 encontró dos de seis contenedores\nde Langfuse corriendo como root y los arregló con user: \"999:999\". Aquello valía la pena y\nsigue valiéndola.
Pero cambia quién es el proceso dentro del contenedor. El demonio que lo arranca sigue\nsiendo root, y el socket sigue siendo una puerta a toda la máquina. La Parte 2 endureció al\npasajero. Este post va a por el conductor.
\nEl demonio deja de correr como root y corre como tú.
\nLos contenedores siguen creyendo que tienen root — el software de dentro sigue funcionando con\nnormalidad. Pero ese \"root\" ahora lo traduce el kernel a una cuenta ordinaria y sin privilegios\nque no posee nada importante. Si algo se escapa del contenedor, no es el administrador. Es\nubuntu.
La traducción usa un bloque de IDs de usuario que el sistema reservó para ti. Aquí está la idea\ncompleta en una imagen — el mismo contenedor, bajo cada demonio:
\n\nLa mitad izquierda es por qué funcionó el primer comando. La derecha es lo que vamos a montar, y\nsu aritmética es algo que puedes verificar tú en un minuto.
\nEsta traducción es una función del kernel de Linux llamada\nespacio de nombres de usuario,\nno un invento de Docker — Docker solo se lo pide al kernel. El bloque de IDs al que mapea se\ndeclara en /etc/subuid:
grep '^ubuntu:' /etc/subuid /etc/subgid
/etc/subuid:ubuntu:100000:65536
/etc/subgid:ubuntu:100000:65536
65.536 IDs a partir de 100000, solo tuyos. Retén ese número — el mapeo se convierte en\naritmética comprobable dentro de un momento.
\nLa documentación asume una instalación que esta máquina no tiene. Aquí está cada muro en el\norden en que te lo encuentras.
\nTodas las guías empiezan con la misma línea. Con el Docker de Ubuntu:
\nsudo apt-get install -y docker-ce-rootless-extras
dpkg -L docker.io | grep -iE 'rootless|rootlesskit'
![\"apt](\"https://development-wec.wiline.com/docs/es/assets/images/h8-no-rootless-package-4540e2d1cdbee668a23f37364afdc535.png\")
E: Unable to locate package docker-ce-rootless-extras
Ese paquete pertenece al repositorio propio de Docker. Este host usa el docker.io de Ubuntu, y\nel segundo comando no devuelve absolutamente nada: el paquete de la distribución no incluye\nninguna herramienta rootless.
Eso importa porque te obliga a elegir. Puedes sustituir docker.io por Docker CE, lo que\nsignifica cambiar el demonio que ahora mismo ejecuta tus contenedores. O puedes instalar un\nsegundo demonio, propiedad de tu usuario, junto al primero. Con 20 servicios corriendo, la\nsegunda opción es la única sensata, y es la que sigue el resto de este post.
Lo que sí necesitas de apt son los ayudantes de mapeo de IDs:
\nsudo apt-get install -y uidmap
En Ubuntu 22.04 esto puede lanzar un diálogo \"Daemons using outdated libraries\" con\ncontainerd.service y tu base de datos ya marcados. uidmap no necesita que se reinicie\nninguno. Desmárcalos, o cancela el diálogo — la instalación se completa igual.
curl -fsSL https://get.docker.com/rootless | sh
# Installing stable version 29.8.1
Aborting because rootful Docker is running and accessible.
Set FORCE_ROOTLESS_INSTALL=1 to ignore.
La protección asume que estás migrando — que un demonio root en marcha significa que estás a\npunto de liarla. Ejecutar ambos a la vez a propósito no se menciona en ningún sitio, y la forma\nde continuar aparece solo dentro del texto del error.
\nFíjate en la versión que nombra: 29.8.1, mientras que el demonio del sistema es 29.1.3.\nVas a acabar con dos versiones distintas de Docker en un mismo host. Aquí es lo esperado, y\nconviene saberlo.
\ncurl -fsSL https://get.docker.com/rootless | FORCE_ROOTLESS_INSTALL=1 sh
Lee las últimas líneas de la salida del instalador:
\n[INFO] Creating CLI context \"rootless\"
[INFO] Using CLI context \"rootless\"
Current context is now \"rootless\"
Ahora pregúntale a Docker qué está corriendo:
\ndocker ps
docker context ls
docker -c default ps -q | wc -l
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/h8-context-hijack-4d422c845ec7d88ee2b2f5a5ffbed4af.png\")
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
NAME DESCRIPTION DOCKER ENDPOINT ERROR
default Current DOCKER_HOST based configuration unix:///var/run/docker.sock
rootless * Rootless mode unix:///run/user/1000/docker.sock
20
Una lista vacía, mientras veinte contenedores funcionan perfectamente. Nada se rompió y nada te\navisó: la CLI está respondiendo a una pregunta distinta de la que crees haber hecho, porque el\ninstalador la reapuntó al terminar.
\nDevuélvela a su sitio y decide por comando:
\ndocker context use default # trabajo diario, sin cambios
docker -c rootless ps # explícito cuando quieras el nuevo
Arranca el demonio y confirma lo que tienes:
\nexport XDG_RUNTIME_DIR=/run/user/$(id -u)
systemctl --user start docker.service
docker -c rootless info --format '{{.ServerVersion}} {{.SecurityOptions}}'
29.8.1 [name=seccomp,profile=builtin name=rootless name=cgroupns]
name=rootless es el demonio confirmando lo que es.
El instalador te dice que añadas ~/bin a tu PATH. Para el uso diario no hace falta: el\ncliente docker del sistema habla perfectamente con el demonio rootless a través del contexto,\ny todos los comandos de este post se ejecutaron así. El PATH solo lo necesitan los scripts de\ninstalación y desinstalación — y sin él fallan con\ndockerd-rootless.sh needs to be present under $PATH, que no te dice nada sobre el problema\nreal.
Pregúntale a un contenedor quién es, y luego mira ese mismo proceso desde fuera:
\ndocker -c rootless run --rm alpine:3.20 id
docker -c rootless run -d --name u0 alpine:3.20 sleep 60
ps -o user=,uid=,cmd= -C sleep | grep 'sleep 60'
docker -c rootless run -d --name u1000 --user 1000:1000 alpine:3.20 sleep 120
ps -o uid=,cmd= -C sleep | grep 'sleep 120'
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h8-uid-mapping-d53136aff71ace37ef98f708404f45d5.png\")
uid=0(root) gid=0(root) groups=0(root),...
ubuntu 1000 sleep 60
100999 sleep 120
Lee esas tres líneas juntas, porque son el mecanismo entero:
\nubuntu.Ese último número es 100000 + 1000 - 1 — el inicio de tu bloque reservado, desplazado por el\nID del propio contenedor, porque el root del contenedor ya ocupó la primera posición al mapearse\na ti.
Lo que te da una prueba en lugar de una promesa. Calcúlalo desde tu propia línea de\n/etc/subuid y comprueba si el número coincide. Si en cambio ves un 1000 pelado, la\ntraducción no está ocurriendo y algo va mal en la instalación.
Limpieza:
\ndocker -c rootless rm -f u0 u1000
Volvamos al comando con el que abrió este post. Misma imagen, mismo montaje del sistema de\narchivos completo, mismos flags. Solo cambia el demonio:
\ndocker -c rootless run --rm -v /:/host alpine:3.20 \\
sh -c 'touch /host/root/rootless-demo || echo DENIED'
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h8-denied-e38f44dfdd6d58bf3f217438f3a584a0.png\")
touch: /host/root/rootless-demo: Permission denied
DENIED
El contenedor sigue creyendo que es root. El kernel no está de acuerdo, porque el proceso que\nhay detrás pertenece a ubuntu, y ubuntu no puede escribir en /root.
Ese es el post, en dos salidas.
\nCuatro cosas, todas medidas aquí en lugar de citadas.
\nLos contenedores no arrancan notablemente más lento. Tres ejecuciones seguidas:
\nfor i in 1 2 3; do /usr/bin/time -f \"run+exit: %es\" \\
docker -c rootless run --rm alpine:3.20 true; done
docker -c rootless run --rm -p 80:80 alpine:3.20 true
![\"Tres](\"https://development-wec.wiline.com/docs/es/assets/images/h8-costs-03291fa4bb34544ae9eff02c34a5fa7a.png\")
run+exit: 1.19s
run+exit: 0.96s
run+exit: 0.97s
Los puertos por debajo de 1024 se rechazan, y, cosa poco habitual, el error te da todas las\nsalidas:
\ncannot expose privileged port 80, you can add
'net.ipv4.ip_unprivileged_port_start=80' to /etc/sysctl.conf (currently 1024),
or set CAP_NET_BIND_SERVICE on rootlesskit binary,
or choose a larger port number (>= 1024)
-p 18080:80 se enlaza sin queja. Detrás de un proxy inverso esto rara vez importa.
Los límites de rendimiento de disco dejan de funcionar. El demonio lo dice al arrancar, y es\nfácil pasarlo por alto:
\nWARNING: No io.max (rbps) support
WARNING: No io.max (wbps) support
Así que --device-read-bps y --device-write-bps no hacen nada, en silencio. Si contabas con\nellos para evitar que un contenedor ahogue a los demás, rootless te lo quita.
Descartar capacidades sigue funcionando, lo que importa porque a menudo se tratan como\nalternativas:
\ndocker -c rootless run --rm --cap-drop=ALL alpine:3.20 sh -c 'echo cap-drop ok'
cap-drop ok
Se acumulan. Sigue usando user: y --cap-drop=ALL — cada capa asume que la anterior falló.
Esta es la parte que pilla a quien mueve un servicio real. Los permisos del host se aplican como\ntú, no como root:
\nD=/tmp/rl-vol; mkdir -p $D; echo hello > $D/mine.txt
sudo sh -c \"echo secret > $D/theirs.txt; chmod 600 $D/theirs.txt\"
docker -c rootless run --rm -v $D:/data alpine:3.20 sh -c \\
'cat /data/mine.txt; cat /data/theirs.txt 2>&1 || echo DENIED'
docker -c rootless run --rm -v $D:/data alpine:3.20 stat -c '%u:%g %n' /data/mine.txt
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h8-volume-permissions-b16a91d894e4363082f108e17d3593e6.png\")
hello
cat: can't open '/data/theirs.txt': Permission denied
DENIED
0:0 /data/mine.txt
Tu propio archivo se lee sin problema. El de root se rechaza — aunque el contenedor se crea\nroot, porque el kernel sabe más. Y tu archivo aparece dentro del contenedor como propiedad de\n0:0, la misma traducción funcionando al revés.
Conviene interiorizarlo antes de mover una base de datos y pasarte una hora preguntándote por\nqué no puede abrir su propio directorio de datos.
\nUna cosa más: el demonio rootless mantiene un almacén de imágenes separado en\n~/.local/share/docker. Las imágenes que ya tiene tu demonio del sistema son invisibles para\nél, y todo se descarga otra vez. Con el disco justo, tenlo en cuenta.
Por simetría, la desinstalación tiene la misma protección:
\nPATH=/home/ubuntu/bin:$PATH ~/bin/dockerd-rootless-setuptool.sh uninstall
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h8-uninstall-refuses-9d0ed4f387ceb4f76df893f91156189a.png\")
[ERROR] Aborting because rootful Docker (/var/run/docker.sock) is running and accessible.
Set --force to ignore.
Añade --force cuando de verdad quieras quitarlo.
Cambia el peor escenario de \"un atacante es dueño de la máquina\" a \"un atacante es dueño de\nesta cuenta de usuario\". En un host donde todos los servicios corren como ubuntu, eso es un\navance grande y no uno completo — tus claves SSH, tus archivos .env y tu código siguen dentro\nde esa cuenta.
Así que el resumen honesto: rootless sube el suelo. No vuelve segura la habitación. Estrechar\nlo que la propia cuenta puede alcanzar es el siguiente peldaño, y ahí es donde entran el filtrado\nde llamadas al sistema y la cadena de suministro de imágenes.
\nPero lo concreto que era cierto al principio de este post — que cualquiera capaz de ejecutar un\ncontenedor podía quedarse con la máquina entera — ya no lo es, y puedes demostrarlo con un\ncomando.
\nsubuid(5) y user_namespaces(7)La parte 4 de orquestación de agentes dividió una caja\nde herramientas para que el agente de agenda no pudiera emitir reembolsos. La\nparte 5 le dio al agente una identidad\npropia en el gateway. La parte 6 puso un verificador de JWT\ndelante del servidor de herramientas para que rechace a quien llama sin identificarse.
\nTodas ellas controlan qué puede llamar el agente. Ninguna controla adónde puede ir.
\nEsa distinción es todo este artículo. La exfiltración no necesita una herramienta. Necesita un\nsocket.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB de RAM, Ubuntu 22.04, kernel 5.15. Docker\n29.1.3 con backend de firewall iptables — que en esta distribución es iptables-nft\nv1.8.7, una capa que en realidad escribe en nftables. El contenedor de pruebas es\nalpine:3.20. UFW está activo.
Cada código de estado, cada mensaje de error y cada medición de este artículo salen de la\nejecución descrita. HTTP plano en una LAN privada donde aparece la LAN, como en toda la serie.
Un firewall decide qué paquetes pueden cruzar un límite. Casi siempre la gente lo dice en una\nsola dirección — entrante: quién desde fuera puede llegar hasta tu servicio. Eso es lo que\nhace publicar un puerto, y de eso trataba la\nparte 1 de esta serie.
\nLa salida es la otra dirección: adónde puede llegar tu servicio. A qué direcciones puede\nabrir una conexión y a cuáles no.
\nCasi nadie configura la salida, y para una aplicación web normal es una decisión razonable.\nHabla con su base de datos y con un proveedor de pagos, hace lo que dice su código, y ese código\nno cambia entre despliegues.
\nUn agente no es eso. Un agente decide qué hacer en tiempo de ejecución, a partir de texto que\nacaba de leer — un correo, un ticket de soporte, una página web, un documento que escribió otra\npersona. Si un atacante controla ese texto, influye en lo que el agente hace a continuación. Y\nlo que no quieres que haga a continuación es exfiltración: enviar tus datos a donde no\ndeben ir.
\nLa exfiltración no necesita ninguna herramienta especial. Cualquier proceso que pueda abrir un\nsocket puede enviar cualquier cosa que pueda leer. Por eso la dirección que nadie vigila es\njusto la que importa aquí.
\nLa referencia principal para este tipo de problema es LLM06:2025 Agencia Excesiva de OWASP.\nSu sección de prevención enumera, en orden: minimizar las extensiones, minimizar la\nfuncionalidad de las extensiones, evitar extensiones abiertas, y algunos puntos más sobre\npermisos y aprobación humana.
\nLee la página buscando la red y no está. Ni \"egress\", ni \"firewall\", ni \"red\", ni \"aislamiento\",\nni \"sandbox\" — esas palabras no aparecen en la entrada.
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h7-owasp-mitigations-d1025852bd1958d91bfe4304dd74c563.png\")
Cada mitigación de esa lista opera sobre herramientas. Quita la extensión, acota la\nextensión, evita la extensión abierta. Todo es buen consejo. Nada de eso cambia un solo byte de\nlo que un proceso comprometido puede hacer con un socket TCP.
\nHay quien defiende que esto es un hueco y no un descuido, y el argumento se está haciendo dentro\ndel propio repositorio de OWASP. Un\nissue abierto que propone un mapeo de aplicación en tiempo de ejecución\npara el Top 10 Agéntico lo dice sin rodeos:
\n\n\nThe enforcement pipeline assumes agents cannot reach tools without passing through the\nproxy. If tools are directly reachable, runtime enforcement collapses.
\n
y concluye que \"Network-level controls (e.g., Kubernetes NetworkPolicy, Docker network\nisolation) are required to close this gap in production.\"
\nFíjate en qué es eso: un issue abierto, presentado por un colaborador, con su mapeo marcado\ncomo (Proposed). No es el estándar. Es alguien argumentando que el estándar debería decir esto.
\nY la razón por la que esto importa no es teórica. EchoLeak\n(CVE-2025-32711) es una inyección de prompt\nindirecta de cero clics contra Microsoft 365 Copilot, registrada en NVD como \"Ai command\ninjection in M365 Copilot allows an unauthorized attacker to disclose information over a\nnetwork.\" Over a network. La lista de herramientas nunca fue lo que falló.
\niptables — el predeterminado. Compruébalo con\ndocker info | grep -i \"Firewall Backend\"sudo, y voluntad de escribir reglas de firewall en una máquina que aún puedas alcanzarDOCKER-USER es estado real del firewall de tu host. Una regla que coincida con más de lo que\npretendías dejará servicios fuera de línea. Todas las reglas de este artículo están acotadas con\n-i br-agent, una interfaz que pertenece a una red creada para este fin — que es justo por lo\nque en el paso 1 nombramos ese bridge a mano en lugar de dejar que Docker genere uno.
Si trabajas por SSH, ninguna de estas reglas toca la cadena INPUT, así que tu sesión no corre\nriesgo. Compruébalo tú mismo antes de creértelo.
Una red, con la interfaz del bridge nombrada explícitamente. Docker documenta la opción como\n\"Interface name to use when creating the Linux bridge\":
\ndocker network create --driver bridge \\
-o com.docker.network.bridge.name=br-agent agent-egress
ip -br link show br-agent
br-agent DOWN 8a:77:65:54:9b:0d <NO-CARRIER,BROADCAST,MULTICAST,UP>
DOWN, porque todavía no hay nada conectado. Una red de Docker es una interfaz que no se\nlevanta hasta que se conecta un contenedor, y una regla con -i br-agent sobre una red inactiva\nno coincide con nada, en silencio. Conviene saberlo antes de pasar una hora depurando una\npolítica que nunca se ejecutó.
El contenedor de pruebas — con versión fijada, no latest:
docker run -d --name agent-sandbox --network agent-egress alpine:3.20 sleep infinity
docker exec agent-sandbox apk add --no-cache curl bind-tools
Ahora cuatro destinos. Fíjate en lo que no hay en este contenedor: ni agente, ni framework, ni\ncliente MCP, ni herramientas. Aquí no se está evadiendo el acotado de herramientas — es que no\nhay nada que evadir.
\ndocker exec agent-sandbox curl -sS -m 8 -o /dev/null -w 'inference API HTTP %{http_code}\\n' https://inference.wiline.com/v1/models
docker exec agent-sandbox curl -sS -m 8 -o /dev/null -w 'arbitrary host HTTP %{http_code}\\n' https://example.com
docker exec agent-sandbox curl -sS -m 8 -o /dev/null -w 'authentik LAN HTTP %{http_code}\\n' http://10.80.4.212:9100/
docker exec agent-sandbox curl -sS -m 8 -o /dev/null -w 'other network exit=%{exitcode} %{errormsg}\\n' http://172.21.0.2:5432/
inference API HTTP 401
arbitrary host HTTP 200
authentik LAN HTTP 302
other network exit=28 Connection timed out after 5002 milliseconds
![\"Cuatro](\"https://development-wec.wiline.com/docs/es/assets/images/h7-before-unrestricted-527fc904745f99b3fdab1b9d08035428.png\")
El 401 es el que conviene entender. No se envió ninguna clave de API, así que la petición\nnunca llega a nada que pudiera cobrarse — pero un 401 es una respuesta HTTP, lo que significa\nque el handshake TCP se completó, que TLS negoció, y que respondió un servidor real.\nAlcanzabilidad demostrada, gratis.
La cuarta línea es la que mantiene esto honesto. Ese es un contenedor de Postgres en otra red de\nDocker, y expira — la parte 1 de esta serie\nestableció que las redes bridge separadas sí aíslan, y esto lo confirma.
\nAsí que la forma del hueco es precisa, no vaga:
\n| Destino | Resultado | |
|---|---|---|
| Otra red de Docker | expira | Docker ya se encarga de esto |
| Tu propia LAN, incluido el proveedor de identidad | 302 | abierto |
| Internet abierto | 200 | abierto |
| La única API que de verdad necesita | 401 | abierto |
Docker aísla los contenedores entre sí y ahí se detiene. Las dos direcciones que importan\npara la exfiltración — tu red e internet — están abiertas de par en par, y ninguna guía de\nDocker lo presenta como un hueco porque, para una aplicación web, no lo es.
\nUna regla. Fíjate en -A y no -I: la denegación va al final de la cadena y se queda ahí,\ny cada permiso que añadamos después se apila encima. Ese orden es la política.
sudo iptables -A DOCKER-USER -i br-agent -j DROP
DOCKER-USER es donde esto corresponde, y la documentación de Docker dice por qué:
\n\nRules appended to the
\nFORWARDchain will be processed after Docker's rules.
DOCKER-USER se procesa antes que ellas — la documentación la describe como \"a placeholder\nfor user-defined rules that will be processed before rules in the DOCKER-FORWARD and DOCKER\nchains.\" En cualquier otro sitio, el ACCEPT del propio Docker llega primero.
Léelo de arriba abajo y la colocación se explica sola. DOCKER-FORWARD contiene un ACCEPT\nincondicional por cada bridge — eso es lo que hace que la salida de los contenedores funcione, y\npor eso una regla añadida a FORWARD nunca se dispara. DOCKER-USER es el único punto que\nqueda por delante.
Repite las mismas cuatro sondas:
\ninference API exit=28 Resolving timed out after 8000 milliseconds
arbitrary host exit=28 Resolving timed out after 8002 milliseconds
authentik LAN exit=28 Connection timed out after 8003 milliseconds
other network exit=28 Connection timed out after 8002 milliseconds
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h7-default-deny-dd96eebe9dcfc37644f95bf30a45d1ae.png\")
Lee el texto del error, no el fallo. Dos mensajes distintos, y la diferencia es información\nde diagnóstico gratuita:
\nLas dos sondas por nombre murieron en la resolución; las dos por IP murieron en el socket. Lo\nque nos dice algo que no es obvio: el resolvedor integrado de Docker reenvía sus consultas a\ntravés de DOCKER-USER. El resolvedor vive en 127.0.0.11 dentro del espacio de nombres del\ncontenedor, y es tentador suponer que ese tráfico nunca toca la ruta de forwarding del host. Sí\nla toca.
Fíjate también en que cada fallo tardó los ocho segundos completos. Un DROP produce\nexpiraciones; un REJECT falla al instante. Sigilo contra facilidad de depuración, y este\nartículo elige el sigilo — pero si todavía estás iterando sobre una política, REJECT te\nahorrará muchísima espera.
Antes de escribir una regla para el resolvedor, averigua qué resolvedor usa realmente el\ncontenedor:
\ndocker exec agent-sandbox cat /etc/resolv.conf
nameserver 127.0.0.11
search corp.internal internal mesh.example.com
options edns0 trust-ad ndots:0
# Based on host file: '/etc/resolv.conf' (internal resolver)
# ExtServers: [8.8.8.8 8.8.4.4]
ExtServers: [8.8.8.8 8.8.4.4]. El contenedor no está usando el DNS de esta red. El host\nresuelve a través de systemd-resolved en 127.0.0.53, que es una dirección de loopback y por\ntanto inútil dentro del espacio de nombres de un contenedor, así que Docker sustituyó el DNS\npúblico de Google sin mencionarlo.
Mira los dominios de búsqueda heredados en el mismo bloque (aquí redactados, pero reales en tu\nmáquina). Cada nombre interno que ese contenedor resuelve se le está preguntando a 8.8.8.8,\ncon el sufijo de los dominios privados que heredó del host. Nadie eligió eso, y nada lo saca a\nla luz salvo leer este fichero.
También decide la regla: permite el resolvedor que el contenedor tiene, no el que supusiste.
\ngetent hosts inference.wiline.com
67.207.107.229 inference.wiline.com
sudo iptables -I DOCKER-USER -i br-agent -p udp --dport 53 -d 8.8.8.8,8.8.4.4 -j ACCEPT
sudo iptables -I DOCKER-USER -i br-agent -p tcp --dport 53 -d 8.8.8.8,8.8.4.4 -j ACCEPT
sudo iptables -I DOCKER-USER -i br-agent -p tcp --dport 443 -d 67.207.107.229 -j ACCEPT
sudo iptables -S DOCKER-USER
-N DOCKER-USER
-A DOCKER-USER -d 67.207.107.229/32 -i br-agent -p tcp -m tcp --dport 443 -j ACCEPT
-A DOCKER-USER -d 8.8.4.4/32 -i br-agent -p tcp -m tcp --dport 53 -j ACCEPT
-A DOCKER-USER -d 8.8.8.8/32 -i br-agent -p tcp -m tcp --dport 53 -j ACCEPT
-A DOCKER-USER -d 8.8.4.4/32 -i br-agent -p udp -m udp --dport 53 -j ACCEPT
-A DOCKER-USER -d 8.8.8.8/32 -i br-agent -p udp -m udp --dport 53 -j ACCEPT
-A DOCKER-USER -i br-agent -j DROP
Cinco permisos sobre una denegación. Las mismas cuatro sondas, por tercera vez:
\ninference API HTTP 401 exit=0
arbitrary host exit=28 Connection timed out after 8002 milliseconds
authentik LAN exit=28 Connection timed out after 8003 milliseconds
other network exit=28 Connection timed out after 8001 milliseconds
![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/h7-allowlist-applied-71e84e955ac296d1b262e120254f5409.png\")
Mira la segunda línea. Dice \"Connection timed out\", no \"Resolving timed out\". El DNS está\nabierto, así que example.com sí resolvió a una dirección real — y entonces el paquete murió.\nLa resolución funcionó y el socket no.
Ese es todo el artículo en una línea. Un proceso comprometido dentro de ese contenedor puede\naveriguar adónde enviar tus datos y no puede enviarlos.
\nTodas las guías sobre este tema te dicen que primero aceptes el tráfico RELATED,ESTABLISHED, y\nla documentación de Docker muestra la regla. Esta política no tiene ninguna, y el 401 de\narriba demuestra que el handshake TLS completo y la respuesta HTTP volvieron igualmente.
La razón es la dirección. Nuestro DROP coincide con -i br-agent — tráfico que llega desde\nel contenedor. Los paquetes de vuelta llevan -o br-agent, nunca coinciden, atraviesan\nDOCKER-USER sin tocarse, y los aceptan después las propias reglas de seguimiento de conexiones\nde Docker.
Necesitas el ACCEPT de conntrack cuando tu DROP puede coincidir con la dirección de vuelta, que\nes el caso de los ejemplos de tráfico entrante de donde viene ese consejo. Un DROP de salida\nespecífico de dirección, no. Añádela igualmente si quieres — no cuesta nada — pero entiende que\ncopiarla sin entenderla es como se llega a la conclusión de que las reglas de firewall son magia\nnegra.
Una política que nadie mide es una política que alguien desactivará cuando haya carga. Así que:\n¿cuánto cuestan seis reglas?
\nEl enfoque obvio, veinte conexiones con las reglas puestas y veinte sin ellas:
\nfor i in $(seq 20); do docker exec agent-sandbox curl -sS -o /dev/null -w '%{time_connect}\\n' -m 8 https://inference.wiline.com/v1/models; done | sort -n | awk '{a[NR]=$1} END{printf \"rules ON — median %.4fs min %.4fs max %.4fs (n=%d)\\n\", a[int(NR/2)+1], a[1], a[NR], NR}'
sudo iptables -F DOCKER-USER
rules ON — median 0.1573s min 0.0940s max 0.3768s (n=20)
rules OFF — median 0.0936s min 0.0911s max 0.1576s (n=20)
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h7-overhead-naive-f360e40c29ad6c2b0c7ff16a3663104c.png\")
64 milisegundos. Lo cual sería un hallazgo serio, si fuera cierto.
\nNo lo es. Seis reglas de coincidencia de paquetes son microsegundos de trabajo del kernel, y los\nmínimos delatan el truco: 0.0940 frente a 0.0911, casi idénticos. La ruta rápida es la misma\nen ambas ejecuciones. Toda la diferencia vive en la cola.
El time_connect de curl se mide desde el inicio de la petición y por tanto incluye la\nresolución del nombre. La primera ejecución pagó una ida y vuelta completa a 8.8.8.8. Para\nla segunda, el resolvedor ya tenía la respuesta en caché. Medimos el orden en que las\nejecutamos.
Mide solo la conexión TCP, restando la resolución:
\nfor i in $(seq 30); do docker exec agent-sandbox curl -sS -o /dev/null -w '%{time_namelookup} %{time_connect}\\n' -m 8 https://inference.wiline.com/v1/models; done | awk '{print ($2-$1)}' | sort -n | awk '{a[NR]=$1} END{printf \"connect-only median %.5fs min %.5fs max %.5fs (n=%d)\\n\", a[int(NR/2)+1], a[1], a[NR], NR}'
rules ON — connect-only median 0.07098s min 0.06999s max 0.08607s (n=30)
rules OFF — connect-only median 0.07102s min 0.06996s max 0.07214s (n=30)
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h7-overhead-94f3b889647c2c273680e82c050b345a.png\")
Una diferencia de mediana de −0,04 ms. Negativa: la ruta protegida midió marginalmente más\nrápido, que es el aspecto que tiene el ruido. Todo cae dentro de unos ±40 µs.
\nAsí que la respuesta honesta no es un número con un signo más delante. Es que el coste de esta\npolítica está por debajo de lo que este método puede resolver — y que la versión ingenua de la\nmisma medición se equivocaba por tres órdenes de magnitud, en la dirección que te habría\nconvencido de no desplegarla.
\nLas reglas de iptables viven en memoria. Ese -F del paso anterior le hizo a la política\nexactamente lo mismo que le hace un reinicio.
El reflejo es iptables-persistent, y aquí es la herramienta equivocada: guarda la tabla entera\nincluidas todas las reglas que generó Docker, y Docker vuelve a generarlas él mismo al arrancar.\nAcabas con duplicados y con un orden que nadie eligió.
Lo que quieres es una unidad que sea dueña solo de tus reglas y que se ejecute después de\nDocker:
\n#!/usr/bin/env bash
# Lista de permitidos de salida para el bridge del agente. Se reaplica tras arrancar Docker.
set -euo pipefail
BR=br-agent
DNS=\"8.8.8.8 8.8.4.4\"
API=$(getent hosts inference.wiline.com | awk '{print $1; exit}')
# Elimina solo nuestras propias reglas, para que sea seguro ejecutarlo dos veces.
# `|| true` importa: con la cadena limpia, grep sale con 1 y abortaría el script.
existing=$(iptables -S DOCKER-USER | grep \" -i ${BR} \" || true)
if [ -n \"${existing}\" ]; then
printf '%s\\n' \"${existing}\" | sed 's/^-A /-D /' |
while read -r rule; do iptables ${rule} || true; done
fi
for d in ${DNS}; do
iptables -I DOCKER-USER -i \"${BR}\" -p udp --dport 53 -d \"${d}\" -j ACCEPT
iptables -I DOCKER-USER -i \"${BR}\" -p tcp --dport 53 -d \"${d}\" -j ACCEPT
done
iptables -I DOCKER-USER -i \"${BR}\" -p tcp --dport 443 -d \"${API}\" -j ACCEPT
iptables -A DOCKER-USER -i \"${BR}\" -j DROP
[Unit]
Description=Egress allowlist for the agent bridge
After=docker.service
Requires=docker.service
[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/usr/local/sbin/agent-egress.sh
[Install]
WantedBy=multi-user.target
sudo chmod +x /usr/local/sbin/agent-egress.sh
sudo systemctl daemon-reload && sudo systemctl enable --now agent-egress.service
Demuestra que es idempotente reiniciándola y comparando la cadena consigo misma:
\nsudo systemctl restart agent-egress.service && sudo iptables -S DOCKER-USER
![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/h7-persistent-unit-08c4df2a28634e493a6a37476e9429fb.png\")
Seis reglas, dos veces, sin duplicados.
\nDos cosas que esto te da de forma discreta. getent se ejecuta en cada arranque, así que la\ndirección de la API se vuelve a resolver al iniciar — no de forma continua, pero sí la mayor\nparte barata del problema del destino móvil, sin ningún demonio extra. Y el bucle de borrado\nelimina solo las reglas que coinciden con -i br-agent, así que la unidad nunca toca nada más\nde la cadena.
Puedes poner una política de denegación por defecto delante de un contenedor, permitir\nexactamente los destinos que necesita, distinguir un fallo de DNS de un fallo de socket leyendo\nel error, medir el coste sin engañarte, y hacer que todo sobreviva a un reinicio.
Docker 29 incluye un backend de firewall nftables junto al de iptables. No es el predeterminado y\neste artículo no lo ejecutó — el cambio reconstruye todas las reglas del host, y verificar el\ncomportamiento completo exige un reinicio. Lo que sigue viene de la documentación de Docker, y se\nmarca como tal.
\nTodo lo anterior deja de aplicarse, porque:
\n\n\nIn Docker's nftables implementation, there is no
\nDOCKER-USERchain.
En su lugar creas tu propia tabla, y la prioridad hace el trabajo que hacía DOCKER-USER:
\n\nIf your rules need to run before Docker's rules, give the base chains a lower priority number\nthan Docker's chain.
\n
Y una regla que bajo iptables sería definitiva, no lo es:
\n\n\nIn nftables, an \"accept\" rule is not final. It terminates processing for its base chain, but\nthe accepted packet will still be processed by other base chains, which may drop it.
\n
Para sobreponerse al drop de Docker hace falta entonces --bridge-accept-fwmark.
La trampa que conviene conocer es la transición, y es silenciosa en ambos sentidos:
\n\n\nWhen starting the daemon with nftables after running with iptables, Docker will not remove the\njump from the
\nFORWARDchain toDOCKER-USER. So, rules created inDOCKER-USERwill\ncontinue to run until the jump is removed or the host is rebooted. When starting with nftables,\nthe daemon will not add the jump. So, unless there is an existing jump, rules inDOCKER-USER\nwill be ignored.
Cambia de backend y tu política sigue funcionando — hasta el siguiente reinicio, cuando deja de\nhacerlo en silencio. iptables -S DOCKER-USER seguirá listando todas las reglas.
status=1/FAILURE y nada más en el journal. La causa es la línea de limpieza: con la cadena\nvacía, grep no encuentra reglas coincidentes y sale con 1, y set -euo pipefail convierte\neso en un aborto antes de añadir ninguna regla. La guarda de idempotencia rompe justo la única\nejecución que no necesita idempotencia. Mira el || true del paso 5.
Comprueba si el fallo dice \"Resolving\" o \"Connection\". Si dice Resolving, el problema es tu\nregla de DNS y nunca se llegó a la regla del destino. Los contenedores a menudo no usan el\nresolvedor que esperas — lee /etc/resolv.conf dentro del contenedor, no en el host.
Comprueba que el bridge esté levantado: ip -br link show br-agent. Una red sin contenedores\nconectados tiene la interfaz DOWN, y una regla con -i sobre ella no coincide con nada.
Eso es DROP comportándose correctamente. Usa REJECT mientras iteras si prefieres fallar\nrápido.
Estás midiendo DNS. Usa %{time_connect} menos %{time_namelookup}, y sospecha de cualquier\nresultado donde los mínimos coincidan y las medianas no.
Hecho: un contenedor que puede alcanzar exactamente un destino y un resolvedor; un intento de\nexfiltración que falla después de una resolución DNS correcta y no antes; una política que se\nreaplica sola tras un reinicio y que vuelve a resolver su destino al hacerlo; y un coste medido\nindistinguible de cero.
\nSin hacer:
\n8.8.8.8, y se pueden\ncolar datos dentro de ellas. Cerrar eso significa un resolvedor propio y una regla que apunte\nsolo a él — que es otro artículo.ACCEPT incondicional en DOCKER-FORWARD.La secuela obvia es el resolvedor: monta uno propio, apunta el contenedor a él, permite el puerto\n53 solo hacia esa dirección, y el canal de DNS se cierra junto con la dependencia de Google.\nTambién prepara el terreno para hacer bien las listas de permitidos por dominio, que es la parte\ndel problema del destino móvil que este artículo deja abierta.
\nLa Parte 5 le dio a un agente su propia\nidentidad en el gateway: un token emitido por authentik con client credentials, con un scope, y\nque expira a los cinco minutos. Terminó nombrando lo que no había cubierto — el servidor de\nherramientas MCP de la\nparte 4 de orquestación de agentes sigue fiándose de\ncualquier cosa que alcance su puerto, issue_refund incluido.
Aquel post fue explícito sobre el límite de lo que había construido:
\n\n\nThe MCP server still trusts everyone. Scoping happens in the client. Anything that can\nreach
\n127.0.0.1:8770can callissue_refunddirectly, agent or not.
Repartir la caja de herramientas por rol impidió que un agente alcanzara una herramienta que\nno le tocaba. No hizo nada contra un curl. Esta parte cierra eso.
La misma máquina que las Partes 3 a 5: una WEC Instance, 8 vCPU AMD EPYC 7601, 15 GB RAM,\nUbuntu 22.04, Python 3.10. authentik 2026.8.1 en el puerto host 9100. fastmcp 4.0.2,\nmcp 2.1.1, langchain 1.4.0. El servidor MCP es office_tools.py de la\nparte 3 de orquestación de agentes, sin más\ncambios que las líneas que se muestran aquí, todavía en 127.0.0.1:8770.
HTTP plano sobre una LAN privada, como en toda esta serie.
Lo obvio es reutilizar el cliente agent-gateway de la Parte 5 y añadirle un segundo scope. Ya\nexiste, el agente ya tiene sus credenciales, y funcionaría.
No lo hagas. Si una sola credencial abre el gateway y el servidor de herramientas, entonces una\nclave de gateway filtrada también emite reembolsos, y el radio de daño de perderla se duplica.\nEl hilo que recorre los grupos de la Parte 4 y los grant types de la Parte 5 es que una\ncredencial debería hacer un solo trabajo.
\nAsí que el servidor de herramientas recibe su propio cliente, su propio scope y — porque en\nauthentik cada proveedor es su propio emisor — su propio emisor. Esto último acaba importando\nmás de lo esperado, y llegamos a ello en el Paso 4.
\nagent-gateway de la Parte 5fastmcp 4.0.0 o posterior — el ayudante de client credentials del Paso 5 no existe antesEsto es el procedimiento de la Parte 5 con otros nombres, así que aquí va deliberadamente\nescueto. Si algo no te resulta familiar,\nla Parte 5 recorre las mismas tres pantallas\ncon figuras.
\nEl proveedor. Applications → Providers → New Provider → OAuth2/OpenID → Next. Nombre\nagent-tools, Client Type Confidential, Redirect URIs vacío, y en Grant Types desmarca\ntodo excepto Client credentials.
El scope. Customization → Property Mappings → New Property Mapping → Scope Mapping. Mapping\nName mcp-invoke, Scope name mcp:invoke, expresión return {}. Los dos campos de nombre son\ncosas distintas: el primero es la etiqueta de authentik, el segundo es la cadena que acaba en el\ntoken.
La aplicación. Applications → Applications → New Application ▾ → with Existing\nProvider…, con nombre Agent Tools, slug agent-tools escrito a mano, proveedor\nagent-tools, oculta del dashboard. Después edita el proveedor → Advanced protocol settings →\nScopes, y mueve mcp-invoke a Selected.
Verifica los grant types desde la base de datos y no desde el formulario, que es\nla lección de la Parte 4:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.providers.oauth2.models import OAuth2Provider
for p in OAuth2Provider.objects.all():
print(f'{p.name}: {p.grant_types}')\" 2>/dev/null | tail -5
Provider for Langfuse: ['authorization_code', 'implicit', 'urn:ietf:params:oauth:grant-type:device_code']
Provider for LiteLLM: ['authorization_code', 'implicit', 'hybrid', 'refresh_token', 'client_credentials', 'password', 'urn:ietf:params:oauth:grant-type:device_code']
agent-gateway: ['client_credentials']
agent-tools: ['client_credentials']
Dos clientes recortados a un solo flujo cada uno y — visible en la misma salida — el proveedor\nde LiteLLM de la Parte 4 todavía con password y otros cinco que nadie eligió. La Parte 5 dijo\nque había que volver y arreglarlos. Esto es el aspecto que tiene no hacerlo.
Lee las credenciales y guárdalas junto a las del gateway, en su propio directorio:
\ncd ~/authentik
read -r TID TSEC < <(docker compose exec -T server ak shell -c \"
from authentik.providers.oauth2.models import OAuth2Provider as P
p = P.objects.get(name='agent-tools')
print(p.client_id, p.client_secret)\" 2>/dev/null | tail -1)
mkdir -p ~/mcp-auth && cd ~/mcp-auth
umask 077
cat > .env <<EOF
AK_TOKEN_URL=http://10.80.4.212:9100/application/o/token/
AK_CLIENT_ID=$TID
AK_CLIENT_SECRET=$TSEC
EOF
cp ~/agent-auth/token.sh ~/mcp-auth/token.sh
El ayudante es el de la Parte 5, sin cambios — recibe un scope y devuelve un access token.
\n~/mcp-auth/token.sh mcp:invoke | jq -R 'split(\".\")[1] | gsub(\"-\";\"+\") | gsub(\"_\";\"/\") | @base64d | fromjson'
{
\"iss\": \"http://10.80.4.212:9100/application/o/agent-tools/\",
\"sub\": \"545a532b77a0f877339a5e4312970069deeb9ded604494c510debdfdce9c970d\",
\"aud\": \"xNxmOEyPMPVThmxgLsyvTCHa3qvnpVjQSOY0bZck\",
\"exp\": 1789050030,
\"iat\": 1789049730,
\"scope\": \"mcp:invoke\"
}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h6-tools-token-611a3b28adc48e09f38c168c63c7d1ac.png\")
Tres campos difieren del token del gateway y los tres cargan peso. El emisor termina en\n/agent-tools/ y no en /agent-gateway/. La audiencia es otro client ID. El scope es\nmcp:invoke. exp menos iat son 300 segundos, igual que en la Parte 5 — recuerda ese número,\nvuelve en el Paso 5.
Si el token vuelve con \"scope\": \"\", el mapping existe pero no está adjunto al proveedor. El\npropio texto de ayuda de authentik en ese panel: \"Select which scopes can be used by the\nclient. The client still has to specify the scope to access the data.\" Adjuntarlo lo hace\ndisponible; el cliente todavía tiene que pedirlo.
FastMCP valida JWT con JWTVerifier, que recibe las cuatro cosas que authentik nos acaba de\ndecir. Haz copia de seguridad del servidor primero, que es el artefacto sobre el que se apoyan\ndos partes ya publicadas:
cp ~/mcp-tools/office_tools.py ~/mcp-tools/office_tools.py.bak
Su configuración va en un fichero, no en el código:
\ncd ~/mcp-tools
umask 077
cat > .env.mcp <<'EOF'
MCP_JWKS_URI=http://10.80.4.212:9100/application/o/agent-tools/jwks/
MCP_ISSUER=http://10.80.4.212:9100/application/o/agent-tools/
MCP_AUDIENCE=<el client id de agent-tools>
EOF
Después, dos cambios en office_tools.py — un import, y un verificador donde estaba el\nconstructor pelado:
from fastmcp import FastMCP, Context
from fastmcp.server.auth.providers.jwt import JWTVerifier
verifier = JWTVerifier(
jwks_uri=os.environ[\"MCP_JWKS_URI\"],
issuer=os.environ[\"MCP_ISSUER\"],
audience=os.environ[\"MCP_AUDIENCE\"],
required_scopes=[\"mcp:invoke\"],
)
mcp = FastMCP(\"office-tools\", auth=verifier)
Ese es todo el cambio del lado del servidor. JWTVerifier descarga el JWKS, empareja el kid\nde cada token con una clave, y comprueba firma, emisor, audiencia, caducidad y scope antes de\nque se ejecute ninguna herramienta.
ssrf_safe y las direcciones privadasJWTVerifier acepta un argumento ssrf_safe que por defecto es False, y activarlo suena a\nbuena idea sin matices. En un montaje como este rompe el verificador. La protección SSRF de\nFastMCP rechaza por IP, y su propio texto de error es \"Private, loopback, link-local, and\nreserved IPs are not allowed\" — la comprobación cubre explícitamente 10.x, 172.16-31.x,\n192.168.x y 127.x. Nuestro JWKS está en 10.80.4.212, así que la petición no sale del\nproceso.
Si quieres la protección activa y tu proveedor de identidad es genuinamente interno, el módulo\nlee FASTMCP_SSRF_TRUST_PROXY, que se salta la resolución DNS y la lista de bloqueo por\ncompleto.
Reinicia con el nuevo entorno cargado:
\npkill -f office_tools.py
cd ~/mcp-tools && set -a && source .env.mcp && set +a && \\
nohup ./.venv/bin/python -u office_tools.py > server.log 2>&1 &
sleep 4 && tail -8 server.log
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h6-server-auth-startup-e2aacc2f7033430c7a21caae3e07b195.png\")
Lee ese log de arranque con atención, por lo que le falta. Informa del transporte, el modo y el\npuerto, y no dice absolutamente nada sobre autenticación. Un servidor con verificador y uno sin\nél escriben las mismas líneas. No hay ningún mensaje de \"auth activada\" que buscar, así que la\núnica forma de saber si el verificador ha entrado es hacer una petición — que es el paso\nsiguiente.
\nLa misma forma que los tres códigos de estado de la Parte 5, porque se lee bien y porque la del\nmedio es la interesante:
\nTOOLS=$(~/mcp-auth/token.sh mcp:invoke)
GW=$(~/agent-auth/token.sh gateway:invoke)
req() {
curl -sS -o /dev/null -w \"$1 HTTP %{http_code}\\n\" -X POST http://127.0.0.1:8770/mcp \\
-H 'Content-Type: application/json' \\
-H 'Accept: application/json, text/event-stream' \\
${2:+-H \"Authorization: Bearer $2\"} \\
-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'
}
req \"no token \"
req \"gateway token\" \"$GW\"
req \"tools token \" \"$TOOLS\"
no token HTTP 401
gateway token HTTP 401
tools token HTTP 200
![\"Tres](\"https://development-wec.wiline.com/docs/es/assets/images/h6-three-way-5268dcb96fa1731e359bf14df5c1b0e8.png\")
La primera línea es el hueco que la parte 4 de orquestación de agentes admitió, ahora cerrado.\nAntes de este cambio, esa petición devolvía el catálogo completo de cinco herramientas a quien\nlo pidiera — y con el token correcto, sigue haciéndolo:
\ncurl -sS -X POST http://127.0.0.1:8770/mcp \\
-H \"Authorization: Bearer $TOOLS\" \\
-H 'Content-Type: application/json' \\
-H 'Accept: application/json, text/event-stream' \\
-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}' \\
| tr -d '\\r' | sed -n 's/^data: //p' | jq '.result.tools | length, (.[].name)'
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h6-tools-list-authorised-e04041592339f5df452a50d4fc2cd30d.png\")
Las mismas cinco herramientas que antes. La autenticación cambió quién puede preguntar, no lo\nque hace el servidor.
\nLa segunda línea es en la que conviene detenerse. Ese es un token de authentik válido, sin\ncaducar y correctamente firmado que funciona perfectamente contra el gateway, y el servidor de\nherramientas lo rechaza. Pregúntale al servidor por qué — enviando la petición otra vez primero,\npara que la respuesta quede al final del log y no enterrada bajo lo que haya llegado desde\nentonces:
\nGW=$(~/agent-auth/token.sh gateway:invoke)
curl -sS -o /dev/null -w 'gateway token: HTTP %{http_code}\\n' -X POST http://127.0.0.1:8770/mcp \\
-H \"Authorization: Bearer $GW\" \\
-H 'Content-Type: application/json' \\
-H 'Accept: application/json, text/event-stream' \\
-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'
tail -12 ~/mcp-tools/server.log
WARNING Bearer token rejected for client aObZ8KvKsKVdQ4MuSsTINp0f65Puz5fzXUUBC6iQ
: issuer mismatch (got 'http://10.80.4.212:9100/application/o/agent-gateway/',
expected 'http://10.80.4.212:9100/application/o/agent-tools/')
INFO Auth error returned: invalid_token (status=401)
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h6-issuer-mismatch-log-67e89b1720edb880e97f3f7258d47aac.png\")
Falló por iss, no por el scope. Ahí está el proveedor aparte dando su fruto. En authentik\ncada proveedor es su propio emisor, así que un token del cliente equivocado se rechaza en la\nprimera puerta, antes de mirar la audiencia o el scope. Si hubiéramos tomado el camino fácil y\nañadido un segundo scope al cliente del gateway, la misma petición habría llegado varias\ncomprobaciones más allá antes de que required_scopes la echara. Mismo resultado, más\nsuperficie.
Otras dos cosas en ese log. Nombra al cliente infractor por su ID, e imprime tanto el emisor que\nrecibió como el que esperaba — así que depurar es un tail, no una adivinanza. Y quien llama\nrecibe solo invalid_token, que es lo correcto: decirle a un cliente qué emisor esperabas es\ndecirle a un atacante qué falsificar.
grep -iE 'invalid|token|401' server.log devuelve la última línea y esconde la primera. Te\nquedas con invalid_token (status=401) y concluyes que el servidor no dice por qué. Sí lo dice,\nen la línea de arriba, repartida en cuatro líneas que tu patrón no captura. Léelo sin filtrar.
El servidor de herramientas ya está protegido, lo que significa que todos los scripts de la\nparte 3 y la\nparte 4 están rotos. Se conectan sin token.
\nFastMCP documenta exactamente lo que hace falta para esto: ClientCredentialsOAuthProvider, que\nejecuta él mismo el flujo de client credentials y — lo que importa dados nuestros tokens de 300\nsegundos — \"when the token expires it is re-acquired automatically on the next request.\"
Aquí no funciona. Pruébalo y obtienes:
\nmcp.client.auth.exceptions.OAuthTokenError: Token exchange failed (404): Not Found
El log del servidor explica lo que pasó de verdad:
\nGET /.well-known/oauth-authorization-server 404
POST /token 404
GET /.well-known/oauth-protected-resource 404
GET /.well-known/oauth-protected-resource/mcp 404
GET /.well-known/openid-configuration 404
El provider recibe la URL del servidor MCP, no un endpoint de token, porque \"the token\nendpoint is discovered from the server's OAuth metadata.\" El nuestro no publica ninguna — y la\npropia documentación de FastMCP lo dice, en otra página: \"TokenVerifier focuses exclusively\non token validation without providing OAuth discovery metadata.\"
O sea que las dos páginas son coherentes y la combinación es un callejón sin salida documentado.\nSolo que hay que leer ambas para enterarse, y el fallo no te cuenta nada de eso: cuatro 404 que\nsolo ves si estás mirando el servidor, un repliegue que hace POST /token contra el servidor de\nrecursos, y un error que nunca menciona el descubrimiento.
El camino que señala la documentación es que el cliente obtenga su token por separado.\nBearerAuth recibe un token que ya tienes y lo adjunta a cada petición — vale la pena probarlo\nsuelto antes de cablearlo en cuatro scripts:
![\"Un](\"https://development-wec.wiline.com/docs/es/assets/images/h6-client-bearer-works-5250c1328730dcadf4366a6843f881c0.png\")
Eso funciona, así que se puede compartir. Un ayudante, usado por todos los scripts de la serie:
\n\"\"\"Un único cliente MCP autenticado, compartido por todos los agentes de la serie.\"\"\"
import os
import subprocess
from fastmcp import Client
from fastmcp.client.auth import BearerAuth
MCP_URL = \"http://127.0.0.1:8770/mcp\"
TOKEN_SH = os.path.expanduser(\"~/mcp-auth/token.sh\")
def fetch_token(scope: str = \"mcp:invoke\") -> str:
\"\"\"Emite un token de corta duración desde authentik con client credentials.\"\"\"
out = subprocess.run([TOKEN_SH, scope], capture_output=True, text=True, check=True)
return out.stdout.strip()
def authed_client() -> Client:
return Client(MCP_URL, auth=BearerAuth(token=fetch_token()))
Cada agente cambia entonces en dos líneas — un import, y lo que le pasa a MCPAdapter:
from mcp_auth import authed_client
async with MCPAdapter(authed_client()) as adapter:
MCPAdapter acepta un Client ya configurado igual de bien que una URL, cosa que\nla parte 3 usó para el caché sin necesitarlo\npara nada más. Aquí es lo que deja entrar el token.
BearerAuth es la forma explícita. FastMCP también acepta el token como cadena pelada —\nClient(url, auth=token) — y añade el esquema él mismo; su documentación es específica en que\n\"do not include the Bearer prefix\" si haces eso. La clase merece el import extra aquí solo\nporque deja la intención clara en el punto de llamada.
BearerAuth guarda una cadena fija. Un token emitido al arrancar el agente está muerto 300\nsegundos después, y nada lo renueva — la renovación automática era justo lo que\nClientCredentialsOAuthProvider nos habría dado. Para una ejecución corta da igual. Para un\nagente que espera a una persona, como\nhace el reembolso de la parte 3,\nperfectamente puede importar. O subes la vida del token en el proveedor, o lo emites por llamada\nen vez de por cliente.
Descubrir no es ejecutar. Un token que lista herramientas todavía podría fallar en la llamada,\nasí que comprueba lo que toca la base de datos:
\nTOOLS=$(~/mcp-auth/token.sh mcp:invoke)
curl -sS -X POST http://127.0.0.1:8770/mcp \\
-H \"Authorization: Bearer $TOOLS\" \\
-H 'Content-Type: application/json' \\
-H 'Accept: application/json, text/event-stream' \\
-d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"find_customer\",\"arguments\":{\"query\":\"Maria\"}}}' \\
| tr -d '\\r' | sed -n 's/^data: //p' | jq -c '.result.content[0].text // .error'
\"[{\\\"id\\\":1,\\\"name\\\":\\\"Maria Alvarez\\\",\\\"email\\\":\\\"maria@example.com\\\"}]\"
![\"Una](\"https://development-wec.wiline.com/docs/es/assets/images/h6-tool-call-authorised-d181de9df9cf4ce219d07511a7b381d2.png\")
Quita la cabecera Authorization y la misma llamada devuelve 401. Una fila real con token, nada\nsin él — eso es autenticación llegando hasta la ejecución, no solo hasta el catálogo.
Puedes poner un verificador de JWT delante de un servidor de herramientas MCP para que rechace a\nquien llama sin identificarse y rechace tokens válidos emitidos a otro cliente — y leer el log\ndel servidor para saber cuál de emisor, audiencia, scope o caducidad hizo el rechazo.
Token exchange failed (404): Not FoundClientCredentialsOAuthProvider contra un servidor con JWTVerifier. El descubrimiento no\nencontró nada y el cliente se replegó a adivinar. Mira el Paso 5; usa BearerAuth.
2 validation errors ... Missing required argumentEl token estaba bien — esto viene de dentro de la herramienta. params.name es el nombre de la\nherramienta, params.arguments son sus parámetros, y ambos anidan un campo llamado name.\nfind_customer recibe query.
invalid_tokenLo filtraste con grep. Mira el aviso del Paso 4.
\nEs lo esperado. Se conectan sin token. Paso 5.
\nHecho: un servidor MCP que autentica a cada quien llama, una credencial que no es la del\ngateway, un rechazo que ocurre en el emisor y no en lo hondo de la comprobación de scope, y un\nlog que nombra a qué cliente se le negó el paso y por qué.
\nSin hacer:
\nissue_refund to anything that isn't billing.\" La mitad ya es cierta: la llamada está\nautenticada. La otra mitad no. required_scopes es una propiedad del servidor, no de una\nherramienta, así que cualquiera con mcp:invoke puede llamar a issue_refund con la misma\nfacilidad que a find_customer, y el servidor sigue sin poder distinguir al scheduler del\nagente de facturación. Repartir herramientas por agente, como\nhizo la parte 4, sigue siendo un arreglo del lado del\ncliente.La autorización por herramienta es el hueco obvio y no tiene una respuesta obvia.\nrequired_scopes protege el servidor; proteger issue_refund de forma distinta a\nfind_customer significa o un segundo servidor con su propio cliente, o autorización dentro del\ncuerpo de cada herramienta leyendo los claims ya verificados. Lo primero son más cajas y una\nfrontera limpia. Lo segundo es una comprobación en cada herramienta que escribas jamás, que es\nprecisamente el modo de fallo del que\navisaba la parte 4 para la política dentro de la\nherramienta.
![\"LiteLLM\"](\"https://development-wec.wiline.com/docs/es/assets/images/litellm-wordmark-86d6f0432720b27534e05bc579dfc29c.png\")
La Parte 4 puso control de acceso por\ngrupos sobre la interfaz de administración del gateway y después, al final, llamó a la API\ndesde un shell sin cuenta, sin sesión y sin grupo. Respondió con normalidad. La conclusión fue\nque el SSO protege un plano de control y que el plano de datos autentica a quien llama por\nmáquina con claves — cosa que tiene que hacer, porque un agente que corre a las 3 de la\nmañana no puede completar un login en un navegador.
\nEso era cierto y era también un punto y aparte, no una respuesta. \"Los clientes máquina usan\nclaves\" te deja con una credencial que nunca expira, que ningún proveedor de identidad conoce,\ny que sobrevive a la persona que la creó. La Parte 4 lo dijo sin rodeos: sacar a alguien de un\ngrupo no revoca sus claves, una clave filtrada no se ve afectada por la identidad en absoluto,\ny las claves sobreviven a las personas.
\nEsta parte le da a la máquina una identidad en lugar de una clave.
\nauthentik le emite al agente un token con el flujo de client credentials — sin navegador,\nsin pantalla de consentimiento, sin humano. El token va firmado, lleva un scope y expira a los\ncinco minutos. El gateway lo verifica localmente contra las claves públicas de authentik y\nrechaza cualquier cosa sin el scope correcto. Al final, tres códigos de estado enseñan el\nlímite aguantando.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB RAM, Docker 29.1.3, kernel 5.15. authentik\n2026.8.1, la misma instancia de las Partes 3 y 4 en el puerto host 9100. LiteLLM 1.96.2\nde la Parte 1 de la serie del gateway,\nenlazado a 127.0.0.1:4000, con los modelos servidos por WEC Inference. La verificación usa\nPyJWT 2.13.0 y cryptography 50.0.0, ambos ya presentes en la imagen de LiteLLM.
HTTP plano sobre una LAN privada, como en las Partes 3 y 4. Sustituye las direcciones por las\ntuyas.
Las Partes 3 y 4 usaron el flujo de authorization code de principio a fin. Una persona\npulsa un botón, se le redirige a authentik, escribe una contraseña, ve una pantalla de\nconsentimiento, y vuelve con un código que la aplicación intercambia por un token. Cada paso\nde eso da por hecho un navegador y una persona sentada delante.
\nEl flujo de client credentials responde otra pregunta. No hay usuario. El cliente es el\nprincipal, y lo demuestra con un ID y un secreto, en una sola petición, sin redirección a\nninguna parte.
\n\nLa propiedad que merece atención: el gateway nunca le pregunta a authentik si un token es\nbueno. Descarga las claves públicas de authentik una vez, las cachea, y comprueba la firma\nella misma. La identidad escala sin que el proveedor de identidad se convierta en un cuello de\nbotella — ni en un punto único de fallo en cada petición.
\nLITELLM_MASTER_KEY, y acceso por shell a la máquinaApplications → Providers → New Provider → OAuth2/OpenID Provider → Next.
\nagent-gatewaydefault-provider-authorization-explicit-consent. Es\nobligatorio, y aquí es inerte: gobierna la pantalla de consentimiento que ve una persona, y\nninguna persona va a usar este cliente. Aun así tienes que elegir uno.Después baja hasta Grant Types, y mira con qué viene un proveedor nuevo.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-grant-types-default-a874ef714983fd8cd1c64bf2b966cb09.png\")
Siete de ocho, activados por defecto. Dos de ellos — Implicit y Password — no llegaron\na OAuth 2.1, que dice claramente que \"some features available in OAuth 2.0, such as the\nImplicit or Resource Owner Credentials grant types, are not specified in OAuth 2.1\"\n(§10.1).\nPassword en concreto hace que el cliente maneje la contraseña real del usuario, y por eso cayó\nen desuso. Nadie te preguntó si los querías y nada te avisa de que están puestos.
\nDesmarca todo excepto Client credentials.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-grant-types-scoped-d5992f14733c7ab87134b9a587a05c87.png\")
Es el mismo reflejo de mínimo privilegio que la Parte 4 aplicó a la pertenencia a grupos, una\ncapa más abajo. Un cliente que solo va a usar un flujo debería tener permitido solo un flujo,\npara que una mala configuración en otro sitio no pueda convertirlo en un endpoint que acepta\ncontraseñas.
\nEsos valores por defecto se aplicaron también a todos los proveedores que creaste en las\nPartes 3 y 4, y nada los ha recortado desde entonces. Pregúntale a la base de datos, no a la\ninterfaz:
cd ~/authentik && docker compose exec server ak shell -c \"
from authentik.providers.oauth2.models import OAuth2Provider
for p in OAuth2Provider.objects.all():
print(f'{p.name}: {p.grant_types}')\" 2>/dev/null | tail -5
Provider for Langfuse: ['authorization_code', 'implicit', 'urn:ietf:params:oauth:grant-type:device_code']
Provider for LiteLLM: ['authorization_code', 'implicit', 'hybrid', 'refresh_token', 'client_credentials', 'password', 'urn:ietf:params:oauth:grant-type:device_code']
agent-gateway: ['client_credentials']
El proveedor del gateway sigue teniendo password y client_credentials además del flujo\nque realmente usa. Ninguno hacía falta, y el flujo de contraseña en particular es una vía de\nentrada viva que nadie puso a propósito. Recorta cada proveedor a los flujos que usa.
Lee el texto de ayuda del propio authentik en el campo Redirect URIs: \"If no explicit\nauthorization redirect URIs are specified, the first successfully used authorization redirect\nURI will be saved.\"
Vacío no significa \"denegar todo\". Significa confianza en el primer uso — authentik fija la\nredirección que aparezca primero y la conserva. Eso es inofensivo para un cliente que nunca\nredirige, que es nuestro caso. No es inofensivo en un proveedor interactivo, donde significa\nque no tienes ninguna validación de redirección hasta que alguien inicia sesión y te la fija.\nLa Parte 3 avisaba de poner el modo en .*; esta es la versión silenciosa del mismo peligro.
Lee las credenciales e intenta obtener un token. Todavía no va a funcionar, y la razón es lo\nmás útil de este post.
\nmkdir -p ~/agent-auth
cd ~/agent-auth
umask 077
cat > .env <<EOF
AK_TOKEN_URL=http://10.80.4.212:9100/application/o/token/
AK_CLIENT_ID=<el client id de la página del proveedor>
AK_CLIENT_SECRET=<el client secret de la página del proveedor>
EOF
umask 077 crea el fichero con permisos 600 en vez de hacer chmod después, así que no hay\nninguna ventana en la que el secreto sea legible por todo el mundo.
Un pequeño ayudante, porque vas a pedir tokens constantemente:
\ncat > ~/agent-auth/token.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
source \"$(dirname \"$0\")/.env\"
curl -sS -X POST \"$AK_TOKEN_URL\" \\
-d grant_type=client_credentials \\
-d client_id=\"$AK_CLIENT_ID\" \\
-d client_secret=\"$AK_CLIENT_SECRET\" \\
-d scope=\"${1:-}\" \\
| jq -r .access_token
EOF
chmod +x ~/agent-auth/token.sh
Pide un token:
\ncd ~/agent-auth
source .env
curl -sS -X POST \"$AK_TOKEN_URL\" \\
-d grant_type=client_credentials \\
-d client_id=\"$AK_CLIENT_ID\" \\
-d client_secret=\"$AK_CLIENT_SECRET\" | jq
{
\"error\": \"invalid_grant\",
\"error_description\": \"The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client\",
\"request_id\": \"757c397b97a745259e288b6d4ff1553c\"
}
Cada cláusula de esa descripción es falsa en nuestro caso. Nada ha expirado, nada está\nrevocado, no se usó ninguna redirección, y el cliente es el dueño de esas credenciales. El log\ndel servidor registra el 400 y ninguna razón. Los Events de authentik tampoco enseñan nada\nútil.
\nLa causa real se ve en la lista de Providers, que lo marca sin disimulo:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h5-provider-unassigned-f6f2e4435e386fcaa6db74ac117566a4.png\")
Un proveedor sin aplicación no puede emitir un token. authentik autoriza contra la\naplicación, así que un proveedor por su cuenta no tiene contra qué autorizar — y dice\ninvalid_grant en lugar de decir eso.
Esto no está en la documentación de client credentials de authentik, que documenta cinco formas\nde autenticarse — tres con credenciales estáticas y dos con JWT — y no dice nada sobre\nnecesitar una aplicación.
\nEmpareja una. Fíjate en la ruta: el asistente de New Application siempre crea un proveedor\nnuevo, así que no puede adoptar el que acabamos de construir.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-application-created-4cf5cd7238257dde87681d0c92e34efd.png\")
Su lista de pasos lo delata — Choose a Provider es el paso 2, y todas las opciones de ahí\nconstruyen uno nuevo. La flecha junto al botón es donde vive el otro camino.
\nApplications → Applications → New Application ▾ → with Existing Provider…
\nAgent Gatewayagent-gateway, escrito a mano. El hallazgo de la Parte 4 fue que authentik\nderiva los slugs de los nombres y convirtió LiteLLM en lite-llm; el slug acaba en la URL\ndel emisor, así que merece la pena ponerlo a mano siempre.agent-gatewayRepite la petición de token y funciona. No cambió nada salvo el emparejamiento.
\nEl token que obtienes ahora lleva \"scope\": \"\". Demuestra quién llama y no concede ninguna\nautoridad. Un gateway que lo reciba sabe que el cliente es agent-gateway y nada más.
Customization → Property Mappings → New Property Mapping → Scope Mapping.
\ngateway-invoke, la etiqueta del objeto dentro de authentikgateway:invoke, la cadena que piden los clientes y que aparece en el tokenreturn {}![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-scope-mapping-93c6d51e31e1b4e0e089d72f023f4714.png\")
Los dos campos de nombre son cosas distintas y el formulario no lo deja claro. La expresión es\nPython cuyo valor de retorno se fusiona con los claims del token; un diccionario vacío es lo\ncorrecto aquí, porque queremos el scope nombrado en el token, no datos extra dentro de él.
\nAdjúntalo: Applications → Providers → agent-gateway → Edit → Advanced protocol settings →\nScopes, y mueve gateway-invoke de Available a Selected.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/h5-provider-scopes-1cf3161c12ea30bfd90af1bc227bb8d1.png\")
Lee el texto de ayuda bajo ese panel, porque es todo el mecanismo:
\n\n\n\"Select which scopes can be used by the client. The client still has to specify the scope to\naccess the data.\"
\n
Adjuntar un scope lo hace disponible. El cliente todavía tiene que pedirlo. Por eso el primer\ntoken volvió vacío aunque ya había tres scopes adjuntos — nadie los había pedido.
\nLa lista doble marca entradas para borrado cuando las pulsas en la columna derecha, y la única\nseñal es una línea de texto pequeño encima que dice \"4 items selected. 1 item marked to\nremove.\" Guardar en ese momento desvincula en silencio el scope que acabas de añadir. Lee esa\nlínea antes de guardar.
Ahora pídelo:
\nTOKEN=$(~/agent-auth/token.sh gateway:invoke)
jq -R 'split(\".\")[1] | gsub(\"-\";\"+\") | gsub(\"_\";\"/\") | @base64d | fromjson' <<< \"$TOKEN\"
{
\"iss\": \"http://10.80.4.212:9100/application/o/agent-gateway/\",
\"sub\": \"2451c6a1bab3085590263f119e650448beb013336146bcfee8241dd5832c200b\",
\"aud\": \"aObZ8KvKsKVdQ4MuSsTINp0f65Puz5fzXUUBC6iQ\",
\"exp\": 1788901322,
\"iat\": 1788901022,
\"acr\": \"goauthentik.io/providers/oauth2/default\",
\"jti\": \"NRDTukijwLJbW7gpPtn9zUZwzTj6d2kBSZCuFYvX\",
\"azp\": \"aObZ8KvKsKVdQ4MuSsTINp0f65Puz5fzXUUBC6iQ\",
\"uid\": \"neugHWoWQOQzADgbV1vKwzew2COQ1RgCXfyywgqa\",
\"scope\": \"gateway:invoke\"
}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-token-scoped-83408e96e6123963ab117fedea8d70de.png\")
exp menos iat son 300 segundos. Ese es el argumento entero a favor de esto frente a una\nclave estática: un token pegado en un chat, en un fichero de log o en una captura no vale nada\ncinco minutos después.
Ahí no hay email ni preferred_username, porque no hay usuario. sub es una cuenta de\nservicio que authentik creó por ti, llamada ak-agent-gateway-client_credentials — aparece en\nDirectory → Users sin que nadie la pidiera.
LiteLLM documenta la autenticación con JWT con un bloque litellm_jwtauth,\nenforce_scope_based_access y scope_mappings. Configúralo en una instalación estándar y no\npasa nada, porque esa misma página dice:
\n\n\"JWT-based Auth requires a LiteLLM Enterprise license.\"
\n
Compruébalo antes de escribir configuración:
\ndocker exec llm-gateway python -c \"
from litellm.proxy.proxy_server import premium_user
print('premium_user =', premium_user)\"
premium_user = False
False significa que todo ese camino documentado está cerrado para ti. La alternativa de\ncódigo abierto es custom_auth, que le pasa cada petición a una función que escribes tú — y\npara este trabajo son unas veinticinco líneas.
Con custom_auth puesto, todas las peticiones pasan por tu función, incluidas las claves\nvirtuales sk- del resto de la serie del gateway y la propia master key. Un handler que\nsolo entienda JWT te deja fuera de tu propio gateway. El de abajo cae de vuelta a la master\nkey a propósito.
Haz copia de seguridad antes de empezar: cp config.yaml config.yaml.bak
import os
import jwt
from fastapi import Request
from litellm.proxy._types import UserAPIKeyAuth
JWKS_URL = os.environ[\"JWT_PUBLIC_KEY_URL\"]
ISSUER = os.environ[\"JWT_ISSUER\"]
AUDIENCE = os.environ[\"JWT_AUDIENCE\"]
REQUIRED_SCOPE = \"gateway:invoke\"
MASTER_KEY = os.environ[\"LITELLM_MASTER_KEY\"]
_jwks = jwt.PyJWKClient(JWKS_URL)
async def user_api_key_auth(request: Request, api_key: str) -> UserAPIKeyAuth:
token = api_key.removeprefix(\"Bearer \").strip()
# No es un JWT: cae a la master key para que las herramientas existentes sigan funcionando.
if token.count(\".\") != 2:
if token == MASTER_KEY:
return UserAPIKeyAuth(api_key=token)
raise Exception(\"not a JWT and not the master key\")
signing_key = _jwks.get_signing_key_from_jwt(token)
claims = jwt.decode(
token,
signing_key.key,
algorithms=[\"RS256\"],
issuer=ISSUER,
audience=AUDIENCE,
)
if REQUIRED_SCOPE not in claims.get(\"scope\", \"\").split():
raise Exception(f\"token is missing scope {REQUIRED_SCOPE}\")
return UserAPIKeyAuth(api_key=token, user_id=claims[\"sub\"])
PyJWKClient hace la parte que parece difícil. Descarga el JWKS, empareja la cabecera kid\ndel token con la clave correcta, y la cachea — así que después de la primera petición la\nverificación es aritmética local. jwt.decode comprueba la firma, el emisor, la audiencia y la\nexpiración en una sola llamada, y lanza excepción si alguna falla.
Tres variables de entorno, añadidas a ~/llm-gateway/.env:
JWT_PUBLIC_KEY_URL=http://10.80.4.212:9100/application/o/agent-gateway/jwks/
JWT_ISSUER=http://10.80.4.212:9100/application/o/agent-gateway/
JWT_AUDIENCE=aObZ8KvKsKVdQ4MuSsTINp0f65Puz5fzXUUBC6iQ
JWT_ISSUER y JWT_AUDIENCE tienen que coincidir exactamente con el iss y el aud que\nviste en el token decodificado, o se rechazan todos los tokens.
Monta el módulo igual que el gateway ya monta scrubber.py, en docker-compose.yml:
- ./jwt_auth.py:/app/jwt_auth.py:ro
Y en config.yaml, bajo general_settings:
custom_auth: jwt_auth.user_api_key_auth
custom_auth_run_common_checks: true
Esa segunda línea importa más de lo que parece. Sin ella, LiteLLM avisa al arrancar:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-custom-auth-warning-863f445ce677a95c6cf806de7ecfc4c7.png\")
\n\n\"custom_auth is configured but 'custom_auth_run_common_checks' is not set. Problem: budgets,\nmodel-access allowlists, and per-model rate limits configured on your DB team/project records\nwill NOT be enforced for custom-auth requests.\"
\n
Léelo con calma. Añadir autenticación por token habría dejado, por defecto, a todos los\nportadores de un token exentos de los controles que ya tenías configurados. Habrías hecho el\ngateway más seguro en una dimensión y más débil en otra sin enterarte, y el único aviso es una\nlínea al arrancar.
\nconfig.yaml es un bind mount. Cambiar su contenido no cambia ninguna parte de la\nespecificación de compose, así que docker compose up -d informa\nContainer llm-gateway Running y no hace nada. Tus pruebas corren entonces contra el proceso\nviejo y reproducen los resultados viejos exactamente, lo que parece que tu cambio no tuvo\nefecto.
Usa docker restart llm-gateway, y confírmalo viendo desaparecer el aviso de arriba del log.
TOKEN=$(~/agent-auth/token.sh gateway:invoke)
NOSCOPE=$(~/agent-auth/token.sh)
curl -sS -o /dev/null -w 'no token HTTP %{http_code}\\n' http://127.0.0.1:4000/v1/chat/completions \\
-H 'Content-Type: application/json' \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Say OK.\"}]}'
curl -sS -o /dev/null -w 'wrong scope HTTP %{http_code}\\n' http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $NOSCOPE\" -H 'Content-Type: application/json' \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Say OK.\"}]}'
curl -sS -o /dev/null -w 'valid token HTTP %{http_code}\\n' http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $TOKEN\" -H 'Content-Type: application/json' \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Say OK.\"}]}'
no token HTTP 401
wrong scope HTTP 401
valid token HTTP 429
![\"Tres](\"https://development-wec.wiline.com/docs/es/assets/images/h5-three-status-codes-0db858ce4b80dda45f7c2626ec09529c.png\")
Las dos primeras no llegan a ningún modelo. La segunda es la que importa: un token válido,\ncorrectamente firmado, sin expirar y del emisor correcto, rechazado porque no llevaba\ngateway:invoke. La identidad por sí sola no es autoridad.
La tercera es la interesante, y no es un 200. Pasó la autenticación y el scope, y la respondió\nuna parte completamente distinta del gateway — la capa de presupuesto y enrutado que\nconfigura la serie del gateway, que en esta\nmáquina ya tenía un tope alcanzado. Ese es el sentido de la forma, no un fallo en ella: un 401\nsignifica no sabemos quién eres, o no puedes hacer esto, y cualquier otra cosa significa que\nla petición pasó la identidad por completo y ahora es decisión de otro. El trabajo de la\nautenticación termina en las dos primeras líneas.
\nConfirma que el rechazo vino de tu comprobación y no de otra cosa:
\ndocker logs llm-gateway --since 10m 2>&1 | grep -iE 'missing scope|401 Unauthorized' | tail -5
user_api_key_auth(): Exception occured - token is missing scope gateway:invoke
Exception: token is missing scope gateway:invoke
INFO: \"POST /v1/chat/completions HTTP/1.1\" 401 Unauthorized
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/h5-scope-refusal-log-aec61cc01ab970a987dee6c534e39c59.png\")
Fíjate en dónde vive esa razón. Quien llama recibe un 401 pelado sin explicación, y está bien\n— decirle a un cliente \"tu token es válido pero le falta el scope X\" le dice a un atacante\nexactamente qué tiene que ir a buscar. Eso sí significa que depurar esto pasa siempre por leer\nel log del gateway, y nunca por el cuerpo de la respuesta.
\nPuedes darle a un agente headless su propia identidad: un cliente confidencial restringido a un\nsolo flujo, un scope que significa algo, y un gateway que verifica la firma localmente y\nrechaza cualquier cosa sin el scope — con el rechazo demostrado desde el log en vez de supuesto\ndesde un código de estado.
invalid_clientLas credenciales no autenticaron en absoluto. Antes de culpar a authentik, mira qué acabó de\nverdad en tu .env:
awk -F= '{printf \"%-18s %3d chars\\n\", $1, length($2)}' ~/agent-auth/.env
AK_TOKEN_URL 48 chars
AK_CLIENT_ID 40 chars
AK_CLIENT_SECRET 128 chars
El client ID tiene 40 caracteres y el secreto 128. Un valor de longitud cero significa que el\nproblema es el fichero, no el proveedor.
\ninvalid_grant, con todo aparentemente correctoEl proveedor no está emparejado con una aplicación. Mira el Paso 2 — la lista de Providers lo\nseñala, el texto del error no.
\nAK_TOKEN_URL: unbound variable, y un secreto corruptoecho 'X=1' >> .env sobre un fichero cuya última línea no termina en salto de línea añade a\nesa línea en vez de crear una nueva:
AK_CLIENT_SECRET=p94oDU...dgJcAK_TOKEN_URL=http://10.80.4.212:9100/application/o/token/
Dos variables destruidas con un solo comando, en silencio — el secreto ahora está mal y la\nvariable nueva no existe. Compruébalo con cat -A, que marca los finales de línea con $, y\nprefiere escribir el fichero entero con un solo heredoc antes que ir añadiendo.
El contenedor nunca se reinició. Mira el aviso del Paso 4.
\n401 sin ninguna razón en la respuestaEs a propósito. La razón está en docker logs llm-gateway.
Hecho: una identidad de máquina emitida por tu proveedor de identidad en vez de acuñada a mano,\nuna credencial que expira en cinco minutos, un scope que hay que pedir y que se comprueba en\ncada llamada, revocación en un solo sitio, y alguien a quien el gateway puede nombrar en sus\nlogs como algo más que un prefijo de clave.
\nSin hacer:
\nissue_refund incluido. El mismo problema, una\ncapa más arriba, y el tema de la próxima parte.scope_mappings entre scopes y modelos es a dónde va eso.ak-agent-gateway-client_credentials sin preguntar, y nada en el token dice que sea una\nmáquina y no una persona.El servidor MCP. FastMCP trae un JWTVerifier que acepta un jwks_uri, un issuer, una\naudience y required_scopes — las mismas cuatro cosas configuradas aquí — así que el\nservidor de herramientas puede exigir un token con scope antes de listar una herramienta, no\ndigamos ejecutarla. Eso cierra el hueco que dejó abierto la Parte 4 de orquestación de agentes,\ndonde el recorte pasaba en el cliente y el servidor se fiaba de quien alcanzara el puerto.
PyJWKClientLa Parte 3 le dio a un agente cinco\nherramientas por MCP — un calendario, una lista de clientes, facturas y un reembolso — y puso a\nun humano delante del reembolso. Terminó admitiendo lo evidente: un solo agente tenía las\ncinco. Nada impedía que el modelo echara mano de issue_refund cuando se le había pedido\nreservar una cita. La pausa humana era lo único que se interponía, y una pausa solo se dispara\nsi el modelo llega a llamar la herramienta.
Esta parte quita la herramienta en su lugar. El de agenda recibe tres y el de facturación tres,\ncompartiendo una. Pídele al de agenda que reembolse una factura y no puede — no porque se le\nhaya dicho que no, no porque una política lo bloquee, sino porque issue_refund nunca estuvo en\nla lista que se le dio.
Luego el supervisor de la Parte 2 vuelve\nencima, y sale a la luz la propiedad interesante: el enrutado decide quién trabaja, el alcance\ndecide qué es posible. Un reembolso mal enrutado sigue sin poder reembolsar.
\n\nLa misma caja, servidor y base de datos que la\nParte 3: una WEC Instance, Ubuntu 22.04,\nPython 3.10, langchain 1.4.0, langgraph 1.2.11, mcp 2.1.1, fastmcp 4.0.2.\noffice_tools.py sin cambios y sirviendo aún cinco herramientas en 127.0.0.1:8770. Modelos a\ntravés del gateway LiteLLM hacia WEC Inference. Reinicia la base de datos con\n./.venv/bin/python seed.py antes de seguir, para que la factura 2 vuelva a estar abierta.
No hay ningún mecanismo nuevo en este post. create_agent recibe una lista de herramientas;\nnosotros le pasamos una lista más corta. Esa es toda la técnica, y vale la pena ser preciso\nsobre por qué es más fuerte que las alternativas:
La última es la única que no depende de que la inferencia salga bien.
\nEl servidor ofrece las cinco a quien pregunte. Lo que cambia es cuáles se le entregan a cada\nagente. find_customer va a los dos, porque buscar un cliente es inofensivo.
La flecha bloqueada es todo el post. El de agenda no puede llamar a issue_refund — no porque\nuna regla se lo prohíba, sino porque la herramienta no está en la lista que se le dio, así que\nnunca llega a su contexto.
~/mcp-tools/.env, como la dejó la Parte 3La Parte 3 ejecutaba el servidor en primer plano, lo que costaba una terminal y moría con la\nsesión SSH. Arráncalo en segundo plano — con una sola sesión basta para todo lo que sigue:
\ncd ~/mcp-tools && nohup ./.venv/bin/python office_tools.py > server.log 2>&1 & sleep 3; ss -tlnp | grep 8770
El servidor sigue ofreciendo cinco herramientas. Los roles nombran subconjuntos de ellas:
\nimport asyncio, os, sys
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
MCP_URL = \"http://127.0.0.1:8770/mcp\"
ROLES = {
\"scheduler\": (\"find_customer\", \"list_availability\", \"book_slot\"),
\"billing\": (\"find_customer\", \"open_invoices\", \"issue_refund\"),
}
model = ChatOpenAI(
base_url=\"http://127.0.0.1:4000/v1\",
api_key=os.environ[\"GATEWAY_KEY\"],
model=\"qwen-mid\",
temperature=0,
)
async def main():
role, request = sys.argv[1], sys.argv[2]
async with MCPAdapter(MCP_URL) as adapter:
catalog = {t.name: t for t in await adapter.list_tools()}
print(f\"server offers : {sorted(catalog)}\")
allowed = [catalog[n] for n in ROLES[role]]
print(f\"{role} can see : {[t.name for t in allowed]}\\n\")
agent = create_agent(model, allowed, checkpointer=InMemorySaver())
cfg = {\"configurable\": {\"thread_id\": f\"{role}-1\"}}
out = await agent.ainvoke({\"messages\": [{\"role\": \"user\", \"content\": request}]}, cfg)
if \"__interrupt__\" in out:
req = out[\"__interrupt__\"][0].value[\"requests\"][0]
print(f\"PAUSED — the server is asking a human:\\n {req['message']}\")
return
print(\"--- answer ---\")
print(out[\"messages\"][-1].content)
asyncio.run(main())
El checkpointer viene de la\nParte 3: issue_refund pausa la ejecución con\nun interrupt, y una ejecución interrumpida necesita algún sitio donde esperar. El de agenda nunca\ndispara uno, pero ambos roles ejecutan el mismo código.
Toda la técnica es una línea:
\nallowed = [catalog[n] for n in ROLES[role]]
find_customer aparece en ambos roles — buscar un cliente es inofensivo y los dos trabajos lo\nnecesitan. book_slot e issue_refund aparecen en exactamente uno cada una.
El script imprime ambas listas en cada ejecución por una razón. server offers es el catálogo\ncompleto que devolvió el servidor MCP; can see es lo que le pasamos a create_agent. Tenerlas\nuna al lado de la otra deja claro que el servidor no ocultó nada — el estrechamiento ocurrió\nen el cliente, en la línea de arriba.
Pídele al agente de facturación que haga su trabajo:
\ncd ~/mcp-tools && set -a && source .env && set +a && ./.venv/bin/python scoped.py billing \"Refund Maria's open invoice.\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-billing-paused-6de8f7f7d8c481db7073918444d88e53.png\")
Encontró a Maria, resolvió \"factura abierta\" como la factura 2, llamó a issue_refund y se\ndetuvo — porque la herramienta exige un humano. Esa es la guarda de la Parte 3, funcionando.
Ahora la frase idéntica al especialista equivocado:
\ncd ~/mcp-tools && ./.venv/bin/python scoped.py scheduler \"Refund Maria's open invoice.\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-scheduler-refused-080822f69c551c7655e8e5fa5093178b.png\")
\n\nI don't have access to tools that can process refunds or handle invoices. The available tools\nI have are for finding customers, listing appointment availability, and booking appointment\nslots.
\n
Esa respuesta es exacta y educada, y sería un error leerla como que el modelo se portó bien. El\nmodelo no podía llamar a issue_refund. Nunca estuvo en la lista, así que nunca estuvo en\nel contexto, así que no había ninguna llamada que rechazar.
La distinción importa porque un modelo que sí tiene una herramienta peligrosa también puede\nproducir una frase educada — incluida una que describa una acción que nunca realizó.\nDocumentamos exactamente eso en la pieza de noticias: un\nerror de era entregado al modelo, y el modelo narrando una aprobación que nadie iba a pedir\njamás. Un rechazo en el que puedes confiar es uno que el modelo no tenía forma de rodear.
Y el de agenda haciendo el trabajo para el que sí tiene herramientas, para que la restricción\nsea dirigida y no paralizante:
\ncd ~/mcp-tools && ./.venv/bin/python scoped.py scheduler \"Book Maria into a free slot on 2026-09-05\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-scheduler-books-56592bddc8b3d38f6f2f0f8d8aaf64ec.png\")
Un rechazo es una frase. La base de datos es la evidencia.
\ncd ~/mcp-tools && ./.venv/bin/python -c \"
import sqlite3
for r in sqlite3.connect('office.db').execute('select id, customer_id, amount, status from invoices'): print(r)\"
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-nothing-happened-3c326c0194b72bcc27c1a87d9a2d05f7.png\")
La factura 2 sigue open, por dos razones distintas: el de agenda no tenía herramienta para\ncambiarla, y el de facturación fue detenido por la puerta humana antes de poder hacerlo. Ninguna\ndependió de que el modelo eligiera bien.
Vale la pena ver también al mismo agente informar de una verdad aburrida. Antes de reiniciar la\nbase de datos, la factura 2 ya se había reembolsado en la Parte 3 — y al pedirle reembolsarla de\nnuevo, facturación miró, no encontró nada abierto, y lo dijo:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-billing-nothing-open-b4f526ef9e6865039b0aefe2909f7918.png\")
Sin factura inventada, sin confirmación entusiasta. Ese es el comportamiento que hace que sus\notras respuestas valgan algo, y no es algo que dar por hecho — es algo que comprobar, y por eso\ncada afirmación de este post tiene una consulta detrás.
\nPuedes dar a dos agentes porciones distintas del mismo servidor MCP, de modo que una capacidad\nque uno de ellos nunca debe tener esté ausente de su contexto en lugar de prohibida por\ninstrucción — y verificar en los datos que la ausencia se sostuvo.
La Parte 2 repartía trabajo entre un agente de agenda y uno de facturación que no tenían\nherramientas. Ahora las tienen.
\nsupervisor.py es scoped.py con el grafo de la Parte 2 alrededor: los mismos ROLES,\nMCPAdapter y ChatOpenAI, más un State TypedDict, un StateGraph, y un agente construido\npor rol dentro del bloque async with — agents = {role: create_agent(model, [catalog[n] for n in names]) for role, names in ROLES.items()}. Aquí solo se muestran las partes nuevas de este\npost.
BILLING_WORDS = (\"invoice\", \"refund\", \"bill\", \"charge\", \"payment\")
def supervisor(state: State) -> Command[Literal[\"scheduler\", \"billing\"]]:
nxt = \"billing\" if any(w in state[\"request\"].lower() for w in BILLING_WORDS) else \"scheduler\"
print(f\"supervisor routes to {nxt}\")
return Command(goto=nxt, update={\"completed\": [f\"supervisor->{nxt}\"]})
async def run(role: str, state: State):
out = await agents[role].ainvoke(
{\"messages\": [{\"role\": \"user\", \"content\": state[\"request\"]}]})
if \"__interrupt__\" in out:
q = out[\"__interrupt__\"][0].value[\"requests\"][0][\"message\"]
return {\"answer\": f\"PAUSED — {q}\", \"completed\": [role]}
return {\"answer\": out[\"messages\"][-1].content, \"completed\": [role]}
async def scheduler_node(state: State):
return await run(\"scheduler\", state)
async def billing_node(state: State):
return await run(\"billing\", state)
La anotación Command[Literal[\"scheduler\", \"billing\"]] hace el mismo trabajo que en la Parte 2 —\nes la única declaración de a dónde le está permitido al supervisor mandar trabajo, y quitarla\nhace que todos los diagramas del grafo mientan.
cd ~/mcp-tools && set -a && source .env && set +a && ./.venv/bin/python supervisor.py \"Refund Maria's open invoice.\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-supervisor-refund-eff231a6a04d02fc5430fa25025750e6.png\")
cd ~/mcp-tools && ./.venv/bin/python supervisor.py \"Book Maria into a free slot on 2026-09-04\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg4-supervisor-book-cb9829d31562e18281b2165e7fb3bf6e.png\")
Ese supervisor es una coincidencia de palabras clave. Es trivialmente engañable — \"salda el\nimporte pendiente de Maria\" no contiene ninguna de BILLING_WORDS y aterriza en el de agenda.
Que es justo lo que hay que llevarse. Un reembolso mal enrutado sigue sin poder reembolsar.\nEl enrutador decide quién recibe el trabajo; los conjuntos de herramientas deciden qué puede\nhacer ese agente con él. Si el enrutado fuera el único control, cada fallo del supervisor sería\nun fallo de seguridad. Con el alcance por debajo, un error de enrutado es solo una mala\nrespuesta.
Puedes poner un enrutador delante de especialistas acotados y razonar con claridad sobre qué\nfallos son peligrosos — porque el radio de impacto de un error de enrutado está limitado por lo\nque se le dio al agente receptor, no por lo que se le pidió hacer.
InvalidUpdateError: Expected dict, got <coroutine object>El nodo es una función async envuelta en un lambda:
builder.add_node(\"scheduler\", lambda s: run(\"scheduler\", s)) # devuelve una corrutina
LangGraph lo llama, recibe una corrutina en lugar de una actualización de estado, y lanza el\nerror. La pista real es la última línea de la salida — RuntimeWarning: coroutine 'run' was never awaited — que es la parte que nadie lee. Define nodos async def de verdad.
RuntimeError: Client failed to connect: All connection attempts failedNo hay nada escuchando en 8770. Si arrancaste el servidor MCP en un shell en primer plano, murió\ncon tu sesión SSH. El error nombra al cliente, lo que te manda a buscar en el sitio\nequivocado.
\nss -tlnp | grep 8770
Arráncalo con nohup ... & para que sobreviva, y comprueba el puerto antes de culpar al código.
Python almacena la salida en búfer cuando se redirige a un archivo, así que una ejecución larga\nparece idéntica a un cuelgue. Añade -u:
nohup ./.venv/bin/python -u supervisor.py \"...\" > run.log 2>&1 &
tail -f run.log
KeyError: 'GATEWAY_KEY'source .env define variables de shell, no variables de entorno, y export no cruza entre\nsesiones SSH. Cada comando que arranca el agente necesita su propio\nset -a && source .env && set +a — incluidos los que van en segundo plano.
Hecho: dos agentes tomando subconjuntos distintos de un mismo servidor MCP, una capacidad que\nestá ausente en lugar de prohibida, y un enrutador cuyos errores cuestan corrección en vez de\ndinero.
\nNo hecho:
\n127.0.0.1:8770 puede llamar a issue_refund directamente, sea un\nagente o no. Esto controla lo que tus agentes pueden hacer, no lo que tu servidor aceptará.Empujar el límite del cliente al servidor: autenticar la llamada a herramienta, para que el\nservidor sepa qué agente pregunta y le niegue issue_refund a cualquiera que no sea\nfacturación. Esa es la misma pregunta que la\nParte 4 de la serie de endurecimiento hizo\nsobre la propia API del gateway — un plano de control y un plano de datos, a una capa de\ndistancia — y FastMCP ya soporta tokens bearer y OAuth 2.1 para ello.
Command y aristas condicionales2026-07-28La Parte 3 puso authentik delante de Langfuse y\nterminó con una confesión: el paso de vinculaciones quedó vacío, así que cualquier cuenta de\nauthentik podía llegar a Langfuse y nada te avisaría.
\nEsta parte cierra ese hueco en la\ngateway LiteLLM — y el cierre salió mal de una\nforma que vale más que el procedimiento. Configuramos las vinculaciones en el asistente de\nauthentik, las vimos aparecer en la tabla del propio asistente, enviamos, y acabamos con\ncero vinculaciones guardadas. La aplicación estaba abierta a todo el mundo, la interfaz\nno dijo nada, y la única razón por la que lo descubrimos es que probamos con una cuenta que\ndebería haber sido rechazada y no lo fue.
\nDespués, ya con el control de acceso funcionando de verdad, llamamos a la API del gateway\ndesde un shell sin cuenta, sin sesión y sin grupo. Respondió con normalidad. Eso no es un\nfallo — es la diferencia entre un plano de control y un plano de datos, y suponer que\nel SSO cubre ambos es cómo la gente concluye que ha asegurado algo que no ha asegurado.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB RAM, Docker 29.1.3, kernel 5.15.\nauthentik 2026.8.1, la misma instancia de la Parte 3 en el puerto host 9100. LiteLLM\nmain-stable de la Parte 1 de la serie del gateway,\nenlazado a 127.0.0.1:4000, con modelos servidos por WEC Inference.
HTTP plano sobre una LAN privada, como en la Parte 3.
La Parte 3 enseñó el asistente — aplicación, proveedor, URI de redirección, scopes. Eso no se\nrepite; está todo en la Parte 3 y los pasos son\nidénticos para cualquier app. Tres cosas son nuevas:
\nUn grupo, como la unidad a la que concedes acceso, de modo que añadir a alguien a un\nequipo y darle acceso sean la misma acción.
\nUna vinculación, que ata ese grupo a una aplicación, de modo que llegar a ella exija\npertenencia en lugar de meramente existir.
\nUn límite, demostrado en vez de afirmado: qué protege el SSO, y qué no toca en absoluto.
\nLITELLM_MASTER_KEY, que necesitarás para crear una clave virtual127.0.0.1Dos cajas, sin flecha entre ellas — ese es el punto. Todo lo que configura este post vive en\nla de la izquierda. La de la derecha nunca consulta a authentik.
\nTambién hay una tercera vía de entrada que el diagrama deja fuera a propósito, porque no\npertenece a ninguno de los dos planos: la clave maestra de LiteLLM entra directamente a\nla interfaz de administración, saltándose por completo la comprobación de grupo. Nos topamos\ncon ella en el Paso 5.
\nDirectory → Groups → New Group, llámalo gateway-admins, y deja Superuser privileges\ndesactivado. Esa bandera convierte a los miembros en administradores del propio authentik y\nno tiene nada que ver con qué aplicaciones pueden alcanzar.
authentik ya trae tres grupos — authentik Admins, authentik Agent-Users,\nauthentik Read-only — y authentik Admins ya contiene tu akadmin. Vincular ese\nfuncionaría hoy y significaría en silencio \"cualquiera a quien alguna vez haga administrador\nde authentik\", que no es la misma intención.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/ak-groups-list-a17357dbbd4468da8f7232d5487ef77a.png\")
Añade akadmin a gateway-admins. Luego Directory → Users → New User, tipo Internal,\nusuario contractor, y sin ningún grupo.
Internal y no External para que la única diferencia entre las dos cuentas sea la pertenencia\n— cualquier otra diferencia enturbia el resultado. Tampoco Service Account: esas son de\nmáquina a máquina y no hacen inicios de sesión interactivos.
\nauthentik crea usuarios sin contraseña, y el diálogo de edición no tiene campo de contraseña\n— es una acción aparte en la página de detalle del usuario. Desde el shell:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import User
u = User.objects.get(username='contractor')
u.set_password('Contractor123!')
u.save()
print('password set for', u.username)
\" 2>/dev/null | tail -2
ak shellCada llamada a ak shell imprime unas sesenta líneas de JSON de arranque antes de tu salida.\n2>/dev/null | tail -N descarta el ruido y conserva las últimas N líneas. Se usa en todo lo\nque sigue.
Ejecuta el asistente de la Parte 3: aplicación LiteLLM, proveedor OAuth2/OpenID, flujo\nde autorización default-provider-authorization-explicit-consent, tipo de cliente\nConfidential.
El gateway está publicado en 127.0.0.1:4000, así que tu navegador no puede alcanzarlo — y\nun inicio de sesión OIDC ocurre en un navegador. Abre un túnel desde tu equipo:
ssh -L 4000:127.0.0.1:4000 ubuntu@10.80.4.212
ssh -L avisa, y luego sigue sin el túnelSi algo ya ocupa el puerto local 4000, ssh imprime bind: Address already in use y aun así\nte da un shell funcionando — con el reenvío muerto. El único síntoma es\nERR_CONNECTION_REFUSED en el navegador, que parece que el gateway estuviera caído.\nComprueba el puerto antes de culpar al gateway: lsof -nP -iTCP:4000 -sTCP:LISTEN.
Todo lo que el navegador escribe es ahora localhost:4000, así que esa es la URI de\nredirección, modo Strict:
http://localhost:4000/sso/callback
Ahora la primera sorpresa. Pregúntale a authentik cómo llamó realmente a las cosas:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
for a in Application.objects.all():
print(repr(a.name), '->', repr(a.slug))
\" 2>/dev/null | tail -5
'Langfuse' -> 'langfuse'
'LiteLLM' -> 'lite-llm'
lite-llm, no litellm. El generador de slugs leyó las mayúsculas de \"LiteLLM\" y las\nseparó. La Parte 3 dijo que el slug carga peso porque acaba en la URL del emisor, y aquí está:\nhttp://10.80.4.212:9100/application/o/lite-llm/. Fija el slug explícitamente en lugar de\ndejar que un nombre en CamelCase lo genere, o carga ese guion en cada URL para siempre.
Lee las credenciales con el slug real:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
p = Application.objects.get(slug='lite-llm').get_provider()
print('CLIENT_ID :', p.client_id)
print('CLIENT_SECRET:', p.client_secret)
\" 2>/dev/null | tail -3
El paso 4 del asistente es Configure Bindings, y la Parte 3 pasó de largo mostrando\nNo bound policies. Esta vez no pasamos de largo. Vinculamos el grupo ahí, el asistente lo\nlistó en su tabla, y enviamos.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/ak-bindings-wizard-empty-996a2adb20faf53dda84769592740e1c.png\"){kind=spacer}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/ak-bindings-wizard-group-2c88ba715a495db175a3e85cf83df1f9.png\")
Luego le preguntamos a la base de datos qué existía:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
app = Application.objects.get(slug='lite-llm')
bs = list(app.bindings.all())
print('binding count:', len(bs))
for b in bs:
print('group', b.group, '| enabled', b.enabled, '| negate', b.negate)
\" 2>/dev/null | tail -4
binding count: 0
Cero. La propia pestaña de vinculaciones de la aplicación coincidía — No Policies bound.\nDos fuentes independientes, una conclusión: el asistente mostró un control de acceso que\nnunca se escribió.
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/ak-bindings-none-71e30bfc7aa65339a119ee1ccb38d3ab.png\")
La lección de la Parte 3 era \"no te saltes las vinculaciones\". El peligro real es que puedes\ncompletarlas, ver tus reglas en la tabla del asistente, enviar, y acabar con una aplicación\nque admite a todo el mundo — sin error, sin aviso, y con una interfaz que se veía correcta\ntodo el rato.
Una aplicación con cero vinculaciones no está rota de ninguna forma que authentik reporte.\nEstá haciendo exactamente lo que debe: nada vinculado significa que nadie queda excluido.\nVerifica las vinculaciones desde la base de datos o desde la propia pestaña de\nvinculaciones de la aplicación — nunca desde el asistente.
Vincúlalo desde la aplicación en su lugar: Applications → LiteLLM → Policy / Group / User\nBindings → Create or bind…, luego Bind a group bajo Bind Existing… → gateway-admins\n→ Create.
Elige Bind a group en concreto. La sección Choose Policy Type de abajo crea políticas\nnuevas (Event Matcher, Expression, GeoIP); una vinculación de grupo ya es una regla y no\nnecesita ninguna de ellas.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/ak-bind-group-dialog-c20ad52e0f590a4df1c9a5e3aa411963.png\")
Luego verifica, porque la tabla es lo que mintió:
\nbinding count: 1
group Group gateway-admins | enabled True | negate False
Puedes restringir una aplicación a un grupo en lugar de dejarla abierta a toda cuenta — y,\nmás importante, verificar que la vinculación realmente persistió (app.bindings.all()) en\nvez de fiarte de la tabla del propio asistente.
Esa página indica el modo con claridad: \"The currently selected policy engine mode is ANY:\nAny policy must match to grant access.\" Con una sola vinculación, ANY y ALL se comportan\nigual. Con dos no — ANY significa que basta con que una regla pase, así que una\nvinculación suelta de User Contractor junto al grupo concedería exactamente el acceso que\neste post intenta denegar.
LiteLLM lee ajustes OIDC genéricos desde GENERIC_*. Los endpoints salen del documento de\ndescubrimiento:
cat >> ~/llm-gateway/.env <<'EOF'
GENERIC_CLIENT_ID=<client id del Paso 2>
GENERIC_CLIENT_SECRET=<client secret del Paso 2>
GENERIC_AUTHORIZATION_ENDPOINT=http://10.80.4.212:9100/application/o/authorize/
GENERIC_TOKEN_ENDPOINT=http://10.80.4.212:9100/application/o/token/
GENERIC_USERINFO_ENDPOINT=http://10.80.4.212:9100/application/o/userinfo/
PROXY_BASE_URL=http://localhost:4000
EOF
PROXY_BASE_URL es la que muerde. LiteLLM construye su URI de redirección a partir de ella,\nasí que tiene que ser igual a lo que el navegador escribe y a lo que authentik tiene\nregistrado. Las nuestras no coincidieron en el primer intento y produjeron un Redirect URI\nError — el redirect_uri de la barra de direcciones es lo que LiteLLM envió, el valor\nStrict del proveedor es lo que authentik esperaba, y basta un puerto, un nombre de host o una\nbarra final entre ambos para fallar.
El archivo compose del gateway usa env_file: .env, así que a diferencia de Langfuse en la\nParte 3 no hay archivo de override que escribir:
cd ~/llm-gateway && docker compose up -d && docker compose exec litellm env | grep -c GENERIC_
Cinco. Antes de la edición era cero — la misma clase de comprobación que la Parte 3 usó para\ncazar variables que nunca llegaban al proceso.
\nAbre http://localhost:4000/ui a través del túnel. La página de inicio de sesión trae un\nhallazgo que este post no fue a buscar.
Login with SSO aparece, como se pretendía. Encima hay un formulario de usuario y\ncontraseña, y el propio panel de LiteLLM lo explica: \"By default, Username is admin and\nPassword is your set LiteLLM Proxy MASTER_KEY.\"
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/litellm-login-sso-a0616071a645fb27014bfa0b35203eaa.png\")
La clave maestra es un bypass completo. Cualquiera que la tenga llega a la interfaz de\nadministración sin tocar authentik, sin grupo, sin vinculación. Todo lo configurado en los\nPasos 1–3 está junto a una puerta que lo ignora — y la llave de esa puerta es además la\ncredencial raíz del gateway, capaz de acuñar claves de API y alcanzar cualquier modelo.
\nAUTO_REDIRECT_UI_LOGIN_TO_SSO=true manda /ui directo a authentik en lugar de mostrar el\nformulario. Deja de anunciar la vía de contraseña; no la elimina. Trata la clave maestra\ncomo una credencial de emergencia y no confundas el redirect con una solución.
Inicia sesión como akadmin, que está en gateway-admins. authentik muestra la pantalla de\nconsentimiento del flujo explícito de la Parte 3, y aterrizas en el panel en\n/ui/?login=success.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/ak-login-litellm-9e4c240eccffd4f7e739199f9b9c594a.png\")
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/ak-consent-akadmin-ea2ed59007a2b3e896f2d0437553763f.png\")
Ahora contractor.
Abrir \"una ventana privada nueva\" mientras ya hay otra abierta reutiliza las mismas cookies,\nasí que authentik te vuelve a identificar como el usuario anterior. El síntoma es un inicio\nde sesión instantáneo que parece un fallo de tu control de acceso. Cierra todas las\nventanas de incógnito, o usa otro navegador.
Permission denied. Request has been denied.
\n![\"authentik](\"https://development-wec.wiline.com/docs/es/assets/images/ak-contractor-denied-14fb1a97964d42b993f3e49504ecb9dd.png\")
Fíjate en dónde ocurrió: authentik rechazó antes de la pantalla de consentimiento. La\ncomprobación de política corre por delante del consentimiento, así que un usuario bloqueado\nnunca ve la página de permisos — que es también cómo cazamos las vinculaciones ausentes antes.\nCuando contractor llegó a una pantalla de consentimiento, esa fue la pista.
Desde un shell en la caja — sin cuenta de authentik, sin sesión, sin grupo, nada más que una\nclave:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions -H \"Authorization: Bearer sk-...\" -H \"Content-Type: application/json\" -d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Say OK.\"}]}' | jq '{model, answer: .choices[0].message.content}'
{
\"model\": \"qwen-mid\",
\"answer\": \"\\n\\nOK\"
}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/litellm-api-still-open-f3c81e08b6e2981f5cd844d8f236a4ec.png\")
Nada está roto. El SSO nunca se aplicó a ese endpoint. Los Pasos 1–5 protegieron /ui —\nel plano de control, donde las personas crean claves y leen el gasto. El plano de datos en\n/v1/* autentica a los llamantes máquina con claves de API, y tiene que hacerlo: un agente\ncorriendo a las 3 de la madrugada no puede completar un login de navegador con pantalla de\nconsentimiento.
Esa clave se creó a su vez desde un shell, con la clave maestra, sin que existiera ninguna\nsesión SSO en ningún sitio:
\ncd ~/llm-gateway && source .env && curl -s http://127.0.0.1:4000/key/generate -H \"Authorization: Bearer $LITELLM_MASTER_KEY\" -H \"Content-Type: application/json\" -d '{\"key_alias\":\"sso-demo\",\"models\":[]}' | jq -r '.key'
Las consecuencias, dichas sin rodeos, porque \"le pusimos SSO al gateway\" se dice en\nreuniones como si zanjara la cuestión:
\ngateway-admins no revoca sus claves. Pierde la interfaz y conserva\ntodas las claves que creó. Dar de baja son dos acciones; solo una es la que la gente\nrecuerda.El propio modelo de claves del gateway — claves acotadas, presupuestos, caducidad, modelos\npor clave — es lo que cubre ese terreno, y es un mecanismo distinto del configurado aquí.\nComplementario, no sustituible.
\nCon la sesión iniciada como akadmin vía SSO, la página de Virtual Keys no tenía botón\nCreate Key.
LiteLLM asigna a los usuarios SSO un rol por defecto que no es administrador. Pasar la\nvinculación de authentik nos metió dentro de la interfaz; lo que podíamos hacer ahí es el\nmodelo de roles propio de LiteLLM, que nunca configuramos. Autenticación, luego autorización,\nluego roles de aplicación — tres capas distintas, y superar una no dice nada de la siguiente.
\nApplication matching query does not existLa búsqueda de ak shell falla aunque la aplicación se vea en la interfaz. El slug no es el\nque supusiste — authentik lo deriva del nombre, y un nombre en CamelCase como LiteLLM se\nconvierte en lite-llm. Pregunta en vez de adivinar:
cd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
for a in Application.objects.all():
print(repr(a.name), '->', repr(a.slug))
\" 2>/dev/null | tail -5
authentik rechaza antes de cualquier formulario. El redirect_uri de la barra de direcciones\nes lo que LiteLLM envió; el valor Strict del proveedor es lo que authentik espera. Los\nnuestros no coincidían porque PROXY_BASE_URL decía un host y la URI registrada otro. Imprime\nlo registrado y compara carácter por carácter:
cd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
p = Application.objects.get(slug='lite-llm').get_provider()
for r in p.redirect_uris:
print(repr(r.matching_mode), repr(r.url))
\" 2>/dev/null | tail -5
Si lo editas y el error persiste, Applications → Clear cache — authentik cachea la\nconfiguración del proveedor.
\nERR_CONNECTION_REFUSED en localhost:4000El túnel no está reenviando, aunque ssh haya conectado. Si algo ya ocupaba el puerto local,\nssh imprimió bind: Address already in use y siguió con un shell funcional y un reenvío\nmuerto. Comprueba el puerto y reinicia el túnel:
lsof -nP -iTCP:4000 -sTCP:LISTEN
Dos causas, ambas reales aquí. O una vinculación de usuario suelta le concede acceso\ndirectamente — el modo ANY significa que basta con que una regla pase — o las vinculaciones\nnunca se guardaron. Pregunta a la base de datos, no a la interfaz:
\ncd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
app = Application.objects.get(slug='lite-llm')
bs = list(app.bindings.all())
print('binding count:', len(bs))
for b in bs:
print('group', b.group, '| user', b.user, '| enabled', b.enabled, '| negate', b.negate)
\" 2>/dev/null | tail -5
Un usuario que llega a la pantalla de consentimiento ya pasó la comprobación de política —\nesa es la pista. Un usuario bloqueado nunca llega tan lejos.
\nSesión del navegador, no política. Todas las ventanas de incógnito de Chrome comparten una\nsesión, así que abrir \"una ventana privada nueva\" mientras hay otra abierta mantiene al\nusuario anterior identificado. Cierra todas las ventanas de incógnito, o usa otro navegador.
\nHas entrado por SSO, y LiteLLM da a los usuarios SSO un rol por defecto que no es\nadministrador. Crea claves desde el shell con la clave maestra, o configura los roles propios\nde LiteLLM — un mecanismo aparte de todo lo que hace authentik.
\nPuedes distinguir un plano de control de un plano de datos en tu propia pila: poner SSO y\npertenencia a un grupo delante de una interfaz de administración, y luego demostrar que la API\ndetrás sigue respondiendo solo con una clave — y nombrar lo que eso significa para las bajas,\nlas claves filtradas y las claves que sobreviven a las personas.
Hecho: un grupo que significa algo, una vinculación que lo aplica y que verificamos en la base\nde datos en lugar de fiarnos de una tabla, y una interfaz de administración donde el acceso\nsigue a la pertenencia.
\nNo hecho:
\nTLS y exposición real. El gateway está en 127.0.0.1:4000 y en este post solo es accesible a\ntravés de un túnel SSH; authentik va por HTTP plano. Hacer que cualquiera de los dos sea\naccesible de verdad significa un proxy inverso, un nombre de host y un certificado — y cada\nURI de redirección, PROXY_BASE_URL y emisor cambia el día que eso ocurra.
La Parte 1 le dio a un agente un estado que\nsobrevive a un reinicio, y una pausa donde un humano aprueba antes de que continúe. La\nParte 2 puso un supervisor delante de un\nagente de agenda y uno de facturación, y repartió el trabajo entre ellos.
\nNinguno de esos agentes agendó ni facturó nada. Lo comentaron. Cada herramienta que tenían era\nuna función que tú escribiste en el mismo proceso, y las interesantes — buscar un cliente,\nocupar un hueco, mover dinero — no existían.
\nEsta parte construye la caja de herramientas que esos dos roles necesitan, por MCP: un\ncalendario, una lista de clientes, facturas y un reembolso. Para reducir piezas móviles\napuntamos un agente a las cinco herramientas en lugar de reconstruir el supervisor de la\nParte 2 — el agente las descubre en tiempo de ejecución en vez de estar cableado a ellas, las\nencadena para responder una pregunta, y escribe filas que puedes ir a comprobar en la base de\ndatos después. Luego el reembolso lo detiene en seco y hace que un humano teclee el importe.
\nRepartir estas herramientas de vuelta entre el agente de agenda y el de facturación — de modo\nque el de agenda no pueda ver issue_refund en absoluto — es el siguiente paso natural, y la\núltima sección explica cómo.
En julio la especificación de MCP eliminó las sesiones por completo.\nEl día que ejecutamos esto, LangChain publicó el soporte para esa revisión en el paquete\nprincipal. Así que esta es una primera ejecución contra un protocolo de cinco semanas y un cliente\ndel mismo día — que es justo por lo que tres cosas de aquí no están todavía en la documentación\nde nadie.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB RAM, Ubuntu 22.04, Python 3.10. langchain\n1.4.0, langchain-openai 1.6.0, langgraph 1.2.11, mcp 2.1.1, fastmcp 4.0.2 — todo\ninstalado el día de escribir esto. Modelos servidos a través del gateway LiteLLM de la\nParte 1 de la serie del gateway, que reenvía a\nWEC Inference. langchain.mcp está en beta y avisa en cada importación; la API puede moverse.
Un servidor publica herramientas. Un cliente le pregunta qué herramientas existen. El modelo\nelige una y el cliente la llama. Ese es todo el protocolo — el valor está en que \"preguntar qué\nherramientas existen\" esté estandarizado, así que cualquier cliente puede usar cualquier\nservidor sin pegamento escrito para ese par concreto.
\nTres palabras que necesitas:
\nHerramienta. Una función que el servidor expone, con una descripción y un esquema JSON para\nsus argumentos. La descripción es lo que el modelo lee para decidir si la llama; el esquema es\nlo que debe rellenar. Nada más de tu código llega al modelo.
\nDescubrimiento. El cliente pide tools/list y recibe ese catálogo. Tu agente aprende lo que\npuede hacer en tiempo de ejecución en lugar de cuando lo escribiste.
Elicitación. Una herramienta que no puede terminar sin preguntarle algo a un humano —\nconfirmar un borrado, aportar un parámetro que el modelo no tenía. Con la nueva especificación\nesto es una petición corriente que el cliente reintenta con la respuesta adjunta.
\nCon la especificación antigua, una herramienta que necesitaba datos mantenía la conexión\nabierta y preguntaba por un canal de retorno. Con 2026-07-28 retorna, y el cliente la llama\notra vez con la respuesta adjunta. Dos peticiones completas en lugar de una de larga\nduración:
La herramienta se ejecuta dos veces. Por eso su cuerpo empieza con\nif ctx.input_responses is None — tiene que estar escrita para ser reentrada, no reanudada.\nNada queda abierto entre medias, así que la respuesta puede llegar después de un redespliegue, o\na otra réplica detrás de un balanceador.
El soporte de MCP ahora vive en el paquete langchain principal. Si tienes\nlangchain-mcp-adapters de antes, es justo lo que esto sustituye.
mkdir -p ~/mcp-tools && cd ~/mcp-tools && python3 -m venv .venv && ./.venv/bin/pip install -q \"langchain[mcp]\" langchain-openai httpx && ./.venv/bin/pip list | grep -iE 'langchain|langgraph|^mcp |fastmcp'
![\"pip](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-versions-5b3443d87f1bcddd968257037aceb26f.png\")
langchain[mcp] necesita 1.4.0 o superior — por debajo, MCPAdapter no existe.
mcp[cli] ya no existeLas guías antiguas te dicen que instales \"mcp[cli]\". En mcp 2.x ese extra ya no existe, y\npip falla con un muro de does not provide the extra 'cli' a lo largo de sesenta versiones\nantes de rendirse con ResolutionImpossible. Parece un conflicto de dependencias; es un extra\neliminado.
Los agentes necesitan datos que existan. SQLite, sembrado una vez — tres clientes, seis huecos\n(uno ya ocupado), cuatro facturas.
\nimport sqlite3
db = sqlite3.connect(\"office.db\")
db.executescript(\"\"\"
DROP TABLE IF EXISTS customers; DROP TABLE IF EXISTS slots; DROP TABLE IF EXISTS invoices;
CREATE TABLE customers(id INTEGER PRIMARY KEY, name TEXT, email TEXT);
CREATE TABLE slots(id INTEGER PRIMARY KEY, day TEXT, time TEXT, customer_id INTEGER);
CREATE TABLE invoices(id INTEGER PRIMARY KEY, customer_id INTEGER, amount REAL, status TEXT);
INSERT INTO customers(name,email) VALUES
('Maria Alvarez','maria@example.com'),
('Tomas Reis','tomas@example.com'),
('Priya Nair','priya@example.com');
INSERT INTO slots(day,time,customer_id) VALUES
('2026-09-04','09:00',NULL),('2026-09-04','11:00',NULL),('2026-09-04','14:00',2),
('2026-09-05','09:00',NULL),('2026-09-05','11:00',NULL),('2026-09-05','16:00',NULL);
INSERT INTO invoices(customer_id,amount,status) VALUES
(1,240.00,'paid'),(1,80.00,'open'),(2,150.00,'paid'),(3,410.00,'open');
\"\"\")
db.commit()
Dos detalles cargan peso. Maria tiene una factura pagada y otra abierta, así que \"reembolsa\nla factura de Maria\" es ambiguo y el agente tiene que resolverlo. Tomas ya ocupa el viernes a\nlas 14:00, así que la disponibilidad es una pregunta real y no \"todo\".
\nCinco herramientas: tres de lectura, una de escritura, y una que no puede terminar sin un\nhumano.
\nimport os, sqlite3
from fastmcp import FastMCP, Context
from mcp.types import InputRequiredResult, ElicitRequest, ElicitRequestFormParams
DB = os.path.join(os.path.dirname(os.path.abspath(__file__)), \"office.db\")
mcp = FastMCP(\"office-tools\")
def q(sql, args=()):
con = sqlite3.connect(DB); con.row_factory = sqlite3.Row
try:
rows = con.execute(sql, args).fetchall(); con.commit()
return [dict(r) for r in rows]
finally:
con.close()
def w(sql, args=()):
con = sqlite3.connect(DB)
try:
cur = con.execute(sql, args); con.commit(); return cur.rowcount
finally:
con.close()
@mcp.tool
async def find_customer(query: str) -> list[dict]:
\"\"\"Find customers whose name or email matches the query.\"\"\"
like = f\"%{query}%\"
return q(\"SELECT id, name, email FROM customers WHERE name LIKE ? OR email LIKE ?\", (like, like))
@mcp.tool
async def list_availability(day: str) -> list[dict]:
\"\"\"List free appointment slots on a given day, formatted YYYY-MM-DD.\"\"\"
return q(\"SELECT id, day, time FROM slots WHERE day = ? AND customer_id IS NULL ORDER BY time\", (day,))
@mcp.tool
async def book_slot(slot_id: int, customer_id: int) -> str:
\"\"\"Book a free slot for a customer. Fails if the slot is already taken.\"\"\"
n = w(\"UPDATE slots SET customer_id = ? WHERE id = ? AND customer_id IS NULL\", (customer_id, slot_id))
if n == 0:
return f\"Slot {slot_id} is already taken or does not exist.\"
row = q(\"SELECT day, time FROM slots WHERE id = ?\", (slot_id,))[0]
return f\"Booked slot {slot_id} ({row['day']} {row['time']}) for customer {customer_id}.\"
@mcp.tool
async def open_invoices(customer_id: int) -> list[dict]:
\"\"\"List a customer's invoices with their amounts and status.\"\"\"
return q(\"SELECT id, amount, status FROM invoices WHERE customer_id = ?\", (customer_id,))
@mcp.tool
async def issue_refund(invoice_id: int, ctx: Context) -> str | InputRequiredResult:
\"\"\"Refund an invoice. A human must approve the amount and give a reason.\"\"\"
inv = q(\"SELECT id, customer_id, amount, status FROM invoices WHERE id = ?\", (invoice_id,))
if not inv:
return f\"No invoice {invoice_id}.\"
inv = inv[0]
responses = ctx.input_responses
if responses is None:
params = ElicitRequestFormParams(
message=(
f\"Refund invoice {inv['id']} for customer {inv['customer_id']}? \"
f\"It is {inv['status']}, amount {inv['amount']:.2f}. \"
\"Confirm the amount to refund and give a reason.\"
),
requested_schema={
\"type\": \"object\",
\"properties\": {
\"amount\": {\"type\": \"number\", \"description\": \"Amount to refund\"},
\"reason\": {\"type\": \"string\", \"description\": \"Why this refund is being issued\"},
},
\"required\": [\"amount\", \"reason\"],
},
)
return InputRequiredResult(
result_type=\"input_required\",
input_requests={\"approve_refund\": ElicitRequest(method=\"elicitation/create\", params=params)},
)
answer = responses[\"approve_refund\"]
if answer.action != \"accept\":
return f\"Refund declined - invoice {inv['id']} unchanged.\"
w(\"UPDATE invoices SET status = 'refunded' WHERE id = ?\", (inv[\"id\"],))
return f\"Refunded {answer.content['amount']:.2f} on invoice {inv['id']}. Reason: {answer.content['reason']}\"
if __name__ == \"__main__\":
mcp.run(transport=\"http\", host=\"127.0.0.1\", port=8770, stateless_http=True)
Los docstrings no son comentarios. Se convierten en las descripciones que el modelo lee para\nelegir, así que escríbelos como instrucciones para alguien que no puede ver más que esa línea.\nLos dejamos en inglés porque son el texto que el modelo consume.
\nbook_slot rechaza un hueco ocupado en SQL en vez de comprobarlo antes — WHERE customer_id IS NULL significa que dos agentes compitiendo por el mismo hueco no pueden ganar ambos.
cd ~/mcp-tools && ./.venv/bin/python office_tools.py
Déjalo corriendo. En una segunda sesión, pregúntale qué herramientas tiene:
\ncurl -s -X POST http://127.0.0.1:8770/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\"}'
La primera vez que ejecutamos esto, sin stateless_http=True:
{\"jsonrpc\":\"2.0\",\"id\":null,\"error\":{\"code\":-32600,\"message\":\"Bad Request: Missing session ID\"}}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-session-error-7897aebee33998b591bd27b4606a6e6b.png\")
La revisión 2026-07-28 eliminó las sesiones del protocolo — sin handshake, sin ID de sesión,\nnada que fije un cliente a una instancia. Todo lo escrito sobre el cambio describe bien el lado\ncliente: no queda nada que fijar.
FastMCP 4.0.2 sigue usando el transporte con estado por defecto. Optas por el nuevo\ncomportamiento con stateless_http=True, y hasta que lo hagas, la primera petición contra tu\nservidor recién creado falla citando un concepto que la especificación borró hace cinco semanas.
run_http_async acepta tanto stateless_http como stateless; el docstring dice que el\nsegundo es \"Alias for stateless_http for CLI consistency\". Un interruptor, dos nombres, ambos\ncon valor por defecto None.
La línea de arranque es donde lo compruebas:
\n![\"FastMCP](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-server-start-9b984393ff73ca52793743fe31bbe9da.png\")
![\"FastMCP](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-server-stateless-8cd7f1d5201b5dc974f4726c52b23f9f.png\")
Con la bandera, la misma petición devuelve el catálogo — sin handshake, sin sesión:
\n![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-tools-list-c1f510e50217be4d48c633e07dafa45d.png\")
El esquema de issue_refund contiene solo invoice_id — el parámetro ctx: Context no está,\nporque FastMCP lo inyecta y el modelo no puede fijarlo. Eso es lo que hace que una confirmación\nobligatoria sea obligatoria.
import asyncio, os, sys
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
from langchain_openai import ChatOpenAI
model = ChatOpenAI(
base_url=\"http://127.0.0.1:4000/v1\",
api_key=os.environ[\"GATEWAY_KEY\"],
model=\"qwen-mid\",
temperature=0,
)
async def main():
async with MCPAdapter(\"http://127.0.0.1:8770/mcp\") as adapter:
tools = await adapter.list_tools()
print(\"discovered:\", [t.name for t in tools])
agent = create_agent(model, tools)
out = await agent.ainvoke({\"messages\": [{\"role\": \"user\", \"content\": sys.argv[1]}]})
print(\"\\n--- answer ---\")
print(out[\"messages\"][-1].content)
asyncio.run(main())
Todos los ejemplos publicados de MCP apuntan el modelo a Anthropic, OpenAI o Gemini. Este apunta\na tu propia gateway LiteLLM, que reenvía a WEC\nInference — las herramientas son locales, el modelo es tuyo, nada sale de la caja.
\nGuarda la clave en un archivo y no en la línea de comandos, donde acabaría en tu historial de\nshell y en cada captura de pantalla:
\ncd ~/mcp-tools && printf 'GATEWAY_KEY=%s\\n' \"$KEY\" > .env && chmod 600 .env
cd ~/mcp-tools && set -a && source .env && set +a && ./.venv/bin/python agent.py \"Who is Maria and what invoices does she have?\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-agent-lookup-d1e719855fca0eb978d89518c2a03cac.png\")
Esa respuesta necesitó dos llamadas a herramientas en secuencia: find_customer(\"Maria\")\npara obtener su id, y luego open_invoices(1) usándolo. Nada encaminó eso — el modelo leyó\ncinco descripciones y dedujo el orden.
Ahora una que escribe:
\ncd ~/mcp-tools && ./.venv/bin/python agent.py \"Book Maria into a free slot on 2026-09-04\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-agent-booking-cf43e46e8fbeb7003efd7d2ceba1ddc4.png\")
Tres llamadas esta vez. Y como una reserva es un cambio real, compruébalo donde el agente no\nllega:
\ncd ~/mcp-tools && ./.venv/bin/python -c \"
import sqlite3
for r in sqlite3.connect('office.db').execute('select s.id,s.day,s.time,coalesce(c.name,\\\"free\\\") from slots s left join customers c on c.id=s.customer_id order by s.day,s.time'): print(r)\"
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-verify-db-e3eda545965f9b86a42918a3fd4bc674.png\")
Puedes levantar un servidor MCP sobre un almacén de datos real, apuntarle un agente, y hacer que\nencadene herramientas descubiertas hasta producir un cambio que verificas en la base de datos —\ncon el modelo en tu propio gateway y no en la de un proveedor.
La pausa de aprobación de la Parte 1 era algo que tú pusiste en el grafo. Esta viene de la\nherramienta, y el agente no tiene forma de saltársela.
\nimport asyncio, json, os
from langchain.agents import create_agent
from langchain.mcp import MCPAdapter
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
model = ChatOpenAI(base_url=\"http://127.0.0.1:4000/v1\",
api_key=os.environ[\"GATEWAY_KEY\"], model=\"qwen-mid\", temperature=0)
def ask_human(req):
print(f\"\\n>>> {req['message']}\")
props = (req.get(\"requested_schema\") or {}).get(\"properties\", {})
content = {}
for name, spec in props.items():
raw = input(f\" {name} ({spec.get('type','string')}): \").strip()
content[name] = float(raw) if spec.get(\"type\") == \"number\" else raw
return {\"action\": \"accept\", \"content\": content}
async def main():
async with MCPAdapter(\"http://127.0.0.1:8770/mcp\") as adapter:
tools = await adapter.list_tools()
agent = create_agent(model, tools, checkpointer=InMemorySaver())
cfg = {\"configurable\": {\"thread_id\": \"refund-1\"}}
out = await agent.ainvoke(
{\"messages\": [{\"role\": \"user\", \"content\": \"Refund Maria's open invoice.\"}]}, cfg)
if \"__interrupt__\" not in out:
print(\"NO INTERRUPT:\", out[\"messages\"][-1].content); return
payload = out[\"__interrupt__\"][0].value
print(\"=== INTERRUPT ===\")
print(json.dumps(payload, indent=2))
responses = {r[\"key\"]: ask_human(r) for r in payload[\"requests\"]}
print(\"\\n=== RESUMING ===\")
out = await agent.ainvoke(Command(resume={\"responses\": responses}), cfg)
print(out[\"messages\"][-1].content)
asyncio.run(main())
El checkpointer y el thread_id no son opcionales — una ejecución interrumpida necesita algún\nsitio donde esperar. El mismo requisito que la pausa de aprobación de la Parte 1.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-elicit-full-b00707c0653a77cd26dcf4221b184fa5.png\")
Lee el orden de los hechos. El modelo resolvió \"la factura abierta de Maria\" como la factura 2\npor sí solo — ella tiene dos, y eligió la abierta. Luego se detuvo. El importe y el motivo los\ntecleó un humano, y solo entonces ocurrió el reembolso.
\nLa carga es {\"type\": \"mcp_elicitation\", \"tool_name\": \"issue_refund\", \"requests\": [...]}. type\nes el discriminador, de modo que un grafo con varios tipos de interrupt puede saber cuál vino de\nMCP. Cada petición lleva una key, un message para un humano, un mode de form o url, y\npara un formulario el requested_schema que la respuesta debe satisfacer — aquí dos campos\nobligatorios, uno de ellos numérico. Reanudas con una respuesta por clave.
Y verifica, otra vez fuera del agente:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-verify-refund-3f9c62f71c37c5e0339cf4d1a4da57df.png\")
Puedes hacer que una herramienta se niegue a terminar sin un humano — devolviendo un formulario\ntipado que el modelo no puede rellenar por su cuenta, pausando la ejecución como un interrupt de\nLangGraph, y reanudándola con una respuesta que una persona tecleó de verdad.
ctx.elicit es la API vieja, y su error aterriza en el contexto del modeloTodos los ejemplos de elicitación de FastMCP que encontrarás llaman a\nawait ctx.elicit(message, response_type) dentro de la herramienta. Ese es el mecanismo de la\nera del handshake: bloquea a mitad de ejecución y habla por el canal de retorno de la sesión —\nel canal de retorno que el transporte sin estado no tiene.
Nuestro primer intento lo usó. El agente no se pausó — pero no porque no se lanzara nada.\nFastMCP lanzó su error de era exactamente como está documentado, LangChain lo convirtió en un\nToolMessage con status=\"error\" (deliberadamente, \"en lugar de terminar la ejecución\"), y el\nmodelo leyó ese error y lo narró como progreso:
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-elicit-old-api-ec02d789aa6970b70a130f83067c235b.png\")
Sin interrupt, código de salida 0, y la factura sigue open. No se reembolsó nada y nada está\nesperando a un humano — pero al usuario se le dijo que hay una aprobación pendiente.
Con el protocolo moderno una herramienta devuelve un InputRequiredResult describiendo lo\nque necesita, y sale. El cliente responde y reintenta la llamada completa con la respuesta\nadjunta. Cada ronda es una petición completa, y por eso sobrevive al balanceo de carga y a los\nredespliegues — y por eso el cuerpo de la herramienta debe escribirse para ser reentrado, no\nreanudado. El nuestro lo hace con if ctx.input_responses is None.
La documentación de FastMCP es explícita: ctx.elicit solo funciona en conexiones\n≤ 2025-11-25, y un servidor multi-era debería ramificar según\nctx.request_context.protocol_version. También promete que el desajuste \"lanza un error de era\nclaro en lugar de fallar de forma oscura\" — y así es. El error simplemente aterriza en el\ncontexto del modelo y no en el tuyo.
El post de LangChain lee el interrupt como paused[\"__interrupt__\"][0].value.requests[0] —\nacceso por atributo. MCPElicitationInterrupt es un TypedDict (ver\nlangchain/mcp/elicitation.py en 1.4.0), así que en tiempo de ejecución es un dict y\n.requests no resuelve. Usa value[\"requests\"] — como hace el propio fragmento unas líneas\ndespués, leyendo question[\"key\"].
Cada ejecución empieza descubriendo herramientas, lo que es un viaje de ida y vuelta antes de\nque el modelo vea nada. La nueva especificación lo hace cacheable:
\nimport asyncio, time
from fastmcp import Client
from langchain.mcp import MCPAdapter
async def main():
client = Client(\"http://127.0.0.1:8770/mcp\", cache=True)
async with MCPAdapter(client) as adapter:
for i in (1, 2):
t = time.perf_counter()
tools = await adapter.list_tools(cache_mode=\"use\")
print(f\"discovery {i}: {len(tools)} tools in {(time.perf_counter()-t)*1000:.1f} ms\")
asyncio.run(main())
discovery 1: 5 tools in 14.6 ms
discovery 2: 5 tools in 12.5 ms
![\"Dos](\"https://development-wec.wiline.com/docs/es/assets/images/mcp-cache-bbadf88f6b26a069ec15e3b3db635c02.png\")
Sin efecto — y ese es el comportamiento correcto, no una caché rota.
\ncache=True es necesario, no suficienteLa caché del cliente \"respeta las pistas ttlMs y cacheScope que el servidor adjunta a cada\nrespuesta\" y solo funciona contra servidores de era moderna que las anuncien. El nuestro no\nanuncia ninguna, así que ambas llamadas van a la red.
Fíjate además en que cache=True va en el fastmcp.Client, no en MCPAdapter — el\nadaptador acepta exactamente un argumento. Y la caché pertenece al cliente, así que un cliente\npor llamante evita que los catálogos se crucen entre inquilinos.
Por loopback no había nada que ahorrar de todos modos: 12–15 ms es el viaje de ida y vuelta. La\ncaché es para servidores remotos con latencia real y un TTL que respetar.
\nResolutionImpossible al instalar mcp[cli]El extra cli se eliminó en mcp 2.x. Instala \"langchain[mcp]\" en su lugar; arrastra un\nmcp y un fastmcp compatibles.
Bad Request: Missing session IDTu servidor está usando el transporte con estado. Añade stateless_http=True a mcp.run(...).
KeyError: 'GATEWAY_KEY'source .env define variables de shell, no variables de entorno — el proceso hijo de Python\nnunca las ve. Usa set -a && source .env && set +a. Y export no cruza entre sesiones SSH, así\nque una segunda terminal necesita su propio source.
address already in use tras reiniciar el servidorLa instancia anterior sigue ocupando el puerto — un reinicio fallido deja vivo el proceso\nantiguo, así que el arreglo que acabas de hacer parece no funcionar. pkill -f office_tools.py,\ny luego comprueba con ss -tlnp | grep 8770.
La herramienta está llamando a ctx.elicit en lugar de devolver InputRequiredResult. En una\nconexión sin estado no hay canal de retorno, y la llamada no lanza el error donde lo esperarías.
Hecho: un servidor MCP sobre un almacén de datos real, un agente que descubre herramientas en\nlugar de estar cableado a ellas y las encadena sin encaminamiento, dos cambios que verificaste en\nla base de datos en vez de creerte al modelo, y un reembolso que no puede ocurrir sin que un\nhumano aporte la cifra.
\nNo hecho:
\n127.0.0.1 y cualquiera en la caja\npuede llamar a todas las herramientas, incluida issue_refund. FastMCP soporta tokens bearer\ny OAuth 2.1; no configuramos ninguno.book_slot reservará para cualquier\ncustomer_id que reciba. No hay noción de quién pregunta — el mismo hueco que la\nParte 4 de la serie de endurecimiento\nencontró entre un plano de control y un plano de datos.ClientGroup conecta varios a la vez y prefija los nombres de\nherramienta por servidor; nosotros usamos un único objetivo.book_slot\nhace más trabajo del que parece bajo concurrencia real.langchain.mcp está en beta y avisa en cada importación.Acotar las herramientas por agente. Ahora mismo un solo agente tiene las cinco, así que nada\nimpide que el modelo elija issue_refund cuando se le pidió reservar un hueco — la pausa humana\nes la única guarda. El supervisor de la Parte 2 ya reparte entre un agente de agenda y uno de\nfacturación; dale a cada uno solo su porción de adapter.list_tools() y el de agenda no podrá\nemitir un reembolso porque nunca se le dijo que la herramienta existe. Eso es una garantía más\nfuerte que pedírselo amablemente a un modelo.
Luego autenticación, para que una llamada a herramienta lleve una identidad en vez de confiar\nen quien alcance el puerto — la misma pregunta que la\nParte 4 de la serie de endurecimiento hizo\nsobre la propia API del gateway, una capa más arriba.
\nlangchain-mcp-adapters2026-07-28La Parte 1 cerró los puertos que nadie\nquiso abrir. La Parte 2 impidió que dos\ncontenedores se ejecutaran como root. Ambas trataban sobre la máquina. Ninguna tocó la\npregunta que una pila de IA autoalojada responde peor: ¿quién tiene permiso para iniciar\nsesión, y dónde se decide eso?
\nLa misma caja de antes. El Langfuse que venimos endureciendo desde la Parte 1 — aquel cuyo\nPostgres, ClickHouse y Redis la Parte 1 encontró correctamente enlazados a localhost, y\ncuyo worker la Parte 2 bajó de root — se desplegó en\nDetecta lo que tus pruebas no ven. Dos\npartes han asegurado ya la máquina por debajo sin tocar ni una vez la puerta de entrada de\nla propia aplicación. Esta es la primera parte que cambia Langfuse en sí.
\nAhora mismo esa decisión se toma en cada app, por separado. Langfuse tiene su propia tabla\nde correo y contraseña. También la tiene cualquier otra herramienta en la caja. Cada una es\nun lugar donde una cuenta puede sobrevivir a la persona que la tenía, donde una contraseña\npuede reutilizarse, y donde \"quitarle el acceso a esta persona\" significa acordarse de que\nesa app existe.
\nEste post mueve esa decisión a un solo lugar. Ese lugar es\nauthentik — un proveedor de identidad de código abierto que\nejecutas tú mismo, la contraparte autoalojada de Okta o Auth0. Guarda las cuentas, muestra\nla pantalla de inicio de sesión, y da fe de quién es alguien ante cualquier app que\npregunte. Las apps dejan de almacenar contraseñas y empiezan a preguntarle a authentik.
\nEs el mismo trabajo que hace Keycloak, y Keycloak es el nombre más conocido. authentik se\ngana la elección aquí por el coste de puesta en marcha: un archivo compose y un asistente\nfrente a los realms, clients y ajustes de JVM de Keycloak. Para una caja y una app, esa\ndiferencia es toda la decisión.
\nLo desplegamos, conectamos Langfuse a él por OIDC, y terminamos con un inicio de sesión que\npasa por authentik y vuelve.
\n\nUna WEC Instance: 8 vCPU AMD EPYC 7601, 15 GB RAM, Docker 29.1.3, kernel 5.15.\nauthentik 2026.8.1 desde ghcr.io/goauthentik/server, Postgres 16. Langfuse v3\n(langfuse/langfuse:3) — el despliegue heredado de las Partes 1 y 2, accesible en\n10.80.4.212:3001. authentik publicado en el puerto host 9100.
Las direcciones de este post son una LAN privada. Sustituye las tuyas. Todo aquí es HTTP\nplano sobre una red de confianza, lo cual está bien para una primera ejecución y no lo\nestá para nada accesible desde fuera — mira Qué sigue.
Toda guía de OIDC asume que ya conoces estas cinco palabras. Tenerlas claras de entrada es\nla diferencia entre configurar esto una vez y adivinar campos durante una hora.
\nOP y RP. El OpenID Provider es lo que sabe quién es la gente — authentik. La\nRelying Party es la app que quiere que se lo digan — Langfuse. La RP nunca ve una\ncontraseña. Recibe una declaración firmada del OP que dice \"este es admin@example.com, yo\nlo verifiqué\".
Proveedor vs aplicación. authentik separa lo que la mayoría de herramientas fusiona. Un\nproveedor es el endpoint del protocolo — la maquinaria OIDC, el client ID y el secreto,\nla URI de redirección. Una aplicación es lo que los usuarios ven y aquello a lo que se\nenganchan las reglas de acceso. Se emparejan uno a uno: una aplicación, un proveedor, y el\nasistente del Paso 3 crea ambos juntos.
\nLa URI de redirección es a dónde authentik tiene permiso de enviar al usuario tras un\ninicio de sesión exitoso. Se compara de forma exacta y es la causa de fallo más común. Ni un\nprefijo, ni un nombre de host — la URL completa, carácter por carácter.
\nScopes vs grant types. Un scope es qué información pide la app\n(openid email profile). Un grant type es el mecanismo con el que la pide\n(authorization_code). Preguntas distintas; la interfaz las pone cerca y es fácil\nconfundirlas.
Lo que vale la pena notar: el código viaja por el navegador, el secreto nunca. Ese\nintercambio del penúltimo paso ocurre entre los dos contenedores directamente, que es por lo\nque el secreto del cliente es un ajuste de lado servidor y por lo que Langfuse debe poder\nalcanzar a authentik por la red — no solo tu navegador.
\n9100)localhost — dos contenedores necesitan alcanzarse entre sí y tu\nnavegador necesita alcanzar a ambosauthentik trae un archivo compose y genera sus propios secretos. Crea un directorio y\ndescarga ambos:
\nmkdir -p ~/authentik && cd ~/authentik
curl -O https://goauthentik.io/docker-compose.yml
Ahora el archivo de entorno. authentik necesita una contraseña de Postgres y una clave\nsecreta, ambas aleatorias, más los puertos que publicará:
\ncd ~/authentik
{
echo \"PG_PASS=$(openssl rand -base64 36 | tr -d '\\n')\"
echo \"AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\\n')\"
echo \"COMPOSE_PORT_HTTP=9100\"
echo \"COMPOSE_PORT_HTTPS=9543\"
} > .env
chmod 600 .env
AUTHENTIK_SECRET_KEY firma sesiones y tokens. Si la pierdes, toda sesión existente y todo\ntoken emitido quedan inválidos — así que pertenece a tu gestor de contraseñas, no solo a\neste archivo.
Levántalo. El primer arranque ejecuta migraciones de base de datos y tarda un minuto o dos:
\ncd ~/authentik && docker compose up -d
cd ~/authentik && docker compose ps
Tres contenedores — server, worker y postgresql — todos reportando (healthy). Los\narchivos compose más antiguos de authentik también traían un servicio redis aparte;\n2026.8.1 ya no lo hace, así que tres es correcto y no falta nada. server es el que tiene\nque estar saludable antes de que continúes.
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-compose-ps-2cdcd74dfeb2be5f3c8d9bb137b646db.png\")
El primer arranque de authentik deja la cuenta de administrador sin reclamar. La URL de\nconfiguración existe exactamente una vez; visitarla es cómo tomas posesión.
\nAbre http://10.80.4.212:9100/if/flow/initial-setup/, y establece el correo y la contraseña\ndel administrador por defecto (akadmin).
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-initial-setup-e170a5fefdbc3d6a5b645819857b6cae.png\")
Usa una dirección que controles. Esta cuenta puede hacer de todo, así que dale una\ncontraseña de verdad y guárdala en algún lugar duradero.
\nHasta que alguien complete este formulario, cualquiera que pueda alcanzar el puerto puede\nconvertirse en administrador de tu proveedor de identidad. Hazlo inmediatamente después de\nque los contenedores levanten — no mañana.
Aterrizas en el Application Dashboard — la vista de cara al usuario, no la de administración,\ny vacía porque no hay nada configurado todavía.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-app-dashboard-empty-fb4aaff0a94a00ac91abe85b9541079d.png\"){kind=spacer}
Create a new application aquí lleva al mismo sitio que la interfaz de administración; el\nbotón Admin interface arriba a la derecha es cómo llegas a todo lo demás.
Applications → Applications → Create. authentik te lleva por cinco pasos, y vale la pena\nleer la lista de pasos de la izquierda antes de tocar nada:
\nApplication → Choose a Provider → Configure Provider → Configure Bindings → Review and\nSubmit
\nEse es el vocabulario de antes, en orden. El asistente crea la aplicación y su proveedor en\nuna sola pasada y los empareja por ti. (Applications → Providers → Create construye un\nproveedor por su cuenta, si alguna vez necesitas uno antes que la app que lo usa.)
Langfuse. La etiqueta que los usuarios ven en el dashboard.langfuse. Carga peso: pasa a formar parte de la URL del emisor, así que\ncambiarlo después cambia la URL con la que tienes que reconfigurar Langfuse.![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-wizard-application-62b3555c7b9b05dedfdd535153d2c084.png\")
Ocho tipos de proveedor. Toma OAuth2/OpenID Provider — \"OAuth2 Provider for generic\nOAuth and OpenID Connect Applications.\"
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-wizard-provider-type-62af4193167bfaa5359808b786af8d41.png\")
Vale la pena saber qué no estás eligiendo, porque dos de estos resuelven un problema\ndistinto: Proxy Provider pone a authentik delante de una app que no soporta SSO por sí\nmisma, y LDAP Provider expone authentik a cosas que solo hablan LDAP. Langfuse habla\nOIDC de forma nativa, así que recibe un proveedor OIDC de verdad.
\nEl paso que importa, y el que te costará tiempo si lo apuras.
\nAuthorization flow — default-provider-authorization-explicit-consent. \"Explicit\"\nmuestra al usuario una pantalla de consentimiento que lista lo que Langfuse pidió. La\nvariante implícita se la salta. Elige explícito para una primera construcción: esa pantalla\nes una lectura en vivo de tu configuración de scopes, lo que hace visible una mala\nconfiguración en lugar de silenciosa.
Client type — Confidential (desplazado por encima de los campos de redirección).\nLangfuse es un servidor y puede guardar un secreto, así que recibe uno. Los clientes\npúblicos son para navegadores y apps móviles que no pueden.
\nRedirect URIs/Origins (RegEx) — el campo con dos desplegables y un valor. Pon el modo\nen Strict, el propósito en Authorization, y la URI en el callback de NextAuth de\nLangfuse:
\nhttp://10.80.4.212:3001/api/auth/callback/custom
El custom final no es un marcador de posición — es el ID de proveedor que NextAuth\nasigna a su proveedor OIDC genérico. Usa tu propio host y puerto, pero esa ruta es fija.
Signing Key — deja authentik Self-signed Certificate. Esto firma el token de ID;\nLangfuse obtiene la clave pública correspondiente del jwks_uri en el Paso 5 y verifica\ncontra ella. Autofirmado es lo correcto aquí — la RP confía en esta clave porque el\ndescubrimiento se la entregó, no porque una CA responda por ella.
Logout URI y las validez de los tokens — déjalos en paz.
\nEl proveedor una vez guardado — flujo de autorización con consentimiento explícito, tipo de\ncliente Confidential, y Authorization Code como grant:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-wizard-configure-provider-11b9bd02c65bf52f23d2afe34f3a8be9.png\")
El desplegable de modo también ofrece Regex, y el propio texto de ayuda de authentik\nseñala que puedes ponerlo en .* para permitir cualquier URI de redirección. No lo hagas.\nUna URI de redirección abierta significa que cualquiera que pueda iniciar un login puede\nhacer que el código de autorización se entregue a un host que él controla. Strict, con una\nURL exacta, es el sentido entero del campo.
Más abajo, Scopes viene precargado con cuatro mapeos: email, openid, profile y\noffline_access. Déjalos. openid es obligatorio y es lo que marca esto como OIDC en lugar\nde OAuth2 a secas. email es el claim con el que Langfuse identifica la cuenta. profile\nlleva el nombre visible. offline_access es el que el asistente añade sin preguntar —\npermite un token de refresco, de modo que una sesión puede renovarse sin mandar al usuario de\nvuelta por el flujo de login.
No bound policies. — y lo vamos a dejar así.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-wizard-bindings-b5cb6f9b81084f2eb498d0b4cdeae6cd.png\")
Lee la descripción del propio asistente: \"These policies control which users can access this\napplication.\" Sin nada vinculado, la respuesta es todo el que pueda autenticarse. En una\ncaja donde eres la única cuenta, eso es lo mismo que \"solo yo\" — que es por lo que resulta\ntolerable aquí y por lo que el asistente te deja saltártelo.
No es control de acceso. Toda cuenta que crees en este authentik entra en Langfuse por\ndefecto, y nada te avisará. Los grupos y las vinculaciones de políticas son cómo se arregla\neso, y son el tema del siguiente post — donde lo que se protege es un gateway y la\nrespuesta importa muchísimo más.
Revisa el slug y la URI de redirección una vez más, y envía.
\nEn lugar de ensamblar URLs a mano, pregúntale a authentik. Todo proveedor OIDC publica un\ndocumento de descubrimiento, y el de authentik vive bajo el slug de la aplicación:
\ncurl -s http://10.80.4.212:9100/application/o/langfuse/.well-known/openid-configuration \\
| jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, grant_types_supported}'
{
\"issuer\": \"http://10.80.4.212:9100/application/o/langfuse/\",
\"authorization_endpoint\": \"http://10.80.4.212:9100/application/o/authorize/\",
\"token_endpoint\": \"http://10.80.4.212:9100/application/o/token/\",
\"userinfo_endpoint\": \"http://10.80.4.212:9100/application/o/userinfo/\",
\"jwks_uri\": \"http://10.80.4.212:9100/application/o/langfuse/jwks/\",
\"grant_types_supported\": [
\"authorization_code\",
\"refresh_token\",
\"implicit\",
\"client_credentials\",
\"password\",
\"urn:ietf:params:oauth:grant-type:device_code\"
]
}
Dos cosas que sacar de esto. El issuer es la única URL que Langfuse necesita — él mismo\nobtendrá este documento y descubrirá el resto. Y grant_types_supported lista lo que el\nprotocolo ofrece, no lo que tu proveedor aceptará; nosotros usamos authorization_code y la\npresencia de password en esa lista no es una invitación.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-discovery-json-959875837069e04a0b42b7cc81ad0b75.png\")
Ahora las credenciales del cliente. Están en la página de detalle del proveedor en la\ninterfaz, pero docker compose exec es más rápido y se copia y pega limpio:
cd ~/authentik && docker compose exec server ak shell -c \"
from authentik.core.models import Application
p = Application.objects.get(slug='langfuse').get_provider()
print('PROVIDER :', p.name)
print('CLIENT_ID :', p.client_id)
print('CLIENT_SECRET:', p.client_secret)
\"
Fíjate en que esto busca el proveedor a través del slug de la aplicación y no por el nombre\ndel proveedor. El asistente nombró a tu proveedor Provider for Langfuse, no langfuse — el\nslug es lo que tú elegiste y lo que se mantiene predecible. get_provider() también importa:\nrecurrir a application.provider devuelve la clase base con client_id vacío, lo que se\nparece alarmantemente a un proveedor roto y no lo es.
Mantén esa salida fuera del historial de tu shell y fuera de las capturas de pantalla.
\nLa página de detalle del proveedor lleva los mismos valores, por si prefieres leerlos ahí —\ntipo de cliente, client ID, la URI de redirección estricta, y cada URL de descubrimiento en\nun solo sitio. El secreto del cliente es lo único que no imprime:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-provider-overview-5b451791d184236f85921a5a394f956e.png\")
Langfuse lee ajustes OIDC genéricos desde variables AUTH_CUSTOM_*. Añádelas a\n~/langfuse/.env:
AUTH_CUSTOM_NAME=authentik
AUTH_CUSTOM_ISSUER=http://10.80.4.212:9100/application/o/langfuse
AUTH_CUSTOM_CLIENT_ID=<el client id del Paso 4>
AUTH_CUSTOM_CLIENT_SECRET=<el client secret del Paso 4>
AUTH_CUSTOM_SCOPE=openid email profile
El issuer aquí no lleva barra final mientras que el documento de descubrimiento reportó una.\nAmbos funcionan — Langfuse lo normaliza.
\nConfirma también que NEXTAUTH_URL coincide con la dirección que realmente navegas:
grep NEXTAUTH_URL ~/langfuse/.env
NEXTAUTH_URL=http://10.80.4.212:3001
Si esto dice localhost mientras tu URI de redirección dice 10.80.4.212, el callback se\nconstruirá con el nombre de host equivocado y authentik lo rechazará.
Ahora la parte que te hará perder la tarde si te la saltas. Escribir esas variables en\n.env no basta. El archivo compose que trae Langfuse lista explícitamente las variables que\npasa al contenedor langfuse-web, y AUTH_CUSTOM_* no está entre ellas — aterrizan en\n.env, Compose las lee para interpolación, y nunca llegan al proceso. Langfuse arranca bien\ny no muestra ningún botón de SSO, sin nada en los registros que diga por qué.
Pásalas con un archivo de override, ~/langfuse/docker-compose.override.yml:
services:
langfuse-web:
environment:
AUTH_CUSTOM_NAME: ${AUTH_CUSTOM_NAME}
AUTH_CUSTOM_ISSUER: ${AUTH_CUSTOM_ISSUER}
AUTH_CUSTOM_CLIENT_ID: ${AUTH_CUSTOM_CLIENT_ID}
AUTH_CUSTOM_CLIENT_SECRET: ${AUTH_CUSTOM_CLIENT_SECRET}
AUTH_CUSTOM_SCOPE: ${AUTH_CUSTOM_SCOPE}
AUTH_CUSTOM_ALLOW_ACCOUNT_LINKING: \"true\"
Compose fusiona docker-compose.override.yml automáticamente, así que el archivo original\nqueda intacto y sobrevive a las actualizaciones. Esa última variable es el arreglo de un\nfallo que si no te encontrarías en el siguiente paso — la sección de resolución de problemas\nexplica qué hace y qué cuesta.
Recrea el contenedor web y verifica que las variables llegaron:
\ncd ~/langfuse && docker compose up -d langfuse-web
cd ~/langfuse && docker compose exec langfuse-web env | grep -c AUTH_CUSTOM
Seis. Si es cero, el override no se está recogiendo — comprueba que estás ejecutando compose\ndesde ~/langfuse y que el nombre del archivo es exactamente docker-compose.override.yml.
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-env-count-c57cd6125a9c2dbc129ef850beee6378.png\")
Abre http://10.80.4.212:3001/auth/sign-in, en una ventana privada para no estar mirando una\nsesión existente. Hay un botón nuevo bajo el separador debajo del formulario de contraseña.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-sso-button-40985ca287c0686b8a2c65f8b7998d3d.png\")
El botón se llama authentik porque ese es tu valor de AUTH_CUSTOM_NAME, renderizado tal\ncual. Ponlo en Company SSO y eso es lo que dirá el botón — es una cadena de visualización y\nnada más depende de ella.
Otras dos cosas en esa captura vale la pena nombrarlas en lugar de pasarlas por alto. El\nformulario de correo y contraseña sigue ahí, y también Sign up — el SSO se ha añadido,\nno sustituido. Y la barra de direcciones dice Not Secure, correctamente: esto es HTTP\nplano.
\nHaz clic en el botón y te entregan a authentik, que te dice de dónde vienes:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-login-langfuse-f20d6f5f65651cb88e1db77bdd2f7c07.png\")
Inicia sesión, y como elegimos el flujo de consentimiento explícito en el Paso 3.3, authentik\nmuestra lo que Langfuse pidió antes de entregar nada:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/authentik-consent-1db931f804b8b9ddaa8562e01b588adf.png\")
Dice You're about to sign into Langfuse, te identifica como akadmin, y lista dos permisos\n— Email address y General Profile Information. Esos son los scopes email y profile\nen forma legible. openid no recibe una línea propia: no lleva datos personales que consentir,\nes la bandera que hace que esto sea OIDC en lugar de OAuth2 a secas. Así que una configuración\nde tres scopes produce una pantalla de consentimiento de dos elementos, lo cual es correcto y\nno señal de que algo se haya perdido.
Continúa, y aterrizas en Langfuse, con la sesión iniciada, como la identidad por la que\nauthentik respondió.
\nEse es el bucle cerrado. Langfuse nunca vio una contraseña.
\nOAuthAccountNotLinkedEl primer intento de inicio de sesión rebotó de vuelta a la página de login de Langfuse con\n?error=OAuthAccountNotLinked en la URL y nada más.
La causa: ya existía una cuenta de Langfuse de correo y contraseña con la misma dirección que\nauthentik estaba presentando ahora. Lo que NextAuth hace por defecto es rechazar la fusión.\nEse comportamiento por defecto es protector — si un proveedor de identidad puede afirmar\ncualquier correo y la app vincula automáticamente solo por el correo, entonces quien controle\nel proveedor puede apoderarse de una cuenta existente reclamando su dirección.
\nAUTH_CUSTOM_ALLOW_ACCOUNT_LINKING: \"true\" le dice a Langfuse que las vincule de todos modos.\nEs seguro aquí porque tú eres dueño del único proveedor y controlas quién puede crear\ncuentas en él. No sería seguro apuntando a un proveedor donde cualquiera pueda auto-registrar\nun correo arbitrario.
La alternativa, si prefieres no habilitarlo: borra la cuenta local preexistente y deja que el\nSSO cree una nueva.
\nredirect_uri, o authentik negándose a redirigirLee la URL que falla en la barra de direcciones y compárala con la URI de redirección del\nproveedor carácter por carácter. En esta ejecución los desajustes que vale la pena nombrar\nfueron la ruta final /api/auth/callback/custom (cualquier otro sufijo falla), localhost\nfrente a la IP LAN, y una barra final suelta. Comparación estricta significa estricta.
Esa es la trampa del entorno de compose del Paso 5. Comprueba que las variables llegaron al\ncontenedor:
\ncd ~/langfuse && docker compose exec langfuse-web env | grep AUTH_CUSTOM_ISSUER
Salida vacía significa que Langfuse está corriendo sin la configuración que nunca supo que le\nfaltaba.
\nQue tu navegador alcance a authentik no es prueba de que Langfuse pueda. El intercambio de\ntokens es de contenedor a contenedor:
\nLa imagen de langfuse-web no trae curl, así que usa el runtime de Node que ya está ahí\ndentro — fetch viene incorporado:
cd ~/langfuse && docker compose exec langfuse-web node -e \\
\"fetch('http://10.80.4.212:9100/application/o/langfuse/.well-known/openid-configuration').then(r=>console.log(r.status)).catch(e=>console.log('FAIL',e.message))\"
200 es lo que quieres. FAIL con un error de conexión significa que el contenedor no puede\nalcanzar authentik en absoluto, que es justo lo que se está probando.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-discovery-200-f17cc0564e966cf97ba8d8a4cc9e7c9f.png\")
Esta es también la razón por la que el issuer es una IP LAN en lugar de localhost — dentro\ndel contenedor de Langfuse, localhost es el contenedor de Langfuse.
Puedes ejecutar tu propio proveedor de identidad y poner una app detrás de él por OIDC —\nleyendo el issuer, el client ID y el secreto desde authentik en lugar de ensamblar URLs a\nmano, y reconociendo los dos fallos que de verdad te detienen: un archivo compose que nunca\npasa las variables, y OAuthAccountNotLinked.
Hecho: un proveedor de identidad, un lugar donde viven las cuentas, un lugar para revocarlas.\nLangfuse ya no almacena una contraseña tuya. Y ahora tienes un proveedor al que puedes apuntar\nla siguiente app en unos cinco minutos.
\nNo hecho, y vale la pena ser claro al respecto:
\nakadmin, pierdes el proveedor que\nhace de fachada de todo lo que apunte a él.La Parte 4 pone identidad delante de algo donde estos huecos dejan de ser tolerables: la\ngateway LiteLLM de la serie del gateway. Tres\ncosas que este post dejó deliberadamente en paz:
\n127.0.0.1:4000, y hacerlo\ncorrectamente accesible significa un proxy inverso, un nombre de host y un certificado.Los pasos de proveedor y aplicación serán un repaso corto con un enlace de vuelta aquí. El\nresto es nuevo.
\nAUTH_CUSTOM_*OAuthAccountNotLinked+La Parte 4 construyó un callback\nque enmascara la PII en lo que el gateway registra sin tocar lo que recibe quien llama.\nTambién señaló que la primera versión funcional usaba un cliente HTTP bloqueante dentro\nde un async def, y que eso costaba 200-350ms sobre cuatro peticiones secuenciales.
Ese post terminaba con una confesión: cuatro peticiones seguidas es la prueba equivocada.\nUn bucle de eventos bloqueado apenas se nota cuando nada más está esperando. El daño\ndebería aparecer bajo concurrencia, y no lo habíamos medido.
\nEsta es esa medición, y el resultado es una forma más que un número. Con el cliente\nbloqueante, algunos lotes tardan muchas veces más de lo que deberían. Con el cliente\nasíncrono, ninguno. Las medianas apenas difieren, que es exactamente la razón por la\nque esto llega a producción sin que nadie lo note.
\nAparecieron dos cosas que no estaban en el plan. El gateway no solo se vuelve lento —\ndescarta peticiones. Y cuando lo hace, lo que expiró fue la llamada de enmascarado,\nmientras quien llama sigue recibiendo 200 OK. Eso significa que la garantía sobre la\nque se construyó la Parte 4 deja de cumplirse en silencio bajo carga.
httpx en tu entorno de PythonUna instancia WEC: 8 vCPU AMD EPYC 7601, 15 GB de RAM, Docker 29.1.3, kernel 5.15.\nLiteLLM 1.96.2 desde ghcr.io/berriai/litellm:main-stable. El analizador y el\nanonimizador de Presidio como contenedores locales en el mismo host. Modelo\nQwen2.5-3B-Instruct sobre la API de Inferencia de WEC. Cinco repeticiones por celda.
Los números de latencia no se transfieren entre máquinas. Trata cada segundo de este post\ncomo una observación de ese entorno, no como una cifra que igualar. Lo que sí debería\nreproducirse es la diferencia entre las dos versiones.
Todo lo que sigue depende de un número, y no es el número que da la documentación.
\nLa CLI del proxy de LiteLLM tiene una opción --num_workers. La\nreferencia publicada dice que su valor por\ndefecto es \"Number of logical CPUs in the system, or 4 if that cannot be determined.\"\nEn una máquina de ocho núcleos eso significaría ocho procesos de trabajo, ocho bucles de\neventos, y una llamada bloqueante atascando una octava parte de tu tráfico.
Pregúntale al host qué se está ejecutando realmente — desde fuera del contenedor, para\nque nada dentro de él pueda informar mal:
\ndocker top llm-gateway
UID PID PPID C STIME TTY TIME CMD
root 2477458 2477435 3 16:43 ? 00:01:19 /app/.venv/bin/python3 /app/.venv/bin/litellm --config /app/config.yaml --port 4000
root 2481091 2477458 0 16:44 ? 00:00:05 /opt/prisma/binaries/node_modules/prisma/query-engine-debian-openssl-3.0.x -p 53053
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-one-process-a28a66c6eafcb70fa88a41c347ddd22d.png\")
Figura 1. Un proceso de python ejecuta todo el proxy. La segunda entrada es Prisma, el\ncliente de base de datos, que no atiende peticiones.
\nSi --num_workers fuera mayor que uno verías varios procesos de python con el primero\ncomo padre. Confírmalo en el registro de arranque:
docker logs llm-gateway 2>&1 | grep -E \"Started server process|Uvicorn running\" | tail -2
INFO: Started server process [1]
INFO: Uvicorn running on http://0.0.0.0:4000 (Press CTRL+C to quit)
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-startup-log-df1d1c66b00b54c6d3cca0e6787ae4eb.png\")
Figura 2. Un proceso de servidor. Este registro se acumula entre reinicios, así que\ntail -2 te mantiene mirando el actual.
Ahora pregúntale a la herramienta cuál es su valor por defecto:
\ndocker exec llm-gateway litellm --help | grep -A5 \"^ --num_workers\"
--num_workers INTEGER Number of worker processes for uvicorn /
gunicorn, or Granian worker processes
(--workers). Default is 1 (from
DEFAULT_NUM_WORKERS_LITELLM_PROXY). With
--run_granian, use --granian_threads for
runtime threads per worker.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-worker-default-a862f11836711c637727b9c24b5d3b0a.png\")
Figura 3. El propio texto de ayuda de la herramienta: \"Default is 1.\"
\nEso es una cadena de ayuda. Como estamos a punto de contradecir la documentación\npublicada, tómalo también del código fuente — ajusta la versión de python en la ruta para\nque coincida con tu imagen:
\ndocker exec llm-gateway grep -rn 'DEFAULT_NUM_WORKERS_LITELLM_PROXY' \\
/app/.venv/lib/python3.13/site-packages/litellm/constants.py
15:DEFAULT_NUM_WORKERS_LITELLM_PROXY = int(os.getenv(\"DEFAULT_NUM_WORKERS_LITELLM_PROXY\", 1))
La referencia de la CLI indica que el valor por\ndefecto de --num_workers es \"Number of logical CPUs in the system, or 4 if that cannot\nbe determined.\" Tres fuentes dicen lo contrario: el contenedor en marcha, el código\ninstalado de 1.96.2, y el main actual del proyecto, donde tanto la constante como el\ntexto de ayuda siguen diciendo 1.
No es un desajuste de versiones, y no es algo de este despliegue. Comprueba el tuyo:
docker exec llm-gateway env | grep -i worker
Una salida vacía significa que estás en el valor por defecto, que es un worker.
Así que: un proceso, un bucle de eventos, compartido por cada petición en vuelo. Esa es la\ncondición que convierte una llamada bloqueante de un impuesto en una caída.
\nLanza N peticiones a la vez, cronometra cada una, informa el tiempo total del lote. El\nmensaje lleva PII para que el callback de enmascarado tenga trabajo real. Una petición\nfallida se cuenta en vez de dejar que abandone la ejecución — vas a necesitar eso.
\n\"\"\"Fire N chat completions at the gateway at once and report how long they take.
The message carries PII so the Presidio masking callback has real work to do.
A failed request is counted and reported, not allowed to abandon the batch.
\"\"\"
import asyncio
import os
import statistics
import sys
import time
import httpx
GATEWAY = \"http://127.0.0.1:4000/v1/chat/completions\"
KEY = os.environ[\"LITELLM_MASTER_KEY\"]
MODEL = \"qwen-small\"
PROMPT = (
\"Priya Raghunathan called from 415-555-0134 about her invoice. \"
\"Reply with exactly: ok\"
)
async def one(client, i):
start = time.perf_counter()
try:
r = await client.post(
GATEWAY,
headers={\"Authorization\": f\"Bearer {KEY}\"},
json={
\"model\": MODEL,
\"messages\": [{\"role\": \"user\", \"content\": PROMPT}],
\"max_tokens\": 5,
},
)
except Exception as exc:
return i, None, None, type(exc).__name__
return i, r.status_code, time.perf_counter() - start, None
async def main():
n = int(sys.argv[1])
async with httpx.AsyncClient(timeout=120.0) as client:
wall = time.perf_counter()
results = await asyncio.gather(*(one(client, i) for i in range(n)))
wall = time.perf_counter() - wall
times = sorted(e for _, _, e, _ in results if e is not None)
errors = [err for _, _, _, err in results if err]
print(f\"concurrency {n} ok {len(times)} failed {len(errors)}\")
if errors:
print(f\" errors {', '.join(sorted(set(errors)))}\")
print(f\" wall {wall:.2f}s\")
if times:
print(f\" fastest {times[0]:.2f}s\")
print(f\" median {statistics.median(times):.2f}s\")
print(f\" slowest {times[-1]:.2f}s\")
asyncio.run(main())
cd ~/llm-gateway && set -a && . ./.env && set +a
~/.venv/bin/python loadtest.py 8
concurrency 8 ok 8 failed 0
wall 1.93s
fastest 1.60s
median 1.91s
slowest 1.93s
![\"Ocho](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-first-load-be7eeba783710fd2f310b7add1c21fdc.png\")
Figura 4. Ocho a la vez, ninguna falló. Por sí solo este número todavía no significa\nnada.
\nAquí está la trampa. El gateway llama a un modelo por la red. Ese modelo tiene su propia\nlatencia, su propia carga y sus propias malas tardes. Cuando un lote tarda doce segundos\nno puedes saber si tu gateway se atascó o si el upstream estaba ocupado — y si adivinas,\nvas a publicar una tontería.
\nAsí que mide el upstream directamente, con el gateway fuera del camino. Copia el archivo y\ncambia las tres constantes de arriba:
\ncd ~/llm-gateway
cp loadtest.py loadtest_direct.py
GATEWAY = \"https://inference.wiline.com/v1/chat/completions\"
KEY = os.environ[\"WEC_API_KEY\"]
MODEL = \"Qwen2.5-3B-Instruct\"
~/.venv/bin/python loadtest_direct.py 8
concurrency 8 ok 8 failed 0
wall 1.15s
fastest 1.05s
median 1.10s
slowest 1.15s
![\"Ocho](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-control-6c9353892f98ded0047bab740eae67a0.png\")
Figura 5. Las mismas ocho peticiones con el gateway quitado. Esta es la referencia\ncontra la que se lee cada número del gateway.
\nAhora ejecuta las dos intercaladas, no una después de la otra, para que un minuto\nlento del upstream no caiga entero sobre una sola versión:
\n#!/bin/bash
# Interleave gateway runs with direct-to-upstream control runs so an upstream
# slowdown cannot be mistaken for a gateway effect.
set -a; . ./.env; set +a
REPS=5
# A restart takes longer than it looks. Firing requests at a port that is not
# answering yet produces instant failures that have nothing to do with the callback.
printf 'waiting for the gateway'
for _ in $(seq 1 60); do
curl -sf http://127.0.0.1:4000/health/liveliness >/dev/null 2>&1 && break
printf '.'; sleep 2
done
curl -sf http://127.0.0.1:4000/health/liveliness >/dev/null 2>&1 || { echo \" never came up — aborting\"; exit 1; }
echo \" up\"
# Do not trust a label passed on the command line — ask the gateway which callback
# it actually loaded. A mislabelled run is worse than no run.
LABEL=$(docker logs llm-gateway 2>&1 | grep '\\[scrubber\\]' | tail -1 | sed 's/.*loaded: //')
if [ -z \"$LABEL\" ]; then echo \"cannot determine loaded callback — aborting\"; exit 1; fi
echo \"callback in use: $LABEL\"
summarise() {
awk '/^concurrency/{failed=$6} /wall/{wall=$2} END{printf \"%s\", wall; if (failed+0 > 0) printf \"(%d failed)\", failed}'
}
# The first request after a restart pays for imports and connection pools, which
# has nothing to do with the callback. Warm both paths before recording anything.
~/.venv/bin/python loadtest.py 4 >/dev/null 2>&1
~/.venv/bin/python loadtest_direct.py 4 >/dev/null 2>&1
for n in 8 16; do
for i in $(seq 1 $REPS); do
g=$(~/.venv/bin/python loadtest.py $n | summarise)
d=$(~/.venv/bin/python loadtest_direct.py $n | summarise)
echo \"$LABEL N=$n rep=$i gateway=$g direct=$d\"
done
done
Tres detalles de ahí no son decoración, y cada uno costó una ejecución perdida para\naprenderlo:
\nEspera al gateway. Un docker compose restart puede tardar más de diez segundos, y\nlanzar peticiones a un puerto que todavía no escucha produce fallos instantáneos —\ngateway=0.03s(8 failed) — que parecen un resultado catastrófico y no significan nada.
Se niega a aceptar una etiqueta tuya. Lee el callback cargado del registro del\ngateway. Pasa blocking por la línea de comandos mientras está cargado el callback\nasíncrono y vas a medir el mismo código dos veces, no ver diferencia, y concluir que aquí\nno hay nada. Eso pasó dos veces escribiendo este post.
Descarta una pasada de calentamiento. El primer lote tras un reinicio paga las\nimportaciones y los pools de conexión, y llega de tres a seis veces más lento que el\nsiguiente, sin importar qué callback esté cargado.
\nEstás a punto de comparar dos versiones de un archivo, y necesitas certeza sobre cuál está\nactiva. El registro de arranque de LiteLLM lista los callbacks de éxito y de fallo pero no\nlitellm_settings.callbacks, y no hay un endpoint que los informe —\n/get/config/callbacks responde 200 con {\"detail\":\"Not Found\"}.
Así que haz que cada versión diga su propio nombre al importarse, donde no cuesta nada por\npetición:
\n# last line of scrubber.py
print(\"[scrubber] loaded: async httpx.AsyncClient\", flush=True)
# last line of scrubber_blocking.py
print(\"[scrubber] loaded: blocking httpx.Client\", flush=True)
Monta los dos archivos y cambia con una línea de configuración:
\n volumes:
- ./config.yaml:/app/config.yaml:ro
- ./scrubber.py:/app/scrubber.py:ro
- ./scrubber_blocking.py:/app/scrubber_blocking.py:ro
- ./recognizers.json:/app/recognizers.json:ro
litellm_settings:
callbacks: [\"scrubber.instance\"] # or scrubber_blocking.instance
sed -i 's/scrubber.instance/scrubber_blocking.instance/' config.yaml
docker compose restart litellm
El script del experimento imprime el callback cargado como primera línea, así que cada\nejecución lleva su propia prueba de lo que midió.
\n./run_experiment.sh
Con el cliente asíncrono:
\ncallback in use: async httpx.AsyncClient
async httpx.AsyncClient N=8 rep=1 gateway=0.98s direct=1.09s
async httpx.AsyncClient N=8 rep=2 gateway=0.86s direct=0.80s
async httpx.AsyncClient N=8 rep=3 gateway=0.92s direct=0.96s
async httpx.AsyncClient N=8 rep=4 gateway=0.78s direct=0.85s
async httpx.AsyncClient N=8 rep=5 gateway=0.90s direct=0.82s
async httpx.AsyncClient N=16 rep=1 gateway=1.61s direct=1.49s
async httpx.AsyncClient N=16 rep=2 gateway=1.65s direct=1.26s
async httpx.AsyncClient N=16 rep=3 gateway=1.28s direct=1.35s
async httpx.AsyncClient N=16 rep=4 gateway=1.33s direct=1.42s
async httpx.AsyncClient N=16 rep=5 gateway=1.77s direct=1.56s
![\"Diez](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-async-runs-44f396a0682d60c0748426e50abc69cf.png\")
Figura 6. El cliente asíncrono. Cada número del gateway está junto a su control, en\nlos dos niveles de concurrencia. Nada destaca porque nada pasó.
\nDespués cambia el callback y ejecuta lo mismo:
\nwaiting for the gateway up
callback in use: blocking httpx.Client
blocking httpx.Client N=8 rep=1 gateway=1.20s direct=0.93s
blocking httpx.Client N=8 rep=2 gateway=0.96s direct=0.83s
blocking httpx.Client N=8 rep=3 gateway=0.92s direct=0.86s
blocking httpx.Client N=8 rep=4 gateway=0.73s direct=0.90s
blocking httpx.Client N=8 rep=5 gateway=1.70s direct=0.90s
blocking httpx.Client N=16 rep=1 gateway=70.18s direct=2.00s
blocking httpx.Client N=16 rep=2 gateway=1.75s direct=1.70s
blocking httpx.Client N=16 rep=3 gateway=2.33s direct=1.78s
blocking httpx.Client N=16 rep=4 gateway=2.88s direct=1.49s
blocking httpx.Client N=16 rep=5 gateway=5.14s direct=1.19s
![\"Diez](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-blocking-runs-df9535bdd0ed417cb65599e60ca5e742.png\")
Figura 7. El cliente bloqueante. Mismo script, misma carga, una palabra distinta en el\ncódigo. La columna de control se mantiene entre 1,19 y 2,00s en todo momento.
\n| Versión | N | Mediana del gateway | Peor del gateway | Mediana del control |
|---|---|---|---|---|
asíncrono AsyncClient | 8 | 0,90s | 0,98s | 0,85s |
asíncrono AsyncClient | 16 | 1,61s | 1,77s | 1,42s |
bloqueante Client | 8 | 0,96s | 1,70s | 0,90s |
bloqueante Client | 16 | 2,88s | 70,18s * | 1,70s |
Figura 8. Cada lote de las Figuras 6 y 7 en un eje logarítmico. El control se mantiene\nen una banda estrecha en los cuatro grupos. Las ejecuciones asíncronas se quedan con él.\nDos bloqueantes lo abandonan.
\nEl lote de 70,18s coincidió con otra prueba de carga no relacionada contra el mismo\ngateway, así que parte de ese tiempo no es atribuible al callback. Se informa porque\nocurrió, no porque esté limpio. Lee el lote de 5,14s como el atasco representativo —\ntodavía más de cuatro veces su propio control de 1,19s.
El efecto en sí se reprodujo en cuatro ejecuciones distintas en este host, con atascos en\nN=16 de 11,22s, 12,44s, 21,22s, 31,14s y 5,14s. En todas las ejecuciones asíncronas\nlimpias: ninguno.
Lee primero las filas asíncronas. En N=8 la mediana del gateway es 0,90s y la del control\n0,85s. El callback, con todas sus idas y vueltas a Presidio, desaparece dentro de la\nlatencia del propio modelo.
\nAhora la fila bloqueante en N=8. Mediana de 0,96s contra un control de 0,90s. Eso es\n0,06s. Si midieras medianas y desplegaras, dirías que está bien — y el peor lote de esas\nmismas cinco tardó 1,70s mientras su propio control tardó 0,90s.
\nEn N=16 deja de esconderse. La mediana sube a 2,88s contra 1,70s, y la cola se sale del\ngráfico.
\nSabes distinguir si un gateway lento es tu propio código o el modelo al que llama —\nejecuta la misma carga contra los dos, intercalada, y lee la cola en vez de la mediana.
Antes de añadir el conteo de fallos al script de carga, una ejecución bloqueante murió del\ntodo:
\nhttpx.RemoteProtocolError: Server disconnected without sending a response.
Dos de diez lotes de esa ejecución perdieron peticiones así. Cero lotes asíncronos lo\nhicieron nunca. El gateway no estuvo lento para esos clientes. Les colgó.
\nPregúntale al gateway qué cree que pasó:
\ndocker logs llm-gateway 2>&1 | grep -c \"httpcore/_sync\"
docker logs llm-gateway 2>&1 | grep -A1 \"httpx.ReadTimeout\" | tail -4
77
INFO: 172.22.0.1:47566 - \"POST /v1/chat/completions HTTP/1.1\" 200 OK
--
httpx.ReadTimeout: timed out
INFO: 172.22.0.1:52870 - \"POST /v1/chat/completions HTTP/1.1\" 200 OK
![\"Setenta](\"https://development-wec.wiline.com/docs/es/assets/images/gw5-sync-timeout-d454e62c9e5512f71923e0ec2c0efbec.png\")
Figura 9. httpcore/_sync aparece 77 veces. El cliente asíncrono produciría _async.\nY el timeout está entre dos líneas 200 OK.
Ese _sync es la huella. Prueba que la llamada que falla es la llamada bloqueante a\nPresidio y no otra cosa de la pila. El error completo nombra a quien llama:
LiteLLM:ERROR: logging_worker.py:103 - LoggingWorker error: timed out
File \".../httpcore/_sync/connection_pool.py\", line 236, in handle_request
httpcore.ReadTimeout: timed out
Ahora mira lo que lo rodea. 200 OK. Las peticiones tuvieron éxito. Lo que falló fue\nel enmascarado.
Esa es la parte en la que vale la pena detenerse, porque toda la promesa de la Parte 4 era\nque la PII llega a tus rastros ya enmascarada. Bajo carga, con el cliente bloqueante, la\nllamada de enmascarado expira contra su propio límite de diez segundos mientras quien\nllama recibe un éxito normal. Nada en la respuesta te dice que la garantía dejó de\ncumplirse. Tendrías que estar leyendo el stderr del gateway para saberlo.
\nhttpx.Client dentro de un async def no cede el control. Cuando el callback llama a\nPresidio, el hilo que ejecuta el bucle de eventos se queda en una lectura de socket hasta\nque Presidio responde, y durante ese tiempo el bucle no atiende nada — ni la llamada al\nmodelo de otra petición, ni una respuesta que vuelve. Es un solo bucle, como confirmaste\nal principio.
Cada petición dispara varias de estas llamadas: los mensajes, la copia en el objeto de\nregistro estándar, y la respuesta. Así que bajo concurrencia las peticiones no se\nsolapan. Se ponen en fila, y la espera de cada una es la suma del tiempo de Presidio de\ntodas las anteriores. Por eso el efecto no es un impuesto constante — depende de cuántas\npeticiones lleguen mientras el bucle está retenido, que es también la razón por la que los\nnúmeros son irregulares en vez de uniformemente peores.
\nPasada cierta profundidad de cola, las esperas superan el propio timeout=10.0 del\nscrubber y el enmascarado se rinde, mientras las conexiones de cliente que esperan sobre\nun bucle congelado se caen. La mediana lo esconde todo porque a la mayoría de los lotes\nles toca suerte. La cola es la verdad.
El arreglo es el que adoptó la Parte 4, y esta es la evidencia a su favor:\nhttpx.AsyncClient con await, que cede el bucle mientras Presidio trabaja.
diff scrubber.py scrubber_blocking.py
26,27c26,27
< async with httpx.AsyncClient(timeout=10.0) as client:
< r = await client.post(f\"{ANALYZER}/analyze\", json={\"text\": text, \"language\": \"en\"})
---
> with httpx.Client(timeout=10.0) as client:
> r = client.post(f\"{ANALYZER}/analyze\", json={\"text\": text, \"language\": \"en\"})
Dos palabras y un await. Esa es toda la diferencia entre la Figura 6 y la Figura 7.
Más workers no es el arreglo, y la documentación explica por qué mejor de lo que podríamos\nnosotros. Sobre --timeout_worker_healthcheck, describiendo --num_workers > 1:
\n\n\"the supervisor process pings each worker; a worker that does not respond within this\nwindow (for example because its event loop is blocked by synchronous work) is killed\nwith SIGKILL and replaced.\"
\n
Con un worker no hay supervisor, así que un bucle bloqueado se atasca. Con varios, un\nworker bloqueado es eliminado y todo lo que tenía en vuelo muere en vez de esperar.\nNinguna de las dos cosas arregla el trabajo sincrónico sobre un bucle de eventos. Arregla\nla llamada.
\nCinco repeticiones por celda bastan para mostrar que existe un atasco al lado de un\ncontrol estable. No bastan para caracterizar la distribución — con qué frecuencia, con qué\ngravedad, o cómo escala más allá de N=16. Si ejecutas esto en producción, ejecútalo más\ntiempo y mira los percentiles.
\nNo probamos --num_workers > 1, respuestas en streaming, ni un Presidio lento o remoto en\nlugar de un contenedor local sano.
La preocupación obvia, cuando la llamada de enmascarado expira en una petición que\ndevolvió 200 OK, es que la carga sin enmascarar acabe igualmente en el rastro. No es\nasí.
Carga sostenida — seis rondas de veinticuatro peticiones concurrentes, cada una con un\nnombre y un número de teléfono — produjo 77 timeouts de enmascarado en el registro del\ngateway. De las 144 peticiones, 62 rastros llegaron a Langfuse y 82 no llegaron\nnunca. Los 62 estaban correctamente enmascarados. Ninguno llevaba un nombre en claro.
\nAsí que el fallo no es un fallo de privacidad. Es un fallo de observabilidad, y silencioso:\nbajo carga sostenida más de la mitad del tráfico simplemente no se registra, mientras cada\ncliente recibe un éxito normal. Si estás leyendo el volumen de rastros como aproximación\ndel tráfico, o contando con los rastros para una pista de auditoría, esa brecha es lo que\nhay que vigilar — y es invisible desde el lado de la respuesta.
\nConstruyendo esta prueba, las peticiones se etiquetaron con un marcador corto para poder\nencontrar cada rastro — [TAG-07] Priya Raghunathan called from …. Nueve rastros\nvolvieron entonces con el teléfono enmascarado y el nombre en claro, que se lee exactamente\ncomo una fuga inducida por la carga.
No lo era. De forma secuencial, sin carga alguna, esa frase enviada directamente a Presidio\ndevuelve solo PHONE_NUMBER; la misma frase sin el prefijo entre corchetes devuelve\nPERSON y PHONE_NUMBER a la vez. El marcador suprimió la detección del nombre, y el\ncallback enmascaró fielmente todo lo que Presidio informó.
Comprueba qué detecta tu analizador en tus cadenas exactas antes de concluir nada sobre el\nenmascarado bajo carga. Un instrumento que cambia lo que mide te va a entregar un hallazgo\nque no está ahí.
![\"PostgreSQL\"](\"https://development-wec.wiline.com/docs/es/assets/images/Postgresql_elephant.svg-62fedb3464ae364ae4e342c86b474ed6.png\")
+Tienes dos agentes. Uno reserva citas. Otro gestiona facturación.
\nLlega un ticket que necesita los dos: cambia la fecha de mi instalación, y mi factura\nparece incorrecta. Así que lo envías a los dos.
\nEl primero reserva el martes. El segundo ve que la cuenta está en mora y la congela. Los\ndos terminan casi en el mismo momento, y los dos guardan lo que decidieron.
\nSolo se guarda uno de ellos. ¿Cuál? El que terminó primero — que depende de lo lenta que\nestuviera una llamada de API ese día. Así que reservas una cita en una cuenta congelada, o\ncongelas una cuenta a la que acabas de prometerle un ingeniero. Después parece que se tomó\nuna única decisión limpia.
\nLa Parte 1 construyó un agente que\nejecuta sus pasos en un orden fijo. Este post tiene varios: un supervisor que elige quién\ntrabaja en qué, un agente que pasa el trabajo a otro a mitad de camino, y dos agentes\npuestos en el camino del otro a propósito — para descubrir qué hace LangGraph cuando no\nestán de acuerdo.
\n\nVersiones verificadas: Python 3.10.12 · langgraph 1.2.11 ·\nlanggraph-checkpoint 4.2.0 · langgraph-checkpoint-postgres 3.1.2 ·\npsycopg 3.3.4 · langchain-openai 1.6.0 · langfuse 4.14.5 contra el servidor\nLangfuse v3.205.1 OSS · imagen postgres:17. El contenedor lg-checkpoints y el\nvirtualenv de la Parte 1 se reutilizan sin cambios.
Dos agentes significa que algo tiene que elegir entre ellos. Ese algo se llama supervisor, y\nes simplemente otro agente cuyo único trabajo es elegir al siguiente.
\nLa Parte 1 conectó sus pasos de antemano con add_edge — paso uno, luego dos, luego tres.\nUn supervisor no puede hacer eso, porque no sabe adónde va el trabajo hasta que lo lee.
En su lugar el nodo devuelve un Command:
from langgraph.types import Command
def supervisor(state: State) -> Command[Literal[\"scheduler\", \"billing\"]]:
nxt = \"billing\" if \"invoice\" in state[\"ticket\"].lower() else \"scheduler\"
print(f\"supervisor routing to {nxt}\", flush=True)
return Command(goto=nxt, update={\"completed\": [f\"supervisor->{nxt}\"]})
Command hace dos trabajos a la vez: goto nombra el siguiente nodo, y update lleva un\ncambio de estado consigo. No hay ningún add_edge desde supervisor a nada — el\nenrutamiento ocurre en tiempo de ejecución, desde dentro de la función.
Guarda todo como lg_super.py:
import sys
from operator import add
from typing import Annotated, Literal
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.types import Command
DB_URI = \"postgresql://langgraph:changeme@127.0.0.1:5434/checkpoints\"
THREAD = sys.argv[1] if len(sys.argv) > 1 else \"sup-1\"
TICKET = sys.argv[2] if len(sys.argv) > 2 else \"reschedule my install\"
class State(TypedDict):
ticket: str
completed: Annotated[list[str], add]
def supervisor(state: State) -> Command[Literal[\"scheduler\", \"billing\"]]:
nxt = \"billing\" if \"invoice\" in state[\"ticket\"].lower() else \"scheduler\"
print(f\"supervisor routing to {nxt}\", flush=True)
return Command(goto=nxt, update={\"completed\": [f\"supervisor->{nxt}\"]})
def scheduler(state: State):
print(\"scheduler running\", flush=True)
return {\"completed\": [\"scheduler\"]}
def billing(state: State):
print(\"billing running\", flush=True)
return {\"completed\": [\"billing\"]}
builder = StateGraph(State)
builder.add_node(\"supervisor\", supervisor)
builder.add_node(\"scheduler\", scheduler)
builder.add_node(\"billing\", billing)
builder.add_edge(START, \"supervisor\")
builder.add_edge(\"scheduler\", END)
builder.add_edge(\"billing\", END)
if \"--draw\" in sys.argv:
print(builder.compile().get_graph().draw_mermaid())
raise SystemExit
with PostgresSaver.from_conn_string(DB_URI) as cp:
cp.setup()
graph = builder.compile(checkpointer=cp)
config = {\"configurable\": {\"thread_id\": THREAD}}
print(\"FINAL:\", graph.invoke({\"ticket\": TICKET, \"completed\": []}, config), flush=True)
La rama --draw imprime el grafo y sale antes de tocar Postgres, así que puedes inspeccionar\nla topología sin base de datos. Se gana su sitio en la sección siguiente.
~/.venv/bin/python ~/lg_super.py sup-1 \"reschedule my install\"
supervisor routing to scheduler
scheduler running
FINAL: {'ticket': 'reschedule my install', 'completed': ['supervisor->scheduler', 'scheduler']}
Y la otra rama, para mostrar que el enrutamiento depende de los datos y no está fijo en el\ncódigo:
\n~/.venv/bin/python ~/lg_super.py sup-2 \"please fix the invoice on my account\"
supervisor routing to billing
billing running
FINAL: {'ticket': 'please fix the invoice on my account', 'completed': ['supervisor->billing', 'billing']}
Esa anotación de retorno parece typing normal que podrías quitar:
\ndef supervisor(state: State) -> Command[Literal[\"scheduler\", \"billing\"]]:
Quítala y el código se ejecuta igual — mismo enrutamiento, misma salida. Así que es\nopcional. Excepto que no lo es.
\nsed 's/ -> Command\\[Literal\\[\"scheduler\", \"billing\"\\]\\]//' ~/lg_super.py > ~/lg_super_noann.py
Pídele a las dos versiones que se dibujen:
\n~/.venv/bin/python ~/lg_super.py --draw
~/.venv/bin/python ~/lg_super_noann.py --draw
Con la anotación, las dos rutas posibles están ahí como aristas condicionales punteadas:
\n__start__ --> supervisor;
supervisor -.-> billing;
supervisor -.-> scheduler;
billing --> __end__;
scheduler --> __end__;
Sin ella, desaparecen, y el grafo afirma algo falso:
\n__start__ --> supervisor;
supervisor --> __end__;
scheduler y billing siguen declarados como nodos, y ahora nada llega a ellos. El\ndiagrama dice que el supervisor va directo al final.
![\"Dos](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-graphs-522fc91da9a7554bb7444d68736b3ee7.png\")
\nFigura 1. El mismo código, con una anotación de diferencia. El grafo de abajo está mal.
La razón es mecánica: goto se decide dentro del cuerpo de la función, donde nada puede\ninspeccionarlo. La anotación es la única declaración de dónde tiene permitido un\nsupervisor mandar trabajo. Omítela y tu código sigue funcionando mientras cada diagrama, y\ncualquier otra cosa que lea la topología, miente en silencio.
draw_ascii() necesita un paquete que LangGraph no incluyeget_graph().draw_ascii() lanza\nImportError: Install grandalf to draw graphs: 'pip install grandalf'.\ndraw_mermaid() no tiene dependencias extra y es lo que usan los ejemplos de arriba.
Un supervisor decide una vez, al principio. Eso es un problema cuando el descubrimiento\nocurre más tarde.
\nToma un ticket que pide cambiar la fecha de una instalación, en una cuenta que resulta estar\nen mora. El supervisor ve una petición de agenda y enruta en consecuencia. El agente de\nagenda empieza a trabajar, lee la cuenta, y encuentra un problema que le pertenece a\nfacturación.
\nEl agente de agenda también puede enrutar — es un nodo, y los nodos devuelven Command.
Copia lg_super.py a lg_handoff.py, reemplaza scheduler con la versión de abajo, y borra\nla línea builder.add_edge(\"scheduler\", END) — el nodo decide su propia salida ahora:
def scheduler(state: State) -> Command[Literal[\"billing\", \"__end__\"]]:
if \"past due\" in state[\"ticket\"].lower():
print(\"scheduler: account is past due, handing off to billing\", flush=True)
return Command(goto=\"billing\", update={\"completed\": [\"scheduler(handoff)\"]})
print(\"scheduler: booking it\", flush=True)
return Command(goto=END, update={\"completed\": [\"scheduler(booked)\"]})
~/.venv/bin/python ~/lg_handoff.py handoff-3 \"reschedule my install, account is past due\"
~/.venv/bin/python ~/lg_handoff.py handoff-4 \"reschedule my install\"
supervisor -> scheduler
scheduler: account is past due, handing off to billing
billing running
FINAL: {'ticket': '...past due', 'completed': ['supervisor', 'scheduler(handoff)', 'billing']}
supervisor -> scheduler
scheduler: booking it
FINAL: {'ticket': 'reschedule my install', 'completed': ['supervisor', 'scheduler(booked)']}
![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-handoff-4bb2edcb710dc048a8d846ee980848c2.png\")
\nFigura 2. El supervisor nunca supo que facturación estaría implicada.
Dos detalles que vale la pena guardar. goto=END funciona desde dentro de un Command, así\nque un nodo puede terminar la ejecución por sí mismo. Y \"__end__\" es la forma en cadena de\nEND en ese Literal — la anotación necesita el valor literal, no la constante.
Esta es la diferencia entre los dos patrones publicados. Un supervisor decide desde\nfuera y necesita conocer cada precondición por adelantado. Un traspaso deja que el\nagente que hace el trabajo redirija en cuanto aprende algo. La mayoría de los sistemas\nreales quieren los dos, que es lo que tiene este grafo.
\nHasta aquí el supervisor elige un agente. A veces quieres los dos — revisar el calendario y\nla cuenta al mismo tiempo, en vez de esperar a uno antes de empezar el otro. goto acepta\nuna lista precisamente para eso:
return Command(goto=[\"scheduler\", \"billing\"], update={\"completed\": [\"supervisor\"]})
Los dos se ejecutan en el mismo super-paso. Que es donde se pone interesante, porque ahora\npueden no estar de acuerdo.
\nCopia lg_super.py a lg_conflict.py. Dale al estado dos tipos de campo:
class State(TypedDict):
completed: Annotated[list[str], add] # has a reducer
decision: str # no reducer
Y haz que cada agente escriba un valor distinto en el que no tiene reducer:
\ndef scheduler(state: State):
return {\"completed\": [\"scheduler\"], \"decision\": \"book tuesday\"}
def billing(state: State):
return {\"completed\": [\"billing\"], \"decision\": \"refund first\"}
~/.venv/bin/python ~/lg_conflict.py conflict-2
supervisor sending work to BOTH
billing deciding
scheduler deciding
Traceback (most recent call last):
...
File \".../langgraph/pregel/_loop.py\", line 692, in after_tick
self.updated_channels = apply_writes(
File \".../langgraph/channels/last_value.py\", line 64, in update
raise InvalidUpdateError(msg)
langgraph.errors.InvalidUpdateError: At key 'decision': Can receive only one value
per step. Use an Annotated key to handle multiple values.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-conflict-906aa9ed90d5c25e9021f93fef593bcf.png\")
\nFigura 3. Los dos agentes terminaron. El grafo se negó a fusionar sus respuestas.
Lee la traza con atención, porque tres cosas de ella importan.
\nLos dos agentes se ejecutaron. billing deciding y scheduler deciding se imprimieron\nlos dos. El trabajo se completó; el fallo vino después, en after_tick → apply_writes.\nEsto no son dos agentes chocando en vuelo. Es el grafo negándose a reconciliarlos en el\nlímite del paso.
completed estuvo bien. Los dos agentes le añadieron valores en el mismo paso y nada se\nquejó, porque add dice qué significan dos valores. Solo falló decision.
LangGraph no elige un ganador. Ni \"el último gana\", ni una elección silenciosa. Que es\nel comportamiento correcto — la alternativa es un agente de reservas que a veces reserva el\nmartes y a veces emite un reembolso según qué tarea terminó primero por casualidad.
\nFíjate también en el orden: billing se imprimió antes que scheduler, al revés de la\nlista de goto. Las ramas paralelas terminan en el orden en que terminen.
El arreglo no es evitar el desacuerdo. Es decir qué significa un desacuerdo. Copia\nlg_conflict.py a lg_resolve.py y añade el reducer:
PRIORITY = {\"refund first\": 2, \"book tuesday\": 1}
def prefer_higher_priority(old: str, new: str) -> str:
\"\"\"The policy: a billing hold outranks a scheduling decision.\"\"\"
winner = max([old, new], key=lambda v: PRIORITY.get(v, 0))
print(f\" reducer: '{old}' vs '{new}' -> '{winner}'\", flush=True)
return winner
class State(TypedDict):
completed: Annotated[list[str], add]
decision: Annotated[str, prefer_higher_priority]
~/.venv/bin/python ~/lg_resolve.py resolve-2
reducer: '' vs '' -> ''
supervisor sending work to BOTH
billing deciding
scheduler deciding
reducer: '' vs 'refund first' -> 'refund first'
reducer: 'refund first' vs 'book tuesday' -> 'refund first'
FINAL: {'completed': ['supervisor', 'billing', 'scheduler'], 'decision': 'refund first'}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-resolve-e9d09a07776b7e33a95a0f951453e628.png\")
\nFigura 4. El print dentro del reducer hace visible la fusión.
Mismo grafo, mismo desacuerdo, ningún error. Y la traza muestra tres cosas que la\ndocumentación no deja claras:
\nEl reducer se ejecuta por pares, plegando hacia la izquierda. No una vez con los dos\nvalores — dos veces, acumulando. Primero fusiona el estado existente con la respuesta de\nfacturación, luego fusiona ese resultado con la del agente de agenda.
\nPor tanto debe ser independiente del orden. Como las ramas terminan en orden arbitrario,\nun reducer del tipo \"toma el más nuevo\" produce respuestas distintas en ejecuciones\ndistintas. max por prioridad no.
Se dispara antes de que se ejecute nada. Ese primer reducer: '' vs '' -> '' es el\nestado inicial siendo escrito, fusionando el valor por defecto con el decision: \"\" pasado a\ninvoke. Tu reducer ve entrada vacía y tiene que tolerarla.
La Parte 1 mostró una ejecución matada reanudando desde su último nodo completado. El trabajo\nparalelo plantea una pregunta más afilada: si una rama termina y su hermana muere, ¿se pierde\nel trabajo terminado?
\nCopia lg_conflict.py a lg_partial.py. Quita el campo decision, añade\nRESUME = \"--resume\" in sys.argv, pasa None if RESUME else {...} a invoke como en la\nParte 1, y reemplaza los dos especialistas por un nodo instantáneo y otro lo bastante lento\npara matarlo:
def fast(state: State):
print(\"fast running — finishes immediately\", flush=True)
return {\"completed\": [\"fast\"]}
def slow(state: State):
print(\"slow running — 30s window, KILL ME HERE\", flush=True); time.sleep(30)
return {\"completed\": [\"slow\"]}
~/.venv/bin/python ~/lg_partial.py partial-2
Pulsa Ctrl+C durante la ventana. Hacen falta dos pulsaciones, y la ejecución termina con algo\nque parece mucho peor que un KeyboardInterrupt:
File \".../langgraph/pregel/_runner.py\", line 613, in commit
self.put_writes()(task.id, task.writes)
...
RuntimeError: cannot schedule new futures after shutdown
Esa es la escritura del checkpoint de fast siendo confirmada contra un executor que ya se\nha cerrado. Se lee como pérdida de datos.
No lo es:
\n~/.venv/bin/python ~/lg_partial.py partial-2 --resume
BEFORE values={'completed': ['supervisor', 'fast']} next=('slow',)
slow running — 30s window, KILL ME HERE
FINAL: {'completed': ['supervisor', 'fast', 'slow']}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-partial-13329c0354dca69472571333fd73fb02.png\")
\nFigura 5. fast recuperado, no se volvió a ejecutar, y next nombra solo la rama que\nmurió.
fast está en el estado recuperado, aparece exactamente una vez en el resultado final, y\nnext=('slow',) nombra solo la rama que nunca terminó. La escritura ya había aterrizado en\ncheckpoint_writes — la misma tabla que impidió que step_one se repitiera en la Parte 1\nahora protege a una hermana completada.
Vale la pena documentarlo precisamente porque el error sugiere lo contrario. Un\nRuntimeError en una ruta de cierre es ruido; el estado es lo que hay que comprobar.
Cada decisión de enrutamiento hasta aquí ha sido \"invoice\" in ticket — coincidencia de\npalabras clave. Ese es el enfoque que medimos desmoronándose en\nel enrutador por complejidad del gateway, donde un\nplural basta para no encontrar una palabra clave.
Así que deja que el modelo decida. Copia lg_super.py a lg_traced.py — mismo grafo, un\nnodo cambiado:
llm = ChatOpenAI(
model=\"gemma4\",
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
temperature=0,
)
def supervisor(state: State) -> Command[Literal[\"scheduler\", \"billing\"]]:
r = llm.invoke(
\"Route this support ticket to exactly one team. \"
\"Answer with one word, either scheduler or billing, nothing else.\\n\\n\"
f\"Ticket: {state['ticket']}\"
)
raw = (r.content or \"\").strip().lower()
nxt = \"billing\" if \"billing\" in raw else \"scheduler\"
print(f\"supervisor: model said {raw!r} -> {nxt}\", flush=True)
return Command(goto=nxt, update={\"completed\": [f\"supervisor->{nxt}\"]})
Las credenciales vienen del entorno, que el .env del gateway ya contiene:
set -a; . ~/llm-gateway/.env; set +a; ~/.venv/bin/python ~/lg_traced.py traced-1
El ticket es deliberadamente ambiguo — \"my bill looks wrong and I need a new install date\"\nmenciona los dos:
\nsupervisor: model said 'billing' -> billing
billing running
FINAL: {'ticket': 'my bill looks wrong and I need a new install date', 'completed': ['supervisor->billing', 'billing']}
Una palabra, sin frase envolvente, y el parseo se mantuvo. Eligió facturación — defendible,\nya que una cuenta sin pagar bloquea la instalación, que es la misma conclusión a la que llegó\nantes el traspaso leyendo la cuenta.
\nPedirle a un modelo que elija no es gratis, y la factura no está donde la buscarías. Activar\nel trazado muestra a dónde fueron el tiempo y los tokens. Es una línea, como en la Parte 1 —\nCallbackHandler() lee sus credenciales del entorno y va en el mismo diccionario de\nconfiguración que el id del hilo:
from langfuse.langchain import CallbackHandler
handler = CallbackHandler()
config = {\"configurable\": {\"thread_id\": THREAD}, \"callbacks\": [handler]}
![\"Rastro](\"https://development-wec.wiline.com/docs/es/assets/images/lg2-trace-771785326bcdaf3d0132233cc7bdf9fc.png\")
\nFigura 6. Tres cosas enmarcadas: lo que costó el enrutamiento, la decisión como dato, y\nla carga llegando.
El árbol de spans es el grafo:
\nLangGraph 8.66s
supervisor 8.53s
ChatOpenAI 8.49s 52 → 412 (Σ 464)
billing 0.01s
Tres hallazgos están en ese cuadro.
\nUna respuesta de una palabra costó 412 tokens de salida. Confirmado contra la API en vez\nde leído en la pantalla:
\nset -a; . ~/llm-gateway/.env; set +a
curl -s -u \"$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY\" \\
\"$LANGFUSE_HOST/api/public/observations?limit=8\" \\
| jq '.data[] | select(.name==\"ChatOpenAI\") | {model, usage}'
{
\"model\": \"gemma4\",
\"usage\": {
\"unit\": \"TOKENS\",
\"input\": 52,
\"output\": 412,
\"total\": 464
}
}
La respuesta visible tiene siete caracteres. La factura es de 412 tokens de salida. Lo que\nsea que el modelo generó antes de decidirse, lo pagaste — y una llamada de enrutamiento\nparece lo más barato del grafo.
\nEl supervisor es el nodo caro, no los especialistas. billing tardó 6ms y ningún token.\nEl enrutador tardó 8,49s y 464. En un grafo multi-agente, las decisiones de orquestación son\nel centro de coste.
La decisión de enrutamiento queda registrada como dato. La salida del supervisor en el\nrastro es el Command serializado:
{\"graph\": null, \"update\": {\"completed\": [\"supervisor->billing\"]}, \"resume\": null, \"goto\": \"billing\"}
Y la entrada de billing contiene [\"supervisor->billing\"] — el update de ese Command\nllegando como estado del agente que lo recibe. Traspaso, coste y carga en un solo cuadro.
scheduler no aparece en ninguna parte de este rastro — ni como span omitido, ni como nodo\ndesactivado. El panel Graph dibuja __start__ → supervisor → billing → __end__. No puedes\nsaber desde un rastro qué alternativas existían, solo cuál se ejecutó, que es una segunda\nrazón por la que importa la anotación Literal que falta: el grafo dibujado es el único\nsitio donde tus alternativas están escritas.
Parte 3: las herramientas que un agente tiene permitido llamar. Todo lo anterior confía en\nque cada nodo haga solo lo que debe — el próximo post pone las herramientas detrás de un\ngateway con permisos por herramienta, para que las capacidades de un agente se concedan en\nvez de asumirse.
\nImportError: Install grandalf to draw graphsdraw_ascii() necesita un paquete del que LangGraph no depende. Usa draw_mermaid().
__end__Al nodo de enrutamiento le falta su anotación de retorno -> Command[Literal[...]]. El\ncódigo sigue funcionando; solo la topología está mal.
InvalidUpdateError: At key 'x': Can receive only one value per stepDos nodos escribieron la misma clave en un super-paso y esa clave no tiene reducer. O le das\nuno con Annotated[T, fn], o dejas de despachar los dos nodos en paralelo.
RuntimeError: cannot schedule new futures after shutdown después de Ctrl+CLa escritura del checkpoint de una rama completada compitió con el cierre del executor.\nComprueba graph.get_state(config).values antes de asumir que se perdió algo — en las\npruebas la escritura había aterrizado todas las veces.
No es independiente del orden. Las ramas paralelas terminan en orden arbitrario, así que un\nreducer que dependa de qué valor llega segundo es no determinista por construcción.
\n+Tu agente lleva cuarenta segundos trabajando en la petición de un cliente. Ha leído el\nticket, ha consultado la cuenta y ha revisado los calendarios de tres ingenieros. Está a\npunto de reservar la cita.
\nEntonces el proceso muere. Un despliegue que sale, el host que se queda sin memoria,\nalguien que reinicia el contenedor — da igual cuál de ellos.
\nEl agente no continúa donde lo dejó, porque no hay nada desde donde continuar. Todo lo que\naprendió vivía en variables dentro de un proceso que ya no existe. El cliente sigue\nesperando. Ejecútalo de nuevo y pagas todo ese trabajo por segunda vez. Y la parte que más\ndebería preocuparte: nadie puede decir si la cita se reservó en el último segundo antes de\nmorir.
\nUn agente es un modelo dentro de un bucle. Como script de Python normal, ese bucle es\nexactamente igual de frágil que el proceso que lo contiene.
\nAquí construimos uno que guarda su estado en Postgres después de cada paso, para que una\ncaída no cueste nada.
\n\nVersiones verificadas: Python 3.10.12 · langgraph 1.2.11 ·\nlanggraph-checkpoint 4.2.0 · langgraph-checkpoint-postgres 3.1.2 ·\npsycopg 3.3.4 · psycopg-pool 3.3.1 · langchain-openai 1.6.0 ·\nlangfuse 4.14.5 contra el servidor Langfuse v3.205.1 OSS · imagen postgres:17.
Lo que quieres es una ejecución reanudable: el resultado de cada paso escrito en algún\nsitio duradero en el momento en que termina, para que un proceso nuevo pueda continuar\ndesde ahí.
\nEso es lo que hace un checkpointer.
\nUn bucle con un try/except y unas cuantas escrituras a base de datos podría hacer esto\npara cuatro pasos fijos. Deja de funcionar en el momento en que el agente elige su propio\ncamino: cuando el modelo escoge la siguiente herramienta, \"¿dónde estamos?\" no tiene una\nrespuesta que puedas escribir.
LangGraph te obliga a declarar el trabajo como un grafo — nodos con nombre, aristas\nexplícitas. Eso parece ceremonia hasta que quieres durabilidad.
\n| Un bucle | Un grafo |
|---|---|
| Los pasos están implícitos en el flujo de control | Los pasos son nodos con nombre |
| \"¿Dónde estoy?\" no tiene respuesta | La posición es un valor que puedes leer |
| El estado vive en variables locales | El estado es un objeto declarado |
| No hay nada que guardar | Hay un momento obvio para guardar: los límites de nodo |
El runtime sabe cuándo empieza y termina un nodo, así que tiene un momento obvio para\nguardar. El estado es un objeto declarado, así que hay algo concreto que escribir.
\nEso es lo que significa \"una máquina de estados determinista alrededor de un modelo no\ndeterminista\": la salida es impredecible, el siguiente paso no. Más sobre ese debate en\n\"Loop Engineering Is Dead\".
\nTres propiedades que los ejemplos habituales no tienen:
\npython3 -m venv .venv
source .venv/bin/activate
pip install \"langgraph\" \"langgraph-checkpoint-postgres\" \"psycopg[binary,pool]\"
| Paquete | Qué hace | Por qué lo necesitas aquí |
|---|---|---|
langgraph | El runtime del grafo — nodos, aristas, estado | La orquestación en sí |
langgraph-checkpoint-postgres | Escribe el estado en Postgres | El objetivo de este tutorial |
psycopg[binary,pool] | Driver de Postgres + pool de conexiones | PostgresSaver requiere un pool |
Vale la pena detenerse en la fila del medio. La persistencia por defecto de LangGraph es\nen memoria. La durabilidad es opcional, en un paquete aparte que tienes que saber que\nhay que instalar. Esa es precisamente la razón por la que tantos ejemplos publicados\npierden el estado en silencio: nunca instalaron esto, y nada les avisó.
\nTres nombres arrastran más de tres paquetes:
\n./.venv/bin/pip list | grep -iE \"langgraph|psycopg\" && python3 --version
langgraph 1.2.11
langgraph-checkpoint 4.2.0
langgraph-checkpoint-postgres 3.1.2
langgraph-prebuilt 1.1.0
langgraph-sdk 0.4.3
psycopg 3.3.4
psycopg-binary 3.3.4
psycopg-pool 3.3.1
Python 3.10.12
langgraph-checkpoint es el que hay que notar: es la interfaz abstracta, y -postgres es\nuna implementación de ella. Esa separación es la razón por la que cambiar Postgres por\nSQLite o Redis más adelante cambia una línea.
El extra pool tampoco es decoración. Instala psycopg a secas y el fallo llega al\nconectar, no al instalar — que es un sitio mucho más confuso donde encontrarlo.
![\"pip](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-versions-21d23b4acd78bb5e757cf1a9f3949f97.png\")
\nFigura 1. Ocho paquetes desde tres nombres — la interfaz de checkpoint y su\nimplementación en Postgres llegan por separado.
docker run -d --name lg-checkpoints \\
-e POSTGRES_USER=langgraph -e POSTGRES_PASSWORD=changeme -e POSTGRES_DB=checkpoints \\
-p 127.0.0.1:5434:5432 postgres:17
Tres decisiones deliberadas:
\nUna base de datos dedicada. Los checkpoints son intensivos en escritura — una fila por\ntransición de nodo, por hilo, para siempre. Mezclados en la base de datos de tu aplicación\nse convierten en una tabla que te da miedo truncar. Separados, son desechables.
\n127.0.0.1:5434:5432, no -p 5434:5432. La forma corta escucha en todas las\ninterfaces, y Docker escribe sus propias reglas de iptables que se saltan UFW — así que un\nfirewall que parece correcto no está protegiendo este puerto. Lo cubrimos en\nEndurecer redes Docker.
El número de la izquierda es el puerto del host, el de la derecha el del contenedor. En una\ninstancia vacía usa 5432:5432. Si ya autoalojas algo con base de datos, ese puerto\nprobablemente esté ocupado — elige cualquiera libre.
postgres:17 fijado. latest significa que alguien que lea esto en seis meses\nejecutará algo que nunca probaste.
Estar en marcha no es lo mismo que estar listo:
\ndocker exec lg-checkpoints pg_isready -U langgraph -d checkpoints
/var/run/postgresql:5432 - accepting connections
Un contenedor informa Up en el instante en que arranca, mientras Postgres dentro todavía\nse está inicializando. Conectar demasiado pronto da un error de conexión que parece un\nproblema de configuración y no lo es.
Ningún LLM en este paso. Si algo falla ahora, es culpa del checkpointer y no del modelo — y\nseparar esas dos cosas es la mayor parte de lo que consiste depurar un agente.
\nfrom operator import add
from typing import Annotated
from typing_extensions import TypedDict
class State(TypedDict):
completed: Annotated[list[str], add]
Esto declara qué recuerda el grafo. TypedDict da la forma; la parte Annotated[..., add]\nes la mitad interesante.
Por defecto, cuando un nodo devuelve un valor para una clave, ese valor reemplaza lo\nque había. Annotated[list[str], add] adjunta un reducer — una función que combina el\nvalor viejo con el nuevo en vez de sobrescribirlo. Con operator.add sobre una lista, eso\nsignifica añadir al final.
| Declaración | step_one devuelve [\"a\"], luego step_two devuelve [\"b\"] |
|---|---|
completed: list[str] | [\"b\"] — el primer resultado se pierde |
completed: Annotated[list[str], add] | [\"a\", \"b\"] — acumula |
Equivócate en esto y tu estado olvida en silencio todo excepto el último nodo.
\ndef step_one(state: State):
print(\"step_one running\", flush=True); time.sleep(2)
return {\"completed\": [\"step_one\"]}
def step_two(state: State):
print(\"step_two running — 30s window, KILL ME HERE\", flush=True); time.sleep(30)
return {\"completed\": [\"step_two\"]}
Un nodo es una función normal. Recibe el estado actual y devuelve una actualización\nparcial — solo las claves que cambió, no el objeto entero. El runtime fusiona esa\nactualización usando los reducers que declaraste.
\nEl sleep de treinta segundos en step_two representa un paso lento — una llamada a un\nmodelo, una API externa, un trabajo por lotes. Es también lo que te da tiempo para matar el\nproceso en el momento justo en el paso siguiente.
builder = StateGraph(State)
for name, fn in [(\"step_one\", step_one), (\"step_two\", step_two), (\"step_three\", step_three)]:
builder.add_node(name, fn)
builder.add_edge(START, \"step_one\")
builder.add_edge(\"step_one\", \"step_two\")
builder.add_edge(\"step_two\", \"step_three\")
builder.add_edge(\"step_three\", END)
StateGraph(State) vincula el esquema. add_node registra una función bajo un nombre — ese\nnombre es el que aparece en los checkpoints y en los rastros más adelante. add_edge\ndeclara el orden, con START y END como los centinelas que marcan la entrada y la salida.
Este grafo es una línea recta. La ramificación llega en la parte 2.
\nwith PostgresSaver.from_conn_string(DB_URI) as checkpointer:
checkpointer.setup()
graph = builder.compile(checkpointer=checkpointer)
config = {\"configurable\": {\"thread_id\": THREAD}}
result = graph.invoke({\"completed\": []}, config)
Cuatro líneas, cada una con su trampa.
\nwith ... as checkpointer. from_conn_string está decorado con @contextmanager en el\ncódigo fuente — cede un valor, no lo devuelve. Asignarlo directamente te entrega un objeto\ngestor de contexto donde esperabas un saver, y el error llega mucho más tarde que el fallo.
También abre la conexión con autocommit=True, prepare_threshold=0 y\nrow_factory=dict_row. Si pasas tu propia conexión tienes que configurar eso tú, o\n.setup() puede parecer que funcionó y no guardar nada. Por qué hace falta cada uno no está\ndocumentado en ninguna parte — mira la\nissue #4937, cerrada sin respuesta.
.setup() es obligatorio en el primer uso. Crea las tablas y ejecuta las migraciones.
compile(checkpointer=...). Sin este argumento el grafo se ejecuta perfectamente y no\nguarda nada. No hay ninguna advertencia. Es la razón más probable por la que alguien cree\nque los checkpoints \"no funcionan\".
thread_id. El identificador de una conversación o de una ejecución. Cada checkpoint\nestá limitado a él, y reanudar significa pasar el mismo. Tiene que quedarse por debajo de\n255 caracteres.
Todo junto, eso es lg_agent.py:
import sys, time
from operator import add
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.postgres import PostgresSaver
DB_URI = \"postgresql://langgraph:changeme@127.0.0.1:5434/checkpoints\"
THREAD = sys.argv[1] if len(sys.argv) > 1 else \"ticket-1\"
RESUME = \"--resume\" in sys.argv
class State(TypedDict):
completed: Annotated[list[str], add]
def step_one(state: State):
print(\"step_one running\", flush=True); time.sleep(2)
return {\"completed\": [\"step_one\"]}
def step_two(state: State):
print(\"step_two running — 30s window, KILL ME HERE\", flush=True); time.sleep(30)
return {\"completed\": [\"step_two\"]}
def step_three(state: State):
print(\"step_three running\", flush=True)
return {\"completed\": [\"step_three\"]}
builder = StateGraph(State)
for name, fn in [(\"step_one\", step_one), (\"step_two\", step_two), (\"step_three\", step_three)]:
builder.add_node(name, fn)
builder.add_edge(START, \"step_one\")
builder.add_edge(\"step_one\", \"step_two\")
builder.add_edge(\"step_two\", \"step_three\")
builder.add_edge(\"step_three\", END)
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
checkpointer.setup()
graph = builder.compile(checkpointer=checkpointer)
config = {\"configurable\": {\"thread_id\": THREAD}}
snap = graph.get_state(config)
print(f\"BEFORE values={snap.values} next={snap.next}\", flush=True)
result = graph.invoke(None if RESUME else {\"completed\": []}, config)
print(\"FINAL:\", result, flush=True)
snap = graph.get_state(config)
print(f\"AFTER values={snap.values} next={snap.next}\", flush=True)
RESUME es lo que hace que --resume funcione: en una reanudación la entrada es None en\nvez de un estado nuevo, que es lo que cubre el paso siguiente.
python lg_agent.py ticket-41
Después de la primera ejecución existen cuatro tablas:
\ndocker exec lg-checkpoints psql -U langgraph -d checkpoints -c '\\dt'
public | checkpoint_blobs | table | langgraph
public | checkpoint_migrations | table | langgraph
public | checkpoint_writes | table | langgraph
public | checkpoints | table | langgraph
| Tabla | Contiene |
|---|---|
checkpoints | Una fila por límite de nodo — el índice de instantáneas |
checkpoint_blobs | Los valores de estado serializados |
checkpoint_writes | Escrituras pendientes de nodos que terminaron en un super-paso |
checkpoint_migrations | Registro de la versión del esquema |
checkpoint_writes es la que hace que funcione la recuperación tras una caída, como\nmuestra el paso siguiente.
![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-tables-f26befffa3adb092e0cecaa4126737c2.png\")
\nFigura 2. .setup() escribe el esquema por ti — sin DDL manual.
snap = graph.get_state(config)
print(f\"BEFORE values={snap.values} next={snap.next}\")
get_state devuelve un StateSnapshot. Importan dos campos: values es el estado ahora\nmismo, y next es la tupla de nodos que quedan por ejecutar. next=() significa que el\nhilo terminó o nunca empezó; cualquier otra cosa nombra lo que está pendiente.
next es cómo respondes \"¿dónde está esta ejecución?\" — la pregunta que un bucle no puede\nresponder.
Arranca un hilo nuevo y pulsa Ctrl+C durante la ventana de treinta segundos.
\npython lg_agent.py ticket-42
BEFORE values={} next=()
step_one running
step_two running — 30s window, KILL ME HERE
^CKeyboardInterrupt
![\"KeyboardInterrupt](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-killed-13e4a54ded6e98bd000ca28160e0eb18.png\")
\nFigura 3. Una caída real — la traza viene de dentro de step_two, que por tanto nunca\nse completó.
Ahora reanuda el mismo thread_id:
python lg_agent.py ticket-42 --resume
BEFORE values={'completed': ['step_one']} next=('step_two',)
step_two running — 30s window, KILL ME HERE
step_three running
FINAL: {'completed': ['step_one', 'step_two', 'step_three']}
AFTER values={'completed': [...]} next=()
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-resumed-060c0f536dc33b295570816403af58d0.png\")
\nFigura 4. La línea BEFORE es la prueba — estado recuperado de Postgres por un proceso\ncompletamente nuevo.
Lee esa primera línea con atención, porque es el tutorial entero:
\nvalues muestra el resultado de step_one, recuperado de Postgres por un proceso que no\nexistía cuando se produjonext=('step_two',) — el grafo sabe exactamente qué nodo no terminóstep_one no se ejecutó otra vez. Se ejecutó una sola vez a lo largo de tres\ninvocacionesEse último punto es lo que compra checkpoint_writes: LangGraph conserva las escrituras\ncompletadas de un super-paso, así que reanudar no repite trabajo que ya tuvo éxito.
La llamada de reanudación en sí es:
\ngraph.invoke(None, config)
None como entrada significa \"sin entrada nueva — continúa desde el checkpoint\". Vale la\npena saberlo: esto está documentado en la página de interrupciones para breakpoints\nestáticos, pero no en las páginas de persistencia o de ejecución duradera, que es donde\nmirarías cuando tu proceso acaba de morir. Funciona; simplemente no está escrito donde lo\nnecesitas.
Mátalo una segunda vez y reanuda otra vez. Funciona, porque leer un checkpoint no lo\nconsume.
\nUna caída es una parada accidental. Una aprobación es una deliberada — y una vez que puedes\nsobrevivir a la primera, la segunda es casi gratis.
\nEl agente está a punto de escribir una cita en el calendario de un cliente. Eso es\nirreversible y lo ve una persona real, así que quieres que alguien lo revise antes.
\nSin estado duradero, esperar a una persona significa mantener un proceso abierto. Con el\nestado en Postgres el agente se detiene, el proceso sale, y la aprobación llega cuando\nllegue — diez minutos o el lunes por la mañana.
\nfrom langgraph.types import interrupt, Command
def approval(state: State):
decision = interrupt({\"question\": \"Approve step_two?\", \"so_far\": state[\"completed\"]})
return {\"completed\": [\"approval\"], \"approved\": decision}
Guárdalo como lg_agent2.py y ejecútalo:
python lg_agent2.py booking-7
interrupt() hace dos cosas a la vez: detiene el grafo, y entrega su argumento a quien lo\nhaya llamado. Ese argumento es tu pregunta para la persona — cualquier valor serializable a\nJSON.
step_one running
RESULT: {'completed': ['step_one'], 'approved': '',
'__interrupt__': [Interrupt(value={'question': 'Approve step_two?',
'so_far': ['step_one']}, id='29f211cf5a73ea78e0f694e1bd38822b')]}
AFTER next=('approval',) interrupts=(Interrupt(...),)
Ninguna excepción, código de salida 0. Nota la diferencia con el Paso 4: la caída producía\nuna traza, esto produce un retorno limpio.
\nLa pausa aparece en dos sitios, y la diferencia importa:
\n| Dónde | Uso |
|---|---|
__interrupt__ en el resultado de invoke | Quien acaba de ejecutar el grafo |
snapshot.interrupts | Cualquier otro proceso — un panel que muestre la pregunta |
El id correlaciona una respuesta con la pausa correcta, que importa en cuanto hay más de\nuna aprobación pendiente.
El proceso ya no existe; el estado está en Postgres. Una hora o una semana después:
\npython lg_agent2.py booking-7 yes
que llama a:
\ngraph.invoke(Command(resume=\"yes\"), config)
approval resumed with: yes
step_two running (approved=yes)
AFTER next=() interrupts=()
Command(resume=...) es distinto de invoke(None, ...). None dice \"continúa\";\nCommand(resume=X) dice \"continúa, y interrupt() debería devolver X\". Ese valor vino de\nla línea de comandos, pasó por el retorno de interrupt(), entró en el estado, y lo leyó el\nnodo siguiente.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-interrupt-ea585f38dd6726bebaeeff4db224460a.png\")
\nFigura 5. Pausa y reanudación — dos procesos distintos, una sola ejecución.
Al reanudar, LangGraph vuelve a ejecutar el nodo interrumpido desde arriba. Esta vez\ninterrupt() devuelve tu valor en vez de pausar — pero todo lo que está por encima en esa\nfunción ya se ejecutó una segunda vez.
Pon un print antes de la interrupción, luego ejecuta un hilo nuevo y apruébalo:
\npython lg_agent2.py booking-8
python lg_agent2.py booking-8 approve
Aparece en las dos ejecuciones, para una sola aprobación:
\nrun 1: step_one running
SIDE EFFECT — before interrupt
RESULT: {... '__interrupt__': [Interrupt(...)]}
run 2: SIDE EFFECT — before interrupt
approval resumed with: approve
step_two running (approved=approve)
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-double-side-effect-89c6352b4d9d897ec50519025547fca8.png\")
\nFigura 6. Una aprobación, dos ejecuciones de todo lo que está antes de la interrupción.
Si esa línea fuera send_email() o charge_card(), una aprobación le cobra al cliente dos\nveces. Nada lanza una excepción. El estado final es correcto. Solo se duplicó el efecto\nsecundario — que es la razón por la que esto es fácil de desplegar y difícil de notar.
No pongas nada antes de interrupt() en ese nodo. Mueve los efectos secundarios\ndespués, o dale a la interrupción un nodo propio que no haga nada más. El mismo\nrazonamiento aplica a reanudar tras una caída: un nodo siempre puede ejecutarse más de una\nvez, así que cualquier cosa con una consecuencia externa debería ser idempotente o estar\naislada.
Dos paquetes más: uno para hablar con el modelo, otro para trazarlo.
\npip install langchain-openai langfuse
llm = ChatOpenAI(
model=\"Qwen2.5-3B-Instruct\",
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
temperature=0,
)
ChatOpenAI no es específico de OpenAI — habla el protocolo de OpenAI, que WEC Inference\nimplementa. Apuntar base_url ahí es toda la integración. temperature=0 mantiene las\nejecuciones comparables mientras pruebas.
La llamada va dentro de un nodo como cualquier otro trabajo:
\ndef write(state: State):
r = llm.invoke(f\"Write one sentence about {state['topic']}.\")
return {\"completed\": [\"write\"], \"draft\": r.content}
Necesitas un proyecto de Langfuse y un par de claves de API para esto — creados en\nOrganization → Project, luego Settings → API Keys, como cubrimos en\nObserva producción con Langfuse.
\nEl trazado se adjunta por invocación, en el mismo diccionario de configuración que el id del\nhilo:
\nfrom langfuse.langchain import CallbackHandler
handler = CallbackHandler()
config = {\"configurable\": {\"thread_id\": THREAD}, \"callbacks\": [handler]}
configurable son los ajustes propios de LangGraph; callbacks es el gancho de\nobservadores de LangChain. Langfuse se suscribe a los eventos de inicio y fin de nodo y\nconstruye spans a partir de ellos — que es la razón por la que el rastro refleja tu grafo\nsin ninguna instrumentación extra.
Las credenciales vienen del entorno — en el SDK v4 CallbackHandler() no acepta\nargumentos, así que esta es la única forma de configurarlo:
export WEC_API_KEY='...'
export LANGFUSE_PUBLIC_KEY='pk-lf-...'
export LANGFUSE_SECRET_KEY='sk-lf-...'
export LANGFUSE_HOST='http://localhost:3001'
Todo junto como lg_llm.py:
import os, sys
from operator import add
from typing import Annotated
from typing_extensions import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.postgres import PostgresSaver
from langchain_openai import ChatOpenAI
from langfuse.langchain import CallbackHandler
DB_URI = \"postgresql://langgraph:changeme@127.0.0.1:5434/checkpoints\"
THREAD = sys.argv[1] if len(sys.argv) > 1 else \"draft-1\"
llm = ChatOpenAI(
model=\"Qwen2.5-3B-Instruct\",
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
temperature=0,
)
class State(TypedDict):
topic: str
completed: Annotated[list[str], add]
draft: str
def plan(state: State):
print(\"plan running\", flush=True)
return {\"completed\": [\"plan\"]}
def write(state: State):
r = llm.invoke(f\"Write one sentence about {state['topic']}.\")
print(\"model said:\", r.content, flush=True)
return {\"completed\": [\"write\"], \"draft\": r.content}
builder = StateGraph(State)
builder.add_node(\"plan\", plan)
builder.add_node(\"write\", write)
builder.add_edge(START, \"plan\")
builder.add_edge(\"plan\", \"write\")
builder.add_edge(\"write\", END)
handler = CallbackHandler()
with PostgresSaver.from_conn_string(DB_URI) as checkpointer:
checkpointer.setup()
graph = builder.compile(checkpointer=checkpointer)
config = {\"configurable\": {\"thread_id\": THREAD}, \"callbacks\": [handler]}
result = graph.invoke(
{\"topic\": \"edge computing\", \"completed\": [], \"draft\": \"\"}, config
)
print(\"FINAL:\", result, flush=True)
python lg_llm.py draft-1
LangGraph 2.18s
plan 0.00s
write 2.14s
ChatOpenAI 2.13s 36 -> 37 (73 tokens)
![\"Rastro](\"https://development-wec.wiline.com/docs/es/assets/images/lg1-langfuse-trace-8385ab962b94706bb03e2df32a87a0a6.png\")
\nFigura 7. Árbol de spans, topología del grafo y conteo de tokens — desde un solo\ncallback.
Casi todo es la llamada al modelo. Eso deja unos 40ms para el grafo y el trazado, y la\ndiferencia se mantuvo cerca de 40ms incluso en ejecuciones que tardaron el doble. plan,\nque no llama a nada, informa 0,00s.
La conclusión útil: la orquestación no es tu problema de latencia. Si un agente se\nsiente lento, el grafo no es la razón.
\naddress already in use frente a port is already allocated. Parecen\nintercambiables y no lo son. El primero significa que un proceso del host tiene el\npuerto; el segundo que lo tiene otro contenedor — la contabilidad propia de Docker, antes\nde intentar el bind. Diagnostica con:
docker ps --format '{{.Names}}\\t{{.Ports}}' && sudo ss -ltnp | grep :543
Un docker run fallido bloquea el nombre. El contenedor se crea, luego muere, y sigue\nconservando su nombre — así que tu reintento falla de forma distinta a la primera vez.\ndocker rm <nombre> antes de reintentar.
ModuleNotFoundError: No module named 'langchain' al importar el CallbackHandler de\nLangfuse. Ni LangGraph ni langchain-openai necesitan el paquete paraguas langchain;\nLangfuse lo importa puramente como centinela de versión. El arreglo es instalar un paquete\nque nada más en tu stack usa.
Vale la pena distinguir dos hilos del proyecto.\n#9758 reportó el fallo de importación en\noctubre de 2025 y está cerrado — pero todavía se reproduce en la versión del SDK de\narriba, así que léelo como historia y no como un arreglo que llegó.\n#13651 está abierto y propone el\nremedio real: leer langchain_core.__version__ en vez de exigir el paquete paraguas.
Langfuse se desactiva en silencio. Olvida una variable de entorno y recibes una línea\nde advertencia, y luego una ejecución completamente normal — código de salida 0, salida\ncorrecta, ningún rastro:
\nAuthentication error: Langfuse client initialized without public_key.
Client will be disabled.
En el SDK v4 CallbackHandler() no acepta argumentos en el constructor, así que las\nvariables de entorno son la única vía de configuración — y que falte una no lanza ninguna\nexcepción. Comprueba que el cliente está habilitado al arrancar en vez de confiar en la\nausencia de errores.
Deriva de versiones. La mayoría del material sobre LangGraph + Langfuse apunta al SDK\nv3 de Langfuse. En v4 el parámetro update_trace ya no existe y lanza TypeError, y las\ncredenciales ya no pueden pasarse al constructor.
Parte 2: pasar trabajo entre agentes — y qué le ocurre al estado compartido cuando no están\nde acuerdo.
\nLecturas relacionadas en este sitio:
\n+La Parte 3 configuró Presidio para enmascarar\nlos prompts en el momento del registro y deliberadamente se detuvo antes de probarlo. Aún no se había\nconectado a un destino de registro, así que no había rastro que inspeccionar.
\nEsta publicación lo conecta, encuentra <PERSON> donde debería estar — y luego encuentra la\ndirección de correo electrónico real del cliente sentada unas líneas más abajo, en la respuesta del modelo.
Todo en esta publicación sigue desde donde se encuentran esos dos hooks. post_call se activa\nantes de la flecha de regreso al llamador, así que enmascarar allí reescribe la respuesta que\nreciben. async_logging_hook se activa después de eso, solo en la rama hacia el registrador.
Langfuse ya está funcionando en esta serie; si seguiste\nel tutorial de observabilidad tienes una instancia. Crea un proyecto para el gateway, luego toma sus dos claves de\nSettings → API Keys.
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-langfuse-keys-0868edc9108438174e185d84a9801382.png\")
Figura 1. Un proyecto separado mantiene el tráfico del gateway alejado de cualquier otra cosa\nque estés rastreando.
\nAgrega tres variables al .env del gateway:
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=http://your-host:3001
La propia pantalla de configuración de Langfuse imprime un bloque .env que contiene\nLANGFUSE_BASE_URL. El gateway no lee eso. Lee:
os.getenv(\"LANGFUSE_HOST\", \"https://cloud.langfuse.com\")
Copia su fragmento tal cual y tu host será ignorado a favor del endpoint de la nube pública — donde tus claves autoalojadas no se autenticarán. Los rastros no van a ninguna parte, y no hay errores.
Luego activa el callback:
\nlitellm_settings:
drop_params: true
success_callback: [\"langfuse\"]
failure_callback: [\"langfuse\"]
docker compose restart litellm
Envía una solicitud después de eso y los registros dicen:
\nEl cliente de Langfuse está deshabilitado ya que no se proporcionó public_key como parámetro
o variable de entorno 'LANGFUSE_PUBLIC_KEY'.
Las claves están en .env. No están en el contenedor:
docker exec llm-gateway printenv | grep -c LANGFUSE
0
restart no recarga env_filedocker compose restart reinicia el proceso dentro del contenedor que\nya existe, con el entorno con el que fue creado. Las nuevas variables en\n.env no se recogen.
El cambio en config.yaml sí tuvo efecto, porque ese es un archivo montado que se lee al inicio. Así que el gateway parece estar configurado correctamente — callbacks inicializados, sin errores — mientras no tiene credenciales en absoluto.
Usa docker compose up -d, que recrea el contenedor.
docker compose up -d
docker exec llm-gateway printenv | grep -c LANGFUSE
3
![\"printenv](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-recreate-env-8aff004f8b60f6c931690f76127937bf.png\")
Figura 2. Después de up -d, las variables están en el contenedor.
Espera a que Application startup complete, luego envía un prompt que lleva un nombre y\nuna dirección:
source .env && curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"¿Cuál es el primer nombre de Maria Alvarez, y cuál es el dominio de maria.alvarez@example.com? Responde en una línea corta.\"}],\"max_tokens\":40}' \\
| jq -r '.choices[0].message.content'
El primer nombre de Maria Alvarez es Maria; el dominio de maria.alvarez@example.com es example.com.
Esa respuesta es el control. El modelo no podría haber producido \"Maria\" de un\nplaceholder, así que la solicitud en vivo llegó a él sin enmascarar — exactamente lo que\npromete logging_only.
Ahora el rastro:
\n![\"Un](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-trace-input-masked-f167939e2680fdb4984817374cb86a8e.png\")
Figura 3. Entrada enmascarada. Salida no.
\n¿Cuál es el primer nombre de <PERSON>, y cuál es el dominio de <EMAIL_ADDRESS>?
El primer nombre de Maria Alvarez es Maria; el dominio de maria.alvarez@example.com es example.com.
La tarea de la Parte 3 está hecha — el prompt está enmascarado en el registro mientras el modelo vio el\ntexto real. Y la PII está en el rastro de todos modos, porque el modelo la repitió.
\nEso no es un caso extremo. Repetir el nombre del cliente es para lo que sirve un asistente de soporte.
\nLa propia base de datos del gateway almacena la misma solicitud de manera diferente:
\ncurl -s http://127.0.0.1:4000/spend/logs \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" | jq '.[0] | {messages, response}'
\"messages\": {}
\"response\": { ... \"content\": \"El primer nombre de Maria Alvarez es Maria;
el dominio de maria.alvarez@example.com es example.com.\" ... }
Sin prompt en absoluto, y la finalización en su totalidad. Dos almacenes, dos formas, el mismo\nhueco en ambos.
\nLa Parte 3 estableció presidio_filter_scope: input. La solución obvia es escanear en ambas\ndirecciones:
presidio_filter_scope: both
Reinicia, envía la solicitud idéntica y lee la respuesta que recibe el llamador:
\nEl primer nombre de <PERSON> es <PERSON>; el dominio de <EMAIL_ADDRESS> es <URL>.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-response-masked-5e5f2e3cd767089449d5067827a9f518.png\")
Figura 4. La propia terminal del llamador, no un visor de registros.
\nEso no es el registro. Esa es la respuesta devuelta al cliente.
\nmode: logging_only sigue configurado. No ayudó, porque nunca llega a la\nruta de salida — la documentación para la configuración del alcance lo dice directamente:
\n\nUsa
\npresidio_filter_scope: output(oboth) cuando quieras que Presidio\nescanee y enmascare activamente la respuesta del modelo antes de que llegue al usuario.
Enmascarar la respuesta en vivo es el propósito documentado de un alcance de salida. Lo que no está documentado es la combinación: nada describe lo que sucede cuando configuras\nlogging_only y un alcance de salida, y el código lo resuelve a favor de la\nruta en vivo.
En guardrail_initializers.py:
if run_output:
output_callback = _make_presidio_callback(
apply_to_output=True,
event_hook=GuardrailEventHooks.post_call.value, # codificado
output_parse_pii=False,
)
El mode que configuraste se pasa al callback de entrada. El callback de salida\nrecibe post_call independientemente.
Una respuesta enmascarada tiene dos posibles causas: la respuesta fue enmascarada en el camino de salida,\no el modelo recibió placeholders y respondió honestamente sobre ellos. Se ven idénticos.
Pide algo que codifique el valor real sin contenerlo — una sola letra no es PII, así que enmascarar no puede ocultarlo:
curl ... -d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde SOLO con la primera letra del primer nombre de Maria Alvarez.\"}],\"max_tokens\":200}'
Mª
M. El modelo tenía el nombre real. Solo se reescribió la respuesta.
Así que las dos configuraciones te dan una elección, y ninguna es la que quieres:
\n| Entrada registrada | Salida registrada | Respuesta del llamador | |
|---|---|---|---|
filter_scope: input | enmascarada | PII sin procesar | intacta |
filter_scope: both | enmascarada | enmascarada | enmascarada |
Esto ha sido reportado.\nIssue #30447 — \"logging_only\nEl guardrail de Presidio corrompe la respuesta orientada al usuario\" — fue presentado el 15 de junio de 2026\ny cerrado al día siguiente, sin discusión, junto con una solicitud de extracción titulada\n\"fix(presidio): no enmascarar la solicitud en vivo cuando el guardrail está en logging_only\".\nEl informe era sobre la respuesta. La solución abordó la solicitud.\n#35951 sigue abierta en un\ncamino relacionado.
\nLa brecha existe porque post_call se ejecuta mientras la respuesta aún viaja\nhacia el llamador. Hay un hook posterior que no lo hace.
async_logging_hook se activa después de que el modelo ha respondido y antes de que se ejecuten los registradores. Recibe la solicitud y el resultado, y lo que devuelve es lo que se registra. El llamador ya tiene su respuesta para entonces.
Ese hook está documentado, bajo\nScrub Logged Data — pero\nel ejemplo allí es un placeholder que reemplaza cada mensaje con la cadena literal MASK_THIS_ASYNC_VALUE. Muestra que el hook existe; no enmascara nada, solo toca kwargs[\"messages\"], y muta en su lugar. Lo que sigue utiliza el mismo punto de extensión y agrega las partes que lo hacen funcionar:\nllamadas reales a Presidio, los tres lugares donde se oculta la PII, y una copia para que la respuesta del llamador sobreviva.
El fragmento en esa página termina con return kwargs, responses, pero el parámetro se llama result. responses no está definido, así que copiarlo tal cual genera un NameError.
Crea scrubber.py junto a config.yaml:
import copy
import os
from typing import Any, Tuple
import httpx
from litellm.integrations.custom_logger import CustomLogger
ANALYZER = os.getenv(\"PRESIDIO_ANALYZER_API_BASE\", \"http://presidio-analyzer:3000\")
ANONYMIZER = os.getenv(\"PRESIDIO_ANONYMIZER_API_BASE\", \"http://presidio-anonymizer:3000\")
async def _mask(text: str) -> str:
if not text or not text.strip():
return text
async with httpx.AsyncClient(timeout=10.0) as client:
r = await client.post(f\"{ANALYZER}/analyze\", json={\"text\": text, \"language\": \"en\"})
found = r.json()
if not found:
return text
r = await client.post(
f\"{ANONYMIZER}/anonymize\",
json={\"text\": text, \"analyzer_results\": found},
)
return r.json()[\"text\"]
class PresidioLogScrubber(CustomLogger):
async def async_logging_hook(
self, kwargs: dict, result: Any, call_type: str
) -> Tuple[dict, Any]:
if call_type not in (\"completion\", \"acompletion\"):
return kwargs, result
kwargs = copy.deepcopy(kwargs)
for message in kwargs.get(\"messages\") or []:
if isinstance(message.get(\"content\"), str):
message[\"content\"] = await _mask(message[\"content\"])
slo = kwargs.get(\"standard_logging_object\")
if isinstance(slo, dict):
for message in slo.get(\"messages\") or []:
if isinstance(message, dict) and isinstance(message.get(\"content\"), str):
message[\"content\"] = await _mask(message[\"content\"])
response = slo.get(\"response\")
if isinstance(response, dict):
for choice in response.get(\"choices\") or []:
message = (choice or {}).get(\"message\") or {}
if isinstance(message.get(\"content\"), str):
message[\"content\"] = await _mask(message[\"content\"])
# `result` es el objeto que ya tiene el llamador. Copiar antes de enmascarar.
logged_result = copy.deepcopy(result)
for choice in getattr(logged_result, \"choices\", None) or []:
message = getattr(choice, \"message\", None)
if message is not None and isinstance(getattr(message, \"content\", None), str):
message.content = await _mask(message.content)
return kwargs, logged_result
instance = PresidioLogScrubber()
Tres detalles llevan todo esto.
\nLa PII se oculta en tres lugares, no en uno. kwargs[\"messages\"] es el prompt.\nkwargs[\"standard_logging_object\"] es lo que las integraciones de registro realmente\nleen — este es el tema del issue #35951. Y result contiene la finalización.\nPerder cualquiera de ellos significa que algo se filtra.
result es el objeto del llamador. Mutarlo en su lugar reproduce el error que\nestamos evitando. Se copia profundamente primero, y la copia es lo que enmascaramos y\ndevolvemos.
_mask es async a propósito. Más sobre eso a continuación, porque hacerlo mal\ncuesta latencia medible.
Monta el archivo y regístralo. Debe estar al lado de config.yaml, porque\nget_instance_fn resuelve la ruta con puntos relativa al directorio del archivo de configuración:
volumes:
- ./config.yaml:/app/config.yaml:ro
- ./scrubber.py:/app/scrubber.py:ro
litellm_settings:
drop_params: true
callbacks: [\"scrubber.instance\"]
success_callback: [\"langfuse\"]
Establece el guardrail incorporado en default_on: false mientras pruebas. Si tanto él como\nel callback están enmascarando, no puedes decir cuál hizo el trabajo.
Agregar un volumen cambia la definición del contenedor, así que esto necesita una recreación, no\nun reinicio:
\ndocker compose up -d
Envía una solicitud y guarda el cuerpo de la respuesta:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"¿Quién es Priya Raghunathan y cuál es el dominio de priya.raghunathan@example.net? Una línea corta.\"}],\"max_tokens\":40}' \\
-o response.json
Lo que recibió el llamador:
\njq -r '.choices[0].message.content' response.json
Priya Raghunathan es una investigadora de IA, y el dominio
priya.raghunathan@example.net es probablemente una dirección de correo electrónico personal.
Lo que almacenó Langfuse:
\ncurl -s -u \"$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY\" \\
\"http://your-host:3001/api/public/traces?limit=1\" -o trace.json
jq -r '.data[0].output.content' trace.json
<PERSON> es una investigadora de IA, y el dominio <EMAIL_ADDRESS> es probablemente una
dirección de correo electrónico personal.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-side-by-side-54fd1e85dfe8ba2b6544c1a470fb77f9.png\")
Figura 5. La misma oración. Una real, una enmascarada.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-scrubber-working-29c3b666ef2aa43daef02208253f2fd4.png\")
Figura 6. Enmascarado en ambos lados del rastro, intacto para el llamador.
\nLeer una UI renderizada prueba menos que verificar las cargas útiles, así que verifícalas:
\ngrep -c \"Priya Raghunathan\" response.json
grep -c \"Priya Raghunathan\" trace.json
grep -o \"PERSON\" trace.json | wc -l
grep -c \"Una línea corta\" trace.json
1
0
2
1
![\"Cuatro](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-grep-proof-f38350595a637c78223db0c9f01b0da1.png\")
Figura 7. El recibo: 1 0 2 1.
El nombre real está en lo que recibió el llamador. No está en el rastro. El\nplaceholder aparece dos veces — entrada y salida. Y la última línea prueba que ambos\narchivos describen la misma solicitud, lo que los primeros tres no establecen por sí solos.
\nPuedes enmascarar lo que un gateway registra sin cambiar lo que devuelve, y probarlo\ninspeccionando las cargas útiles en ambos lados de una sola solicitud.
La primera versión funcional de _mask usó un cliente bloqueante — httpx.Client\ndentro de un async def. Enmascaró correctamente. También hizo esto:
| ejecución 1 | ejecución 2 | |
|---|---|---|
| sin callback | 0.74 s | — |
bloqueando httpx.Client | 1.10 s | 0.97 s |
async httpx.AsyncClient | 0.77 s | 0.77 s |
Medianas cálidas, cuatro solicitudes secuenciales cada una, la primera descartada como fría. La figura asíncrona se repitió exactamente; la bloqueante no, que es el punto — la penalización depende de lo que más esté haciendo el bucle.
\n![\"Ejecuciones](\"https://development-wec.wiline.com/docs/es/assets/images/gw4-timing-97e67eb7eb08fb9770f75d0b038bb147.png\")
Figura 8. La misma solicitud, el mismo enmascaramiento, una palabra diferente en el código.
\nUna llamada HTTP bloqueante dentro de un hook asíncrono detiene el bucle de eventos hasta que Presidio\nresponde, y cada solicitud hace varias de tales llamadas. El enmascaramiento no está en la ruta crítica del\nllamador — pero está en la de todos los demás, porque nada más puede ser atendido mientras espera.
\nCambiar httpx.Client a httpx.AsyncClient y esperar las llamadas elimina\nel costo: 0.77s contra una línea base de 0.74s, dentro del ruido de la llamada del modelo\nen sí, y se reprodujo hasta el centésimo en dos ejecuciones separadas.
Estos números son cuatro solicitudes secuenciales. Bloquear el bucle de eventos apenas\nse muestra en una solicitud a la vez — es bajo concurrencia que las dos versiones\ndivergen, y no hemos medido eso aquí. Si ejecutas esto a volumen, pruébalo bajo carga\nantes de confiar en la tabla anterior.
Cada solicitud también significa dos llamadas HTTP a Presidio por mensaje más dos para la\nfinalización. A volumen real, Presidio se convierte en un servicio que dimensionas y monitoreas,\nno un detalle de fondo.
| Entrada registrada | Salida registrada | Respuesta del llamador | Costo | |
|---|---|---|---|---|
filter_scope: input | enmascarada | PII sin procesar | intacta | ninguno |
filter_scope: both | enmascarada | enmascarada | enmascarada | 0.30s de duración del guardrail |
| hook de registro | enmascarada | enmascarada | intacta | ninguno medible |
Vale la pena ser claro sobre el límite de lo que esto logra: la PII aún viaja.\nLlega al modelo y llega al llamador. Lo que se ha eliminado es\nretención — ya no está sentada en un almacén de rastros que un grupo más amplio\nde personas puede leer, meses después, mucho después de que la solicitud misma se haya ido.
\nVerificado contra ghcr.io/berriai/litellm:main-stable, UI de administración reportando\nv1.96.2, el 21 de agosto de 2026. Si una versión posterior agrega un modo de salida con\nalcance de registro, prefierelo sobre esto.
Verifica que LANGFUSE_HOST esté configurado, no LANGFUSE_BASE_URL, y confirma que las variables\nestén dentro del contenedor con docker exec llm-gateway printenv | grep LANGFUSE.\nUn docker compose restart no las habrá cargado.
Una mala ruta con puntos falla silenciosamente. scrubber.py debe estar en el mismo directorio que\nconfig.yaml — dentro del contenedor, no solo en el host — y el nombre del objeto\ndespués del punto debe existir. Busca en el registro de inicio ImportError y\nAttributeError.
La copia profunda falta, o el guardrail incorporado sigue habilitado con un\nalcance de salida. Establece default_on: false en él y confirma con\ncurl /guardrails/list.
Verifica que _mask use httpx.AsyncClient con await, no httpx.Client. Consulta las\nmediciones anteriores.
Las mediciones aquí son secuenciales, y el modo de falla que costó 200-350ms\nes uno que solo afecta adecuadamente bajo concurrencia. La próxima publicación pone el gateway\nbajo carga paralela y mide lo que realmente sucede con la latencia cuando varias\nsolicitudes compiten por el mismo bucle de eventos.
\n+La Parte 2 terminó con la puerta de enlace decidiendo\nqué modelo responde a cada solicitud — y aún así reenvía cada solicitud tal cual,\nincluyendo las que llevan nombres de clientes, correos electrónicos y números de teléfono.
\nEsta publicación coloca un filtro de PII en ese camino. No delante del modelo, sin embargo:\ndelante de los registros. El modelo que lee\ntu solicitud está haciendo su trabajo; el riesgo es lo que se almacena. Así que el texto sin procesar\nva al modelo y una copia enmascarada va a tus registros.
\nEso es lo que la puerta de enlace publicita. Seguir su configuración documentada me dio\nlo opuesto: un modelo que respondió correctamente y una respuesta que regresó como\n<LOCATION>. Así es como encontrar eso y cómo solucionarlo.
LiteLLM 1.96.2 (ghcr.io/berriai/litellm:main-stable), imágenes de Presidio de\nghcr.io/data-privacy-stack, modelos qwen-small (Qwen2.5-3B-Instruct) y\nqwen-mid (Qwen3.5-9B) a través de la API de Inferencia WEC, el 20 de agosto de 2026. Los valores predeterminados\ncambian — si tus resultados difieren, verifica primero tu versión.
Presidio detecta datos personales\nen texto: nombres, correos electrónicos, números de teléfono, números de tarjeta. Le envías una cadena y\ndevuelve las entidades que encontró, con desplazamientos de caracteres y un puntaje de confianza.
\nSe envía como dos servicios: un analizador que encuentra PII y un anonimizador\nque lo reemplaza. La puerta de enlace llama a ambos.
\nUna nota sobre nombres que confunde a la gente: Presidio era el proyecto de Microsoft y la mayoría\nde los tutoriales aún lo llaman así. El repositorio se trasladó a la organización data-privacy-stack\ny github.com/microsoft/presidio ahora responde Moved Permanently. Mismo proyecto, nuevo hogar, que es por qué las imágenes a continuación no están bajo\nuna ruta de Microsoft.
Presidio solo habla con la puerta de enlace, por lo que no necesita puertos publicados.\nAbre el docker-compose.yml de la Parte 1 y agrega dos servicios después del bloque db:\n, encima de volumes::
presidio-analyzer:
image: ghcr.io/data-privacy-stack/presidio-analyzer:latest
container_name: presidio-analyzer
restart: unless-stopped
presidio-anonymizer:
image: ghcr.io/data-privacy-stack/presidio-anonymizer:latest
container_name: presidio-anonymizer
restart: unless-stopped
Dos espacios de sangría, al mismo nivel que litellm: y db:.
Nota lo que está ausente: no hay ports:. Colocarlos en el mismo proyecto de compose que\nla puerta de enlace significa que Docker les da una red y DNS compartidos, por lo que la puerta de enlace\nlos alcanza por nombre de servicio y nada más en tu red puede alcanzarlos. Si desplegaste Presidio por separado con ports: [\"5002:3000\"], eso\nexpondría tu analizador de PII a todo lo que pueda enrutar hacia el host — vale la pena deshacerlo.
cd ~/llm-gateway && docker compose up -d
docker compose ps
Cuatro contenedores, y las filas de Presidio deberían mostrar 3000/tcp sin mapeo de host:
NAME SERVICE STATUS PORTS
llm-gateway litellm Up 127.0.0.1:4000->4000/tcp
llm-gateway-db db Up (healthy) 5432/tcp
presidio-analyzer presidio-analyzer Up (healthy) 3000/tcp
presidio-anonymizer presidio-anonymizer Up (healthy) 3000/tcp
![\"Cuatro](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-compose-ps-57ff2d738b0cb45457ecc59f8325613d.png\")
Si docker compose ps muestra solo dos contenedores, el archivo de compose no se guardó.\nConfirma lo que compose está leyendo realmente:
docker compose config --services
Eso debe listar cuatro nombres. Lee el archivo en disco, así que captura una edición que\nnunca salió de tu editor.
\nAntes de conectar nada, ve lo que Presidio realmente encuentra:
\nNo hay puertos de host ahora, así que pregunta desde dentro de la puerta de enlace. La imagen de LiteLLM\nno incluye curl, así que usa su Python:
docker exec llm-gateway python -c \"import json,urllib.request as u; r=u.Request('http://presidio-analyzer:3000/analyze', data=json.dumps({'text':'Llama a Rafael al 555-0142 o rafael@example.com','language':'en'}).encode(), headers={'Content-Type':'application/json'}); print(u.urlopen(r).read().decode())\"
[{\"entity_type\": \"EMAIL_ADDRESS\", \"score\": 1.0, \"start\": 27, \"end\": 45},
{\"entity_type\": \"PERSON\", \"score\": 0.85, \"start\": 5, \"end\": 11},
{\"entity_type\": \"URL\", \"score\": 0.5, \"start\": 34, \"end\": 45}]
![\"Respuesta](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-analyze-scores-16b5f56ac49060ffafbba8dc8a2c2333.png\")
Lee eso cuidadosamente, porque establece expectativas para todo lo que sigue.
\nEncontró el correo electrónico con plena confianza y el nombre en 0.85. No encontró el\nnúmero de teléfono en absoluto. 555-0142 son siete dígitos sin código de área, y\nPresidio valida contra planes de numeración reales en lugar de hacer coincidir patrones\nque se vean como teléfonos. Agrega un código de área:
docker exec llm-gateway python -c \"import json,urllib.request as u; r=u.Request('http://presidio-analyzer:3000/analyze', data=json.dumps({'text':'Llama a Rafael al (415) 555-0142 o rafael@example.com','language':'en'}).encode(), headers={'Content-Type':'application/json'}); print(u.urlopen(r).read().decode())\"
Ahora aparece PHONE_NUMBER — puntuando 0.4, frente a 1.0 para el correo electrónico.
Vale la pena verificar si el prefijo 555 es el problema, ya que ese rango está\nreservado para ficción. No lo es. Un número plausible se comporta de manera idéntica:
docker exec llm-gateway python -c \"import json,urllib.request as u; r=u.Request('http://presidio-analyzer:3000/analyze', data=json.dumps({'text':'Llama a Rafael al (415) 682-4531 o al 682-4531','language':'en'}).encode(), headers={'Content-Type':'application/json'}); print(u.urlopen(r).read().decode())\"
[{\"entity_type\": \"PERSON\", \"score\": 0.85, \"start\": 5, \"end\": 11},
{\"entity_type\": \"PHONE_NUMBER\", \"score\": 0.4, \"start\": 15, \"end\": 29}]
Misma puntuación de 0.4 para el número completo, y el bare 682-4531 sigue sin ser detectado. Así que dos\ncosas son ciertas: un código de área es lo que hace que un número de teléfono sea detectable,\ny 0.4 es simplemente lo que este reconocedor devuelve para números de teléfono — no una\npenalización por números falsos.
Lo que significa que los tipos de entidad no son igualmente confiables, y la confianza es un número\nque querrás establecer deliberadamente. Presidio expone presidio_score_thresholds\npara exactamente eso: un umbral por entidad por debajo del cual se descartan las detecciones. Establecerlo\nen 0.5 y dejarías de enmascarar silenciosamente cada número de teléfono en tu tráfico.
No construyas una historia de cumplimiento sobre la suposición de que esto captura todo.
\nHay una salida, y vale la pena saberlo antes de decidir que la cobertura\nes inaceptable. presidio_ad_hoc_recognizers toma una ruta a un archivo JSON de\nreconocedores adicionales, cargados cuando se inicia la guardia:
[
{
\"name\": \"LocalPhoneRecognizer\",
\"supported_language\": \"en\",
\"supported_entity\": \"PHONE_NUMBER\",
\"patterns\": [
{ \"name\": \"us-local-7\", \"regex\": \"\\\\b\\\\d{3}-\\\\d{4}\\\\b\", \"score\": 0.9 }
]
}
]
Móntalo junto a la configuración y apunta la guardia hacia él:
\n - ./recognizers.json:/app/recognizers.json:ro
presidio_ad_hoc_recognizers: /app/recognizers.json
Recrea el contenedor — un nuevo volumen necesita up -d, no restart — y la misma\nsolicitud que se filtró ahora se enmascara:
Respuesta OK. Contacta a <PERSON> al <PHONE_NUMBER> sobre la factura.
Por qué la puntuación es 0.9 y no 0.8. Coloca 682-4531 dentro de una oración —\nLlama a 682-4531 — y los reconocedores predeterminados devuelven DATE_TIME en\n0.85: siete dígitos con un guion, leídos como una fecha. (Pasa el número por sí solo,\nsin oración alrededor, y nada se activa; el modelo NER quiere\ncontexto antes de comprometerse a nada.) A 0.8 tu reconocedor de teléfono pierde la\nsuperposición y el número se enmascara como <DATE_TIME>: sigue redactado, pero archivado\nbajo la entidad equivocada, lo que rompe silenciosamente cualquier informe que cuente por tipo.\nA 0.86 o más PHONE_NUMBER gana.
Medido en tres ejecuciones cada uno, completamente determinista:
\n| Texto | Predeterminado | Reconocedor a 0.8 | Reconocedor a 0.9 |
|---|---|---|---|
Llama a 555-0142 | dejado en claro | <PHONE_NUMBER> | <PHONE_NUMBER> |
Llama a 682-4531 | <DATE_TIME> | <DATE_TIME> | <PHONE_NUMBER> |
(415) 682-4531 o al 682-4531 | uno bare filtra | ambos enmascarados | ambos enmascarados |
Nota que la fila del medio no es un fallo — es una clasificación errónea, y el anonimizador\naún lo redacta. Las primeras y terceras filas son las verdaderas filtraciones, y un reconocedor\ncierra ambas.
\nSiete dígitos y un guion son una forma, no un significado, y muchas cosas comparten eso.\nEjecuta ese reconocedor contra texto de una cola de soporte real:
\n| Texto | Enmascarado como |
|---|---|
El pedido 482-1099 se envió ayer | <PHONE_NUMBER> |
La factura 100-2000 está vencida | <PHONE_NUMBER> |
El número de parte 250-4000 está descontinuado | <PHONE_NUMBER> |
El código de error era 500-1001 | <PHONE_NUMBER> |
Nuestra oficina está en 200-4500 Main Street | <PHONE_NUMBER> |
RFC 793-1981 define TCP | <PHONE_NUMBER> |
Seis de seis. Y el 0.9 que configuraste para ganar la superposición de DATE_TIME ahora gana cada\nsuperposición, por lo que el reconocedor no solo agrega ruido — sobrescribe clasificaciones correctas con una incorrecta. Rastreos llenos de <PHONE_NUMBER> donde solían estar los números de pedido son peores que rastreos con un número en claro, porque\nahora no puedes decir cuál es cuál.
La solución es dejar de coincidir solo por forma y requerir una palabra clave delante de los\ndígitos. Eso tiene que ser un lookbehind: Presidio redacta toda la coincidencia, así que\n(call\\W+)(\\d{3}-\\d{4}) tragaría la palabra \"llama\" junto con el número —\nlos grupos de captura no reducen el alcance. El re de Python solo permite lookbehinds de ancho fijo,\nque es por qué esto es una alternancia en lugar de una lista ordenada:
[
{
\"name\": \"LocalPhoneRecognizer\",
\"supported_language\": \"en\",
\"supported_entity\": \"PHONE_NUMBER\",
\"patterns\": [
{
\"name\": \"us-local-7-cued\",
\"regex\": \"(?i)(?:(?<=call )|(?<=called )|(?<=calling )|(?<=phone )|(?<=phone: )|(?<=phone is )|(?<=tel )|(?<=tel: )|(?<=cell )|(?<=cell: )|(?<=cell is )|(?<=mobile )|(?<=mobile: )|(?<=contact )|(?<=contact: )|(?<=number )|(?<=number: )|(?<=number is )|(?<=me on )|(?<=him on )|(?<=her on )|(?<=them on )|(?<=us on )|(?<=me at )|(?<=him at )|(?<=her at )|(?<=them at )|(?<=us at ))(?<!part number )(?<!serial number )(?<!order number )(?<!invoice number )(?<!account number )(?<!model number )(?<!tracking number )(?<!reference number )(?<!batch number )(?<!ticket number )(?<!case number )\\\\d{3}-\\\\d{4}\\\\b\",
\"score\": 0.9
}
]
}
]
Los lookbehinds negativos finales están ahí porque number es una pista útil y\npart number no lo es.
Medido en doce frases de teléfono y doce similares:
\n\\b\\d{3}-\\d{4}\\b | Anclado por pista | |
|---|---|---|
| Números de teléfono enmascarados | 12/12 | 12/12 |
| Similares enmascarados erróneamente | 12/12 | 0/12 |
Dos cosas que esto no soluciona, y debes conocer ambas. El pedido 482-1099 sigue\nregresando como <DATE_TIME> — eso es un fallo de spaCy por sí mismo, con o sin\ntu reconocedor. Y un número de teléfono introducido por una frase que no pensaste\nvuelve a filtrarse. Una lista de pistas es una suposición sobre cómo la gente escribe, así que trátala\ncomo algo que revisar contra tu propio tráfico en lugar de un artefacto terminado.
BR está en la lista de regiones predeterminadas, así que (11) 91234-5678 es reconocido — y\n91234-5678 sin el DDD no lo es, exactamente como con un código de área de EE. UU. faltante. El\nmismo reconocedor lo cierra con \\d{4,5}-\\d{4} y una lista de pistas en portugués.
La puerta de enlace llama a Presidio a través de una guardia. Abre config.yaml y agrega un\nbloque guardrails: al final — esta es la configuración que la documentación de LiteLLM\nda para enmascarar solo en el camino de registro:
guardrails:
- guardrail_name: presidio-log-mask
litellm_params:
guardrail: presidio
mode: logging_only
default_on: true
presidio_analyzer_api_base: http://presidio-analyzer:3000
presidio_anonymizer_api_base: http://presidio-anonymizer:3000
mode: logging_only es el importante. La documentación lo describe como:
\n\nEjecutar después de la llamada LLM, aplicar solo el enmascaramiento de PII antes de registrar en Langfuse, etc.\nNo en la solicitud / respuesta real de la API llm.
\n
default_on: true lo aplica a cada solicitud en lugar de solo a aquellas que lo piden\npor nombre. Y los dos valores api_base son los nombres de servicio del archivo\ncompose — la guardia se ejecuta dentro del contenedor de la puerta de enlace, así que localhost\napuntaría al lugar equivocado.
Reinicia y espera a que el proxy realmente regrese — toma de 30 a 60\nsegundos, que es más largo que la mayoría de los comandos sleep que la gente pone delante de él:
docker compose restart litellm
until curl -sf localhost:4000/health/readiness >/dev/null 2>&1; do printf '.'; sleep 3; done; echo \" listo\"
Luego confirma que la guardia se cargó, lo cual es más confiable que leer registros:
\nKEY=$(grep -m1 LITELLM_MASTER_KEY ~/llm-gateway/.env | cut -d= -f2- | tr -d '\"') && \\
curl -s localhost:4000/guardrails/list -H \"Authorization: Bearer $KEY\" \\
| python3 -c \"import sys,json; g=json.load(sys.stdin)['guardrails'][0]; p=g['litellm_params']; print(json.dumps({'guardrail_name': g['guardrail_name'], **{k: p.get(k) for k in ('guardrail','mode','presidio_filter_scope','default_on','presidio_analyzer_api_base','presidio_anonymizer_api_base','fail_on_error','unreachable_fallback')}}, indent=2))\"
El punto final devuelve cada posible campo de guardia, la mayoría de ellos null, así que esto\nselecciona los que importan:
{
\"guardrail_name\": \"presidio-log-mask\",
\"guardrail\": \"presidio\",
\"mode\": \"logging_only\",
\"presidio_filter_scope\": \"input\",
\"default_on\": true,
\"presidio_analyzer_api_base\": \"http://presidio-analyzer:3000\",
\"presidio_anonymizer_api_base\": \"http://presidio-anonymizer:3000\",
\"fail_on_error\": true,
\"unreachable_fallback\": \"fail_closed\"
}
Esos últimos dos son los valores predeterminados que vale la pena conocer antes de que esto vea tráfico real: si\nPresidio no está disponible, las solicitudes fallan en lugar de pasar sin enmascarar.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-guardrail-list-cd2a45b09b50cc051970b5b85feba496.png\")
Ahora la parte que importa. Envía una solicitud cuya respuesta pruebe si el modelo\nvio el texto real — pedirle que repita la PII de vuelta es inútil, porque la respuesta\ntambién se escanea:
\nKEY=$(grep -m1 LITELLM_MASTER_KEY ~/llm-gateway/.env | cut -d= -f2- | tr -d '\"') && \\
curl -s localhost:4000/v1/chat/completions \\
-H \"Authorization: Bearer $KEY\" -H 'Content-Type: application/json' \\
-d '{\"model\":\"qwen-small\",\"temperature\":0,\"messages\":[{\"role\":\"user\",\"content\":\"¿A qué ciudad de EE. UU. pertenece este código de área: (415) 555-0142? Responde solo con el nombre de la ciudad.\"}]}' \\
| python3 -c \"import sys,json; print(json.load(sys.stdin)['choices'][0]['message']['content'])\"
Esperado: San Francisco, probando que el modelo leyó los dígitos.
Real:
\n<LOCATION>
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-masked-answer-1467b181d83013e63ad42b11ffcdfa95.png\")
El modelo respondió a una pregunta que requiere leer un código de área real — y luego\nla respuesta misma regresó enmascarada. logging_only se suponía que debía permanecer fuera de\nla respuesta real.
Hay una segunda configuración, y su valor predeterminado está haciendo el trabajo.
\npresidio_filter_scope controla qué dirección se escanea. De la\ndocumentación:
\n\n\n
input: solo se escanea el contenido de usuario → modelo;output: solo se escanea el contenido de modelo → usuario;both(predeterminado): escanear ambas direcciones
Y, en la misma página:
\n\n\nUsa
\npresidio_filter_scope: output(oboth) cuando quieras que Presidio escanee y enmascare activamente la respuesta del modelo antes de que llegue al usuario.
Así que both — el predeterminado — enmascara activamente las respuestas. El ejemplo documentado de logging_only\nno establece presidio_filter_scope en absoluto, lo que lo deja en both.\nEl resultado es una configuración que enmascara la cosa que la misma página dice que no\ntocará.
En el código fuente, initialize_presidio lee ese alcance y registra un segundo\ncallback con apply_to_output=True en post_call siempre que el escaneo de salida esté\nhabilitado. El gancho de evento de ese callback está codificado, por lo que el mode que estableces nunca\nllega a él.
Esto ha sido reportado.\nIssue #30447, \"la guardia de Presidio en modo logging_only corrompe la respuesta orientada al usuario (contenido del asistente reemplazado con tokens de PII)\", fue presentado el 15 de junio de 2026 y cerrado al día siguiente sin discusión, junto con una solicitud de extracción titulada \"fix(presidio): no enmascarar la solicitud en vivo cuando la guardia es logging_only\". El informe trataba sobre la respuesta; la solución abordó la solicitud. En la imagen main-stable utilizada aquí, el comportamiento anterior aún se reproduce.
Un segundo informe está abierto:\n#35951 señala que en\nmodo logging_only el gancho de enmascaramiento reescribe kwargs[\"messages\"] pero no\npropaga a standard_logging_object, que es lo que leen los registradores posteriores.
Una línea. Agrega presidio_filter_scope: input a la guardia:
guardrails:
- guardrail_name: presidio-log-mask
litellm_params:
guardrail: presidio
mode: logging_only
presidio_filter_scope: input
default_on: true
presidio_analyzer_api_base: http://presidio-analyzer:3000
presidio_anonymizer_api_base: http://presidio-anonymizer:3000
Reinicia, espera a que esté listo y ejecuta la misma solicitud:
\nSan Francisco
Puedes ejecutar Presidio junto a una puerta de enlace, enmascarar solicitudes en el momento del registro sin\ntocar la solicitud en vivo, y distinguir las dos direcciones con\npresidio_filter_scope.
Una respuesta correcta podría ser una suposición afortunada — \"San Francisco\" es un predeterminado plausible\npara una pregunta de código de área enmascarado, y temperature: 0 hace que una suposición se repita\ntan confiablemente como una respuesta real. Así que pregunta sobre varios códigos de área que el modelo no\npuede engañar:
KEY=$(grep -m1 LITELLM_MASTER_KEY ~/llm-gateway/.env | cut -d= -f2- | tr -d '\"')
for ac in 907 808 216 505; do
printf \"área %s -> \" \"$ac\"
curl -s localhost:4000/v1/chat/completions \\
-H \"Authorization: Bearer $KEY\" -H 'Content-Type: application/json' \\
-d \"{\\\"model\\\":\\\"qwen-mid\\\",\\\"temperature\\\":0,\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"¿A qué estado de EE. UU. pertenece el código de área de este número de teléfono: ($ac) 555-0142? Responde solo con el nombre del estado.\\\"}]}\" \\
| python3 -c \"import sys,json; print(' '.join(json.load(sys.stdin)['choices'][0]['message']['content'].split()))\"
done
área 907 -> Alaska
área 808 -> Hawaii
área 216 -> Ohio
área 505 -> Nuevo México
![\"Cuatro](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-area-codes-9448b7ab1d15d52e9cafb0d8ad0e5b86.png\")
Cuatro de cuatro. El modelo está leyendo los dígitos, así que la solicitud le está llegando\nsin enmascarar. La colapsación de espacios en blanco en ese comando no es una tontería cosmética — qwen-mid es\nun modelo de razonamiento y antepone sus respuestas con saltos de línea, lo suficientemente inconsistentes\nque .strip() solo deja una salida irregular.
Es la pregunta obvia, y la respuesta obvia es incorrecta. mode: pre_call\nenmascara la solicitud antes de que el modelo la vea — lo que suena como el arreglo más seguro posible.
Cambia la única línea y descubre:
\n mode: pre_call
Reinicia, luego pregunta la misma cosa:
\nKEY=$(grep -m1 LITELLM_MASTER_KEY ~/llm-gateway/.env | cut -d= -f2- | tr -d '\"') && \\
curl -s localhost:4000/v1/chat/completions \\
-H \"Authorization: Bearer $KEY\" -H 'Content-Type: application/json' \\
-d '{\"model\":\"qwen-small\",\"temperature\":0,\"max_tokens\":60,\"messages\":[{\"role\":\"user\",\"content\":\"¿A qué estado pertenece el código de área de este número de teléfono: (907) 555-0142? Responde solo con el nombre del estado.\"}]}' \\
| python3 -c \"import sys,json; print(' '.join(json.load(sys.stdin)['choices'][0]['message']['content'].split()))\"
Para determinar el estado de un código de área de un número de teléfono dado, necesitaría saber
el código de área específico del número de teléfono proporcionado. Por favor, proporciona el código de área
o el número de teléfono completo para que pueda identificar el estado correspondiente.
La redacción exacta se mueve entre ejecuciones incluso a temperature: 0 — el punto\nes que cada versión de ella te pide el número que ya enviaste.
![\"Bajo](\"https://development-wec.wiline.com/docs/es/assets/images/gw3-precall-blind-12b8776adeda133b79cac28a0bb36166.png\")
El modelo está pidiendo educadamente el número que acabas de darle. Recibió\n<PHONE_NUMBER> y no hay nada en un marcador de posición para razonar. Nada falló, nada\ndio error — simplemente obtuviste una respuesta inútil, que es el modo de fallo que es más difícil de notar en producción.
qwen-mid se comportó peor en mis ejecuciones: la misma solicitud se agotó dos veces a 40 segundos con max_tokens: 60, donde respondió en menos de un segundo con entrada sin enmascarar. No reclamaría un mecanismo de dos muestras, pero si estás\ndirigiéndote a un modelo de razonamiento, mide esto antes de confiar en él.
Así que las tres ubicaciones, la misma pregunta cada vez:
\n| Configuración | El modelo recibe | Resultado |
|---|---|---|
mode: pre_call | <PHONE_NUMBER> | te pide el número que se le dio |
mode: logging_only, alcance dejado por defecto | dígitos reales | respuesta correcta, devuelta como <LOCATION> |
mode: logging_only, presidio_filter_scope: input | dígitos reales | San Francisco |
Solo el tercero te da una aplicación funcional. Pon mode de vuelta a\nlogging_only antes de continuar.
Ahora tienes solicitudes que llegan a los modelos intactas, con el enmascaramiento de PII adjunto al\ncamino de registro en lugar del camino de solicitud — y a una configuración de distancia de enmascarar silenciosamente\nlas respuestas de tus usuarios.
\nUna cosa que esta solución no cubre, y es importante: el alcance input enmascara solo la solicitud.\nLo que sea que el modelo diga se registra tal cual — y un modelo preguntado sobre un cliente repetirá el nombre de ese cliente. Así que la PII que eliminaste\nde la solicitud reaparece en la finalización. Ampliar el alcance a both cierra\nese agujero y reintroduce la corrupción de respuesta anterior; no hay configuración que haga ambas.\nLa Parte 4 mide la filtración\ny construye la pieza que falta en async_logging_hook, el callback documentado\nque se ejecuta después de que se ha enviado la respuesta.
Siendo directo sobre el límite: la copia enmascarada aterriza donde sea que tus callbacks de registro la envíen. La propia tabla LiteLLM_SpendLogs de la puerta de enlace no es una de\nesas — messages se mantuvo en {} en cada configuración que probé, incluso con\nstore_prompts_in_spend_logs configurado tanto en config.yaml como como variable de entorno. La documentación apunta a Langfuse y destinos similares, que es\ndonde se ve la próxima publicación. Hasta que hayas conectado uno y visto una carga enmascarada en él, trata la mitad de enmascaramiento como no probada en tu propio despliegue.
Dos cosas más que vale la pena saber antes de que esto se ponga frente a tráfico real. La\nguardia predetermina fail_on_error: true con unreachable_fallback: fail_closed, así que si Presidio se cae tus solicitudes fallan en lugar de pasar\nsin enmascarar — el valor predeterminado correcto, pero planifica para ello. Y cada llamada a Presidio agrega\nlatencia al camino de registro; el método de temporización de la Parte 2 se aplica aquí también.
docker compose ps muestra dos contenedores, no cuatroEl archivo de compose no se guardó. docker compose config --services lee lo que está\nen disco — si Presidio falta allí, la edición no se realizó.
curl: archivo ejecutable no encontrado en $PATHLa imagen de LiteLLM no tiene curl. Sondea con la línea de un solo comando python -c anterior.
Nombre o servicio no conocido al alcanzar presidio-analyzerLas dos pilas están en diferentes redes de Docker. Ambos conjuntos de servicios deben estar en\nel mismo proyecto de compose, o compartir una red externa.
\nValidationError: mode Field requiredmode es obligatorio en una guardia. Omitirlo sale del proxy al inicio —\nApplication startup failed. Exiting. No puedes expresar solo registro dejando\nfuera mode.
<LOCATION> o <PHONE_NUMBER>presidio_filter_scope está en su predeterminado both. Establecerlo en input.
Verifica la puntuación. 555-0142 no se detecta en absoluto; (415) 555-0142 puntúa 0.4.\nUsa presidio_score_thresholds para establecer un umbral por entidad.
config.yaml parecen no tener efectoEdita el archivo, luego reinicia — en ese orden. Y un cd de un paso anterior\nse lleva consigo, así que verifica en qué directorio estás antes de ejecutar docker compose.
.env son ignoradosdocker compose restart no recarga el entorno. Usa\ndocker compose up -d --force-recreate litellm.
El enmascaramiento está configurado, pero aún no has visto aterrizar una carga enmascarada\nen ninguna parte. La próxima publicación conecta un destino de registro real a la puerta de enlace y busca\n<PERSON> en un rastreo — cerrando el bucle que esta deja deliberadamente abierto —\ny luego se dirige a presupuestos y lo que realmente cuesta todo el arreglo.
presidio_filter_scope y presidio_score_thresholds+![\"Qwen\"](\"https://development-wec.wiline.com/docs/es/assets/images/qwen-209001e8f781e3651b8d7b863343f2dc.png\")
+Parte 1 terminó en un número incómodo. La misma respuesta de tres palabras costó 3 tokens de un modelo pequeño y 200 de un modelo de razonamiento — que gastó los 200 pensando y no devolvió nada en absoluto.
\nCada solicitud que envían tus aplicaciones elige un modelo, y en su mayoría esa elección se hace una vez, codificada de forma rígida, y nunca se revisita. Esta publicación pone al gateway a cargo de ello en su lugar: clasifica la solicitud, la enruta a un modelo adecuado para el trabajo. Luego mide lo que cuesta esa decisión, porque no es gratis y la mayoría de los informes omiten esa parte.
\n\n\nEl gateway de la Parte 1 ya tiene tres modelos registrados. Un enrutador es solo otra entrada en model_list que asigna niveles de complejidad a ellos:
- model_name: smart-router
litellm_params:
model: auto_router/complexity_router
complexity_router_config:
tiers:
SIMPLE: qwen-small
MEDIUM: qwen-mid
COMPLEX: qwen-large
REASONING: qwen-large
return_raw_model_name: true
return_raw_model_name: true es el importante por ahora. Sin él, la respuesta informa smart-router y no tienes idea de qué modelo te sirvió. Con él, la respuesta nombra el modelo que realmente se ejecutó — así que cada prueba a continuación se verifica por sí misma.
docker compose restart litellm
Enviarás la misma solicitud muchas veces con solo el prompt cambiando, así que envuélvelo una vez:
\nask() { curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d \"{\\\"model\\\":\\\"smart-router\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"$1\\\"}],\\\"max_tokens\\\":10}\" | jq -r .model; }
Luego cinco prompts de dificultad creciente:
\nask \"hi\"
ask \"what is a vpc\"
ask \"write a python function that retries an http call with backoff\"
ask \"our two services deadlock under load, walk me through diagnosing it\"
ask \"prove that the halting problem is undecidable\"
Una línea por prompt, en el orden enviado:
\nQwen2.5-3B-Instruct
Qwen2.5-3B-Instruct
Qwen3.5-9B
Qwen2.5-3B-Instruct
Qwen2.5-3B-Instruct
![\"Cinco](\"https://development-wec.wiline.com/docs/es/assets/images/gw2-heuristic-route-af0d1b1a3a318287720fa1b18160e760.png\")
\nFigura 1. La solicitud de código subió un nivel. Las dos preguntas más difíciles no.
Un saludo en el modelo pequeño es correcto. Una solicitud de Python en el modelo medio es correcta. Pero un bloqueo de sistemas distribuidos y una de las preguntas más difíciles en ciencias de la computación aterrizaron en un modelo de 3 mil millones de parámetros.
\nPara entender por qué, debes saber lo que realmente está haciendo el enrutador.
\nPor defecto, este enrutador no hace llamadas a la API. Puntúa el prompt localmente con coincidencias de patrones — eso es lo que \"heurística\" significa aquí: una regla de oro barata que aproxima un juicio sin hacerlo.
\nPuntúa siete dimensiones, cada una produciendo un valor entre −1 y +1, luego multiplica cada una por un peso fijo y las suma:
\n| Dimensión | Peso | Se activa en |
|---|---|---|
codePresence | 0.30 | function, class, api, schema, … |
reasoningMarkers | 0.25 | \"paso a paso\", \"pensar a través\", \"analizar\" |
technicalTerms | 0.25 | \"arquitectura\", \"distribuido\", \"cifrado\" |
tokenCount | 0.10 | −1.0 bajo 15 tokens, +1.0 sobre 400 |
simpleIndicators | 0.05 | \"qué es\", \"definir\", saludos — puntúa −1.0 |
multiStepPatterns | 0.03 | \"primero… luego\", pasos numerados |
questionComplexity | 0.02 | más de tres signos de interrogación |
La suma ponderada se asigna a un nivel en tres límites: por debajo de 0.15 es SIMPLE, por debajo de 0.35 MEDIUM, por debajo de 0.60 COMPLEX, y por encima de eso REASONING. Todos esos valores están documentados y son configurables.
\nDos dimensiones pueden empujar la puntuación hacia abajo. Un prompt corto puntúa −1.0 en tokenCount. Un prompt que contiene \"qué es\" puntúa −1.0 en simpleIndicators.
El enrutador registra su propio trabajo. Cada solicitud enrutada escribe una decisión en el registro de gastos:
\ncurl -s http://127.0.0.1:4000/spend/logs \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
| jq -r '.[].metadata.routing_decision | select(.) | \"\\(.tier) \\(.score) -> \\(.routed_model) \\(.signals)\"' | head -5
Más reciente primero, así que esto se lee de abajo hacia arriba en contra del orden en que se enviaron los prompts:
\nSIMPLE -0.1 -> qwen-small [\"corto (11 tokens)\"]
SIMPLE 0 -> qwen-small null
MEDIUM 0.3 -> qwen-mid [\"código (función, python)\"]
SIMPLE -0.15000000000000002 -> qwen-small [\"corto (3 tokens)\",\"simple (qué es)\"]
SIMPLE -0.15000000000000002 -> qwen-small [\"corto (0 tokens)\",\"simple (hola)\"]
![\"Decisiones](\"https://development-wec.wiline.com/docs/es/assets/images/gw2-decisions-c9f72192a937dfe8928c7a438f555144.png\")
\nFigura 2. No es una caja negra: el enrutador informa la puntuación y las señales que se activaron.
Toma el último. prueba que el problema de parada es indecidible:
tokenCount -1.0 × 0.10 = -0.10 11 tokens, bajo el umbral de 15
codePresence 0.0 × 0.30 = 0.00 sin palabras clave de código
reasoningMarkers 0.0 × 0.25 = 0.00 \"prueba\" no está en la lista de marcadores
technicalTerms 0.0 × 0.25 = 0.00
simpleIndicators 0.0 × 0.05 = 0.00
multiStepPatterns 0.0 × 0.03 = 0.00
questionComplexity 0.0 × 0.02 = 0.00
------
-0.10 por debajo de 0.15 → SIMPLE → modelo 3B
Cada término es cero excepto una penalización por ser corto. La pregunta se enruta hacia abajo porque es breve.
\nAhora el prompt de bloqueo, que es peor: puntuó 0.00 sin señales en absoluto. No es una puntuación baja — nada coincidió. \"Nuestros dos servicios se bloquean bajo carga, guíame a través del diagnóstico\" no contiene ninguna palabra clave que el puntuador reconozca, por lo que cae en SIMPLE por defecto.
\nPuedes leer una decisión de enrutamiento — nivel, puntuación y las señales que la produjeron — y reproducir la aritmética a mano a partir de los pesos de las dimensiones.
El enrutador no está fallando. Está haciendo exactamente lo que dicen sus reglas. Las reglas simplemente no tienen forma de ver la dificultad que no esté escrita en el vocabulario que conoce.
\nEl modo de falla es sistemático, no aleatorio: los prompts cortos que necesitan un pensamiento profundo se enrutan hacia abajo. Esos son también los prompts donde un modelo incorrecto es más obvio para el usuario.
Las palabras clave de una sola palabra se coinciden en los límites de las palabras, por lo que endpoint no coincide con endpoints. Cada palabra clave de una sola palabra en las listas predeterminadas es singular, y ninguna de ellas coincide con un plural.
Si eso cambia algo depende de cuán cerca esté la puntuación de un límite, porque las dimensiones son escalonadas en lugar de lineales — technicalTerms puntúa 0.5 en dos coincidencias y 1.0 en cuatro, por lo que perder una coincidencia a menudo no cambia nada. A veces cambia el modelo:
Revisa nuestro api endpoint para problemas de autenticación y autorización → COMPLEJO +0.425
Revisa nuestros api endpoints para problemas de autenticación y autorización → MEDIUM +0.275
Una letra, un nivel. La dirección siempre es la misma: un plural puntúa más bajo o igual, nunca más alto, por lo que la deriva es hacia el modelo más barato.
\nLos plurales que te importan se pueden agregar a la lista técnica con custom_technical_keywords. No hay equivalente para palabras clave de código — la única palanca es code_keywords, que reemplaza la lista incorporada en lugar de extenderla.
La alternativa es gastar una llamada de modelo en la decisión. Cuatro líneas:
\n classifier_type: llm
classifier_llm_config:
model: qwen-small
timeout_ms: 3000
Ahora el enrutador envía el prompt a qwen-small con un rubro y un esquema que obliga a devolver exactamente uno de SIMPLE, MEDIUM, COMPLEX, REASONING, y enruta según la respuesta. El clasificador aquí es el modelo más barato que tenemos — el mismo 3B que estaba respondiendo incorrectamente a las preguntas difíciles hace un momento. Resulta ser un mejor juez de dificultad de lo que es un respondedor de ella.
Reinicia, luego vuelve a ejecutar los cinco prompts idénticos:
\nQwen2.5-3B-Instruct
Qwen3.5-9B
Qwen3.5-122B
Qwen3.5-122B
Qwen3.5-122B
![\"Los](\"https://development-wec.wiline.com/docs/es/assets/images/gw2-llm-route-9a7f2aa9f50bca506a1786ae36cf8c3b.png\")
\nFigura 3. Ambos fallos corregidos — y dos prompts subieron que, argumentablemente, no deberían haberlo hecho.
| Prompt | Heurística | Clasificador LLM |
|---|---|---|
hi | 3B | 3B |
qué es un vpc | 3B | 9B |
función de python … retroceso | 9B | 122B |
bloqueo bajo carga | 3B ✗ | 122B ✓ |
problema de parada | 3B ✗ | 122B ✓ |
Los dos casos rotos están arreglados. Pero lee de nuevo las filas 2 y 3 — todo subió. \"¿Qué es un vpc?\" es una búsqueda fáctica que un modelo de 3B responde perfectamente, y ahora se ejecuta en el 9B. Has dejado de subestimar los prompts difíciles y comenzado a sobreestimar los fáciles. Si esa compensación vale la pena depende de tu mezcla de tráfico, y deberías medir la tuya en lugar de confiar en esta tabla.
\nEsta es la parte que se omite. Agrega un gemelo que omita el enrutador, luego mide ambos:
\ndirect() { curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d \"{\\\"model\\\":\\\"qwen-small\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"$1\\\"}],\\\"max_tokens\\\":10}\" | jq -r .model; }
time ask \"hi\"
time ask \"hi\"
time direct \"hi\"
Qwen2.5-3B-Instruct real 0m2.474s ← primera llamada después del reinicio
Qwen2.5-3B-Instruct real 0m1.041s
qwen-small real 0m0.529s
![\"salida](\"https://development-wec.wiline.com/docs/es/assets/images/gw2-timing-ea97fdf0902b60a49ea16f3951a173c6.png\")
\nFigura 4. Mismo prompt, mismo modelo lo responde, el doble del tiempo de reloj.
El mismo modelo de 3B produjo ambas respuestas. La única diferencia es que una solicitud fue clasificada primero. Ahora descompónlo: el registro de gastos mide cada llamada por separado:
\n| Reloj | Llamada del clasificador | Llamada de servicio |
|---|---|---|
| 2.474 s (frío) | 1449 ms | 806 ms |
| 1.041 s | 549 ms | 456 ms |
| 0.529 s (directo) | — | 495 ms |
La aritmética cierra: 549 + 456 = 1005 ms contra 1.041 s medidos en la terminal.
\nTres cosas se desprenden:
\nEl costo adicional no es constante. A través de las muestras del día, la llamada del clasificador varió de 476 ms a 1449 ms, y la primera solicitud después de un reinicio costó 1449 ms por sí sola. Es una llamada de inferencia completa y hereda lo que sea que esté haciendo el backend. Cualquier número único que cites para ello es el número que te tocó capturar.
\nEl costo de tokens es fijo y mayor de lo que pensarías. Cada clasificación envió 281–293 tokens de entrada — el rubro — y devolvió alrededor de 10. Enrutar hi, un prompt de un token, cuesta ~281 tokens de clasificación antes de que algo responda.
La llamada de servicio también se ralentiza. 456–806 ms cuando se enruta, contra 495 ms directos para la solicitud idéntica. El clasificador parece dejar al backend ocupado para la solicitud en cola detrás de él. Nunca verías esto solo con el tiempo de reloj.
\nEl tiempo de reloj emparejado te dice que se volvió más lento, nunca dónde. Descompón en la llamada del clasificador y la llamada de servicio antes de que cites una cifra — el primer número honesto aquí fue casi el doble del que una sola ejecución de time sugirió.
Si la llamada de clasificación se agota, devuelve la forma incorrecta o vuelve vacía, el enrutador vuelve a el puntuador heurístico — la cosa cuyas fallas acabas de pagar medio segundo para evitar. Silenciosamente.
\nLa documentación oficial nombra la salida: establece classifier_fallback: default_model y un tiempo de espera enruta a un modelo que elegiste deliberadamente, en lugar de al puntuador que envía preguntas difíciles a un modelo de 3B.
También vale la pena verificar en lugar de asumir: la documentación da a timeout_ms un valor predeterminado de 2000, mientras que el paquete en nuestro contenedor tiene un valor predeterminado de 3000. Lee la versión que realmente instalaste.
| Heurística | Clasificador LLM | |
|---|---|---|
| Latencia añadida | sub-milisegundo | 476–1449 ms |
| Llamadas API adicionales | ninguna | una por solicitud |
| Tokens de entrada adicionales | ninguno | ~280 por solicitud |
| Prompts difíciles pero cortos | enrutados hacia abajo | enrutados correctamente |
| Prompts fáciles | enrutados correctamente | enrutados hacia arriba |
| Falla por | estar confidentemente equivocado | agotarse, luego estar confidentemente equivocado |
La heurística es el valor predeterminado correcto para tráfico de alto volumen que se parece, y puedes mejorarlo mucho con custom_technical_keywords para tu propio vocabulario de dominio. El clasificador LLM justifica su costo cuando los prompts son variados, cuando equivocarse de modelo es costoso y cuando medio segundo no importa — trabajo por lotes, agentes, cualquier cosa que ya esté tomando segundos.
Lo que ninguno de ellos es, es gratis.
\nsmart-router en lugar de un nombre de modeloreturn_raw_model_name no está configurado. Sin él, el enrutador repite el alias que pediste y no puedes decir qué sirvió la solicitud.
Verifica el campo signals en la decisión de enrutamiento. Si es null, ninguna dimensión coincidió y el prompt puntuó 0.00, lo que cae en SIMPLE. Eso es una señal de que tu tráfico no utiliza el vocabulario que las listas de palabras clave predeterminadas esperan.
Están en la solicitud enrutada, bajo metadata.routing_decision, no en la llamada del clasificador. Filtra con map(select(.)) como arriba — la mitad de las filas son las llamadas del clasificador en sí y no llevan ninguna decisión.
Inicio en frío. La primera clasificación aquí tomó 1449 ms contra aproximadamente 550 ms una vez caliente. Descarta la primera muestra al medir.
\nEl gateway ahora decide qué modelo se ejecuta, y sabes lo que cuesta esa decisión en latencia y tokens. Aún reenvía cada prompt textualmente al modelo que gana — incluidos los que contienen nombres de clientes, correos electrónicos y claves API.
\nLa próxima publicación pone un filtro en ese camino.
\n+Así es como suele ir. Una aplicación necesita un modelo, así que pegas la clave API en\nsu .env. Luego una segunda aplicación necesita una. Luego un script. Seis meses después, la misma\nclave está en cinco lugares, nadie recuerda cuál de ellas sigue funcionando, y no\npuedes rotarla sin romper algo que solo descubrirás cuando se rompa.
Un gateway es la solución aburrida. Un endpoint frente a cada modelo, un lugar que\nmantiene la credencial real, y una clave específica por aplicación que puedes revocar por su cuenta.\nEsta publicación despliega uno en una instancia WEC y lo apunta a la API de Inferencia WEC.
\n\n\nEl host ya ejecuta cinco otras pilas, lo cual es importante: este es el caso normal,\nno una VM limpia. Antes de agregar algo, verifica qué está escuchando y qué está libre:
\ndocker ps --format '{{.Names}}\\t{{.Ports}}'
sudo ss -tlnp | grep -E ':(4000|5432|5433)\\b'
langfuse-postgres-1 127.0.0.1:5433->5432/tcp
langfuse-clickhouse-1 127.0.0.1:8123->8123/tcp, 127.0.0.1:9000->9000/tcp
openclaw-caddy-1 100.87.239.229:80->80/tcp, 100.87.239.229:443->443/tcp
...
LISTEN 0 244 127.0.0.1:5432 users:((\"postgres\",pid=892))
LISTEN 0 4096 127.0.0.1:5433 users:((\"docker-proxy\"))
El puerto 4000 está libre. Postgres 5432 pertenece al host y 5433 a Langfuse, así que la\nbase de datos del gateway no obtiene ninguno: no publicará un puerto en absoluto.
\nLuego confirma que el backend responde antes de poner algo frente a él:
\ncurl -s https://inference.wiline.com/v1/models \\
-H \"Authorization: Bearer $WEC_API_KEY\" | jq -r '.data[].id'
whisper-large-v3
gemma4
wiline-coding
zai-org/GLM-5.2
Qwen2.5-3B-Instruct
Qwen3.5:9B
Qwen3.5-122B
kokoro
Llama3.1-8B-Instruct
bge-m3
Qwen3.5-9B
wiline-auto
wiline-cost
Trece modelos en una clave. Eso es lo que estamos a punto de dejar de repartir.
\nDos contenedores: el gateway y un Postgres para su propio estado. Crea un directorio y\nescribe el archivo de composición:
\nmkdir -p ~/llm-gateway && cd ~/llm-gateway
services:
litellm:
image: ghcr.io/berriai/litellm:main-stable
container_name: llm-gateway
restart: unless-stopped
ports:
- \"127.0.0.1:4000:4000\"
volumes:
- ./config.yaml:/app/config.yaml:ro
command: [\"--config\", \"/app/config.yaml\", \"--port\", \"4000\"]
env_file: .env
depends_on:
db:
condition: service_healthy
db:
image: postgres:17
container_name: llm-gateway-db
restart: unless-stopped
user: \"999:999\"
environment:
POSTGRES_USER: llmproxy
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: litellm
volumes:
- gateway-db:/var/lib/postgresql/data
healthcheck:
test: [\"CMD-SHELL\", \"pg_isready -U llmproxy -d litellm\"]
interval: 5s
timeout: 5s
retries: 10
volumes:
gateway-db:
Cuatro de esas líneas están haciendo trabajo real:
\n127.0.0.1:4000:4000 mantiene el gateway fuera de Internet público. Mantiene cada\ncredencial de modelo que posees, así que publicarlo en 0.0.0.0 pondría todas\ndetrás de una sola contraseña compartida. Parte 1 de la serie de endurecimiento es la versión larga de por qué\neso es un mal intercambio.
La base de datos no tiene ports: en absoluto. Nada fuera de la red de composición necesita\nalcanzarla, y 5432 ya estaba ocupado.
user: \"999:999\" ejecuta Postgres como su usuario no root incorporado desde el primer arranque.\nParte 2 cubre lo que eso te ofrece\ny cómo encontrar el UID correcto para una imagen en lugar de adivinar.
condition: service_healthy importa más de lo que parece. El gateway ejecuta migraciones de base de datos al inicio: sin ello, compite con Postgres y entra en un bucle de fallos.
model_list:
- model_name: qwen-small
litellm_params:
model: openai/Qwen2.5-3B-Instruct
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: qwen-mid
litellm_params:
model: openai/Qwen3.5-9B
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: qwen-large
litellm_params:
model: openai/Qwen3.5-122B
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
- model_name: embeddings
litellm_params:
model: openai/bge-m3
api_base: https://inference.wiline.com/v1
api_key: os.environ/WEC_API_KEY
general_settings:
master_key: os.environ/LITELLM_MASTER_KEY
database_url: os.environ/DATABASE_URL
store_model_in_db: true
litellm_settings:
drop_params: true
model_name es el alias que tus aplicaciones piden. model: es lo que el gateway realmente\nllama. Esa indirecta es la mayor parte del valor: cambia qwen-mid para apuntar a otro lugar\nel próximo mes y ningún cliente cambia.
El prefijo openai/ dice \"habla el protocolo OpenAI a un api_base personalizado.\" La\nAPI de Inferencia WEC es compatible con OpenAI, así que eso es todo lo que se necesita.
Genera las contraseñas en lugar de inventarlas:
\nPGPW=$(openssl rand -hex 16)
MK=\"sk-$(openssl rand -hex 20)\"
cat > .env <<EOF
POSTGRES_PASSWORD=${PGPW}
DATABASE_URL=postgresql://llmproxy:${PGPW}@db:5432/litellm
LITELLM_MASTER_KEY=${MK}
WEC_API_KEY=your-wec-key-here
EOF
chmod 600 .env
Luego pon tu clave WEC real en lugar de your-wec-key-here. La clave maestra es la\ncredencial raíz del gateway: puede crear claves, eliminar claves y acceder a cada modelo,\nasí que va en tu gestor de contraseñas y en ningún otro lugar.
docker compose up -d
✔ Imagen ghcr.io/berriai/litellm:main-stable Descargada 58.2s
✔ Red llm-gateway_default Creada 0.1s
✔ Volumen llm-gateway_gateway-db Creado 0.1s
✔ Contenedor llm-gateway-db Saludable 8.8s
✔ Contenedor llm-gateway Creado 0.2s
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/gw-compose-up-e741e826f043d86aa7f1a7214f71fbcb.png\")
\nFigura 1. Una descarga, dos contenedores, una red y un volumen.
Creado en lugar de Iniciado en esa última línea es normal para la salida de composición,\npero verifica de todos modos — y verifica cuánto te costó la imagen en disco mientras estás allí:
docker compose ps -a && echo && df -h /
NOMBRE IMAGEN SERVICIO ESTADO PUERTOS
llm-gateway ghcr.io/berriai/litellm:main-stable litellm Arriba 3 minutos 127.0.0.1:4000->4000/tcp
llm-gateway-db postgres:17 db Arriba 3 minutos (saludable) 5432/tcp
Sistema de archivos Tamaño Usado Disponible Uso% Montado en
/dev/vda1 58G 54G 4.2G 93% /
Nota la columna PUERTOS de la base de datos: 5432/tcp sin enlace de host delante de\nella. La imagen del gateway es de 1.16GB, lo cual en una caja que ya ejecuta cinco pilas no es\nnada despreciable. Verifica que tienes espacio antes de comenzar, no después.
Dos líneas en el registro de inicio valen la pena leer, porque ambas se ven peores de lo que son:
\ndocker compose logs litellm --tail 40
✅ Diferencia de migración aplicada con éxito
INFO: Inicio de la aplicación completo.
INFO: Uvicorn ejecutándose en http://0.0.0.0:4000 (Presiona CTRL+C para salir)
register_model: model=openai/Qwen2.5-3B-Instruct no en el mapa de costos incorporado y ningún
prefijo/variante de región coincidió; los campos de costo de caché se establecerán en 0.
![\"Estado](\"https://development-wec.wiline.com/docs/es/assets/images/gw-ps-logs-ed50299979281a4fb3dfd6ec9c89d189.png\")
\nFigura 2. Migraciones aplicadas, inicio de la aplicación completo y una advertencia del mapa de costos por modelo.
0.0.0.0:4000 es el enlace dentro del contenedor. La publicación en el host sigue siendo\n127.0.0.1, que es lo que realmente controla el acceso. Y la advertencia del mapa de costos es\nmás específica de lo que parece: se trata de la fijación de precios de caché específicamente. La\nfijación de precios de tokens regulares sigue ocurriendo, lo cual resulta ser importante más adelante.
set -a && . ./.env && set +a
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":20}' | jq
\"finish_reason\": \"length\",
\"message\": {
\"reasoning_content\": \"Proceso de Pensamiento:\\n\\n1. **Analiza la Solicitud:**\\n * Entrada: \\\"\",
\"content\": null
}
\"usage\": {\"completion_tokens\": 20, \"prompt_tokens\": 16, \"total_tokens\": 36}
![\"Respuesta](\"https://development-wec.wiline.com/docs/es/assets/images/gw-reasoning-null-2d60fce2efcb8e175da27120082ac585.png\")
\nFigura 3. Una llamada exitosa sin nada en ella.
content: null. La llamada funcionó: se enruta, llegó al backend, contó tokens\n— pero no hay respuesta en ella.
Qwen3.5-9B es un modelo de razonamiento. Gastó todos los veinte tokens pensando y no le quedaron\npara hablar. El movimiento obvio es darle más espacio:
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":200}' | jq '.choices[0].message.content, .usage'
null
{
\"completion_tokens\": 200,
\"prompt_tokens\": 16,
\"total_tokens\": 216
}
Doscientos tokens, aún nada. Y esta es la parte que vale la pena pausar: una ejecución anterior de ese mismo comando sí respondió, con 192 tokens. Mismo modelo, mismo aviso,\ndiferente cantidad de pensamiento. No hay un max_tokens que puedas establecer que garantice\nuna respuesta, porque la longitud del razonamiento no es fija.
Ahora el mismo aviso a través del modelo pequeño, con los veinte tokens originales:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"Responde exactamente: gateway works\"}],\"max_tokens\":20}' | jq '.choices[0].message.content, .usage'
\"gateway works\"
{
\"completion_tokens\": 3,
\"prompt_tokens\": 35,
\"total_tokens\": 38
}
![\"Modelo](\"https://development-wec.wiline.com/docs/es/assets/images/gw-token-contrast-922bab5aa94a6417e02dbc0d6fe0c874.png\")
\nFigura 4. Doscientos tokens y ninguna respuesta, contra tres tokens y la respuesta.
Nada está roto aquí. El modelo de razonamiento está haciendo exactamente lo que se supone que debe hacer,\nen una pregunta que no lo necesitaba. La solución no es un presupuesto de tokens más grande: no\nenviar trabajo trivial a ese modelo en primer lugar. Lo cual es todo el argumento\npara el enrutamiento, y el tema de la próxima publicación.
\nPuedes poner un gateway frente a varios modelos, dar a cada uno un alias que tus aplicaciones\nllamen en lugar de un ID de modelo de proveedor, y leer una respuesta lo suficientemente bien como\npara distinguir un modelo de razonamiento de uno simple.
Un gateway que mantiene cada credencial que posees debería rechazar a cualquiera sin una clave.\nVale la pena verificar en lugar de asumir:
\ncurl -s -o /dev/null -w \"sin clave: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}]}'
curl -s -o /dev/null -w \"clave incorrecta: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer sk-not-a-real-key\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}]}'
curl -s -o /dev/null -w \"clave maestra: %{http_code}\\n\" http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-mid\",\"messages\":[{\"role\":\"user\",\"content\":\"hola\"}],\"max_tokens\":5}'
sin clave: 401
clave incorrecta: 401
clave maestra: 200
![\"Tres](\"https://development-wec.wiline.com/docs/es/assets/images/gw-auth-401-a9d9d89ff8432a6ec7a29486800ea82c.png\")
\nFigura 5. Tanto anónimos como falsificados rechazados, la clave real a través.
El gateway incluye una interfaz web, y está vinculada a localhost — que es el\npunto, así que accede a ella a través de SSH en lugar de abrir un puerto:
\nssh -L 4000:127.0.0.1:4000 ubuntu@your-wec-instance
Deja eso funcionando y abre http://localhost:4000/ui. Nombre de usuario admin, la contraseña\nes la clave maestra de tu .env.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw-ui-login-94d370f9590bd022684fb80ccabb2aff.png\")
\nFigura 6. La página de inicio de sesión indica sus propias credenciales predeterminadas, lo cual es un buen\nrecordatorio de que la clave maestra es lo único que está ahí.
Haz clic en Modelos + Endpoints:
\n![\"Gestión](\"https://development-wec.wiline.com/docs/es/assets/images/gw-ui-models-4372c39b1bfb45a2d61782e145f1c5e2.png\")
\nFigura 7. Todos los cuatro alias registrados, cada uno mapeado a su objetivo openai/....
La clave maestra puede acceder a cada modelo y crear más claves. Ninguna aplicación debería\ntenerla nunca. En su lugar, emite una clave virtual específica para lo que esa aplicación realmente necesita.
\nClaves Virtuales → + Crear Nueva Clave:
\n| Campo | Valor |
|---|---|
| Propietario | Tú |
| Equipo | dejar vacío |
| Nombre de Clave | demo-app |
| Modelos | qwen-small |
| Presupuesto Máximo (USD) | 0.10 |
| Restablecer Presupuesto | diario |
Dos cosas sobre este formulario. Presupuesto Máximo vive bajo Configuraciones Opcionales,\nque comienza colapsada — fácil de perder y luego preguntarse dónde fue el campo de presupuesto. Y\ndejar Modelos vacío significa todos los modelos, lo opuesto a lo que quieres aquí.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw-key-create-f440427f7d6f55ad01482ed469ff3624.png\")
\nFigura 8. Específico para un modelo, limitado a diez centavos al día.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/gw-key-saved-e13c0abfcd4b4c0bfefa791764eaae50.png\")
\nFigura 9. El diálogo lo dice claramente. Créelo.
La clave generada se muestra una vez y nunca más. Cierra esto sin copiar y\ntu única opción es eliminar la clave y crear otra.
Ahora la parte que justifica todo el ejercicio. La misma clave, dos modelos:
\ncurl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $VK\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-small\",\"messages\":[{\"role\":\"user\",\"content\":\"di hola\"}],\"max_tokens\":20}' | jq -r '.choices[0].message.content'
¡Hola! ¿Cómo puedo ayudarte hoy?
curl -s http://127.0.0.1:4000/v1/chat/completions \\
-H \"Authorization: Bearer $VK\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"qwen-large\",\"messages\":[{\"role\":\"user\",\"content\":\"di hola\"}],\"max_tokens\":20}' | jq
{
\"error\": {
\"message\": \"clave no permitida para acceder al modelo. Esta clave solo puede acceder a modelos=['qwen-small']. Intentó acceder a qwen-large\",
\"type\": \"key_model_access_denied\",
\"param\": \"model\",
\"code\": \"403\"
}
}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/gw-key-403-ff8ff7ee956b8b081dd67c4d3834ac10.png\")
\nFigura 10. Una credencial, un modelo. Filtrarla y el radio de explosión es esa única línea.
Compara eso con la situación en la que comenzamos: una clave en cinco archivos .env, con acceso\na todos los trece modelos y sin forma de saber qué aplicación la está utilizando.
Puedes emitir una credencial específica por aplicación, restringirla a modelos específicos\ncon un límite de gasto, y revocarla por su cuenta sin tocar nada más.
Cada llamada aterriza en un registro de gastos:
\ncurl -s http://127.0.0.1:4000/spend/logs \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
| jq '[.[] | select(.spend > 0)] | .[-3:] | .[] | {model, spend, prompt_tokens, completion_tokens}'
{
\"model\": \"openai/Qwen3.5-9B\",
\"spend\": 8.520000000000001e-05,
\"prompt_tokens\": 16,
\"completion_tokens\": 20
}
{
\"model\": \"openai/Qwen3.5-9B\",
\"spend\": 2.62e-05,
\"prompt_tokens\": 11,
\"completion_tokens\": 5
}
![\"Filas](\"https://development-wec.wiline.com/docs/es/assets/images/gw-spend-logs-dfdc834679299ecd1fcfcc774e83b5b3.png\")
\nFigura 11. Tokens contados por llamada, con un precio adjunto a cada uno.
Ese select(.spend > 0) no es cosmético. Las llamadas fallidas también se registran, con cero\ntokens y cero gasto: los 401 de antes están todos ahí con status: \"failure\". Útil por sí mismo: el registro de gastos también sirve como un registro de\nalguien intentando claves que no funcionan.
Esas cifras en dólares son reales. Coinciden con la fijación de precios por modelo publicada para la\nAPI que este gateway está llamando: $0.70 por millón de tokens de entrada y $3.70 por millón\nde salida para Qwen3.5-9B, las mismas tarifas que ves listadas contra cada modelo antes\nde elegir uno. Así que el registro de gastos es un registro genuino de lo que costó cada llamada,\ndesglosado por clave y por modelo, desde la primera solicitud.
Dos cosas más en la entrada completa del registro, ambas útiles:
\n\"litellm_overhead_time_ms\": 36.189,
\"messages\": {},
\"response\": {}
El gateway mide su propia sobrecarga y la informa por solicitud: 36ms aquí, que es un número real al que puedes exigirle. Y los avisos y respuestas no se almacenan por defecto: el registro sabe que ocurrió una llamada y cuánto costó, no lo que se dijo.
\nCasi siempre es la base de datos. Verifica docker compose logs litellm para errores de migración: si el gateway se levantó antes de que Postgres estuviera listo, falta la condición depends_on o el healthcheck no está pasando.
content regresa null con finish_reason: \"length\"El modelo es un modelo de razonamiento y utilizó todo tu presupuesto de tokens pensando. Aumentar\nmax_tokens ayuda pero no garantiza nada: el mismo aviso con 200 tokens respondió en una ejecución y devolvió null en la siguiente. Para trabajos que no necesitan\nrazonamiento, envíalos a un modelo que no haga ninguno.
Está vinculada a 127.0.0.1, así que es inaccesible desde cualquier lugar que no sea la propia caja.\nUsa un túnel SSH. Si el túnel está activo y la página aún no se carga, confirma que el\npuerto en docker compose ps coincide con el que has reenviado.
Las cadenas unidas con && se detienen en el primer comando que falla, y un grep fallido\ncuenta como un fallo. Sourcing un archivo env cuyo nombre de variable adivinaste mal\ndeja un marcador de posición en su lugar y todo parece bien hasta un error de autenticación tres\npasos después. Verifica los marcadores de posición explícitamente:
grep -c 'your-wec-key-here' .env
Desde la terminal, por alias:
\ncurl -s -X POST http://127.0.0.1:4000/key/delete \\
-H \"Authorization: Bearer $LITELLM_MASTER_KEY\" \\
-H \"Content-Type: application/json\" \\
-d '{\"key_aliases\":[\"demo-app\"]}' | jq
Ahora tienes un endpoint, una credencial por aplicación y un registro de cada llamada. La\npregunta obvia es la que planteó la Figura 4: si el modelo pequeño responde en 3 tokens\nlo que el modelo de razonamiento gasta 200 sin responder en absoluto, ¿por qué se enruta algo\nal costoso por defecto?
\nLa próxima publicación pone al gateway a cargo de esa decisión y mide lo que cuesta pedirle.
\nParte 1 de esta serie auditó una caja multi-agente en vivo y encontró cada pregunta sobre exposición de red que valía la pena hacer. Una línea de esa auditoría no se siguió: \"el Postgres, ClickHouse y Redis detrás de Langfuse estaban publicados en 127.0.0.1 en lugar del mundo — alguien tomó una buena decisión allí. Mantén ese pensamiento.\"
Aquí está la otra mitad de ese pensamiento: conseguir la red correcta no dice nada sobre lo que sucede después de que alguien ya esté dentro de un contenedor. Si el proceso que se ejecuta allí es root, un compromiso comienza con las llaves de todo el sistema de archivos. Así que verificamos — en la misma caja, la misma pila de Langfuse que la Parte 1 ya alabó — si \"red correcta\" también significaba \"privilegio correcto.\" No lo era, para dos de los seis contenedores. Aquí está cómo se veía realmente la solución, incluyendo la parte que se rompió.
\n\nDocker no te dice esto por defecto — un contenedor puede estar publicado correctamente, saludable y ejecutándose como root todo el tiempo, sin que nada en docker ps lo sugiera. La única forma de saberlo es preguntar directamente al contenedor:
docker exec langfuse-postgres-1 id -u
docker exec langfuse-redis-1 id -u
0
0
![\"Ambas](\"https://development-wec.wiline.com/docs/es/assets/images/privsec-root-confirmed-9af63f21bf8c07c7554a6cbab4f02929.png\")
\nFigura 1. La verificación que la mayoría de las configuraciones nunca ejecutan: ambas llamadas a id -u regresan 0. Saludables, publicados correctamente, y root todo el tiempo.
0 es root. Ambos estaban ejecutándose como root, y al mirar el archivo de composición se explica por qué — ninguno de los servicios tiene una directiva user: en absoluto:
redis:
image: docker.io/redis:7
restart: always
command: >
--requirepass ${REDIS_AUTH:-myredissecret}
--maxmemory-policy noeviction
...
postgres:
image: docker.io/postgres:${POSTGRES_VERSION:-17}
restart: always
...
Nadie decidió que estos debían ejecutarse como root. Es simplemente lo que sucede cuando no configuras nada — la misma forma que el hallazgo de la Parte 1 de que una contraseña de Redis no configurada predetermina la falta de autenticación. El servicio clickhouse en el mismo archivo muestra la solución ya medio hecha, sentada justo allí para comparación:
clickhouse:
image: docker.io/clickhouse/clickhouse-server
restart: always
user: \"101:101\"
Una línea. Alguien lo configuró para ClickHouse y nunca llegó a los otros dos.
\nNo inventes un UID — ambas imágenes oficiales ya incluyen un usuario no root construido para exactamente esto, y adivinar mal significa un error de permisos o, peor aún, un UID que silenciosamente no coincide con el que los propios archivos de la imagen son propiedad:
\ndocker exec langfuse-postgres-1 id postgres
docker exec langfuse-redis-1 id redis
uid=999(postgres) gid=999(postgres) groups=999(postgres),101(ssl-cert)
uid=999(redis) gid=999(redis) groups=999(redis)
Ambas imágenes utilizan 999:999 para su usuario no root incorporado. Agrégalo al archivo de composición:
redis:
image: docker.io/redis:7
user: \"999:999\"
restart: always
...
postgres:
image: docker.io/postgres:${POSTGRES_VERSION:-17}
user: \"999:999\"
restart: always
...
docker compose up -d --force-recreate postgres redis
✔ Contenedor langfuse-postgres-1 recreado
✔ Contenedor langfuse-redis-1 recreado
sleep 5
docker compose ps
docker exec langfuse-postgres-1 id -u
docker exec langfuse-redis-1 id -u
langfuse-postgres-1 Up 34 seconds (healthy) 127.0.0.1:5433->5432/tcp
langfuse-redis-1 Up 34 seconds (healthy) 127.0.0.1:6379->6379/tcp
999
999
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/privsec-nonroot-healthy-2aa6142e51931837aa80ee308e8be448.png\")
\nFigura 2. Los mismos dos contenedores, segundos después de --force-recreate: ambos healthy, ambos id -u ahora 999 en lugar de 0.
Sin errores de permisos, sin dramas de propiedad, ambos saludables en segundos. Eso vale la pena decirlo claramente porque no siempre es cierto — si estos volúmenes se hubieran inicializado como root en algún lugar upstream y nunca se les hubiera hecho chown, este comando exacto puede fallar con permission denied en el directorio de datos. No falló aquí, pero revisa tus propios registros después de recrear, no asumas que \"sin salida\" significa \"sin problema.\"
Puedes verificar si un contenedor en ejecución es realmente root (docker exec <container> id -u), encontrar el usuario no root previsto de su imagen en lugar de adivinar un UID (docker exec <container> id <username>), y convertirlo con una línea user: en la composición.
Todo lo anterior fue limpio. Luego, los registros de un contenedor completamente diferente contaron una historia diferente:
\ndocker logs langfuse-langfuse-worker-1 --tail 20
Error: getaddrinfo ENOTFOUND redis
at GetAddrInfoReqWrap.onlookupall [as oncomplete] (node:dns:122:26)
Error de Redis getaddrinfo ENOTFOUND redis
Error de Redis connect ECONNREFUSED 172.19.0.5:6379
El trabajo de cola mixpanel-integration-processing-queue falló: Error: Tiempo de espera de socket.
Esperando datos, pero no se recibió ninguno en 30000ms.
El trabajo de cola trace-delete falló: Error: Tiempo de espera de socket. Esperando datos, pero no se recibió ninguno en 30000ms.
![\"registros](\"https://development-wec.wiline.com/docs/es/assets/images/privsec-worker-broken-e776f29e677755bd8a5e61864dbe22bc.png\")
\nFigura 3. Un contenedor que nadie tocó, fallando de todos modos — cada trabajo de cola con el mismo tiempo de espera de socket de 30 segundos contra Redis, mucho después de la recreación que lo causó.
langfuse-worker nunca tocó la propiedad de Postgres o Redis — solo mantiene una conexión activa a Redis, y --force-recreate derribó el contenedor al que apuntaba esa conexión. La propia verificación de salud de Docker decía que Redis estaba healthy de nuevo mucho antes de que el trabajador se rindiera al reintentar; ioredis simplemente no se reconecta limpiamente por sí mismo aquí, y siguió fallando con tiempos de espera de socket de 30 segundos mucho después de que la dependencia de la que dependía volvió.
La solución es el reinicio del propio servicio dependiente, no otra mirada a Redis:
\ndocker compose restart langfuse-worker langfuse-web
2026-08-10T19:40:22.505Z info La conexión a Redis se ha cerrado.
2026-08-10T19:40:22.769Z info Apagado completo, saliendo del proceso...
sleep 10
docker logs langfuse-langfuse-worker-1 --tail 15
experiment-create-queue executor started: true
posthog-integration-queue executor started: true
data-retention-queue executor started: true
webhook-queue executor started: true
Listening: http://21caf9a28775:3030
![\"registros](\"https://development-wec.wiline.com/docs/es/assets/images/privsec-worker-recovered-ca07f68b5e4cb0994524f20c497f41ca.png\")
\nFigura 4. El mismo contenedor, un reinicio después — cada ejecutor de cola comienza limpio, sin errores de Redis en ninguna parte del registro.
Inicio limpio de la cola, sin errores de Redis. Esa es toda la lección: endurecer un contenedor no se limita a ese contenedor. Cualquier cosa que mantenga una conexión activa con la cosa que acabas de recrear necesita su propio reinicio, a propósito, no como un pensamiento posterior que descubres a partir de un registro de errores veinte minutos después.
\n--force-recreate en una dependencia compartida (una base de datos, una cola, un caché) puede romper silenciosamente cada servicio que ya tenía una conexión abierta a ella — incluso después de que la dependencia misma informe que está saludable de nuevo. Reinicia explícitamente a los dependientes; no asumas que lo notarán por sí mismos.
| Contenedor | Antes | Solución | ¿Rompe algo? |
|---|---|---|---|
langfuse-postgres-1 | root (uid 0) | user: \"999:999\" | No — recreado limpio |
langfuse-redis-1 | root (uid 0) | user: \"999:999\" | No — recreado limpio |
langfuse-clickhouse-1 | ya 101:101 | ninguna necesaria | — |
langfuse-langfuse-worker-1 | intocable | ninguna — solo necesitaba un reinicio | Sí — perdió su conexión a Redis después de que los otros dos contenedores fueron recreados |
Dos soluciones de una línea. El costo real no fue la solución — fue notar que el tercer contenedor que nadie tocó fue el que se rompió.
\ndocker compose restart dijo \"no se proporcionó archivo de configuración: no encontrado\"No estás en el directorio del proyecto que Compose espera — solo encuentra docker-compose.yml relativo a tu directorio de trabajo actual (o a través de -f). Primero, cd en la carpeta de la pila; este error exacto significa que Compose nunca miró siquiera a tus contenedores.
Reiniciar la dependencia no ayuda — la conexión que se rompió pertenece al servicio dependiente. Reinicia la cosa que mantiene la conexión (aquí, langfuse-worker), no la cosa a la que se conecta.
docker exec <container> id <username> devuelve \"no existe tal usuario\"La imagen no incluye un usuario no root dedicado bajo ese nombre — consulta la documentación de la imagen, o docker exec <container> cat /etc/passwd para ver qué está realmente disponible antes de elegir un UID.
El privilegio es la segunda capa: el endurecimiento de la red evita que un compromiso se propague entre pilas, el no root evita que un compromiso posea todo el contenedor. La última capa en esta serie es la identidad — poner autenticación real frente a los puertos que deben permanecer expuestos, que es donde NetBird y Caddy entran en juego.
\nComienzas con un agente. Luego necesita una base de datos. Después agregas un segundo agente, un puente de mensajería, una pila de observabilidad. Seis meses después, una única instancia de WEC está ejecutando cinco proyectos de compose, veinte y tantos contenedores, y nadie recuerda qué puertos están abiertos al mundo.
\nEso no es un hipotético — esa es la caja en la que se escribió este tutorial. Así que en lugar de teorizar, lo investigamos: ¿pueden los contenedores alcanzarse entre sí a través de pilas? ¿Pueden alcanzar las bases de datos? ¿Está el firewall realmente protegiendo algo?
\nTres de las respuestas me sorprendieron. Una de ellas fue una base de datos sentada allí sin contraseña. Y el firewall — el firewall estaba mintiendo.
\n\nCinco proyectos de compose independientes, desplegados durante meses, cada uno con su propia red (host, none y bridge son los integrados de Docker, más uno sobrante de un servicio que no está en ejecución):
docker network ls
NETWORK ID NAME DRIVER SCOPE
655850b24125 bridge bridge local
05e5d49e7e9d evolution-api_default bridge local
e8bd75ecbb0a host host local
ce697baac173 langfuse_default bridge local
ead3e0822ce6 nlp-evaluation-service_nlp-net bridge local
5d0ab32d14d7 none null local
9a6727150f2b openclaw_default bridge local
ec77b98f457b rag-service_default bridge local
5f88cabf97f0 remark42_default bridge local
Y aquí está lo que se publica al mundo:
\ndocker ps --format '{{.Names}}\\t{{.Ports}}' | grep '0.0.0.0'
remark42-remark42-1 0.0.0.0:8082->8080/tcp, [::]:8082->8080/tcp
evolution-api-evolution-api-1 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp
langfuse-langfuse-web-1 0.0.0.0:3001->3000/tcp, [::]:3001->3000/tcp
langfuse-minio-1 0.0.0.0:9090->9000/tcp, [::]:9090->9000/tcp, 127.0.0.1:9091->9001/tcp
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-exposure-audit-904ef03d2c7552d9b1b8c9d9e69218dd.png\")
\nFigura 1. El inicio de cualquier auditoría. Nueve redes: tres integradas de Docker (bridge, host, none), cinco proyectos de compose, y uno sobrante. Cuatro servicios publicados en 0.0.0.0 — cada interfaz, incluida la pública.
Cuatro servicios escuchando en cada interfaz. Nota lo que no está en esa lista: los Postgres, ClickHouse y Redis detrás de Langfuse. Esos fueron publicados en 127.0.0.1 en su lugar — alguien tomó una buena decisión allí. Mantén ese pensamiento.
La preocupación clásica: OpenClaw es comprometido, y el atacante entra en la base de datos de Langfuse al lado. Vamos a averiguarlo en lugar de adivinar. Obtén las IPs de los contenedores:
\nfor c in langfuse-postgres-1 evolution-api-evolution-postgres-1; do
docker inspect -f '{{.Name}} {{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' $c
done
/langfuse-postgres-1 172.19.0.5
/evolution-api-evolution-postgres-1 172.23.0.4
Ahora intenta alcanzar ambos desde dentro del contenedor de OpenClaw, por IP — sin DNS, sin atajos:
\ndocker exec openclaw-openclaw-gateway-1 node -e '
const net=require(\"net\");
[[\"langfuse-postgres\",\"172.19.0.5\",5432],[\"evolution-postgres\",\"172.23.0.4\",5432]]
.forEach(([n,ip,p])=>{
const s=net.connect({host:ip,port:p,timeout:4000});
s.on(\"connect\",()=>{console.log(`ALCANZADO ${n}`);s.destroy()});
s.on(\"timeout\",()=>{console.log(`bloqueado ${n}`);s.destroy()});
s.on(\"error\",e=>console.log(`error ${n} ${e.code}`));
});'
bloqueado langfuse-postgres
bloqueado evolution-postgres
![\"Las](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-isolation-blocked-52d0644c0dbd63427ca62b09eb5b9947.png\")
\nFigura 2. Conectando por IP cruda desde el contenedor de una pila a la base de datos de otra pila: ambos se agotan. Las reglas de aislamiento de Docker están haciendo su trabajo.
Bloqueado. Las instalaciones modernas de Docker instalan reglas de DOCKER-ISOLATION-STAGE que eliminan el tráfico entre redes de puente definidas por el usuario, y funcionan. Si has leído que \"las redes Docker no realmente aíslan\", pruébalo en tu propia caja antes de creerlo — en Docker actual, sí lo hacen.
Puedes verificar el aislamiento de red empíricamente en lugar de confiar en el folclore: obtén la IP del objetivo con docker inspect, luego conecta por IP desde dentro de otro contenedor.
Así que el aislamiento entre pilas está bien. Lo que significa que el verdadero riesgo está en otro lugar.
\nCada proyecto de compose coloca todos sus servicios en una red. Esa es la predeterminada, y significa que el contenedor de la aplicación puede alcanzar cada servicio de respaldo — lo cual es intencionado. La pregunta es cómo se ve realmente ese acceso. Desde el contenedor de puente de Evolution API:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket
for name, host, port in [(\"postgres\",\"evolution-postgres\",5432),
(\"redis\",\"evolution-redis\",6379),
(\"api\",\"evolution-api\",8080)]:
s=socket.socket(); s.settimeout(4)
try:
s.connect((host,port)); print(f\"ALCANZADO {name}:{port}\")
except Exception as e:
print(f\"bloqueado {name}:{port} -- {type(e).__name__}\")
finally: s.close()'
ALCANZADO postgres:5432
ALCANZADO redis:6379
ALCANZADO api:8080
Alcanzable es esperado. No autenticado no lo es. Verifica si esos servicios realmente piden credenciales — primero Redis:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(5); s.connect((\"evolution-redis\",6379))
s.sendall(b\"INFO server\\r\\n\")
print(s.recv(200).decode(errors=\"replace\")[:120])'
$625
# Server
redis_version:7.4.9
redis_git_sha1:00000000
redis_git_dirty:0
redis_build_id:b61b4eb609520881
redis_
![\"Redis](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-redis-noauth-22e25e2b5bbf007d514a914ec9ec8b91.png\")
\nFigura 3. El hallazgo: INFO server respondió sin credenciales (salida truncada a 120 caracteres por la sonda). Cualquier contenedor en esta red puede leer o borrar el almacén de sesiones.
Eso es un comando INFO respondido sin AUTH — el Redis que mantiene el estado de sesión de este despliegue no tiene contraseña. Cualquier cosa que obtenga ejecución de código en cualquier contenedor en esa red puede leerlo, escribir en él, o FLUSHALL en él.
Postgres, en la misma pila, se comporta correctamente:
\ndocker exec evolution-api-bridge-1 python3 -c '
import socket,struct
s=socket.socket(); s.settimeout(5); s.connect((\"evolution-postgres\",5432))
msg=b\"user\\x00postgres\\x00database\\x00postgres\\x00\\x00\"
s.sendall(struct.pack(\"!ii\",len(msg)+8,196608)+msg)
print(s.recv(64))'
b'R\\x00\\x00\\x00\\x17\\x00\\x00\\x00\\nSCRAM-SHA-256\\x00\\x00'
Exige SCRAM-SHA-256. La misma caja, la misma red, dos servicios de respaldo — uno pide una contraseña, el otro no. Nadie decidió eso; es simplemente lo que las imágenes predeterminan cuando no estableces una contraseña.
\nLa lección: \"red interna\" no es un límite de seguridad. Es una conveniencia. Trata cada servicio como si el atacante ya estuviera en esa red, porque si un contenedor cae, ellos están.
\nAhora lo grande. Activa UFW y deniega todo lo entrante excepto SSH:
\nsudo ufw allow 22/tcp # SIEMPRE primero, o te bloqueas
sudo ufw default deny incoming
sudo ufw --force enable
sudo ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip
To Action From
-- ------ ----
60000:61000/udp ALLOW IN Anywhere
22/tcp ALLOW IN Anywhere
60000:61000/udp (v6) ALLOW IN Anywhere (v6)
22/tcp (v6) ALLOW IN Anywhere (v6)
Denegar entrante — solo SSH y el rango UDP de mosh permitido. Ahora, desde una máquina diferente, abre la interfaz de usuario de Langfuse y la API de Evolution:
\nhttp://<instance-ip>:3001 -> La interfaz de usuario de Langfuse se carga normalmente
http://<instance-ip>:8080 -> {\"status\":200,\"message\":\"Bienvenido a la API de Evolution...\"}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-ufw-bypass-130569873d3680226c3534f016c4756a.png\")
Figura 4. El firewall dice que deniega todo lo entrante. La API de Evolution en :8080 responde de todos modos — estado 200, directamente desde un navegador en otra máquina.
Ambos completamente abiertos, a través de un firewall configurado para bloquearlos. Esta es la sorpresa de seguridad más común en Docker auto-alojado, y no es un error.
\nMira el orden de la cadena FORWARD:
sudo iptables -L FORWARD -n --line-numbers | head -8
Chain FORWARD (policy DROP)
num target prot opt source destination
1 DOCKER-USER all -- 0.0.0.0/0 0.0.0.0/0
2 DOCKER-FORWARD all -- 0.0.0.0/0 0.0.0.0/0
3 ACCEPT all -- 0.0.0.0/0 0.0.0.0/0 ctstate RELATED,ESTABLISHED
4 ACCEPT all -- 0.0.0.0/0 0.0.0.0/0
5 ufw-before-logging-forward all -- 0.0.0.0/0 0.0.0.0/0
6 ufw-before-forward all -- 0.0.0.0/0 0.0.0.0/0
![\"UFW](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-ufw-chains-7a5553d8ce1882eb415c7e12e1beb065.png\")
\nFigura 5. La explicación completa en una pantalla: el firewall dice denegar entrante, y las cadenas de Docker están en las posiciones 1-2 mientras que las de UFW comienzan en 5.
Las cadenas de Docker están en las posiciones 1 y 2. Las de UFW no aparecen hasta 5 y 6. Y publicar un puerto no es un oyente en el host — es una regla de NAT:
\nsudo iptables -t nat -L DOCKER -n | grep -E '3001|8080'
DNAT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:8080 to:172.23.0.3:8080
DNAT tcp -- 0.0.0.0/0 0.0.0.0/0 tcp dpt:3001 to:172.19.0.2:3000
El paquete llega, el NAT de Docker reescribe el destino al contenedor, y se convierte en tráfico reenviado que la propia cadena de Docker acepta — mucho antes de que se consulte cualquier regla de UFW. Tus reglas de UFW no son ignoradas; simplemente nunca se alcanzan.
\nufw deny no protege un puerto Docker publicado. Si has estado confiando en UFW frente a -p 8080:8080, ese puerto ha estado abierto todo el tiempo.
La solución más limpia no es una regla de firewall; es no abrir la puerta. Si un servicio solo es consumido por otros contenedores, no necesita ninguna entrada ports: — el tráfico de servicio a servicio funciona a través de la red de compose por nombre.
Si necesitas que sea accesible desde el host (un puerto de depuración, un psql local), enlázalo explícitamente al loopback:
\nservices:
postgres:
# prefijo 127.0.0.1 = solo host, nunca la interfaz pública
ports:
- \"127.0.0.1:5433:5432\"
Eso es exactamente lo que la pila de Langfuse en esta caja ya hace — su Postgres, ClickHouse y Redis están todos en 127.0.0.1, que es por qué nunca aparecieron en nuestra auditoría de exposición. El predeterminado \"5433:5432\" significa 0.0.0.0 — cada interfaz, incluida la pública.
internalUna red por proyecto de compose es la predeterminada, no un diseño. Da a los servicios de respaldo su propia red, y coloca solo la aplicación en ambas:
\nservices:
app: # habla con el mundo Y con la base de datos
image: your-agent
networks: [frontend, backend]
db:
image: redis:7
command: redis-server --requirepass ${REDIS_PASSWORD}
networks: [backend] # solo backend — sin ruta hacia afuera
public: # por ejemplo, un receptor de webhook
image: your-public-thing
networks: [frontend] # no puede ver la base de datos en absoluto
networks:
frontend:
backend:
internal: true # sin gateway: sin entrada, sin salida
Verificado en la misma caja:
\n# el contenedor solo de frontend intenta alcanzar la base de datos
docker exec netsecdemo-public-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(4)
try: s.connect((\"db\",6379)); print(\"ALCANZADO db <- fuga\")
except Exception as e: print(f\"bloqueado: {type(e).__name__}\")'
# la app, que está en ambas redes
docker exec netsecdemo-app-1 python3 -c '
import socket
s=socket.socket(); s.settimeout(4)
try: s.connect((\"db\",6379)); print(\"ALCANZADO db <- correcto, lo necesita\")
except Exception as e: print(f\"bloqueado: {type(e).__name__}\")'
# y puede la base de datos alcanzar Internet?
docker exec netsecdemo-db-1 timeout 6 getent hosts pypi.org >/dev/null \\
&& echo \"resuelto DNS externo\" || echo \"sin salida a Internet <- interno funcionando\"
bloqueado: gaierror
ALCANZADO db <- correcto, lo necesita
sin salida a Internet <- interno funcionando
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-internal-demo-6231d6936686cf9d282c7f494797a185.png\")
Figura 6. Tres propiedades probadas en una ejecución — el contenedor de cara pública ni siquiera puede resolver la base de datos, la app puede alcanzarla, y la base de datos no tiene ruta a Internet.
\nTres propiedades a la vez: el contenedor de cara pública ni siquiera puede resolver la base de datos, la app puede, y la base de datos no puede comunicarse — lo cual importa el día que una dependencia tuya se vuelva maliciosa.
\nNuestra auditoría encontró a Redis respondiendo INFO sin credenciales. Una línea lo soluciona:
db:
image: redis:7
command: redis-server --requirepass ${REDIS_PASSWORD}
-NOAUTH Authentication required.
Esa es la salida real de esta caja, después de aplicar la solución — el hallazgo de la Prueba 2 está cerrado. Si estableces una contraseña en un Redis que algo ya usa, recuerda actualizar la cadena de conexión del cliente también (redis://:<password>@host:6379/0), o cambiarás una base de datos abierta por una rota.
Haz esto incluso para servicios que no están publicados. La defensa en profundidad significa que la segunda capa se mantiene cuando la primera falla.
\nDOCKER-USERA veces un puerto realmente tiene que ser de cara pública pero restringido por origen. La cadena a usar es DOCKER-USER — Docker garantiza que se ejecute antes de sus propias reglas de aceptación, y nunca la sobrescribe:
# solo 203.0.113.0/24 puede abrir nuevas conexiones al puerto 3000 del contenedor
sudo iptables -I DOCKER-USER 1 -p tcp --dport 3000 \\
-m conntrack --ctstate NEW ! -s 203.0.113.0/24 -j DROP
Probado en vivo en el puerto de Langfuse, desde un navegador en otra máquina:
\nhttp://<instance-ip>:3001 -> La interfaz de usuario de Langfuse se carga
ERR_CONNECTION_TIMED_OUT
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/netsec-docker-user-blocked-8e34c54fd3b4552806e49bf87aed7cfb.png\")
Figura 7. Misma URL, mismo firewall, una regla en la cadena correcta — y el puerto está finalmente cerrado. Nota la propia sugerencia de Chrome: \"Verificando el proxy y el firewall.\" Esta vez el firewall realmente es la respuesta.
\nMientras tanto, la API de Evolution en :8080, que deliberadamente dejamos sola, siguió respondiendo. La regla es quirúrgica, y funciona exactamente donde UFW no pudo.
iptables -I no es persistente. Usa iptables-persistent (netfilter-persistent save), o coloca la regla en una pequeña unidad de systemd que se ejecute después de docker.service. Una regla de firewall que desaparece al reiniciar es peor que ninguna, porque pensarás que estás protegido.
Puedes auditar y asegurar un host Docker multi-pila: prueba qué es alcanzable, enlaza o divide lo que no debería ser, autentica los backends, y filtra los puertos publicados en la única cadena que Docker respeta.
Ejecuta estos cuatro comandos en cualquier caja que poseas. Toman un minuto y te dicen más que cualquier diagrama de arquitectura:
\n# 1. ¿Qué está expuesto al mundo?
docker ps --format '{{.Names}}\\t{{.Ports}}' | grep '0.0.0.0'
# 2. ¿Están tus reglas de firewall incluso en la ruta? (Las cadenas de Docker antes de ufw = no lo están)
sudo iptables -L FORWARD -n --line-numbers | head -8
# 3. ¿Qué puede alcanzar un contenedor comprometido en su propia red?
docker exec <container> python3 -c \"import socket;s=socket.socket();s.settimeout(3);s.connect(('<svc>',<port>));print('alcanzado')\"
# 4. ¿Ese servicio de respaldo pide una contraseña?
docker exec <container> python3 -c \"
import socket;s=socket.socket();s.settimeout(4);s.connect(('redis',6379))
s.sendall(b'INFO server\\r\\n');print(s.recv(60))\"
| Hallazgo | Severidad | Solución |
|---|---|---|
| El aislamiento entre redes funciona | ✅ ninguno | nada — Docker ya hace esto |
| Cada servicio en una red, mutuamente alcanzable | ⚠️ medio | dividir por zona de confianza, internal: true |
Redis respondiendo sin AUTH | 🔴 alto | una línea: --requirepass |
ufw deny no aplicado a puertos publicados | 🔴 alto | enlazar a 127.0.0.1, o regla DOCKER-USER |
Bases de datos de respaldo en 127.0.0.1 (Langfuse) | ✅ ninguno | ya correcto — copia este patrón |
Ninguna de las soluciones tomó más de una línea de YAML. La parte costosa fue saber qué línea — y la única manera de saberlo es sondear tu propia caja en lugar de confiar en el diagrama en tu cabeza.
\nDOCKER-USER y nada cambióDos causas habituales. Primero, --dport debe ser el puerto del contenedor, no el publicado — el DNAT ya reescribió el destino para cuando DOCKER-USER ve el paquete (en nuestro caso 3000, no 3001). Segundo, las conexiones existentes no se ven afectadas: la coincidencia --ctstate NEW solo toca las nuevas, así que una pestaña de navegador ya abierta sigue funcionando.
sudo ufw allow 22/tcp antes de ufw enable, siempre. Si ya estás bloqueado, la mayoría de los proveedores te dan una consola serial/VNC — úsala para ejecutar ufw disable.
internal: true rompió la instalación de paquetes de mi contenedorEso es que está funcionando. Una red interna no tiene gateway, así que no hay salida en absoluto — sin pip install, sin DNS, sin llamar a una API externa. Los servicios de respaldo no deberían necesitar nada de eso; si un contenedor lo hace, también pertenece a la red de frontend.
El DNS de Compose solo resuelve nombres dentro de una red compartida. Si app y db están en diferentes redes sin nada en común, db no se resolverá. La app tiene que ser miembro de ambas, como en la Solución 2.
El endurecimiento de la red es la capa que evita que un contenedor comprometido se convierta en un host comprometido. Las siguientes capas, en el orden en que las haría: ejecutar contenedores como no-root (user: en compose) para que una ruptura comience con menos privilegios, y poner un proveedor de identidad frente a los puertos que debes exponer — una malla privada con\nNetBird más autenticación es la combinación natural con todo lo anterior.
![\"Hermes](\"https://development-wec.wiline.com/docs/es/assets/images/hermesagent-c76bbe81610ae2e70b0950e0f96bec8a.png\")
+En Parte 1 alojaste Hermes con\nmemoria persistente. Esta parte lo conecta al mismo bot de Telegram de la\nserie OpenClaw — el chat que\ntus usuarios ya conocen sigue funcionando exactamente como antes, solo que con un agente diferente respondiendo detrás. No hay un nuevo bot que anunciar, ni un canal al que migrar a la gente.
\n\nContinúa en la misma instancia WEC que la Parte 1. El gateway de Hermes ya está\ninstalado y funcionando como un servicio de usuario systemd — esta parte es configuración,\nno instalación. Cada comando y error a continuación es de la ejecución real.
El autoalojamiento solo vale la pena si no te ata al agente con el que comenzaste. El bot en sí — su nombre, su historial de chat, las personas que ya hablan con él — es el activo. El agente detrás de él es reemplazable. Cambiar OpenClaw por Hermes en el mismo bot prueba eso: misma puerta de entrada de Telegram, mismo hilo de conversación, nuevo cerebro.
\nhermes gateway setup
Selecciona Telegram de la lista de plataformas, luego elige cómo conectarlo:
\n◆ Telegram
¿Cómo te gustaría crear tu bot de Telegram?
[1] Automático (recomendado)
Escanea un código QR → confirma en Telegram → listo.
No se necesita copiar y pegar el token.
[2] Manual
Crea un bot a través de @BotFather tú mismo y pega el token.
Opción [1/2] [1]: 2
Crear un bot a través de @BotFather en Telegram
Token de bot de Telegram: **********************************************
✓ Token de Telegram guardado
Toma la opción 2 — la opción 1 crea un bot completamente nuevo a través de un código QR, lo cual derrota el propósito si estás reutilizando uno existente.
\nA continuación, el asistente pregunta quiénes pueden usar el bot:
\n🔒 Seguridad: Restringir quién puede usar tu bot
Para encontrar tu ID de usuario de Telegram:
1. Envía un mensaje a @userinfobot en Telegram
2. Te responderá con tu ID numérico (por ejemplo, 123456789)
IDs de usuario permitidos (separados por comas, deja vacío para acceso abierto):
Si no tienes tu ID a mano, déjalo en blanco y continúa — puedes restringir esto más tarde. Pero el aviso es engañoso: dejarlo vacío no abre el acceso por defecto. Los registros del gateway contaron la verdadera historia después del reinicio:
\nWARNING gateway.run: No se han configurado listas de permitidos de usuarios. Todos los usuarios no autorizados
serán denegados. Establece GATEWAY_ALLOW_ALL_USERS=true en ~/.hermes/.env para permitir
acceso abierto, o configura listas de permitidos de plataforma (por ejemplo,
TELEGRAM_ALLOWED_USERS=tu_id).
Una lista de permitidos vacía significa denegar a todos, no acceso abierto. Si deseas acceso abierto (bien para un bot personal, no para nada público), necesitas un paso más:
\necho 'GATEWAY_ALLOW_ALL_USERS=true' >> ~/.hermes/.env
El asistente también pregunta por un Canal Principal — donde Hermes entrega resultados de cron\ny mensajes entre plataformas. Déjalo en blanco también; puedes configurarlo más tarde\ndesde dentro del chat con /sethome.
Termina el asistente y deja que reinicie el gateway:
\n¿Reiniciar el gateway para recoger cambios? [Y/n]: Y
✓ Servicio de usuario reiniciado
![\"Terminal](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-gateway-setup-wizard-7293ce9021ee147b93bad2dcb7a72a53.png\")
\nFigura 1. Todo el asistente, de principio a fin — token, la advertencia de la lista de permitidos, y el reinicio.
Si agregaste GATEWAY_ALLOW_ALL_USERS después de que el asistente ya reinició\nuna vez (como arriba), reinicia de nuevo para que recoja el cambio en .env:
systemctl --user restart hermes-gateway.service
Envía un mensaje a tu bot. No a @BotFather — a tu bot, por el nombre de usuario que le diste\ncuando lo creaste. Es fácil confundirse: BotFather responde todo con\nsu propio menú de comandos fijo, así que si ves eso en lugar de una respuesta real,\nestás en el chat equivocado.
\nEl primer mensaje puede recibir un empujón del sistema en lugar de una respuesta de chat — eso es\nHermes notando que aún no hay un canal principal, no un fallo:
\n📬 No se ha establecido un canal principal para Telegram. Un canal principal es donde Hermes
entrega resultados de trabajos cron y mensajes entre plataformas.
Escribe /sethome para hacer de este chat tu canal principal, o ignora para omitir.
Envía otro mensaje y responde de verdad:
\n![\"Chat](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-telegram-verified-17c22677d5e1e6a1d6147099b58fdc53.png\")
\nFigura 2. El mismo bot de la serie OpenClaw, ahora respondiendo a través de Hermes.
Pregúntale algo con profundidad real, y entrega una respuesta estructurada real\n— no solo una respuesta estándar:
\n![\"Chat](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-telegram-sky-blue-139494c527c4075440bf7afa25c14039.png\")
\nFigura 3. Mismo agente, una pregunta real — explicación completa, no una línea.
Mismo bot, mismo historial de chat, nuevo agente.
\n\"No se han configurado listas de permitidos de usuarios. Todos los usuarios no autorizados serán denegados.\" —\ndejar el aviso de la lista de permitidos vacío no significa acceso abierto; significa\ndenegar a todos. Establece GATEWAY_ALLOW_ALL_USERS=true en ~/.hermes/.env y reinicia\nel gateway.
\"Conflicto de sondeo de Telegram... asegúrate de que solo una instancia de bot esté\nejecutándose\" — aparece durante unos segundos justo después de un reinicio, mientras\nlos servidores de Telegram terminan de liberar la sesión anterior. Intenta de nuevo y\nse limpia solo dentro de los 20 segundos; no se necesita acción a menos que siga\nrepitiéndose más allá del 5to intento, lo que significa que otro proceso realmente está sondeando\nel mismo token.
\nEl bot no responde en absoluto — verifica que estás enviando un mensaje al bot mismo, no\na @BotFather. BotFather siempre responde con su propia lista de comandos independientemente de\nlo que le envíes.
\nEl bot responde — lo siguiente es ponerlo en un horario: un informe matutino o un\nchequeo de salud del servicio entregado a este mismo chat, sin necesidad de sondeo.
\n![\"SearXNG\"](\"https://development-wec.wiline.com/docs/es/assets/images/searxng-mark-1b536bb949960590cea598d56becda08.png\")
+Supón que has construido un chatbot de soporte o un asistente RAG en WEC. Es sólido en tus documentos y\nen lo que el modelo ya sabe, pero pregúntale algo actual (\"¿cuál es la última\nversión de X?\", precios de hoy, un cambio reciente) y o bien adivina o te dice que su\nconocimiento está desactualizado. Para cualquier cosa que necesite estar al día, eso es una verdadera brecha.
\nWEC Inference ahora tiene una herramienta de búsqueda web integrada. Agrégala a una llamada normal\n/v1/chat/completions y el modelo puede buscar cosas en la web en vivo: la búsqueda\nse realiza en la propia infraestructura de WiLine (SearXNG), por lo que nada se envía a un proveedor de búsqueda de terceros. Vamos a probarlo.
Las llamadas llegan a https://inference.wiline.com/v1/chat/completions con tu clave API de WEC Inference,\nmodelo Qwen3.5-9B. No hay nada que instalar: la herramienta es parte de la API.
Una llamada normal, preguntando algo reciente:
\ncurl -sS https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen3.5-9B\",
\"messages\": [{\"role\": \"user\", \"content\": \"¿Cuál es la última versión estable de Docker Engine, y cuándo fue lanzada?\"}]
}'
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/websearch-without-aeaee1a5d9a326ccb92d56a8ec08bdc5.png\")
\nFigura 1. Sin herramienta, el modelo no se compromete a una versión — dice que su conocimiento está\nlimitado a su fecha de corte de entrenamiento y te señala las notas de la versión en su lugar.
La misma solicitud, más una herramienta web_search y tool_choice: auto:
curl -sS https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen3.5-9B\",
\"messages\": [{\"role\": \"user\", \"content\": \"¿Cuál es la última versión estable de Docker Engine, y cuándo fue lanzada?\"}],
\"tools\": [{
\"type\": \"function\",
\"function\": {
\"name\": \"litellm_web_search\",
\"description\": \"Buscar en la web información actual\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {\"query\": {\"type\": \"string\", \"description\": \"La consulta de búsqueda\"}},
\"required\": [\"query\"]
}
}
}],
\"tool_choice\": \"auto\"
}'
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/websearch-with-ae28b4b9dbd33effc4676a36ce37a4e0.png\")
\nFigura 2. Mismo modelo, misma pregunta, más la herramienta — ahora devuelve una versión concreta\ny fecha de lanzamiento obtenida de la web en vivo. El modelo decidió buscar, WEC ejecutó la consulta,\ny alimentó los resultados antes de responder.
Esa es toda la función: una herramienta en el cuerpo de la solicitud, respuestas actuales saliendo.
\nLa búsqueda web inyecta los resultados en tu aviso, por lo que una llamada con búsqueda cuesta más tokens que\nuna simple (en nuestra prueba, los tokens de aviso pasaron de ~26 a ~2,776). Mantén tool_choice: auto\npara que el modelo solo busque cuando realmente lo necesita — omitirá la búsqueda para preguntas que\nya puede responder.
auto se encarga de eso por ti.Dirígete a un asistente RAG o un chatbot y puede mantenerse actualizado sin que tengas que configurar un\nservicio de búsqueda separado.
\nUn agente que llama a herramientas hace dos cosas muy diferentes: razona (\"Debería buscar en la documentación\") y actúa (realmente llama a la herramienta). Cuando algo sale mal, la primera pregunta siempre es qué capa falló — ¿pensó mal o se rompió la acción? Un registro plano no puede responder eso. Un trazado puede.
\nEn este tutorial, construirás un pequeño agente que llama a herramientas en WEC Inference, lo instrumentarás con Langfuse para que cada paso de razonamiento y cada llamada a la herramienta se conviertan en un nodo inspeccionable, y luego depurarás dos fallos reales del árbol de trazado — incluyendo el peor tipo: una respuesta incorrecta y confiada que nunca lanza un error. Cada comando, error y captura de pantalla a continuación proviene de una ejecución real.
\n\nConstruido en una instancia de WEC con Docker, contra WEC Inference (Qwen3.5-122B) y un Langfuse autoalojado del\ntutorial de observabilidad. Las herramientas del agente incluyen el servicio RAG del\ntutorial de RAG — así que esta pieza une toda la serie. Todas las llamadas al modelo permanecen en WEC; nada sale hacia una API de terceros.
Las líneas punteadas son el punto: cada paso se informa a Langfuse, por lo que el razonamiento del agente y sus acciones se presentan como nodos separados e inspeccionables.
\nRequisitos previos: una instancia de WEC con Docker, una clave API de WEC Inference, un Langfuse en funcionamiento (clave pública + clave secreta, URL del host) y una herramienta que el agente pueda llamar — aquí el servicio RAG /ask. Todos los comandos se ejecutan en ~/agent-tracing.
Regla: nunca instrumentes antes de haber visto el comportamiento en bruto. Así que v1 hace lo mínimo — pregunta al modelo una cuestión con una definición de herramienta, y muestra lo que regresa. Configura el espacio de trabajo y la clave de WEC:
\nmkdir -p ~/agent-tracing && cd ~/agent-tracing
grep '^WEC_API_KEY=' ~/evolution-api/.env > .env
agent.py (v1):
import os, requests
WEC_URL = \"https://inference.wiline.com/v1/chat/completions\"
WEC_API_KEY = os.environ[\"WEC_API_KEY\"]
MODEL = \"Qwen3.5-122B\"
TOOLS = [{
\"type\": \"function\",
\"function\": {
\"name\": \"search_docs\",
\"description\": \"Buscar en la documentación de WEC para obtener una respuesta a una pregunta.\",
\"parameters\": {
\"type\": \"object\",
\"properties\": {\"query\": {\"type\": \"string\"}},
\"required\": [\"query\"],
},
},
}]
def call_model(messages):
r = requests.post(WEC_URL,
headers={\"Authorization\": f\"Bearer {WEC_API_KEY}\"},
json={\"model\": MODEL, \"messages\": messages, \"tools\": TOOLS, \"tool_choice\": \"auto\"},
timeout=120)
r.raise_for_status()
return r.json()[\"choices\"][0][\"message\"]
if __name__ == \"__main__\":
msg = call_model([{\"role\": \"user\", \"content\": \"¿Cómo creo una instancia de cómputo en WEC?\"}])
print(\"=== CAPA DE RAZONAMIENTO (lo que pensó) ===\")
print(msg.get(\"reasoning_content\") or \"(ninguno)\")
print(\"\\n=== CAPA DE ACCIÓN (lo que decidió hacer) ===\")
for tc in msg.get(\"tool_calls\") or []:
print(f\"herramienta: {tc['function']['name']} args: {tc['function']['arguments']}\")
Ejecuta esto en un contenedor (mismo patrón que el resto de la serie):
\nFROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir requests
COPY agent.py .
CMD [\"python\", \"agent.py\"]
services:
agent:
build: .
env_file: .env
docker compose run --rm --build agent
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/agent-reasoning-action-56b6f9e7c5b8aef031cd06c04187e291.png\")
\nFigura 1. WEC Inference devuelve las dos capas en una respuesta: reasoning_content\n(el pensamiento) y tool_calls (la decisión). No tenemos que inferir la división — la API nos la proporciona.
Qwen3.5-122B devuelve finish_reason: tool_calls con un array tool_calls adecuado, más un campo reasoning_content que contiene la cadena de pensamiento del modelo antes de actuar. Ese campo de razonamiento es exactamente lo que hace visible la división entre razonamiento y acción más adelante.
v1 decidió buscar pero no lo hizo. Ahora llama realmente a la herramienta (el servicio RAG /ask), alimenta el resultado de vuelta y deja que el modelo escriba la respuesta final. Agrega la herramienta + el bucle:
import json
RAG_URL = \"http://<tu-ip-vm>:8000/ask\" # el servicio RAG = nuestra única herramienta
def search_docs(query):
r = requests.post(RAG_URL, json={\"question\": query}, timeout=120)
r.raise_for_status()
return r.json()[\"answer\"]
def run(user_input):
messages = [{\"role\": \"user\", \"content\": user_input}]
while True:
msg = call_model(messages)
if not msg.get(\"tool_calls\"):
print(\"\\n=== RESPUESTA FINAL ===\\n\" + (msg.get(\"content\") or \"\"))
return msg.get(\"content\")
messages.append({\"role\": \"assistant\", \"content\": msg.get(\"content\") or \"\",
\"tool_calls\": msg[\"tool_calls\"]})
for tc in msg[\"tool_calls\"]:
args = json.loads(tc[\"function\"][\"arguments\"])
print(f\"[razonamiento] {(msg.get('reasoning_content') or '').strip()[:140]}\")
print(f\"[acción] {tc['function']['name']}({args})\")
result = search_docs(args[\"query\"])
print(f\"[resultado de la herramienta] {result[:140]}...\")
messages.append({\"role\": \"tool\", \"tool_call_id\": tc[\"id\"], \"content\": result})
docker compose run --rm --build agent
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/agent-loop-b09953660869437421c9222da3f9b135.png\")
\nFigura 2. El bucle completo — el modelo razona, llama a search_docs, obtiene el resultado de RAG y escribe una respuesta fundamentada. Funciona. Pero un terminal que funciona no te dice nada sobre si el razonamiento fue correcto — eso es lo que arreglamos a continuación.
El terminal aplana todo en un solo flujo. Langfuse convierte cada función en un nodo para que puedas ver la estructura. Reutiliza las claves de Langfuse del tutorial de observabilidad (mismo proyecto que tus trazas de RAG):
\ngrep -E '^LANGFUSE_(PUBLIC_KEY|SECRET_KEY|HOST)=' ~/rag-service/.env >> .env
Agrega el SDK (pip install ... langfuse) y decora tres funciones — esa es toda la instrumentación. @observe envuelve una función como un span; as_type=\"generation\" marca las llamadas LLM para que Langfuse capture modelo, tokens y costo:
from langfuse import observe, get_client
@observe(as_type=\"generation\")
def call_model(messages):
...
data = r.json()
get_client().update_current_generation(model=MODEL, usage_details=data.get(\"usage\"))
return data[\"choices\"][0][\"message\"]
@observe()
def search_docs(query):
...
@observe()
def run(user_input):
...
if __name__ == \"__main__\":
run(\"¿Cómo creo una instancia de cómputo en WEC?\")
get_client().flush() # script de corta duración: empujar trazas antes de salir
docker compose run --rm --build agent
Abre Langfuse → Trazado → Trazas. Lo primero que notarás: hay dos trazas por pregunta.
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/trace-list-3a0d985919db7d12160c4109ab85dede.png\")
\nFigura 3. Trazado distribuido, gratis: la traza run de tu agente y la propia traza ask del servicio RAG son separadas — cada servicio se instrumenta a sí mismo. Ver ambas es cómo sigues una solicitud a través de los límites del servicio.
Abre la más nueva run:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/trace-tree-green-c19c35d6b1ba42189355bdd0e79d96f8.png\")
\nFigura 4. El turno del agente como un árbol: run → call_model (decidir) → search_docs (actuar) → call_model (respuesta). Langfuse también capturó latencia, uso de tokens (801→306) y una puntuación de corrección — todo por tres decoradores.
Haz clic en el primer call_model y abre su salida:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/trace-reasoning-content-c5e9876f6e9a640d45e9f5f54c5594cc.png\")
\nFigura 5. La capa de razonamiento, capturada: reasoning_content (\"Debería buscar en la documentación de WEC…\") se encuentra justo al lado de los tool_calls que produjo. Este es el registro contra el que depuras.
Planta un error realista: la API de RAG espera {\"question\": ...}, pero es natural enviar {\"query\": ...} porque el parámetro de la herramienta se llama query. Una clave incorrecta:
sed -i 's/{\"question\": query}/{\"query\": query}/' agent.py
docker compose run --rm --build agent
Se bloquea:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/agent-422-crash-af97e2fe3ae5709ec3fe6d5f859095a0.png\")
\nFigura 6. El terminal te da un rastreo de pila — te dice dónde se rompió el código. No te dice si el agente pensó correctamente. Para eso, ve al trazado.
Abre la run fallida y haz clic en el span rojo search_docs:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/trace-error-span-ddca621bf15a8cc64c96371cd6a42e1a.png\")
\nFigura 7. Todo el diagnóstico en una imagen: call_model es verde (el razonamiento fue correcto — eligió correctamente buscar), search_docs es rojo, murió en 0.04s, y el panel muestra el 422 más la carga útil exacta que envió. Un fallo instantáneo es un rechazo, no un tiempo de espera — apuntando directamente a una mala solicitud.
Arregla la línea y confirma que está verde:
\nsed -i 's/{\"query\": query}/{\"question\": query}/' agent.py
docker compose run --rm --build agent
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/trace-fixed-green-c3b4677676dc40f861fca6dafe1594bb.png\")
\nFigura 8. De vuelta a verde — search_docs tiene éxito y se produce la respuesta final. Diagnosticaste y verificaste la corrección desde el trazado.
Ese fue el fallo ruidoso — se bloqueó, así que lo habrías atrapado eventualmente incluso sin un trazado. El peligroso es el siguiente.
\nLos agentes reales tienen más de una herramienta, y las decisiones interesantes ocurren cuando el modelo elige entre ellas. Agrega una herramienta get_pricing junto a search_docs, y enruta las llamadas a través de una tabla de despacho indexada por el nombre de la herramienta:
TOOLS = [
{\"type\": \"function\", \"function\": {
\"name\": \"search_docs\",
\"description\": \"Buscar en la documentación de WEC para preguntas sobre cómo hacer y configurar.\",
\"parameters\": {\"type\": \"object\", \"properties\": {\"query\": {\"type\": \"string\"}}, \"required\": [\"query\"]}}},
{\"type\": \"function\", \"function\": {
\"name\": \"get_pricing\",
\"description\": \"Obtener el precio de un recurso de WEC (por ejemplo, 'instancia de cómputo', 'almacenamiento en bloque', 'inferencia').\",
\"parameters\": {\"type\": \"object\", \"properties\": {\"resource\": {\"type\": \"string\"}}, \"required\": [\"resource\"]}}},
]
PRICES = {
\"instancia de cómputo\": \"$0.03 / hora-vCPU\",
\"almacenamiento en bloque\": \"$0.10 / GB-mes\",
\"inferencia\": \"$0.50 por 1M tokens\",
}
@observe()
def get_pricing(resource):
return PRICES.get(resource.lower().strip(), f\"No se encontró precio para '{resource}'.\")
TOOL_FUNCS = {\"search_docs\": search_docs, \"get_pricing\": get_pricing}
# en run(), despachar por la herramienta que el modelo realmente eligió:
for tc in msg[\"tool_calls\"]:
name = tc[\"function\"][\"name\"]
args = json.loads(tc[\"function\"][\"arguments\"])
print(f\"[acción] {name}({args})\")
result = str(TOOL_FUNCS[name](**args))
messages.append({\"role\": \"tool\", \"tool_call_id\": tc[\"id\"], \"content\": result})
Haz una pregunta de precio (run(\"¿Cuánto cuesta una instancia de cómputo en WEC?\")) y ejecútala. El agente debería elegir get_pricing, no search_docs:
![\"Trazado](\"https://development-wec.wiline.com/docs/es/assets/images/trace-two-tools-ba891f9c0ec4d99aea2e499dcbba3189.png\")
\nFigura 9. Selección genuina de herramientas: dado dos herramientas, el agente eligió get_pricing y respondió $0.03/vCPU-hora, Corrección 1.00. La elección en sí misma es ahora algo que puedes ver en el trazado.
Ahora un error que no se bloquea. Alguien refactoriza el despacho y codifica en duro la antigua herramienta única, olvidando la nueva — así que cada llamada ejecuta search_docs sin importar lo que eligió el modelo:
sed -i 's/result = str(TOOL_FUNCS\\[name\\](\\*\\*args))/result = str(search_docs(list(args.values())[0])) # ERROR/' agent.py
docker compose run --rm --build agent
[action] get_pricing({'resource': 'instancia de cómputo'})
=== RESPUESTA FINAL ===
Basado en la información de precios disponible, la categoría de instancia de cómputo más cara en WEC es $1,586.77. ...
Lee eso cuidadosamente. El modelo eligió get_pricing (correcto). La respuesta es confiada, detallada — y completamente incorrecta (el precio real es $0.03/vCPU-hora). No hay error, ni rastreo. Un registro se vería perfectamente saludable. Este es el modo de fallo que se envía a producción y miente silenciosamente a los usuarios.
El trazado es lo único que lo atrapa. Abre la run:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/trace-silent-failure-162a3ce9394bad7caca0e908be683b67.png\")
\nFigura 10. Tres indicios que un registro no puede mostrar: (1) el span ejecutado es search_docs — no hay span de get_pricing, a pesar de que el modelo lo eligió: decisión ≠ acción; (2) el nodo de razonamiento puntuó Corrección 0.00 — el juez LLM marcó automáticamente la respuesta incorrecta; (3) la salida muestra al modelo confundido por un resultado de herramienta que no coincidía con lo que pidió. Arregla el despacho de vuelta a TOOL_FUNCS[name](**args) y el precio es correcto de nuevo.
Instrumentaste un agente que llama a herramientas para que su razonamiento y sus acciones sean nodos de trazado separados e inspeccionables — y depuraste dos fallos reales desde el trazado: el ruido del choque y la respuesta silenciosa, confiada pero incorrecta que nunca revelaría un rastreo de pila.
get_client().flush() antes de que el proceso termine (ya está en v3).search_docs faltante. Solo las funciones decoradas con @observe se convierten en nodos —\ndecora la función, no el sitio de llamada.usage_details=data.get(\"usage\") a través de\nupdate_current_generation; sin ello, Langfuse no puede calcular el costo.tool_calls del modelo (lo que eligió)\ncontra los spans ejecutados (lo que realmente se ejecutó). Un desajuste es un error de despacho/ruteo — y una puntuación de corrección en el trazado lo marcará automáticamente.Ahora puedes ver a un agente pensar, actuar y fallar silenciosamente — y atraparlo. Apunta la misma instrumentación a un agente real de múltiples pasos, agrega puntuación de corrección automatizada en cada trazado, y tendrás una observabilidad de producción que resalta fallos silenciosos antes de que lo hagan tus usuarios.
\ncd ~/agent-tracing && docker compose down --rmi local
![\"WhatsApp\"](\"https://development-wec.wiline.com/docs/es/assets/images/whatsapp_logo-cc34546fcff90d36128c7230c48c496f.png\"){kind=logo}
++![\"Evolution\"](\"https://development-wec.wiline.com/docs/es/assets/images/0_hT2ECga7Z67dEbYz-62f9ab60d339ae8868fee46475e505bc.png\")
La mayoría de las guías de \"autoalbergar un asistente de IA para WhatsApp\" se detienen en \"el contenedor se inició\". Esta va hasta el final: despliegas una puerta de enlace de WhatsApp programable real (API de Evolution), luego escribes el puente tú mismo — las ~50 líneas que convierten un mensaje entrante en una respuesta de LLM y la envían de vuelta. Ese puente (webhook → modelo → respuesta) es el patrón reutilizable detrás de cada integración de chat-AI: SMS, Slack, Telegram, voz — cambia el canal, la forma es idéntica.
\nY porque esto es una construcción real, encontramos — y solucionamos — cada detalle: una imagen que movió a los editores, un bucle de versión de Baileys, un bucle de respuesta infinito, spam en grupos de chat, la nueva dirección LID de WhatsApp, y una genuina pared de entrega que la mayoría de los tutoriales pretenden que no existe. Cada comando, error y salida a continuación es de una ejecución real.
\n\nEvolution se vincula a un número de WhatsApp como un dispositivo compañero (como WhatsApp Web) — el bot actúa como esa cuenta y puede leer cada DM y grupo que recibe. Para una demostración en un número que controlas está bien; para cualquier cosa real, usa un número dedicado. Y consulta la limitación de entrega al final antes de construir esto en producción.
Cuatro contenedores: Evolution + su Postgres + Redis, y el puente que escribirás. El puente es el objetivo principal — todo lo demás es estándar.
\nRequisitos previos: una instancia WEC con Docker + Compose, una clave de API de Inferencia WEC (Inferencia → Claves de API), un número de WhatsApp para la demostración, y ~2 GB de espacio libre en disco.
\nEvolution necesita su propio Postgres y Redis. Le damos un conjunto dedicado en una red interna y exponemos solo el puerto de la API (8080). docker-compose.yml:
services:
evolution-api:
image: evoapicloud/evolution-api:v2.2.3
restart: unless-stopped
ports:
- \"8080:8080\"
env_file: .env
volumes:
- evolution_instances:/evolution/instances
depends_on: [evolution-postgres, evolution-redis]
logging:
driver: json-file
options: { max-size: \"50m\", max-file: \"3\" }
evolution-postgres:
image: postgres:17
restart: unless-stopped
environment:
POSTGRES_USER: evolution
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: evolution
volumes:
- evolution_pgdata:/var/lib/postgresql/data
evolution-redis:
image: redis:7
restart: unless-stopped
volumes:
- evolution_redis:/data
volumes:
evolution_instances:
evolution_pgdata:
evolution_redis:
El bloque logging: limita los logs del contenedor a 3×50 MB. Si lo omites, un contenedor ruidoso puede llenar el disco y hacer que la máquina se caiga — una lección aprendida de la manera difícil en esta VM. Configúralo antes de necesitarlo.
El archivo .env (secretos generados, URIs de conexión y — lo más importante — una versión de WhatsApp-Web de Baileys fijada):
cd ~/evolution-api && cat > .env << EOF
AUTHENTICATION_API_KEY=$(openssl rand -hex 24)
SERVER_URL=http://<tu-ip-vm>:8080
POSTGRES_PASSWORD=$(openssl rand -hex 16)
DATABASE_ENABLED=true
DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_URI=postgresql://evolution:\\${POSTGRES_PASSWORD}@evolution-postgres:5432/evolution?schema=public
CACHE_REDIS_ENABLED=true
CACHE_REDIS_URI=redis://evolution-redis:6379/0
CACHE_REDIS_PREFIX_KEY=evolution
CACHE_LOCAL_ENABLED=false
QRCODE_LIMIT=30
EOF
Levántalo:
\ndocker compose up -d
sleep 15
curl -s http://localhost:8080 | jq
{
\"status\": 200,
\"message\": \"¡Bienvenido a la API de Evolution, está funcionando!\",
\"version\": \"2.2.3\",
...
}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/wa-evolution-up-680a7f5fe9e4a450cacf33f1df5ed6f7.png\")
\nFigura 1. La pila está activa: Evolution responde en :8080 con su versión y estado.
(1) El editor se mudó. La imagen a la que la mayoría de las guías hacen referencia — atendai/evolution-api — ahora devuelve \"acceso denegado al pull / el repositorio no existe.\" La imagen actual es evoapicloud/evolution-api. La lista de etiquetas del antiguo repositorio aún se resuelve, lo que te envía por un camino sin salida; confirma con un pull fresco de hello-world que no está limitando la tasa.\n(2) Fija una etiqueta real. v2.1.1 (de un blog popular) nunca fue publicada — verifica https://hub.docker.com/v2/repositories/evoapicloud/evolution-api/tags y fija una que exista (usamos v2.2.3).
Establece tu clave de API como una variable de shell (cada solicitud la necesita en un encabezado apikey:):
APIKEY=$(grep '^AUTHENTICATION_API_KEY=' .env | cut -d= -f2)
Crea la instancia:
\ncurl -s -X POST http://localhost:8080/instance/create \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" \\
-d '{\"instanceName\":\"wec-demo\",\"integration\":\"WHATSAPP-BAILEYS\",\"qrcode\":true}' | jq '.instance'
Luego abre el Administrador integrado en http://<tu-ip-vm>:8080/manager, ingresa tu URL de servidor + clave de API, haz clic en wec-demo, y escanea el QR desde WhatsApp → Configuración → Dispositivos vinculados → Vincular un dispositivo. Confirma que está conectado:
curl -s http://localhost:8080/instance/fetchInstances -H \"apikey: $APIKEY\" \\
| jq '.[] | {name, connectionStatus}'
{ \"name\": \"wec-demo\", \"connectionStatus\": \"open\" }
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/wa-manager-connected-d91fda82b98c6238d0d747b47636645b.png\")
\nFigura 2. El panel de control del Administrador de Evolution una vez que la instancia se vincula: Conectado, con conteos de contactos, chats y mensajes en vivo.
Si la instancia nunca sale de conectando y los logs muestran ChannelStartupService reinicializándose cada pocos segundos con una línea Baileys version env: 2,3000,..., la versión de WhatsApp-Web fijada está obsoleta y WhatsApp rechaza el apretón de manos antes de que se genere un QR. Obtén la versión actual y fíjala, luego recrea:
curl -s \"https://raw.githubusercontent.com/WhiskeySockets/Baileys/master/src/Defaults/baileys-version.json\"
# {\"version\":[2,3000,1035194821]}
echo \"CONFIG_SESSION_PHONE_VERSION=2.3000.1035194821\" >> .env
docker compose up -d --force-recreate evolution-api
Ahora la parte que realmente escribes. Regla: nunca conectes la lógica antes de haber visto los datos reales. Así que v1 no hace nada más que imprimir lo que Evolution envía.
\nEl puente se ejecuta como otro contenedor en el mismo Compose, por lo que Evolution lo alcanza por nombre (http://bridge:8090) y el puente alcanza a Evolution en http://evolution-api:8080. Crea bridge/main.py:
from fastapi import FastAPI, Request
app = FastAPI()
@app.post(\"/webhook\")
async def webhook(request: Request):
data = await request.json()
print(\"=== WEBHOOK RECIBIDO ===\", flush=True)
print(data, flush=True)
return {\"received\": True}
flush=True es importanteSin él, la salida de print se almacena en búfer y nunca aparece en docker compose logs — estarás mirando un log vacío convencido de que está roto.
bridge/Dockerfile:
FROM python:3.12-slim
WORKDIR /app
RUN pip install --no-cache-dir fastapi uvicorn requests
COPY main.py .
CMD [\"uvicorn\", \"main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8090\"]
Agrega el servicio a docker-compose.yml (dentro de services:), luego constrúyelo:
bridge:
build: ./bridge
restart: unless-stopped
env_file: .env
depends_on: [evolution-api]
logging:
driver: json-file
options: { max-size: \"10m\", max-file: \"3\" }
docker compose up -d --build bridge
Ahora registra el webhook para que Evolution envíe mensajes al puente:
\ncurl -s -X POST \"http://localhost:8080/webhook/set/wec-demo\" \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" \\
-d '{\"webhook\":{\"enabled\":true,\"url\":\"http://bridge:8090/webhook\",\"webhookByEvents\":false,\"events\":[\"MESSAGES_UPSERT\"]}}' | jq '.enabled, .url'
Sigue los logs (docker compose logs -f bridge) y envíate un mensaje de WhatsApp. La carga real aparece:
{'event': 'messages.upsert', 'instance': 'wec-demo',
'data': {'key': {'remoteJid': '123456789012345@lid', 'fromMe': False, 'id': '...'},
'pushName': 'Contacto de Prueba',
'message': {'conversation': 'Oii'},
'messageType': 'conversation'},
'sender': '5511988887777@s.whatsapp.net', ...}
Tres cosas que ahora sabemos — y cada una impulsa el código siguiente:
\ndata.message.conversation (plano) o data.message.extendedTextMessage.text (citado)data.key.fromMe — True para nuestros propios mensajes (el guardia de bucle)remoteJid termina en @lid — el identificador de privacidad de WhatsApp, no un número de teléfono (esta es una saga; Paso 5)Dale al puente la clave de Inferencia WEC para que pueda llamar al modelo:
\necho \"WEC_API_KEY=<tu-clave-de-inferencia-wec>\" >> ~/evolution-api/.env
Ahora la lógica — main.py v2:
import os, requests
from fastapi import FastAPI, Request
app = FastAPI()
EVOLUTION_URL = \"http://evolution-api:8080\"
INSTANCE = \"wec-demo\"
EVOLUTION_APIKEY = os.environ[\"AUTHENTICATION_API_KEY\"]
WEC_API_KEY = os.environ[\"WEC_API_KEY\"]
WEC_URL = \"https://inference.wiline.com/v1/chat/completions\"
MODEL = \"Qwen2.5-3B-Instruct\"
def ask_llm(text: str) -> str:
r = requests.post(WEC_URL,
headers={\"Authorization\": f\"Bearer {WEC_API_KEY}\"},
json={\"model\": MODEL, \"messages\": [{\"role\": \"user\", \"content\": text}]},
timeout=60)
r.raise_for_status()
return r.json()[\"choices\"][0][\"message\"][\"content\"]
def send_whatsapp(number: str, text: str):
r = requests.post(f\"{EVOLUTION_URL}/message/sendText/{INSTANCE}\",
headers={\"apikey\": EVOLUTION_APIKEY, \"Content-Type\": \"application/json\"},
json={\"number\": number, \"text\": text}, timeout=60)
print(f\"ENVIAR -> {r.status_code}\", flush=True)
@app.post(\"/webhook\")
async def webhook(request: Request):
data = (await request.json()).get(\"data\", {})
key = data.get(\"key\", {})
if key.get(\"fromMe\"): # (1) GUARDIA DE BUCLE
return {\"skipped\": \"fromMe\"}
msg = data.get(\"message\", {}) # (2) extraer texto
text = msg.get(\"conversation\") or msg.get(\"extendedTextMessage\", {}).get(\"text\")
if not text:
return {\"skipped\": \"no text\"}
to = key.get(\"remoteJid\")
print(f\"ENTRADA {to}: {text}\", flush=True)
answer = ask_llm(text) # (3) pensar
send_whatsapp(to, answer) # (4) responder
print(f\"SALIDA {to}: {answer[:60]}...\", flush=True)
return {\"ok\": True}
La única línea que los principiantes siempre pasan por alto es (1) el guardia de bucle. Cuando el puente envía una respuesta, ese mensaje saliente dispara otro webhook MESSAGES_UPSERT con fromMe: true — sin el guardia, el puente se responde a sí mismo, para siempre. Reconstruye:
docker compose up -d --build bridge
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/wa-bridge-logs-53cb3cf64a3d62d69794ee3a0bf3742b.png\")
\nFigura 3. v2 en acción: un DM llega, el modelo responde, la respuesta se envía.
Ahora responde a DMs. Pero observa lo que sucede a continuación.
\nSigue los logs con el bot en vivo y verás que intenta responder a cada grupo en el que estás, incluidos grupos de promoción/spam, y Evolution se agota al enviarles — errores de inundación:
\nENTRADA 120363040812472138@g.us: *ALÔ CORREDORES 🏃 ... pechin.co/135449*
requests.exceptions.ReadTimeout: HTTPConnectionPool(host='evolution-api', port=8080): Read timed out.
Una cuenta compañera recibe todo. Solución: responder solo a DMs — los grupos terminan en @g.us:
to = key.get(\"remoteJid\", \"\")
if to.endswith(\"@g.us\") or \"broadcast\" in to: # Solo DMs
return {\"skipped\": \"not a DM\"}
Ahora la pared más sutil. Con los grupos filtrados, un DM real llega — pero la respuesta es rechazada:
\n{\"status\":400,\"error\":\"Bad Request\",\"response\":{\"message\":[
{\"exists\":false,\"jid\":\"123456789012345@lid\",\"name\":\"Contacto de Prueba\",\"number\":\"123456789012345@lid\"}]}}
![\"Evolution](\"https://development-wec.wiline.com/docs/es/assets/images/wa-lid-400-84cc0430abac7bdd5aa6d29cf1c100b5.png\")
\nFigura 4. La pared LID en los logs: el DM entrante llega como @lid, y la respuesta es rechazada con exists:false.
exists: false. Esta es la dirección LID de WhatsApp (un cambio de privacidad de 2025): los DMs entrantes llegan con un identificador @lid, y no puedes enviar de vuelta a un @lid — Evolution necesita el verdadero JID de teléfono @s.whatsapp.net. Sin embargo, el almacén de contactos de Evolution tiene ambos:
curl -s -X POST \"http://localhost:8080/chat/findContacts/wec-demo\" \\
-H \"apikey: $APIKEY\" -H \"Content-Type: application/json\" -d '{}' \\
| jq '[.[] | select(.pushName==\"Contacto de Prueba\")]'
[ { \"remoteJid\": \"123456789012345@lid\", \"pushName\": \"Contacto de Prueba\" },
{ \"remoteJid\": \"5511999999999@s.whatsapp.net\", \"pushName\": \"Contacto de Prueba\" } ]
![\"findContacts](\"https://development-wec.wiline.com/docs/es/assets/images/wa-findcontacts-275c01bee94ec0da990f2cdd0ec6acf2.png\")
\nFigura 5. Evolution almacena ambas identidades para la misma persona — el @lid y el verdadero JID de teléfono. Esa es la clave para resolver la dirección de respuesta.
Así que resolvemos el @lid al número de teléfono antes de responder. Agrega un resolvedor y úsalo:
def resolve_number(remote_jid: str, push_name: str):
if remote_jid.endswith(\"@s.whatsapp.net\"):
return remote_jid.split(\"@\")[0]
# LID: encontrar el número real del contacto haciendo coincidir el nombre
contacts = requests.post(f\"{EVOLUTION_URL}/chat/findContacts/{INSTANCE}\",
headers={\"apikey\": EVOLUTION_APIKEY, \"Content-Type\": \"application/json\"},
json={}, timeout=30).json()
for c in contacts:
if c.get(\"pushName\") == push_name and c.get(\"remoteJid\", \"\").endswith(\"@s.whatsapp.net\"):
return c[\"remoteJid\"].split(\"@\")[0]
return None
En el manejador, resuelve antes de enviar:
\n number = resolve_number(to, data.get(\"pushName\", \"\"))
if not number:
return {\"skipped\": \"unresolved lid\"}
...
send_whatsapp(number, answer)
Ahora ENVIAR -> 201. (Hacer coincidir por nombre es un heurístico — dos contactos que comparten un nombre colisionarían; la producción mantiene un mapa adecuado LID→teléfono. Pero funciona, y es el estado honesto del soporte LID de Evolution en v2.2.3.)
Los LLM emiten Markdown (**negrita**, [texto](url)), pero WhatsApp tiene su propio formato: la negrita es *asterisco simple*, y los enlaces de Markdown no se renderizan. Así que **Compute** aparece con asteriscos literales. Traduce la salida del modelo antes de enviar, y agrega las fuentes del RAG como URLs simples:
import re
def to_whatsapp(md: str) -> str:
md = re.sub(r\"\\*\\*(.+?)\\*\\*\", r\"*\\1*\", md) # **negrita** -> *negrita*
md = re.sub(r\"\\[([^\\]]+)\\]\\((https?://[^)]+)\\)\", r\"\\1 (\\2)\", md) # [t](url) -> t (url)
md = re.sub(r\"(?m)^#{1,6}\\s*\", \"\", md) # eliminar encabezados #
return md
Verificado contra una respuesta real — exactamente lo que WhatsApp renderizará:
\nPara crear una instancia de computación en WiLine Edge Cloud (WEC), sigue estos pasos:
1. Inicia sesión en WiLine Edge Cloud.
2. En la barra lateral, haz clic en *Compute*.
3. Selecciona *Instances*.
4. Haz clic en el asistente \"Launch Virtual Machine\" para comenzar el proceso de despliegue.
_Fuentes:_
https://wec.wiline.com/docs/cloud_portal/platform/compute/instances/compute_instance/
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/wa-formatted-output-766cfd620ca72685d8f37110da283d56.png\")
\nFigura 6. La salida del modelo después de to_whatsapp(): negrita con asterisco simple, enlaces simples, fuentes añadidas.
Todo hasta ahora usa el modelo en bruto, así que una pregunta de WEC obtiene una respuesta general. Para hacer que responda desde tu documentación, cambia ask_llm para llamar al servicio RAG de la serie de evals — una función, nada más cambia:
RAG_URL = \"http://<tu-ip-vm>:8000/ask\"
def ask_llm(text: str) -> str:
r = requests.post(RAG_URL, json={\"question\": text}, timeout=120)
r.raise_for_status()
d = r.json()
answer = to_whatsapp(d[\"answer\"])
sources = d.get(\"sources\", [])[:2]
if sources:
answer += \"\\n\\n_Fuentes:_\\n\" + \"\\n\".join(sources)
return answer
Ese es el beneficio del patrón de puente: cambia el cerebro, mantén la plomería. Ahora WhatsApp responde a preguntas de WEC desde la documentación real, con fuentes:
\n![\"WhatsApp](\"https://development-wec.wiline.com/docs/es/assets/images/wa-bridge-reply-bf0eaa9a06721ee1396cbf44fd96ae3a.png\")
\nFigura 7. Un mensaje real en → el puente → RAG sobre la documentación de WEC → una respuesta fundamentada entregada en WhatsApp, fuentes incluidas.
Has autoalbergado una puerta de enlace programable de WhatsApp y escribiste el puente que lo convierte en un asistente de IA — webhook entrante, modelo saliente, respuesta de vuelta — fundamentado en tu propia documentación.
Aquí está la parte que otros tutoriales no te dirán. Incluso con ENVIAR -> 201, las respuestas a una cuenta migrada a LID frecuentemente llegan como \"Esperando este mensaje\" en el teléfono del destinatario — WhatsApp aceptó el texto cifrado pero ningún dispositivo puede descifrarlo. Es una limitación conocida del dispositivo compañero de Baileys, y el despliegue de LID de WhatsApp lo empeora.
Lo que observamos, honestamente:
\n\"Esperando este mensaje\" regresa — aunque cada envío aún informa 201.Así que el puente es correcto de extremo a extremo; el transporte no oficial de Baileys es el eslabón débil. Si estás construyendo esto para algo real:
\nEvolution brilla para automatización saliente a números que controlas (notificaciones, alertas, flujos). Como asistente de IA bidireccional en una cuenta personal de LID, trata la entrega como un esfuerzo mejor.
\nacceso denegado al pull en atendai/evolution-api → imagen movida a evoapicloud/evolution-api.conectando, bucle de reinicio → versión de Baileys obsoleta; fija CONFIG_SESSION_PHONE_VERSION.fromMe.@g.us; responde solo a DMs.ENVIAR -> 400 exists:false ...@lid → resuelve el LID al JID de teléfono a través de findContacts.**asteriscos** en respuestas → traduce Markdown al formato de WhatsApp.cd ~/evolution-api && docker compose down # agrega -v para también borrar la DB/sesión
Desvincula el dispositivo en WhatsApp → Dispositivos vinculados si has terminado.
\nHas construido el patrón de puente reutilizable — webhook → resolver → modelo → respuesta. Apúntalo a un cerebro diferente, a un canal diferente, o agrega herramientas. Si deseas un agente de IA en WhatsApp sin las advertencias de Baileys, el canal nativo de WhatsApp de OpenClaw es el camino gestionado; para respuestas fundamentadas en documentos, la serie de evals y observabilidad construye el servicio RAG en el que se conecta este tutorial.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/whatsapp-ai-assistant-evolution-api/", "title": "Crea un asistente de IA para WhatsApp desde cero con Evolution y la API de WEC", "summary": "Autoalberga una puerta de enlace programable de WhatsApp (API de Evolution) y escribe el puente de ~50 líneas que lo convierte en un asistente de IA: webhook entrante, LLM saliente, respuesta de vuelta. Cada detalle es real: la imagen que movió a los editores, el bucle de la versión de Baileys, el guardia de bucle, el spam en grupos, la dirección LID de WhatsApp y la pared de entrega de la que nadie te advierte.", "date_modified": "2026-07-21T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "whatsapp", "evolution-api", "docker", "inferencia" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/add-whatsapp-channel-openclaw/", "content_html": "![\"OpenClaw\"](\"https://development-wec.wiline.com/docs/es/assets/images/openclaw-wordmark-003352a1a7f02afc3bd877ae6f2dc175.png\")
+Telegram (Parte 3) le dio a tu agente un bot.\nWhatsApp le da una línea telefónica — la aplicación que ~3 mil millones de personas ya usan, accesible sin fricción. Una advertencia que vale la pena entender desde el principio: WhatsApp no tiene cuenta de bot, así que OpenClaw se vincula a un número real como un dispositivo compañero (como WhatsApp Web) y el agente actúa como esa cuenta. Cada comando y error a continuación proviene de una ejecución real.
\n\nCualquiera envía un mensaje al número; la puerta de enlace — vinculada como un dispositivo compañero — lo procesa a través de tu modelo y responde desde el número mismo. Sin puertos de entrada, sin cuenta de bot.
\n\nRequisitos previos: Partes 1–4 completadas (OpenClaw en ~/openclaw), una cuenta de WhatsApp en tu\nteléfono, ~1 GB de espacio libre en disco. Todos los comandos se ejecutan en ~/openclaw.
OpenClaw trata las aplicaciones de mensajería como canales; WhatsApp es uno de primera clase:
\ndocker compose run --rm openclaw-cli channels add --channel whatsapp
Plugin de WhatsApp instalado
Cuenta de WhatsApp \"default\" añadida.
requires plugin API >=2026.7.1? Estás en una versión anterior de OpenClaw — actualiza primero.El canal de WhatsApp es un plugin restringido a versiones más nuevas:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/wa-version-wall-db236509ca6e250b19147327473e0932.png\")
\nFigura 1. La pared de versión — el plugin de WhatsApp necesita OpenClaw ≥2026.7.1.
Haz una copia de seguridad, descarga, recrea y confirma que tus canales existentes sobrevivieron (:latest no\nse actualiza automáticamente — debes descargar deliberadamente):
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak-$(date +%Y%m%d)
docker compose pull openclaw-gateway
docker compose run --rm openclaw-cli --version # espera 2026.7.1+
docker compose up -d --force-recreate openclaw-gateway
docker compose run --rm openclaw-cli channels status # Telegram debería seguir conectado
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/wa-version-check-b1b98be0f2990d46e5686130b2722d3b.png\")
\nFigura 2. Después de descargar, la imagen informa 2026.7.1 — se cumple el requisito.
Luego vuelve a ejecutar el channels add anterior.
Verifica el estado y el canal está detenido con un error críptico:
\n![\"WhatsApp](\"https://development-wec.wiline.com/docs/es/assets/images/wa-trust-error-7a8033b008450d82190f783b79998f71.png\")
\nFigura 3. detenido — un plugin no confiable no puede usar openKeyedStore, por lo que el canal no se iniciará.
Esa es una característica de seguridad: OpenClaw aísla los plugins de terceros, y uno no confiable no puede usar openKeyedStore (el almacenamiento que WhatsApp necesita para su sesión). Confía en él —\nincluye cualquier otro plugin no empaquetado que ya esté cargando (aquí codex) para que no lo bloquees\n— y recrea:
docker compose run --rm openclaw-cli config set \\
--batch-json '[{\"path\":\"plugins.allow\",\"value\":[\"codex\",\"whatsapp\"]}]'
docker compose up -d --force-recreate openclaw-gateway
docker compose run --rm openclaw-cli channels status
![\"plugins.allow](\"https://development-wec.wiline.com/docs/es/assets/images/wa-trust-fix-503842c5815cf95dc4bde07dc3b4a6ee.png\")
\nFigura 4. Confiado — plugins.allow ahora lista whatsapp (y codex).
El reinicio es importante — la puerta de enlace lee plugins.allow antes de inicializar el\nplugin. Ahora está en funcionamiento:
![\"WhatsApp](\"https://development-wec.wiline.com/docs/es/assets/images/wa-connected-d4ec6a75486c355d24570487f62305c8.png\")
\nFigura 5. En vivo — WhatsApp funcionando, conectado, saludable, y Telegram sigue activo.
docker compose run --rm openclaw-cli channels login
Escanea el QR del terminal desde WhatsApp → Configuración → Dispositivos Vinculados → Vincular un Dispositivo.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/wa-qr-544d7332e052ce0469c77d7e60fec42a.png\")
\nFigura 6. Escanea para vincular; ✅ Vinculado después del reinicio maneja la reconexión del código 515.
código 515 es normalWhatsApp obliga a una reconexión justo después del emparejamiento; OpenClaw lo maneja automáticamente. Este\nes exactamente el lugar donde las configuraciones manuales se quedan atrapadas en un bucle — aquí simplemente funciona.
Desde otro teléfono, envía un mensaje al número:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/wa-reply-08f4125cb353af3cff9a2418928be7ec.png\")
\nFigura 7. Una pregunta enviada, la respuesta del agente — enviada desde el número, como la cuenta.
Responde — pero nota que responde desde tu número, como tú. Eso es el modo compañero:\nel agente es la cuenta. Genial para un asistente personal, y la razón de la advertencia\na continuación.
\nTu agente de OpenClaw responde en WhatsApp — de forma nativa, sin puente, sin cuenta de bot.
Procesa cada DM y grupo que recibe la cuenta (Escuchando ... DM + todos los grupos). Para cualquier cosa real: vincula un número dedicado (una SIM prepago barata — los números virtuales son a menudo rechazados), y establece una lista de permitidos antes de exponerlo.
Estaciona el canal cuando termines de probar (Telegram sigue funcionando; tu enlace permanece guardado):
\ndocker compose run --rm openclaw-cli config set \\
--batch-json '[{\"path\":\"channels.whatsapp.accounts.default.enabled\",\"value\":false}]'
docker compose up -d --force-recreate openclaw-gateway
openKeyedStore solo está disponible para plugins confiables — el canal se instala pero permanece\ndetenido. Agrega el id a plugins.allow y recrea la puerta de enlace (Paso 2). Un cambio de configuración en vivo no es suficiente una vez que ya ha fallado al iniciar.código 515 — reinicio normal después del emparejamiento. Si nunca se estabiliza, elimina\nentradas obsoletas en WhatsApp → Dispositivos Vinculados y escanea un QR nuevo.Parte 5 completada — tu agente llega a Telegram y WhatsApp desde una caja privada y reforzada.
\ndocker compose run --rm openclaw-cli channels remove --channel whatsapp
docker compose restart openclaw-gateway
Y desvincula el dispositivo en WhatsApp → Dispositivos Vinculados si has terminado.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/add-whatsapp-channel-openclaw/", "title": "Agregar un canal de WhatsApp a OpenClaw", "summary": "Coloca tu agente autoalojado en WhatsApp. Agrega el canal, confía en el plugin, escanea un QR — y entiende por qué un enlace de compañero hace que el agente actúe como tu cuenta. Cada comando y error de una ejecución real.", "date_modified": "2026-07-20T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "openclaw", "whatsapp", "chatbot" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/deepeval-regression-testing-wiline-inference/", "content_html": "Nuestro análisis de economía de tokens de GPT-5.6 terminó con un desafío:\nlas promesas de referencia son una hipótesis, no una razón — ejecuta la evaluación en tu carga de trabajo antes de que\ncreas en un reclamo de \"menos tokens por tarea\". Este tutorial es nosotros siguiendo nuestro propio consejo.
\nTomamos el asistente de documentos RAG de parte 5,\nlo envolvemos en una suite de regresión DeepEval — en contenedor, juzgada por gemma4 en la API de\nInferencia WEC, sin dependencia de OpenAI — y luego usamos esa suite para responder a una pregunta genuinamente abierta:\n¿deberíamos cambiar el modelo de generación del servicio? Qwen2.5-3B-Instruct (actual) vs\ngemma4 (candidato), tasa de aprobación y tokens por tarea, medidos cara a cara.
Spoiler: la evaluación nos salvó de una migración innecesaria. Y en el camino encontramos cuatro fallos reales\nde producción: un espiral mortal por disco lleno, una condición de carrera en el arranque, una trampa de variable de Docker Compose\nque evaluó silenciosamente el modelo incorrecto, y la solución que hace que esa clase de\nerror sea imposible. Cada comando, número y error a continuación proviene de una ejecución real.
\n\nTres decisiones de diseño desde el principio:
\ndocker compose run eval en ambos lugares. (Nuestro primer intento fue un\nvenv. Murió por un disco lleno antes de instalar nada; consulta Solución de problemas.)tests.csv de promptfoo incrusta cada\nhecho de referencia dentro de una cadena llm-rubric — una expresión regular lo extrae. Tus datos de evaluación\nsobreviven a tu marco de evaluación.rag-api respondiendo en :8000, eval/tests.csv presente).df -h / ahora. El nuestro leía 100% y la historia de por qué\nestá en Solución de problemas.Nunca evalúes un servicio que no hayas probado manualmente primero:
\ncurl -s -X POST localhost:8000/ask \\
-H \"Content-Type: application/json\" \\
-d '{\"question\": \"¿Cómo creo una instancia de cómputo en WEC?\"}' | python3 -m json.tool
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-smoke-test-98290b8dda1f2a3f5e57a82fa43c2dfa.png\")
\nFigura 1. El sistema bajo prueba, vivo: /ask responde del corpus de documentos de WEC y cita\nsus fuentes. Nunca evalúes un servicio que no hayas probado manualmente primero.
eval/Dockerfile:
FROM python:3.12-slim
WORKDIR /eval
RUN pip install --no-cache-dir deepeval==3.*
# El código de la suite se monta en tiempo de ejecución para que las ediciones no necesiten una reconstrucción
CMD [\"deepeval\", \"test\", \"run\", \"test_rag_regression.py\"]
Agrega el servicio a docker-compose.yml dentro del bloque services: (el archivo de la parte 5 termina\ncon una sección volumes: de nivel superior — agregar ciegamente coloca tu servicio en el bloque incorrecto;\ndocker compose config --quiet lo detecta):
eval:
build: ./eval
profiles: [\"eval\"]
env_file: .env
environment:
RAG_API_URL: http://rag-api:8000
volumes:
- ./eval:/eval
depends_on:
- rag-api
profiles: [\"eval\"] lo mantiene fuera de un docker compose up normal — solo se ejecuta cuando lo pides.\nConstruyelo:
docker compose --profile eval build eval
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-eval-build-58810296ef048e28edf1a9f90735d2eb.png\")
\nFigura 2. El ejecutor de evaluación se construye en ~42s: python:3.12-slim más DeepEval 3.x. Esta imagen exacta\nes la que CI ejecuta más tarde — sin venv, sin desviaciones.
Las métricas de LLM-como-juez de DeepEval quieren una clave de OpenAI. No tenemos una y no queremos una.\neval/wec_judge.py:
\"\"\"Juez personalizado de DeepEval respaldado por WiLine Inference (compatible con OpenAI).\"\"\"
import os
from openai import OpenAI
from deepeval.models.base_model import DeepEvalBaseLLM
WEC_BASE_URL = os.getenv(\"WEC_BASE_URL\", \"https://inference.wiline.com/v1\")
class WECJudge(DeepEvalBaseLLM):
def __init__(self, model: str | None = None):
self.model_name = model or os.getenv(\"JUDGE_MODEL\", \"gemma4\")
self.client = OpenAI(
base_url=WEC_BASE_URL,
api_key=os.environ[\"WEC_API_KEY\"],
)
def load_model(self):
return self.client
def generate(self, prompt: str) -> str:
response = self.client.chat.completions.create(
model=self.model_name,
messages=[{\"role\": \"user\", \"content\": prompt}],
temperature=0,
)
return response.choices[0].message.content
async def a_generate(self, prompt: str) -> str:
return self.generate(prompt)
def get_model_name(self):
return f\"WEC/{self.model_name}\"
Prueba que responde desde dentro de la red de compose antes de construir nada sobre ello:
\ndocker compose --profile eval run --rm eval \\
python -c \"from wec_judge import WECJudge; j = WECJudge(); print('el juez dice:', j.generate('Responde exactamente: juez WEC en línea'))\"
el juez dice: juez WEC en línea
![\"Verificación](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-judge-online-c5844beb37c759e19f698f4ea927ec8c.png\")
\nFigura 3. \"juez WEC en línea\" — gemma4 respondiendo a través del contenedor, en la misma red de compose que el servicio que juzgará. Sin clave de OpenAI en ninguna parte de la pila.
Una advertencia honesta que llevamos a través del resto de este tutorial: en la comparación de modelos más adelante,\ngemma4 es tanto juez como concursante. La mitigación es estructural: el juez solo compara\nrespuesta frente a hecho de referencia, nunca \"qué modelo escribió esto\" — y observamos sus veredictos en los\ncasos conocidos difíciles para favoritismo. (No mostró ninguno: cada caso en el que falló gemma4 es un caso en el que también falla Qwen.)
\nPuedes apuntar las métricas juzgadas por LLM de DeepEval a cualquier punto final compatible con OpenAI. Tus veredictos de evaluación — preguntas, respuestas, razonamiento — nunca salen de tu infraestructura.
El /ask de la parte 5 devolvió answer y sources — y desechó el uso de tokens que venía con cada finalización. Para la economía de tokens lo necesitamos, y para el A/B necesitamos que el modelo sea intercambiable. Tres variables de entorno y dos campos de respuesta en app/main.py (montado en volumen; uvicorn\nrecarga en caliente, sin reconstrucción):
# El modelo de generación es configurable para que la suite de evaluación pueda A/B modelos.
# Los valores predeterminados preservan la configuración del tutorial-5.
GEN_MODEL = os.getenv(\"GEN_MODEL\", \"Qwen2.5-3B-Instruct\")
GEN_BASE_URL = os.getenv(\"GEN_BASE_URL\", \"https://inference.wiline.com/v1\")
GEN_API_KEY = os.getenv(\"GEN_API_KEY\", os.environ[\"WEC_API_KEY\"])
generate() ahora también devuelve resp.usage, y /ask informa ambos:
{
\"answer\": \"Para ver tus estados de cuenta ...\",
\"sources\": [\"...\"],
\"model\": \"Qwen2.5-3B-Instruct\",
\"usage\": {
\"prompt_tokens\": 1238,
\"completion_tokens\": 122,
\"total_tokens\": 1360
}
}
![\"/ask](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-ask-usage-b1a5b036ae1af43fa37d1c91c9d2f092.png\")
\nFigura 4. Los nuevos campos model y usage: 1,238 tokens de prompt + 122 tokens de finalización para una\npregunta de facturación. Este es el número del debate sobre economía de tokens.
Ese bloque usage es el número del marketing de GPT-5.6 — medido en tu carga de trabajo,\npor solicitud. Pasa la variable a través de compose (GEN_MODEL: ${GEN_MODEL:-Qwen2.5-3B-Instruct}\nbajo rag-api's environment:) y recuerda esta línea — vuelve a morder en\nSolución de problemas.
eval/test_rag_regression.py. Lee el tests.csv de la parte 5, extrae el hecho de referencia de\ncada rúbrica de promptfoo, pregunta al servicio en vivo, registra el uso de tokens y afirma una métrica de corrección\nde GEval juzgada por WECJudge:
\"\"\"Suite de regresión DeepEval para el servicio RAG de documentos WEC.
Reutiliza el conjunto dorado de promptfoo (tests.csv) del tutorial anterior:
el hecho de referencia se analiza de cada cadena llm-rubric.
\"\"\"
import csv, json, os, re
import pytest
import requests
from deepeval import assert_test
from deepeval.metrics import GEval
from deepeval.test_case import LLMTestCase, LLMTestCaseParams
from wec_judge import WECJudge
RAG_API_URL = os.getenv(\"RAG_API_URL\", \"http://rag-api:8000\")
USAGE_LOG = os.getenv(\"USAGE_LOG\", \"usage_log.jsonl\")
MAX_CASES = int(os.getenv(\"MAX_CASES\", \"0\")) # 0 = todos
FACT_RE = re.compile(r'Hecho de referencia de los documentos oficiales: \"(.*?)\"')
def load_cases():
with open(\"tests.csv\", newline=\"\") as f:
for row in csv.DictReader(f):
m = FACT_RE.search(row[\"__expected\"])
yield row[\"question\"], (m.group(1) if m else \"\")
CASES = list(load_cases())
if MAX_CASES:
CASES = CASES[:MAX_CASES]
judge = WECJudge()
correctness = GEval(
name=\"Correctness\",
criteria=(
\"La salida real debe abordar correctamente la pregunta de entrada y no debe \"
\"contradecir el hecho de referencia dado como salida esperada. Diferente redacción \"
\"está bien. Fallar solo si la respuesta es incorrecta, contradice el hecho de referencia, \"
\"o no responde a la pregunta.\"
),
evaluation_params=[
LLMTestCaseParams.INPUT,
LLMTestCaseParams.ACTUAL_OUTPUT,
LLMTestCaseParams.EXPECTED_OUTPUT,
],
model=judge,
threshold=0.5,
)
@pytest.mark.parametrize(
\"question,reference\", CASES, ids=[q[:50] for q, _ in CASES]
)
def test_rag_regression(question, reference):
r = requests.post(f\"{RAG_API_URL}/ask\", json={\"question\": question}, timeout=120)
r.raise_for_status()
data = r.json()
expect = os.getenv(\"EXPECT_MODEL\")
assert not expect or data[\"model\"] == expect, (
f\"la suite esperaba {expect} pero el servicio está ejecutando {data['model']}\"
)
with open(USAGE_LOG, \"a\") as f:
f.write(json.dumps({
\"model\": data.get(\"model\"),
\"question\": question,
**data.get(\"usage\", {}),
}) + \"\\n\")
assert_test(
LLMTestCase(
input=question,
actual_output=data[\"answer\"],
expected_output=reference,
),
[correctness],
)
(Esa afirmación EXPECT_MODEL no estaba en la primera versión. Existe debido a un error que encontrarás en un momento.)
Primera ejecución, limitada a 5 casos para fallar rápido:
\ndocker compose --profile eval run --rm \\
-e MAX_CASES=5 -e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
eval
4 de 5 pasaron en 2:37 — y tanto los pases como la falla valen la pena leer. La\nfalla (\"¿Cuál es el punto de partida para la facturación?\", puntuación 0.3) no es un error del servicio: la\nrespuesta era factualmente correcta, pero la etiqueta dorada es un título de sección (\"Cómo Funciona la Facturación\")\ny el juez quería que se nombrara. Recuerda este caso — parpadea entre pasar y fallar durante todo el tutorial, y ese parpadeo se convierte en un hallazgo. Mientras tanto, en \"número total de eventos\"\nel juez puntuó un 0.6, un pase límite con el razonamiento exactamente correcto (el servicio\ndescribió la característica en lugar de dar pasos). Veredictos matizados de un juez autoalojado —\nla cosa que la gente asume que necesitas modelos de clase GPT-4 para.
\n![\"Primera](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-first-run-cabfff276f20b525d0c7c20bb52c1a6a.png\")
\nFigura 5. Primera ejecución: 4 de 5 pasaron en 2:37, cada veredicto con razonamiento escrito del\njuez gemma4 — incluyendo la única falla, un veredicto estricto sobre una etiqueta de título de sección\nen lugar de un error del servicio.
Nota la línea de resumen de DeepEval: costo de token: Ninguno. No puede calcular el precio de un juez autoalojado — que es\nexactamente por qué la suite escribe su propio usage_log.jsonl.
![\"Registro](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-usage-log-65042f9bd05652b9ff3814cd52b37270.png\")
\nFigura 6. La contabilidad propia de la suite: una línea JSON por pregunta — modelo, prompt, finalización,\ntotal — los datos en bruto de cada comparación en este tutorial se construyen a partir de esto.
Tienes una suite de regresión que califica un servicio RAG en vivo — reutilizando el conjunto dorado del último tutorial\nsin cambios, juzgada por un modelo autoalojado, con contabilidad de tokens por pregunta que el marco\nmismo no puede proporcionarte.
La pregunta que la suite existe para responder: nuestro servicio genera con Qwen2.5-3B-Instruct —\n¿debería hacerlo? gemma4 es más nuevo, bien considerado, ya está en el catálogo de WEC. Se siente como una mejora.\nSe siente. Vamos a medir.
\nLínea base, todos los 16 casos:
\ndocker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e USAGE_LOG=usage_qwen.jsonl \\
eval
14/16 (87.5%) en 8:50. Las dos fallas son artefactos de etiqueta, no errores de RAG: los hechos dorados\nde la parte 5 son títulos de sección (\"Cómo Funciona la Facturación\"), y el juez penalizó respuestas que eran\nfactualmente correctas pero no repetían el título; y mp3 frente a la etiqueta audio/mpeg — el mismo hecho en\ndos niveles de abstracción, dictaminado como una contradicción. Lee tus fallas antes de confiar en tu tasa de aprobación. Dejamos ambas: son una deuda de etiqueta honesta, y se convierten en nuestro canario de favoritismo del juez en el A/B.
![\"Línea](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-qwen-baseline-5b61265199e0d615241bbbfdb30d7a81.png\")
\nFigura 7. La línea base: 87.5% en 8:50. Ambas fallas son artefactos de etiqueta, no errores de RAG —\nlee tus fallas antes de confiar en tu tasa de aprobación.
Desafiante — misma suite, una variable de entorno (prefíjela en cada comando de compose; Solución de problemas\nexplica por qué en sangre):
\nGEN_MODEL=gemma4 docker compose up -d rag-api
until curl -sf localhost:8000/health > /dev/null; do echo \"esperando...\"; sleep 3; done
curl -s -X POST localhost:8000/ask -H \"Content-Type: application/json\" -d '{\"question\": \"ping\"}' \\
| python3 -c \"import json,sys; print('>>> el modelo es:', json.load(sys.stdin)['model'])\"
GEN_MODEL=gemma4 docker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e USAGE_LOG=usage_gemma4.jsonl \\
-e EXPECT_MODEL=gemma4 \\
eval
Y verifica el registro, porque las etiquetas de ejecución mienten:
\nsort <(cat eval/usage_gemma4.jsonl | python3 -c \"import json,sys; [print(json.loads(l)['model']) for l in sys.stdin]\") | uniq -c
# 16 gemma4
![\"Cambiando](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-gemma4-run-6a7c64183ec8b68e6d5e5ff76dd0924a.png\")
\nFigura 8. Cambiando el desafiante: GEN_MODEL=gemma4, espera por /health, luego confirma\n>>> el modelo es: gemma4 desde la propia respuesta — antes de gastar un solo minuto de evaluación.
![\"Resumen](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-gemma4-verified-8d7291e9dfcda2f337f83ca7e4988071.png\")
\nFigura 9. La ejecución de gemma4: 81.25% en ~13 minutos — y sus tres fallas son los mismos\ncasos de artefactos de etiqueta en los que Qwen parpadea. Sin favoritismo del juez gemma4 hacia el concursante gemma4.
Un script sobre los registros de uso:
\n| ejecución | tasa de aprobación | tokens promedio de prompt | tokens promedio de finalización | tokens totales |
|---|---|---|---|---|
| Qwen2.5-3B (ejecución 1) | 87.5% | 1,126 | 75 | 19,225 |
| Qwen2.5-3B (ejecución 2) | 81.25% | 1,126 | 75 | 19,225 |
| gemma4 | 81.25% | 1,199 | 415 | 25,834 |
![\"Tabla](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-verdict-table-fc9c10d332e08f09d63c768e48c1b23c.png\")
\nFigura 10. El veredicto en cinco líneas: misma tasa de aprobación, 5.5× los tokens de finalización. La evaluación\njusto previno una migración innecesaria.
Dos hallazgos, uno esperado y uno no:
\nEl veredicto: no cambies. Misma calidad efectiva, mismos casos de falla — pero gemma4 usa\n5.5× los tokens de finalización (415 frente a 75 por respuesta) y se ejecuta ~45% más lento por pregunta. En una\ncarga de trabajo RAG donde el contexto recuperado de ~1,100 tokens domina el prompt, la columna de finalización es toda la diferencia de costo. \"Modelo más nuevo\" perdió ante \"mídelo\" en una tarde. Esta es precisamente la evaluación que el post de noticias de GPT-5.6 dijo que ejecutarías — y es la misma evaluación que ejecutarías\ncontra GPT-5.6 mismo: cambia GEN_MODEL, GEN_BASE_URL, y GEN_API_KEY, nada más.
El juez tiene un umbral de ruido. Mira las dos filas de Qwen: cuentas de tokens idénticas —\n19,225 en ambas ejecuciones, porque la generación con temperatura 0 es determinista — sin embargo 87.5% frente a 81.25%.\nLas respuestas no cambiaron; solo los veredictos del juez lo hicieron (un límite de 0.6 se convirtió en un 0.3).\nEso aísla limpiamente la no determinación del juez del comportamiento del modelo, y establece tu umbral de CI:\nuna puerta en \"≥ 87.5%\" fallaría. El nuestro tolera un veredicto cambiado y falla en dos o más\nregresiones reales.
\n![\"Ejecución](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-qwen-run2-48156c484cd782d1e346e0938b1080b9.png\")
\nFigura 11. Ejecución 2 de Qwen: las mismas 16 respuestas deterministas, 81.25% esta vez — el juez, no\nel modelo, es donde vive la variación.
Puedes resolver un debate sobre el cambio de modelo con datos medidos — tasa de aprobación y tokens por tarea — y\nconoces el umbral de ruido de tu juez, así que puedes establecer un umbral de CI que no falle.
La recompensa de contenerizar todo: el trabajo de CI es el comando que has estado ejecutando todo\nel tiempo. .github/workflows/eval.yml:
name: rag-regression-eval
on:
pull_request:
paths: [\"app/**\", \"eval/**\"]
workflow_dispatch:
jobs:
eval:
runs-on: [self-hosted, wec] # corredor con acceso a inference.wiline.com
steps:
- uses: actions/checkout@v4
- name: Ejecutar suite de regresión
env:
WEC_API_KEY: ${{ secrets.WEC_API_KEY }}
run: |
docker compose up -d rag-api
docker compose --profile eval run --rm \\
-e DEEPEVAL_TELEMETRY_OPT_OUT=YES \\
-e EXPECT_MODEL=Qwen2.5-3B-Instruct \\
eval
- name: Desmontar
if: always()
run: docker compose down
Cualquier PR que toque la aplicación o la evaluación debe sobrevivir a 16 preguntas juzgadas contra el servicio en vivo — con la identidad del modelo afirmada — antes de que se fusione.
\nTu evaluación es una puerta de CI. El contenedor que ejecutaste localmente es byte por byte lo que CI ejecuta — sin\n\"funciona en mi máquina\" brecha entre desarrollo y la tubería.
[Errno 28] No hay espacio en el dispositivo — y volvióNuestra primera pip install deepeval falló: disco 100% lleno, 58G de 58G. Liberamos 2 GB de registros de diario\ny caché de construcción… y estaba lleno de nuevo minutos después. El culpable:
7.9G /var/lib/docker/containers/10281d.../10281d...-json.log
langfuse-clickhouse-1 estaba en un bucle de error, rociando trazas de pila en un registro json de Docker con\nsin rotación configurada — un espiral mortal, porque un disco lleno causa más errores que causa más\nregistros. Había estado \"no saludable\" durante 8 días. La solución, en orden (el orden importa — truncar mientras\nel contenedor se ejecuta simplemente vuelve a llenar):
docker stop langfuse-clickhouse-1
sudo sh -c \"truncate -s 0 /var/lib/docker/containers/10281d*/*-json.log\"
Luego hazlo permanente — rotación de registros en la sobrecarga de compose, aplicada a cada servicio:
\nx-logging: &default-logging
logging:
driver: json-file
options:
max-size: \"50m\"
max-file: \"3\"
services:
clickhouse:
<<: *default-logging
# ... cada otro servicio
docker compose up -d para recrear. ClickHouse se volvió saludable por primera vez en 8 días.\nEl controlador json-file de Docker no rota por defecto; en una caja que ejecuta infraestructura LLM\nque registra entusiastamente, los registros de contenedor sin límites son una bomba de tiempo.
Conexión rechazada, luego 3 pasanCambiar GEN_MODEL recrea rag-api, y la aplicación tarda ~3 minutos en arrancar (Chroma +\ncarga del modelo de incrustación). Nuestra suite comenzó a golpear /ask inmediatamente: 13 fallas\nde conexión rechazadas seguidas, luego la API cobró vida a mitad de ejecución y las últimas 3 pasaron. Flaky de la peor manera — la\nfalla depende del tiempo de reloj de pared.
Soluciona esto en la suite, no en la disciplina humana — eval/conftest.py:
\"\"\"Rechaza iniciar la suite hasta que la API RAG esté saludable.\"\"\"
import os, time
import requests
RAG_API_URL = os.getenv(\"RAG_API_URL\", \"http://rag-api:8000\")
READY_TIMEOUT = int(os.getenv(\"READY_TIMEOUT\", \"300\"))
def pytest_configure(config):
deadline = time.time() + READY_TIMEOUT
while time.time() < deadline:
try:
requests.get(f\"{RAG_API_URL}/health\", timeout=3).raise_for_status()
return
except requests.RequestException:
time.sleep(3)
raise RuntimeError(f\"rag-api no saludable después de {READY_TIMEOUT}s — abortando evaluación\")
La más desagradable, porque nada falló. ${GEN_MODEL:-Qwen…} en compose se interpola\ndesde tu shell en cada invocación. Comenzamos el servicio con\nGEN_MODEL=gemma4 docker compose up -d — correcto. Luego ejecutamos la evaluación sin el prefijo.\nCompose resolvió la variable de nuevo al valor predeterminado de Qwen, vio el contenedor en ejecución como un desvío de configuración\ny — a través de depends_on — silenciosamente recreó rag-api con Qwen. La ejecución se completó,\nel resumen decía \"gemma4\" en cada veredicto (el juez era gemma4), y cada respuesta había sido\nescrita por Qwen.
Solo lo atrapamos porque la suite registra el modelo desde la respuesta:
\nsort <(... usage_gemma4.jsonl ...) | uniq -c
# 16 Qwen2.5-3B-Instruct ← la ejecución \"gemma4\"
Nunca confíes en la etiqueta de una ejecución; verifica desde los datos que el sistema bajo prueba informa sobre sí mismo.\nLa solución permanente es la afirmación EXPECT_MODEL en la suite (Paso 4). Prueba que funciona — la\nprueba de fallo deliberado:
FAILED ... AssertionError: la suite esperaba gemma4 pero el servicio está ejecutando Qwen2.5-3B-Instruct
1 falló en 2.44s
Menos de tres segundos, antes de gastar una sola llamada de juez — frente a los 10+ minutos que cada ejecución mal etiquetada\nnos costó.
\n![\"Guardia](\"https://development-wec.wiline.com/docs/es/assets/images/deepeval-expect-model-ccc34be3d936ecfd93823c565073b405.png\")
\nFigura 12. La guardia en acción: modelo incorrecto → fallo ruidoso en menos de tres segundos, antes de que se gaste una\nsola llamada de juez. Compara con los 10+ minutos que cada ejecución mal etiquetada nos costó.
sleep 5 no es una verificación de disponibilidadPequeño bono: después de recrear el contenedor, canalizamos la salida de /ask a un analizador JSON 5\nsegundos después y obtuvimos json.decoder.JSONDecodeError: Esperando valor: línea 1 columna 1 — el\nservidor no estaba arriba, curl devolvió vacío, el analizador se ahogó en nada. Sondea /health en un bucle;\nnunca duermas un número adivinado.
gemma4 + GEval): veredictos con razonamiento, sin clave de OpenAIEXPECT_MODEL que convierte la evaluación silenciosa del modelo incorrecto en un fallo ruidoso en menos de tres segundosLa suite juzga respuestas. Las trazas de Langfuse de la parte 4 saben por qué — qué fragmentos fueron recuperados,\ncuánto costó el rango de generación, dónde se oculta la latencia. Conectar fallas de evaluación de vuelta a sus trazas\n(ID de prueba de DeepEval ↔ ID de traza de Langfuse) convierte \"la prueba falló\" en \"aquí está la recuperación que\nlo causó.\" Esa es la historia de depuración a nivel de componente, y es hacia donde va esta serie a continuación.
\n![\"Promptfoo\"](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-avatar-31b32c657d72dac0a7edbd77c24ec717.jpg\"){kind=avatar}
+Todo en esta serie apuntaba a esto. Sabes demostrar que un modelo funciona\n(parte 1), hacer su salida fiable para\nmáquinas (parte 2), generar datos de prueba\nreales (parte 3) y observar producción\n(parte 4). Ahora gastamos las cuatro habilidades a\nla vez en el patrón que está detrás de casi todo producto LLM serio: RAG — generación aumentada\npor recuperación.
\nVamos a construir un asistente de documentación: un servicio HTTP en contenedor que responde\npreguntas de clientes desde la propia documentación de WEC. No un notebook — un servicio,\nDocker primero, con la forma que realmente desplegarías. Y como esta serie no hace demos del camino\nfelíz: por el camino nuestro RAG alucina un precio de GPU, encontramos la causa en nuestro\npropio scraper, la arreglamos y fijamos el arreglo con un test de regresión. Cada comando, número\ny error de abajo viene de una ejecución real.
\n\nUna decisión de arquitectura por delante: repartimos el trabajo. Los embeddings corren\nlocalmente (un modelo ONNX pequeño — rápido, gratis, sin GPU) y la generación corre en WEC.\nEste es un reparto de producción completamente estándar: la recuperación es barata y sensible a la\nlatencia, así que mantenerla junto a tu almacén de vectores ahorra una ida y vuelta de red por\nconsulta — mientras la generación es donde el modelo grande se gana el sueldo.
\nEl catálogo de WEC ahora incluye bge-m3 (1024 dimensiones, multilingüe, entrada por lotes) en\n/v1/embeddings:
curl -s https://inference.wiline.com/v1/embeddings \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"bge-m3\",\"input\":[\"first chunk\",\"second chunk\"]}' | jq '.data | length'
Pasar este tutorial a esa vía es un cambio de dos funciones — reemplaza las llamadas a fastembed\nen ingest.py y main.py por el mismo cliente de OpenAI apuntando a /v1/embeddings\n(wec.embeddings.create(model=\"bge-m3\", input=chunks)), y vuelve a ingerir (la dimensión del vector\ncambia de 384 a 1024, así que borra y reconstruye la colección). Mantenemos la vía local abajo\nporque es gratis, funciona sin conexión, y cada número de esta guía se midió con ella — pero las dos\nson legítimas en producción; elige según tu latencia y tus preferencias de operación.
df -h /. Nuestra máquina estaba al\n99% y sobrevivió, pero el disco justo es el asesino silencioso número uno de las builds de Docker.Las funciones RAG reales se despliegan como servicios, así que empezamos como uno: una app de\nFastAPI en un contenedor, con el código montado para que uvicorn --reload recoja cada edición —\nsin rebuild por cambio.
mkdir -p ~/rag-service/app && cd ~/rag-service
cat > requirements.txt <<'EOF'
fastapi==0.115.6
uvicorn==0.34.0
chromadb==0.5.23
fastembed==0.4.2
openai==1.59.7
langfuse
requests==2.32.3
beautifulsoup4==4.12.3
EOF
cat > Dockerfile <<'EOF'
FROM python:3.12-slim
WORKDIR /srv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app/ app/
EXPOSE 8000
CMD [\"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\", \"--reload\"]
EOF
cat > docker-compose.yml <<'EOF'
services:
rag-api:
build: .
ports:
- \"8000:8000\"
volumes:
- ./app:/srv/app # live code - edit on host, uvicorn reloads
- chroma-data:/data # persisted vector index
- model-cache:/root/.cache # embedding model cache (survives rebuilds)
environment:
ANONYMIZED_TELEMETRY: \"False\"
WEC_API_KEY: ${WEC_API_KEY}
LANGFUSE_PUBLIC_KEY: ${LANGFUSE_PUBLIC_KEY}
LANGFUSE_SECRET_KEY: ${LANGFUSE_SECRET_KEY}
LANGFUSE_HOST: ${LANGFUSE_HOST}
volumes:
chroma-data:
model-cache:
EOF
Los secretos viven en un archivo .env junto al compose (compose lo carga automáticamente — las\nclaves nunca entran en el YAML). Mantenlo fuera del control de versiones desde el principio:
cat > .env <<'EOF'
WEC_API_KEY=sk-your-wec-key
LANGFUSE_PUBLIC_KEY=pk-lf-…
LANGFUSE_SECRET_KEY=sk-lf-…
LANGFUSE_HOST=http://<your-langfuse-host>:3000
EOF
echo \".env\" >> .gitignore
Una app mínima para que el contenedor tenga algo que servir:
\ncat > app/main.py <<'EOF'
from fastapi import FastAPI
app = FastAPI(title=\"WEC docs RAG\")
@app.get(\"/health\")
def health():
return {\"status\": \"ok\"}
EOF
docker compose up -d --build
curl -s localhost:8000/health
{\"status\":\"ok\"}
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/rag-deploy-health-850c74e1ed3eff7a20368db371456f79.png\")
\nFigura 1. Un comando cada uno: el contenedor arriba, /health respondiendo, y la comprobación\nde disco (la nuestra marca 99% — esta máquina vive peligrosamente). La build tarda unos 90s y son\nunos 700 MB de imagen.
En el mundo real, la base de conocimiento de la que quieres que responda tu asistente normalmente no\nes una carpeta ordenada de markdown — es un sitio web vivo: documentación de producto, un wiki,\nun centro de ayuda. Así que la habilidad de adquisición de corpus que vale la pena aprender es\nscraping real, no cargar archivos.
\nPara este tutorial extraemos el propio sitio de documentación de WEC. Está hecho con Docusaurus,\ny Docusaurus (como la mayoría de generadores de sitios) publica un sitemap.xml — lo que significa\nque puedes descubrir cada página programáticamente en vez de adivinar URLs. El mismo enfoque\nfunciona en cualquier sitio que publique un sitemap:
curl -s https://wec.wiline.com/docs/sitemap.xml | grep -c \"<loc>\" # 109 URLs on the whole site
Filtramos a la documentación de producto (/docs/cloud_portal/), traemos cada página, y nos\nquedamos solo con el elemento <article> — Docusaurus envuelve el contenido real en él, así que la\nnavegación, la barra lateral y el pie nunca llegan al índice:
cat > app/ingest.py <<'EOF'
\"\"\"Scrape the WEC docs site -> chunk -> embed locally -> Chroma.\"\"\"
import re, requests, chromadb
from bs4 import BeautifulSoup
from fastembed import TextEmbedding
SITEMAP = \"https://wec.wiline.com/docs/sitemap.xml\"
FILTER = \"/docs/cloud_portal/\" # product docs only
CHUNK, OVERLAP = 700, 100 # chars
def discover():
xml = requests.get(SITEMAP, timeout=30).text
urls = re.findall(r\"<loc>([^<]+)</loc>\", xml)
return [u for u in urls if FILTER in u]
def scrape(url):
html = requests.get(url, timeout=30).text
art = BeautifulSoup(html, \"html.parser\").find(\"article\") # Docusaurus main content
return art.get_text(\"\\n\", strip=True) if art else \"\"
def chunk(text):
out, i = [], 0
while i < len(text):
out.append(text[i:i + CHUNK])
i += CHUNK - OVERLAP
return out
if __name__ == \"__main__\":
urls = discover()
print(f\"sitemap -> {len(urls)} product-doc pages\")
docs, metas = [], []
for u in urls:
for c in chunk(scrape(u)):
docs.append(c)
metas.append({\"url\": u})
print(f\"scraped -> {len(docs)} chunks\")
embedder = TextEmbedding(\"BAAI/bge-small-en-v1.5\") # local, ~66MB ONNX, no GPU needed
vectors = [v.tolist() for v in embedder.embed(docs)]
print(f\"embedded -> {len(vectors)} vectors (dim {len(vectors[0])})\")
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
col.add(ids=[str(i) for i in range(len(docs))],
documents=docs, metadatas=metas, embeddings=vectors)
print(f\"indexed -> collection 'wec-docs' now has {col.count()} chunks\")
EOF
docker compose exec rag-api python -m app.ingest
sitemap -> 37 product-doc pages
scraped -> 281 chunks
model_optimized.onnx: 100%|████████████| 66.5M/66.5M [00:03<00:00, 16.9MB/s]
embedded -> 281 vectors (dim 384)
indexed -> collection 'wec-docs' now has 281 chunks
![\"Ejecución](\"https://development-wec.wiline.com/docs/es/assets/images/rag-ingest-2a1ffde1c98f1968bbf60532fa0a0a00.png\")
\nFigura 2. Todo el corpus de documentación de producto indexado en menos de un minuto. El modelo\nde embeddings se guarda en caché en el volumen model-cache, así que se descarga exactamente una\nvez.
Sabes convertir cualquier sitio web de documentación en un índice vectorial consultable —\ndescubrimiento por sitemap, extracción de contenido, troceado, embeddings locales.
get_text(\"\\n\", …)Nuestra primera versión usaba get_text(\" \") — un solo espacio como separador. Parecía inofensivo y\ncausó una alucinación auténtica que verás en el Paso 4. Conserva el salto de línea; volveremos a\nesto. (¿Quieres ver el bug ocurrir en tu propia máquina? Cambia \"\\n\" de vuelta a \" \" en\nscrape(), vuelve a ejecutar la ingesta, y haz la pregunta del Paso 4 — luego devuelve el salto de\nlínea y vuelve a ingerir.)
Puedes ver Failed to send telemetry event ClientStartEvent: capture() takes 1 positional argument… — un choque conocido de versiones entre chromadb y posthog. Es inofensivo (tus datos\nestán bien), y la variable ANONYMIZED_TELEMETRY: \"False\" del compose lo silencia.
/ask: recuperar, generar, trazarAhora el servicio en sí. Tres decisiones de diseño que vale la pena declarar:
\nsources es determinista.langfuse.openai (el reemplazo directo de la parte 4), y cada etapa\nrecibe un span con @observe — así que cada petición produce un árbol\nask → retrieve → generate en Langfuse.timeout=60 en el cliente. La lección de la parte 4: sin timeout por defecto, un backend\natascado cuelga tu servicio en silencio.cat > app/main.py <<'EOF'
import os, chromadb
from fastapi import FastAPI
from pydantic import BaseModel
from fastembed import TextEmbedding
from langfuse import observe, get_client
from langfuse.openai import openai # auto-traces the WEC call
app = FastAPI(title=\"WEC docs RAG\")
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
embedder = TextEmbedding(\"BAAI/bge-small-en-v1.5\")
wec = openai.OpenAI(
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
timeout=60,
)
class Ask(BaseModel):
question: str
@observe() # span: retrieve
def retrieve(question: str, k: int = 4):
qv = list(embedder.embed([question]))[0].tolist()
res = col.query(query_embeddings=[qv], n_results=k)
chunks = res[\"documents\"][0]
sources = sorted({m[\"url\"] for m in res[\"metadatas\"][0]})
return chunks, sources
@observe() # span: generate (WEC call nested inside)
def generate(question: str, chunks: list[str]) -> str:
context = \"\\n---\\n\".join(chunks)
resp = wec.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\", # small on purpose: cheap + fast per query,
# and its failures teach (see Step 5)
name=\"rag-generate\",
messages=[{\"role\": \"user\", \"content\":
\"Answer the question using ONLY the context below. \"
\"If the context doesn't contain the answer, say so. \"
\"When quoting a price or number, copy it VERBATIM with its unit and the item \"
\"it belongs to; never combine numbers from different lines and never compute \"
\"new numbers from examples.\\n\\n\"
f\"Context:\\n{context}\\n\\nQuestion: {question}\"}],
)
return resp.choices[0].message.content
@app.post(\"/ask\")
@observe() # root span: the whole request
def ask(body: Ask):
chunks, sources = retrieve(body.question)
answer = generate(body.question, chunks)
get_client().flush()
return {\"answer\": answer, \"sources\": sources}
@app.get(\"/health\")
def health():
return {\"status\": \"ok\"}
EOF
docker compose up -d --build
Hazle una pregunta real de cliente:
\ncurl -s localhost:8000/ask -H \"Content-Type: application/json\" \\
-d '{\"question\": \"How do I create an API key for the Inference API?\"}' | python3 -m json.tool
{
\"answer\": \"To create an API key for the Inference API, follow these steps:\\n1. Log in to the WiLine Edge Cloud.\\n2. Expand the \\\"Inference\\\" section in the left sidebar.\\n3. Click on the \\\"API Keys\\\" tab.\\n4. Click the \\\"+ Create Key\\\" button located above the keys table. ...\",
\"sources\": [
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/api/wiline-edge-cloud-inference-api/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/api_keys/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/examples/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/models_hub/\",
\"https://wec.wiline.com/docs/cloud_portal/platform/inference/overview/\"
]
}
![\"Primera](\"https://development-wec.wiline.com/docs/es/assets/images/rag-first-ask-301b6dfc7a64a463e0eb1e6d93b53837.png\")
\nFigura 3. Al primer intento: el flujo exacto de la clave de API sacado de la documentación, con\nla página correcta citada. Extraer → embeddings → recuperar → generar, de punta a punta.
Abre Langfuse → Tracing y encontrarás la petición como un árbol de spans — ask → retrieve → generate → rag-generate — con latencia y tokens por paso. Cuando una respuesta es mala, así\ndistingues mala recuperación de mala generación (la habilidad de la parte 4, ahora en una app\nreal).
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/rag-trace-tree-769e5224814989dedc4896f9e4e1873f.png\")
\nFigura 4. Cada /ask se convierte en un árbol: la recuperación y la generación tienen cada una\nsu dirección.
Tienes un servicio RAG trazado y en contenedor respondiendo desde documentación extraída en vivo.
Un buen RAG tiene que negarse a lo que la documentación no cubre. Pínchalo:
\ncurl -s localhost:8000/ask -H \"Content-Type: application/json\" \\
-d '{\"question\": \"Does WEC offer a free GPU tier for students?\"}' | python3 -m json.tool
Nuestra primera versión (la del scraper con get_text(\" \")) respondió:
\"No, WEC does not offer a free GPU tier specifically for students. The pricing for
GPU hourly is listed as $0.66/GPU-hr with a 25% off annual prepay option at
$0.10/GB-mo for block storage. There is no mention of a free GPU tier in the
provided information.\"
La negativa es correcta. Pero vuelve a leer la frase del precio: \"$0.66/GPU-hr con una opción\nde prepago anual con 25% de descuento a $0.10/GB-mo para almacenamiento en bloque\" — son tres\nhechos distintos soldados en una sola afirmación falsa, pegando una tarifa de almacenamiento a la\nopción de prepago de GPU. Consulta la página real de precios y descubres que simplemente son tres\nelementos adyacentes:
\nEl modelo cosió un precio de almacenamiento a \"GPU\". ¿Por qué? Mira el trozo que le dimos. Nuestra\nextracción separada por espacios había aplastado las tarjetas de precios en una única línea\nindiferenciada:
\n... $1.44 /mo Starting at $0.66 /GPU-hr GPU hourly 25 % off Annual prepay $0.10 /GB-mo Block storage ...
La alucinación la fabricó nuestra propia ingesta. El modelo confundió precios porque destruimos\nla estructura antes de generar los embeddings. Este es el fallo RAG más clásico que existe — basura\nentra, basura sale — y solo lo cazas pinchando con preguntas y leyendo los trozos recuperados.
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/rag-hallucination-18e9fb70cb217a347f31057d36b774e8.png\")
\nFigura 5. El bug en libertad: negativa correcta, precios revueltos — una tarifa de\nalmacenamiento pegada a la opción de prepago de GPU. Las fuentes parecen perfectamente plausibles.\nPor esto \"cita fuentes\" no es lo mismo que \"está fundamentado\".
Dos arreglos, los dos ya en el código de arriba:
\nget_text(\"\\n\", strip=True) conserva los límites de\nlínea, así que las tarjetas de precio siguen siendo líneas separadas en vez de una sopa.Después de volver a ingerir con el arreglo, la confusión con el precio de almacenamiento desaparece.\nQueda ambigüedad residual — la tira de precios todavía contiene fragmentos como \"$1.44/mo\" (un\nprecio de instancia de cómputo) cerca de la línea de GPU, y arreglar eso de verdad necesita\nextracción consciente de tablas (mira Lo que viene). Que es exactamente la razón por la que existe\nel paso siguiente: fijar el bug arreglado para que no pueda volver en silencio.
\nEste paso necesitó cuatro rondas de arreglos para conseguir un número honesto — y el viaje del\n39% al 87% es la mejor lección de la serie, porque casi nada de lo que arreglamos por el camino era\nel RAG en sí.
\nReutilizamos la habilidad de la parte 3 — generar un conjunto de QA desde el propio corpus — y\ncalificamos el endpoint HTTP vivo con Promptfoo. La primera versión del generador pedía una\npregunta por página con un key_fact que la respuesta debía contener, y devolvió 37/37 pares.\nAlgunas etiquetas ya olían mal — un vago \"All paid\", rutas de menú en vez de respuestas — pero\nvamos a ejecutarlo de forma naíf primero y dejar que los fallos nos enseñen. Convierte a un conjunto\nde datos de Promptfoo con aserciones de subcadena simples (icontains: + el hecho clave) y apúntalo\nal servicio en marcha. El proveedor es HTTP — calificamos la API real, exactamente lo que haría\nuna puerta de CI:
mkdir -p eval
{ echo 'question,__expected'; jq -r '[.question, (\"icontains:\" + .key_fact)] | @csv' app/qa.jsonl; } > eval/tests.csv
cat > eval/promptfooconfig.yaml <<'EOF'
description: \"RAG service eval — QA set generated from the scraped docs + regression\"
providers:
- id: https
config:
url: http://localhost:8000/ask
method: POST
headers:
Content-Type: application/json
body:
question: \"{{question}}\"
transformResponse: json.answer
tests:
- file://tests.csv
# regression: the storage-price-as-GPU-price conflation from Step 4
- vars:
question: \"What is the pricing model for GPU hourly usage in Edge Cloud?\"
assert:
- type: not-icontains
value: \"0.10\"
- type: not-icontains
value: \"GB-mo\"
EOF
cd eval && npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Results:
✓ 15 passed (39.47%)
✗ 23 failed (60.53%)
Duration: 40s (concurrency: 4)
Ese 39,5% es lo que medimos durante el desarrollo, con el bug del Paso 4 todavía vivo. Vuelve a\nejecutar la misma eval naíf contra el servicio terminado y sale mucho más alto — 27/38:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/rag-eval-icontains-284e4ea4fa5a8f2dec99a5079c84c4f7.png\")
\nFigura 6. La misma eval naíf contra el servicio terminado: 71,05%. Mejor servicio, las mismas\netiquetas ruidosas — la diferencia de 30 puntos entre estas dos ejecuciones es toda calidad del\nservicio, y los dos números significan poco hasta que lees las filas.
Lee los fallos antes de entrar en pánico. De los 23 fallos de la ejecución de desarrollo, la\nmayoría no son fallos del RAG:
\n| Fallo | Qué pasó en realidad |
|---|---|
| Respuesta de \"Balance due\": \"the amount that remains due… $0.00\" | Respuesta correcta; la etiqueta exigía la frase All paid — etiqueta mala |
| Payment Information: da la ruta de menú exacta y correcta | Correcto; la redacción de la etiqueta no coincide como subcadena — aserción frágil |
| Precio de GPU: \"$0.10 per GB-month\" | Fallo real — la confusión del Paso 4, reproduciéndose sistemáticamente |
| Formato por defecto de TTS: \"not specified in the context\" | Fallo real de recuperación — el trozo con el valor por defecto no se recuperó |
La coincidencia de subcadenas (icontains) era perfecta para el único campo JSON de la parte 2 y es\ndemasiado frágil para respuestas RAG largas. La mejora obvia es la habilidad de la parte 4: un\njuez LLM calificando la consistencia semántica (aserciones llm-rubric: + un modelo juez en\ndefaultTest). Hicimos exactamente eso — las mismas 37 etiquetas, juez en vez de subcadenas — y\nobtuvimos:
Results:
✓ 17 passed (44.74%)
✗ 21 failed (55.26%)
Duration: 8m 21s (concurrency: 4)
39,5% → 44,7%. Apenas se movió — porque el juez hace cumplir fielmente unas etiquetas malas.\nLas filas con key_fact basura siguen fallando: la referencia está mal, no la respuesta. Un\ncalificador mejor no puede rescatar un conjunto de datos malo. El cuello de botella nunca fue el\ntipo de aserción.
Así que arregla los datos (la disciplina de la parte 3, ahora impuesta por código). El generador v2\nexige que la etiqueta sea la respuesta — no una ruta de menú, no un nombre de sección — y añade una\npuerta de curación: el key_fact tiene que existir literalmente en el texto de origen, o la\nfila se rechaza en el sitio:
cat > app/gen_qa.py <<'EOF'
\"\"\"Generate a QA eval set from the indexed docs — v2, curated labels.\"\"\"
import os, json, chromadb
from openai import OpenAI
wec = OpenAI(base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"], timeout=60)
db = chromadb.PersistentClient(path=\"/data\")
col = db.get_or_create_collection(\"wec-docs\")
data = col.get(include=[\"documents\", \"metadatas\"])
pages = {}
for doc, meta in zip(data[\"documents\"], data[\"metadatas\"]):
pages.setdefault(meta[\"url\"], []).append(doc)
kept, skipped = 0, 0
with open(\"/srv/app/qa.jsonl\", \"w\") as f:
for url, chunks in sorted(pages.items()):
ctx = \"\\n\".join(chunks[:2])[:2000]
resp = wec.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\", temperature=0.3,
messages=[{\"role\": \"user\", \"content\":
\"From this documentation excerpt, write ONE question a customer would ask, \"
\"and the fact that ANSWERS it. Return ONLY JSON with keys:\\n\"
\"question (string), key_fact (string).\\n\"
\"Rules for key_fact: it must be THE ANSWER to the question (not a menu path, \"
\"not a section name), a short phrase copied VERBATIM from the excerpt, \"
\"max 8 words.\\n\\n\"
f\"Excerpt:\\n{ctx}\"}],
)
raw = resp.choices[0].message.content
try:
start, end = raw.index(\"{\"), raw.rindex(\"}\") + 1
row = json.loads(raw[start:end])
# curation gate: the label must literally exist in the source text
if row[\"key_fact\"].lower().strip() not in ctx.lower():
print(f\"SKIP {url.split('/docs/')[1]}: key_fact not verbatim in source\")
skipped += 1
continue
row[\"url\"] = url
f.write(json.dumps(row) + \"\\n\")
kept += 1
print(f\"ok {url.split('/docs/')[1]}: {row['question'][:50]} -> {row['key_fact'][:40]}\")
except Exception as e:
print(f\"SKIP {url}: {e}\")
skipped += 1
print(f\"done -> {kept} kept, {skipped} rejected by curation gate\")
EOF
docker compose exec rag-api python -m app.gen_qa
ok cloud_portal/management/billing/how_billing_works/: What is the starting point ... -> How Billing Works
SKIP cloud_portal/management/billing/overview/: key_fact not verbatim in source
ok cloud_portal/platform/inference/api/wiline-edge-cloud-inference-api/: What is the base URL ... -> https://inference.wiline.com/v1
SKIP cloud_portal/platform/inference/api_keys/: key_fact not verbatim in source
...
done -> 15 kept, 22 rejected by curation gate
15 conservados, 22 rechazados. Esa tasa de rechazo es el punto: más de la mitad de lo que\nprodujo el generador habría calificado el RAG contra referencias equivocadas. Un conjunto de datos\nmás pequeño y fiable vence a uno más grande y envenenado.
\nEl generador muestrea con temperatura 0.3, así que el recuento exacto cambia ligeramente entre\nejecuciones — aquí una regeneración posterior que conservó 16 de 37; la tasa de rechazo sigue siendo\nbrutal en cualquier caso:
\n![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/rag-qa-gen-8dfb631c47f8fc4cb9c506fef0f651d2.png\")
\nFigura 7. La puerta en acción: 16 conservados, 21 rechazados en esta ejecución. Cada etiqueta\nque sobrevive está demostrablemente en la documentación — hechos-respuesta reales como audio/mpeg y\nla URL base de la API, no rutas de menú. (Las ejecuciones documentadas abajo usan nuestro primer\nconjunto curado: 15 pares + la regresión = 16 tests.)
Reconstruye tests.csv con una rúbrica que le dé al juez la pregunta y la referencia verificada,\nmás reglas explícitas de PASS/FAIL (una redacción distinta está bien; una contradicción falla):
{ echo 'question,__expected'; jq -r '[.question, (\"llm-rubric:Question asked: \\\"\" + .question + \"\\\". Reference fact from the official docs: \\\"\" + .key_fact + \"\\\". PASS if the answer correctly addresses the question and does not contradict the reference fact — different wording is fine. FAIL only if the answer is wrong, contradicts the reference, or fails to answer the question.\")] | @csv' ../app/qa.jsonl; } > tests.csv
Results:
✓ 12 passed (75.00%)
✗ 4 failed (25.00%)
Duration: 2m 47s (concurrency: 4)
75%. Mejor — pero antes de celebrarlo, lee los cuatro fallos. Y aquí el hábito de la serie paga\nuna vez más, porque tres de ellos tampoco eran fallos del RAG.
\nLos tres fallos cuya razón de calificación era solo \"No output\" compartían dos señales:\ngraderError: true, y una completación de exactamente 1024 tokens — el max_tokens por defecto\nde Promptfoo. Nuestro juez es un modelo que razona: gastó todo el presupuesto razonando y quedó\ncortado antes de emitir el JSON del veredicto, que Promptfoo cuenta como FAIL. El cuarto \"fallo\"\nsí obtuvo un veredicto — pero el juez pequeño había repetido literalmente el marcador del esquema\n(reason: \"string\") en vez de calificar. Las dos respuestas eran de hecho correctas.
Dos líneas de configuración lo arreglan — un juez más grande, y espacio para pensar:
\ndefaultTest:
options:
provider:
id: openai:chat:Qwen3.5-122B
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
# thinking models spend tokens on reasoning before the verdict JSON;
# the 1024 default silently truncated the judge and failed 3 tests
max_tokens: 4096
Results:
✓ 14 passed (87.50%)
✗ 2 failed (12.50%)
Y la fila que más importa:
\n│ What is the pricing model for GPU hourly usage in Edge Cloud? │ [PASS] ... starting at $0.66/GPU-hour. │
La regresión está en verde — la confusión del Paso 4 está fijada y no puede volver en silencio.\n(Una nota cosmética: el juez de 122B a veces reduce su texto de razón a un lacónico ... — los\nveredictos en sí son correctos, que es lo que lee la puerta.)
Sabes poner una puerta de CI a un servicio RAG vivo: QA generado y curado por una puerta, un juez\npara la semántica, regresiones deterministas para bugs conocidos — y sabes depurar al propio juez.
Un hábito que esta serie machaca: vuelve a ejecutar antes de creer. Lo hicimos — y obtuvimos\n75%, con filas distintas fallando que antes. Facturación, que acababa de pasar, ahora falló\ncon un eco circular; la respuesta de TTS decía \"mp3\" en una ejecución y \"sin especificar\" en la\nsiguiente. La puntuación era una lotería porque el servicio mismo era no determinista:\ngenerate() no pasaba temperature, así que cada eval calificaba una tirada distinta de dados con\nel valor por defecto de 1.0.
Una línea acaba con la lotería — añádela a la llamada a create() en generate():
temperature=0, # determinism: same question -> same answer
Vuelve a ejecutar dos veces. 13/16 — 81,25% — las dos veces, con los mismos tres fallos. El\nnúmero bajó y eso es la victoria: el 87,5% era en parte suerte (las filas inestables cayeron bien\nen esa ejecución); el 81,25% es reproducible. Alguien que repita tu eval debería obtener tu número.
\nDespués de cuatro rondas arreglando la medición, lo que queda es señal — estable entre\nejecuciones, y cada uno es un tipo clásico de fallo RAG distinto:
\n\"iated with subnets\\nData Transfer…\"). El troceado de tamaño fijo por caracteres partió el\nhecho por un límite, y la mitad con la respuesta no aparece en el ranking. Clase de arreglo: más\nsolapamiento, k mayor, o troceado consciente de la estructura.Una eval fiable no es la meta; es el mapa. Acaba de decirnos que dos de tres fallos son de la misma\nclase — hechos que no llegan a los cuatro trozos recuperados. El arreglo más barato de esa clase es\nun carácter, en retrieve():
def retrieve(question: str, k: int = 6): # was 4 — two misses said \"not enough context\"
Vuelve a ejecutar. Y luego otra vez, porque ya es el hábito:
\nResults:
✓ 14 passed (87.50%)
✗ 2 failed (12.50%)
14/16 — 87,5% — dos veces, los mismos dos fallos. Lee qué pasó con cada uno:
\nk=6 el trozo con el bloque de estadísticas no aparece en\nel ranking: este fallo es semántico, no de presupuesto — el texto destrozado por el límite\n(\"iated with subnets…\") genera embeddings pobres. Más k no puede arreglar lo que el troceado\nrompió; este necesita de verdad troceado consciente de la estructura.El número vuelve a 87,5% — el mismo que la ejecución afortunada — pero esta vez se reproduce, y\ncada punto tiene una explicación.
\n![\"Eval](\"https://development-wec.wiline.com/docs/es/assets/images/rag-eval-final-eb3776d3a5abed5af34d6896bbee06d0.png\")
\nFigura 8. La ejecución final: 14/16, los mismos dos fallos cada vez, regresión en PASS.
39,5% → 44,7% → 75% → 87,5% (con suerte) → 81,25% (honesto) → 87,5% (ganado). Hasta el\núltimo paso, el RAG apenas cambió — lo que cambió fue la medición: las aserciones (subcadenas →\njuez), las etiquetas (puerta de curación), la configuración del propio juez (truncamiento), el\ndeterminismo (temperatura). Solo entonces un parámetro de recuperación, elegido por la eval, movió\nla calidad de verdad. Esa es la última lección de la serie:
\nPOST /ask\ncon citas deterministas.Las partes 1 a 4 eran la caja de herramientas. Esto es para lo que sirve la caja de herramientas.
\n/ask no devuelve nada después de reindexarSi borras y recreas la colección de Chroma mientras la API está en marcha, el servicio conserva un\nhandle obsoleto de la colección y cada consulta lanza:
\nchromadb.errors.InvalidCollectionException: Collection 9b486740-… does not exist.
El proceso en marcha guardó en caché el UUID de la colección antigua. Reinicia el servicio\n(docker compose restart rag-api) — o resuelve la colección por petición en vez de al arrancar.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/rag-stale-handle-1639bfb9ef1938577ff551daa191a889.png\")
\nFigura 9. Reindexar invalida los handles abiertos — una trampa clásica de producción del tipo\n\"funciona hasta que reconstruyes el índice\".
Failed to send telemetry event … capture() takes 1 positional argumentChoque inofensivo de versiones entre chromadb y posthog. Pon ANONYMIZED_TELEMETRY: \"False\" en el\nentorno (ya está en nuestro compose).
graderError: true)Comprueba los tokens de completación del registro de calificación: si son exactamente 1024 — el\nmax_tokens por defecto de Promptfoo — tu juez con razonamiento gastó todo el presupuesto razonando\ny quedó cortado antes del JSON del veredicto. Pon max_tokens: 4096 en el proveedor del juez. Señal\nrelacionada: un juez pequeño devolviendo reason: \"string\" está repitiendo el marcador del esquema\nen vez de calificar — usa un juez más grande.
Los jueces con razonamiento son lentos (~minutos para una docena de filas) e imperfectos — espera\ncambios de veredicto ocasionales entre ejecuciones. Mantén aserciones deterministas para bugs\nconocidos (son gratis y nunca cambian) y trata la puntuación del juez como una tendencia, no como\nuna verdad. Si una fila del juez se cuelga del todo, normalmente es un hipo transitorio de red y no\ntu configuración — reintenta antes de depurar.
\nLa imagen necesita ~1 GB (chromadb y onnxruntime son las capas pesadas). Comprueba df -h / primero\ny docker system df para ver espacio reclamable — pero nunca hagas prune a ciegas en una máquina\ncompartida: \"reclamable\" miente cuando hay contenedores de otros proyectos en marcha.
Las limitaciones honestas son la hoja de ruta, y cada una viene de un fallo que viste ocurrir:\ntroceado consciente de la estructura (el fallo de subredes sobrevivió a k=6 — el trozo\ndestrozado por el límite genera embeddings pobres, así que ningún presupuesto de recuperación lo\nrescata), trabajo de prompt o de modelo en la generación (el eco de facturación: obliga al\nmodelo a nombrar la página que cita, o usa un generador más fuerte), extracción consciente de\ntablas (la tira de precios sigue siendo sopa de fragmentos — la regresión pasa, pero \"$1.44/mo\"\ntodavía se filtra cerca de la línea de GPU; añade una aserción positiva para la cifra correcta, no\nsolo not-icontains para las equivocadas), y calibración del juez (califica al juez contra un\npuñado de veredictos humanos). Cada una mueve la tasa de aprobados por una razón que puedes nombrar\n— que, después de cinco partes, es el punto entero: no adivinas si tu IA funciona. La mides, la\nobservas, y la haces demostrarlo.
Un cliente dice que tu bot de soporte les prometió una política de reembolso que no existe. Tu función\nhizo dos llamadas LLM: clasificar y luego responder. ¿Cuál de ellas la inventó? Si no puedes responder eso,\ntu aplicación es una caja negra — y esta guía soluciona exactamente eso.
\nAhora puedes probar que un modelo funciona (parte 1),\nhacer que su salida sea confiable para máquinas (parte 2),\ny generar un conjunto de pruebas real para verificarlo\n(parte 3). Pero todo eso se ejecuta fuera de línea,\nen CI, con entradas que elegiste. La producción no juega de esa manera.
\nEsta guía cierra la brecha. Autoalojaremos Langfuse — la alternativa de código abierto y autoalojable\na LangSmith — rastrearemos cada llamada real, evaluaremos automáticamente el tráfico en vivo con un juez LLM,\nprofundizaremos en el paso exacto que falla y retroalimentaremos los fallos para que tu conjunto de datos de la parte 3 se vuelva\nmás fuerte. La evaluación fuera de línea te dice que funcionó en tu conjunto de pruebas; esto te dice que funciona en el mundo real.
\n\nAl final podrás tomar cualquier función WEC y: ver dentro de cada llamada, evaluar la calidad en tráfico real automáticamente, encontrar la llamada exacta que falló y por qué, y convertir los fallos de producción en nuevos casos de prueba. Esa es la diferencia entre \"pasó CI\" y \"se mantiene en producción.\"
\nMantendremos el ejemplo en ejecución de la parte 3 — un clasificador de tickets de soporte en la API de Inferencia WEC — y lo pondremos bajo observación.
\nTu aplicación llama a la API WEC como de costumbre; Langfuse (autoalojado) captura silenciosamente cada llamada como un\nrastreo, un juez LLM evalúa cada una, y los fallos fluyen de vuelta a tu conjunto de datos de la parte 3 — para que la producción siga fortaleciendo tus evaluaciones:
\n\nUsamos Langfuse porque es el líder de código abierto en observabilidad LLM (licencia MIT,\nautoalojable), su SDK es compatible con OpenAI por lo que apunta a la API WEC sin cambios, y — la\nrazón por la que encaja en esta serie — tiene conjuntos de datos, evaluación y evaluadores LLM-como-juez integrados.\nEso permite que tu conjunto de datos de la parte 3 y el bucle de \"evaluar producción, retroalimentar fallos\" sean\nde primera clase en lugar de añadidos.
\nLa desventaja: la pila de producción es pesada (Postgres + ClickHouse). Si no necesitas las características de evaluación\ny quieres algo más ligero, alternativas razonables son Arize Phoenix (nativa de OpenTelemetry,\nfuerte para evaluación fuera de línea), Helicone (un proxy de una línea — pero sin evaluaciones), o OpenLIT\n(un solo binario, nativa de OTEL). Para un flujo de trabajo impulsado por evaluaciones como este, los contenedores adicionales valen la pena; para un simple rastreo, uno de esos puede ser más adecuado para ti.
\nLa pila autoalojada de Langfuse consta de seis servicios (web + worker, ClickHouse, Postgres, Redis, almacenamiento de objetos), así que dale una Instancia WEC con ~15 GB de disco y 4 GB+ de RAM — no lo metas en una máquina que ya esté ocupada.
\ngit clone https://github.com/langfuse/langfuse.git && cd langfuse
Genera tres secretos y colócalos en un .env (la ENCRYPTION_KEY debe ser hex, o el contenedor web no arrancará):
cat > .env <<EOF
NEXTAUTH_SECRET=$(openssl rand -base64 32)
SALT=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
NEXTAUTH_URL=http://<tu-ip-de-instancia>:3000
EOF
docker compose up -d
docker compose ps
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-deploy-ps-597bc541cd07b60e848e6c0dfe6246fc.png\")
\nFigura 1. docker compose ps — los seis servicios (web, worker, ClickHouse, Postgres, Redis, MinIO) en funcionamiento y saludables.
Si la máquina ya ejecuta algo en el puerto 3000 o 5432, Langfuse no arrancará (\"dirección ya en uso\"). Las bases de datos de respaldo no necesitan puertos de host en absoluto — edita docker-compose.yml para mover langfuse-web a un puerto de host libre (por ejemplo, 3001:3000) y elimina el mapeo del host de Postgres. Mantener tus bases de datos fuera de la red del host es una buena práctica de todos modos. Consulta Solución de problemas.
Abre http://<ip-de-instancia>:3000, crea una cuenta (el primer usuario es el propietario), luego una\nOrganización → Proyecto, y bajo Configuración → Claves API crea un par de claves\n(pk-lf-… / sk-lf-…).
Apunta el SDK de Langfuse a tu instancia y usa su OpenAI drop-in — traza automáticamente cualquier\nllamada compatible con OpenAI, incluida la API de Inferencia WEC, sin código adicional alrededor de cada solicitud:
\npython3 -m venv ~/lf-env && source ~/lf-env/bin/activate
pip install langfuse openai
export LANGFUSE_PUBLIC_KEY=\"pk-lf-…\"
export LANGFUSE_SECRET_KEY=\"sk-lf-…\"
export LANGFUSE_HOST=\"http://<ip-de-instancia>:3000\" # usa el puerto que expusiste — 3001 si lo remapeaste en el Paso 1
export WEC_API_KEY=\"sk-tu-clave-wec\"
import os
from langfuse.openai import openai # drop-in: auto-traza cada llamada
from langfuse import get_client
client = openai.OpenAI(
base_url=\"https://inference.wiline.com/v1\",
api_key=os.environ[\"WEC_API_KEY\"],
timeout=30, # SIEMPRE establece esto — un backend lento cuelga indefinidamente de lo contrario
)
def classify(ticket: str) -> str:
resp = client.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\",
name=\"ticket-classify\", # nombra el rastreo en Langfuse
messages=[{\"role\": \"user\", \"content\":
\"Clasifica este ticket de soporte. Devuelve SOLO JSON con claves \"
\"categoría (facturación/técnico/cuenta/otro), prioridad (baja/media/alta), \"
f\"resumen. Ticket: {ticket}\"}],
)
return resp.choices[0].message.content
if __name__ == \"__main__\":
print(classify(\"Me cobraron dos veces este mes.\"))
get_client().flush() # empuja los rastros antes de que el proceso termine
Ejecuta el código, luego abre Trazado — la llamada aparecerá en segundos con entrada, salida, latencia, conteos de tokens, y (una vez que agreguemos precios) costo.
\n![\"Un](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-first-trace-f013e891fddc5d65b3525d5e1ad59fb7.png\")
\nFigura 2. Una llamada ticket-classify en Langfuse: el prompt, la salida JSON, latencia (~1.2s),\ny conteos de tokens — capturados sin código adicional alrededor de la solicitud.
El cliente de OpenAI no tiene un tiempo de espera predeterminado. Si el modelo es lento o el backend se detiene, tu\naplicación se cuelga indefinidamente — sin error, sin rastreo. timeout=30 convierte eso en un fallo rápido y visible.
Una llamada es fácil de registrar; no necesitas Langfuse para eso. El rastreo se justifica en funciones de múltiples pasos,\ndonde muestra toda la cadena como un árbol para que puedas ver qué paso falló. Hagamos que\nla función sea realista — clasifica el ticket, luego redacta una respuesta de esa categoría (dos llamadas WEC) —\ny agrúpalas en un solo rastreo con el decorador @observe:
from langfuse import observe, get_client
from app import client, classify # reutiliza el cliente WEC trazado + clasificador
def draft_reply(ticket: str, category: str) -> str:
resp = client.chat.completions.create(
model=\"Qwen2.5-3B-Instruct\",
name=\"draft-reply\",
messages=[{\"role\": \"user\", \"content\":
f\"Un cliente envió este ticket {category}. Escribe una respuesta corta y útil.\\nTicket: {ticket}\"}],
)
return resp.choices[0].message.content
@observe() # agrupa todo lo que está debajo en UN rastreo
def handle_ticket(ticket: str) -> str:
category = classify(ticket) # span hijo 1
reply = draft_reply(ticket, category) # span hijo 2
return reply
if __name__ == \"__main__\":
print(handle_ticket(\"Me cobraron dos veces este mes.\"))
get_client().flush()
Abre ese rastreo y obtendrás un árbol: handle_ticket → ticket-classify → draft-reply, cada\nhijo con su propia entrada, salida, latencia y tokens. Ahora un fallo tiene una dirección — puedes\napuntar al paso exacto que falló en lugar de adivinar (usamos esto en el Paso 5).
Ahora puedes ver dentro de cualquier llamada LLM en producción — entrada, salida, latencia, tokens — sin\nescribir una línea de código de registro.
Para obtener una señal real (no una llamada), empuja tu conjunto de datos de la parte 3 a través del clasificador para que\nel tablero tenga tráfico que analizar:
\nimport os, json
from langfuse.openai import openai
from langfuse import get_client
from app import classify # reutiliza la función trazada
for line in open(os.path.expanduser(\"~/tickets_dataset.jsonl\")):
if line.strip():
classify(json.loads(line)[\"ticket\"])
get_client().flush()
Ahora el Tablero de inicio muestra rastros a lo largo del tiempo, una distribución de latencia (p50/p95), tokens por\nmodelo, y un total de costos — la vista de \"observa en producción\".
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-scores-dashboard-e46938c8695864fa98dc8afa0e488b3a.png\")
\nFigura 3. Después de reproducir el conjunto de datos de la parte 3: rastros a lo largo del tiempo, una distribución de latencia, tokens\npor modelo, y un total de costos — la vista de \"observa en producción\".
Langfuse calcula automáticamente el costo para los modelos que conoce (OpenAI, Anthropic), pero la API de Inferencia WEC\nno devuelve costo en dólares y Langfuse no conoce los precios de los modelos de WEC — así que el costo muestra $0. Esta es\nla misma brecha que encontramos en parte 1. Soluciona esto una vez:\nConfiguración → Modelos → agregar un modelo que coincida con Qwen2.5-3B-Instruct con tus precios por token de entrada/salida.\nAhora cada rastreo y el tablero muestran el gasto real — el seguimiento de costos que Promptfoo\nno pudo darnos.
La evaluación de CI verifica un conjunto fijo. Aquí evaluamos cada llamada real automáticamente con un LLM-como-juez.\nEste paso parece pura configuración — también es donde encontramos y solucionamos el mejor error de la\nserie.
\nCrea el evaluador a través de Evaluadores → + Nuevo evaluador. Es un asistente de 3 pasos:
\n1. Seleccionar Evaluador — elige la plantilla de Correctitud LLM-como-juez.
\n2. Configurar conexión LLM — el juez necesita un modelo para llamar, y aún no hay ninguno, así que haz clic\n+ Agregar conexión LLM. El diálogo tiene más campos de los que esperarías — aquí está exactamente lo que necesita cada uno:
\nopenaiwec-judge) — solo el nombre de la conexión en Langfusehttps://inference.wiline.com/v1 — crítico; si se deja en blanco, golpea a OpenAI realQwen3.5:9B — la elección del modelo importa mucho aquí, como veráswec-judge y el modelo Qwen3.5:9B → Guardar.![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-llm-connection-e83545064c144db968575c7d85d0c809.png\")
\nFigura 4. El diálogo de Nueva Conexión LLM: adaptador openai, la URL base de la API WEC, modelos\npredeterminados desactivados, y un modelo personalizado agregado — esto es lo que apunta al juez a WEC en lugar de\nOpenAI real.
3. Ejecutar Evaluador — agrega un filtro Nombre = ticket-classify, activa Ejecutar en observaciones entrantes en vivo para que evalúe el nuevo tráfico, y Ejecutar.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-evaluator-config-328cb01c6a061467eca223c1d7266d31.png\")
\nFigura 5. El evaluador de Correctitud — nombre de la evaluación, el filtro ticket-classify, y \"ejecutar en\nobservaciones entrantes en vivo.\"
Configuramos todo, enviamos tráfico fresco… y nada. Sin puntuación en ningún rastreo. Así es como lo\nrastreamos — puedes encontrar la misma pared:
\nLa solicitud ha superado el tiempo de espera después de 120000ms. Cada ejecución, exactamente 120s — así que el juez estaba disparando, su\nllamada LLM simplemente nunca regresó.Qwen2.5-3B-Instruct, rechazó las llamadas a herramientas de inmediato\n(400 instantáneo — una configuración vLLM faltante en el backend; más sobre eso a continuación). Cambiamos a\nQwen3.5:9B, que responde a una llamada directa a la herramienta en ~3s. Aún así, se agotó el tiempo.curl desde el host: 200 en medio segundo. La misma solicitud de estilo juez desde dentro del contenedor worker: ~3s. Modelo, red, contenedor — todo bien.response_format) para que la puntuación regrese en un formato legible por máquina. Reproducir esa forma exacta de llamada expuso el problema: en este backend, las solicitudes de estilo juez al modelo de razonamiento son increíblemente lentas e impredecibles — la solicitud idéntica varió de 3 a 95 segundos en diferentes ejecuciones (el modelo \"piensa\" durante mucho tiempo, y el modo JSON añade sobrecarga). Con el prompt real más largo del juez, las ejecuciones superaron el tiempo de espera de 120s. Nada estaba roto — simplemente era más lento que el tiempo de espera.La solución son dos líneas de configuración. Langfuse lee su tiempo de espera LLM de\nLANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS (predeterminado 120000). Dale espacio:
services:
langfuse-worker:
environment:
LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: \"600000\"
langfuse-web:
environment:
LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: \"600000\"
docker compose up -d langfuse-worker langfuse-web
# verifica que se haya aplicado dentro del contenedor:
docker compose exec langfuse-worker env | grep TIMEOUT
Envía un nuevo rastreo a través de app.py, espera un par de minutos, y:
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-score-on-trace-99653e359fac7e126dc097103602a4e5.png\")
\nFigura 6. Ahí está — Correctitud: 1.00 adjunta a un rastreo ticket-classify en vivo, con\nel razonamiento del juez a un clic de distancia. Cada nueva llamada ahora se evalúa automáticamente.
Ahora puedes calificar automáticamente el tráfico real de producción — y depurar un evaluador que produce\nsilencio: verifica sus Registros, aísla modelo vs. red vs. contenedor, ajusta el tiempo de espera a la realidad.
El juez necesita llamadas a herramientas. Si tu modelo devuelve un 400 en cualquier solicitud de tools, eso\ngeneralmente es la configuración de servicio, no el modelo — en vLLM son las banderas --enable-auto-tool-choice y\n--tool-call-parser. Ese fue nuestro caso: lo informamos, el equipo de la plataforma habilitó las\nbanderas en Qwen2.5-3B-Instruct el mismo día, y el 400 desapareció. Solo la conexión del juez se ve afectada — tu aplicación mantiene su modelo.
La puntuación es lenta (~2 min/puntuación) y eso es el backend, no tú. El modelo de razonamiento \"piensa\"\ndurante mucho tiempo en los prompts del juez — vale la pena informarlo a tu equipo de plataforma (límites de presupuesto de razonamiento, o un backend de decodificación guiada como xgrammar en vLLM). El tiempo de espera elevado mantiene la puntuación confiable mientras tanto.
Una vez que se habilitó la llamada a herramientas en Qwen2.5-3B, lo intentamos como juez — las puntuaciones regresaron en\n2–10 segundos en lugar de ~2 minutos. Pero eran basura: el mismo tipo de respuesta correcta obtuvo\n1, 1, 0 y 0.05 en cuatro ejecuciones, con racionales casi idénticos adjuntos a puntuaciones opuestas. El modelo pequeño llena el formato de puntuación perfectamente; simplemente no puede evaluar realmente.\nImagen espejo del hallazgo de parte 3: el modelo pequeño gana en clasificación y pierde en evaluación — la evaluación es una tarea de razonamiento. Mantén el juez en Qwen3.5:9B: lento pero coherente.
Aquí es donde el árbol de spans da sus frutos. Abre un rastreo handle_ticket y no obtienes un solo blob opaco — obtienes la cadena completa como un árbol, cada paso con su propia entrada, salida, latencia y\ntokens:
![\"Profundizando](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-failing-trace-8fcb77412fc10f743dad85e747382695.png\")
\nFigura 7. El árbol handle_ticket — handle_ticket → ticket-classify → draft-reply — con\nlatencia y tokens por paso. Cada paso tiene una dirección que puedes inspeccionar.
Esa estructura es lo que hace que los fallos de producción sean depurables. Supongamos que un cliente recibe una respuesta sin sentido.\nSin rastreo solo sabrías \"la respuesta fue mala.\" Con el árbol lo expandes y lees cada paso — por ejemplo:
\nticket-classify → categoría: \"facturación\" ✅ correcto — así que el clasificador no es el problema.draft-reply → inventó una política de reembolso que no existe ❌ — el error está en el paso 2.Has localizado el fallo en el paso exacto, entrada y salida — deberías corregir el prompt de draft-reply,\nno perder tiempo en el clasificador. La evaluación fuera de línea te dice que la tasa de aprobación cayó; el rastreo\nte dice qué llamada, en qué entrada, produjo qué salida incorrecta, en qué paso. Y ahora que el Paso 4 evalúa cada llamada, ni siquiera tienes que buscar: filtra Trazado por puntuación baja y los rastros sospechosos emergen por sí mismos — a menudo una redacción que tu conjunto de datos de la parte 3 nunca cubrió, que es exactamente lo que capturas de nuevo a continuación.
Ahora puedes asignar un fallo de producción al paso exacto, entrada y salida — no más adivinanzas\nsobre qué llamada inventó esa política de reembolso.
Un fallo de producción es un caso de prueba faltante — y Langfuse hace que capturarlo sea un clic. Crea\nel conjunto de datos una vez (Conjuntos de datos → + Nuevo conjunto de datos, por ejemplo, fallos-de-producción), luego en cualquier rastreo haz clic en\n+ Agregar a conjuntos de datos y selecciónalo. La entrada y salida del rastreo se completan automáticamente como un nuevo ítem:
![\"Agregando](\"https://development-wec.wiline.com/docs/es/assets/images/langfuse-dataset-loop-9e09a4627451a945e4df5245e6018fe7.png\")
\nFigura 8. \"Agregar a conjuntos de datos\" convierte un rastreo de producción en un nuevo caso de prueba — entrada y salida esperada completadas automáticamente — alimentándolo directamente de nuevo a tu conjunto de datos de la parte 3.
Para automatizarlo, extrae los rastros que has marcado o agregado a un conjunto de datos a través del SDK de Langfuse, escribe\nfilas {ticket, categoría, prioridad} en tickets_dataset.jsonl, y vuelve a ejecutar la evaluación de Promptfoo de la parte 1/parte 3 — ahora cubre el caso del mundo real.
Ahora tu evaluación de CI es más fuerte porque la producción encontró un agujero en ella. Ese es el ciclo virtuoso:\nevaluación fuera de línea → enviar → observar y evaluar tráfico real → capturar fallos → la evaluación fuera de línea se vuelve\nmás fuerte.
\nHas cerrado el ciclo: los fallos de producción ahora hacen que tus evaluaciones sean más fuertes — el ciclo virtuoso que\nmantiene una función de IA buena después de que se envía.
Esa es la etapa de \"mantenerlo bueno después del envío\". La evaluación fuera de línea (partes 1–3) prueba que funciona antes\ndel lanzamiento; esto prueba — y mantiene — que funciona después.
\ndocker compose upOtro servicio ocupa el puerto 3000 (web) o 5432 (Postgres). Las bases de datos no necesitan puertos de host —\nen docker-compose.yml, remapea langfuse-web a un puerto libre (3001:3000) y elimina el mapeo del host de Postgres. Compose fusiona las listas de ports, así que un archivo de anulación con ports: [] no las eliminará; edita el compose directamente.
Casi siempre ENCRYPTION_KEY — debe ser openssl rand -hex 32 (64 caracteres hexadecimales), no base64.\nVerifica docker compose logs langfuse-web.
$0Langfuse no tiene precio para los modelos de WEC por defecto. Agrega el modelo + precios por token en\nConfiguración → Modelos (Paso 3).
\nVerifica Evaluadores → tu evaluador → Registros primero — un error allí te dice que está ejecutándose y\nfallando, no inactivo. Luego empareja el error:
\ntool_choice — la llamada a herramientas no está habilitada para ese modelo en\nel backend de servicio (en vLLM: las banderas --enable-auto-tool-choice / --tool-call-parser).\nDos formas de salir: apunta la Conexión LLM del juez a un modelo donde funcione (Qwen3.5:9B), o pide\na tu equipo de plataforma que habilite las banderas — eso es lo que solucionó Qwen2.5-3B-Instruct para nosotros. De cualquier manera, solo cambia el juez — tu aplicación mantiene su modelo.La solicitud ha superado el tiempo de espera después de 120000ms — la llamada de salida estructurada del juez es más lenta que\nel tiempo de espera predeterminado de Langfuse. Aumenta LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS (Paso 4) y\nconfirma con docker compose exec langfuse-worker env | grep TIMEOUT. Si curl simple es rápido\npero la puntuación aún se agota, no persigas la red — la ruta de salida estructurada es lo que es\nlento, y eso es una solución de backend.Eso no es un colapso — es el modelo de razonamiento generando una larga cadena de pensamiento oculta en los prompts del juez (muy variable: la misma solicitud puede tardar 3s o 95s), además de la sobrecarga de salida estructurada.\nAumentar el tiempo de espera hace que la puntuación sea confiable pero no rápida — la verdadera solución está del lado de la plataforma\n(límites de presupuesto de razonamiento, backend de decodificación guiada).
\nAhora puedes construir, probar, observar y mejorar una sola función WEC. La última etapa es el patrón real\nde la aplicación: RAG — recuperación + generación — con todo de las partes 1–4 integrado\n(salida verificada por esquema, un conjunto de datos de evaluación, y rastreo de Langfuse sobre todo el pipeline). Ahí es donde todo se une.
\n++Tu evaluación pasa el 100% — de los dos casos de prueba que escribiste a mano. Los usuarios reales no expresarán las cosas como tú lo hiciste.
\nEn parte 1 y\nparte 2 construimos un arnés de evaluación real —\nafirmaciones, validación de esquema, una matriz de modelos. Pero dos casos no pueden decirte si tu aplicación funciona;\nsolo pueden decirte que no se bloqueó con dos entradas.
\nEsta guía soluciona eso. La habilidad es producir un conjunto de datos en el que realmente puedas confiar: usamos la\nAPI de Inferencia de WEC para generar tickets etiquetados, luego validarlos y curarlos — porque\nlas etiquetas generadas no son automáticamente correctas, y tratarlas como verdad solo mueve el error.\nEl resultado es datos de prueba reales a gran escala. Cuando finalmente lo ejecutes a través del arnés de la parte 2, la cobertura\nrevela las fallas — malas clasificaciones genuinas y etiquetas debatibles — que dos casos seleccionados a mano ocultan.
\n\nCada paso alimenta al siguiente, terminando en un conjunto de datos que se conecta directamente a la evaluación de la parte 2:
\n\nUna clave de API de Inferencia de WEC — consulta Inferencia → Claves de API.
\njq, curl, y Node.js 22+ (Promptfoo se ejecuta a través de npx).
Tu clave exportada y saneada (una clave pegada a menudo lleva caracteres invisibles):
\nexport WEC_API_KEY='sk-your-key'
export WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
Si una llamada devuelve un 401 / \"clave de API inválida\", tu clave ha expirado o ha sido revocada — genera una\nnueva en Inferencia → Claves de API. Consulta Solución de problemas.
Pide al modelo tickets con sus respuestas — las etiquetas son lo que lo convierte en un conjunto de datos, no\nsolo entradas. Reutilizamos el esquema exacto de la parte 2 (category + priority enums):
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{
\"model\": \"Qwen2.5-3B-Instruct\",
\"temperature\": 0.7,
\"messages\": [{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]
}' | jq -r '.choices[0].message.content'
{\"ticket\":\"Nuestro servidor se cayó inesperadamente y no estamos seguros de qué lo causó.\",\"category\":\"technical\",\"priority\":\"high\"}
{\"ticket\":\"Necesitamos actualizar nuestro plan pero el sistema muestra un mensaje de error al intentar cambiar de planes.\",\"category\":\"account\",\"priority\":\"medium\"}
{\"ticket\":\"Estamos teniendo problemas para acceder a nuestra base de datos y no podemos iniciar sesión.\",\"category\":\"technical\",\"priority\":\"high\"}
... 5 líneas más ...
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-gen-batch-adc9c63dcd4af4c2991e7581ea5908ec.png\")
\nFigura 1. Una única generación: 8 tickets diversos, cada uno ya llevando su etiqueta de category y priority.
JSONL limpio, etiquetas válidas, verdadera diversidad — y regresó en segundos. Elegimos deliberadamente un\nmodelo pequeño y no razonador (Qwen2.5-3B-Instruct) para la generación. Aquí está el porqué de su importancia.
Los modelos razonadores devuelven su cadena de pensamiento en un campo separado reasoning_content — tokens\npor los que pagas pero que nunca usas. Pide a un modelo razonador como Qwen3.5:9B algunos tickets y compara el\nrazonamiento oculto con la respuesta real:
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen3.5:9B\",\"temperature\":0.7,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 3 tickets de soporte al cliente realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL, claves: ticket, category, priority. Sin markdown, sin cercas.\"}]}' \\
| jq '{model, completion_tokens: .usage.completion_tokens, reasoning_chars: (.choices[0].message.reasoning_content|length), answer_chars: (.choices[0].message.content|length)}'
{
\"model\": \"Qwen3.5:9B\",
\"completion_tokens\": 2000,
\"reasoning_chars\": 7116,
\"answer_chars\": 412
}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-gen-usage-5ee23a331ab19ce10dfddd509162743d.png\")
\nFigura 1b. Para solo 3 tickets, Qwen3.5:9B escribió 7,116 caracteres de razonamiento oculto para\nproducir 412 de respuesta — pagas por todos los ~2,000 tokens de finalización. (Los conteos varían por llamada; la\nasimetría no.) Por eso generamos con el pequeño y no razonador Qwen2.5-3B — y es la misma razón por la que esos modelos razonadores tropiezan con la salida estructurada en la matriz de la Parte 5.
Nunca trates los datos generados como verdad absoluta sin verificarlos. Guarda un lote y valida tres\ncosas: cada línea se analiza, cada etiqueta está en el enum, y las clases están razonablemente equilibradas.
\ncurl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen2.5-3B-Instruct\",\"temperature\":0.7,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]}' \\
| jq -r '.choices[0].message.content' > tickets.jsonl
# 1) ¿todas las líneas se analizan como JSON?
jq -e . tickets.jsonl > /dev/null && echo \"todas las líneas son JSON válidos\" || echo \"JSON INVÁLIDO presente\"
# 2) ¿hay etiquetas fuera del enum? (sin filas impresas = todas válidas)
jq -c 'select((.category|IN(\"billing\",\"technical\",\"account\",\"other\")|not) or (.priority|IN(\"low\",\"medium\",\"high\")|not))' tickets.jsonl
# 3) distribución de clases
jq -rs 'group_by(.category)[] | \"\\(.[0].category): \\(length)\"' tickets.jsonl
todas las líneas son JSON válidos
account: 2
billing: 2
other: 1
technical: 3
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-validate-9b1201646866c2062c5e9aa3d093cfd2.png\")
\nFigura 2. Salida de validación — cada línea se analiza, sin etiquetas fuera del enum, y una distribución de clases razonable.
El intuitivo [\"billing\",...] | index(.category) falla con \"No se puede indexar un array con\ncadena\" — dentro del pipe, . es el array, así que .category intenta indexarlo. Usa\n.category | IN(\"billing\", ...) en su lugar. Consulta Solución de problemas.
Un lote de 8 no es suficiente. Repite la llamada varias veces (temperatura más alta para variedad entre\nlotes), concatena, y luego elimina duplicados por texto del ticket:
\nfor i in $(seq 1 5); do
curl -s https://inference.wiline.com/v1/chat/completions \\
-H \"Authorization: Bearer $WEC_API_KEY\" -H \"Content-Type: application/json\" \\
-d '{\"model\":\"Qwen2.5-3B-Instruct\",\"temperature\":0.9,\"messages\":[{\"role\":\"user\",\"content\":\"Genera 8 tickets de soporte al cliente diversos y realistas para una empresa de alojamiento en la nube. Devuelve SOLO JSONL (un objeto JSON por línea), cada uno con claves: ticket (cadena), category (uno de: billing, technical, account, other), priority (uno de: low, medium, high). Sin markdown, sin cercas.\"}]}' \\
| jq -r '.choices[0].message.content // empty'
echo \"lote $i hecho\" >&2
done > tickets_raw.jsonl
# eliminar duplicados por texto del ticket
jq -sc 'unique_by(.ticket)[]' tickets_raw.jsonl > tickets_dataset.jsonl
echo \"crudo: $(wc -l < tickets_raw.jsonl) → deduplicado: $(wc -l < tickets_dataset.jsonl)\"
crudo: 40 → deduplicado: 40
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-scale-dedupe-74ac55864b3da488aa334816e11ede4a.png\")
\nFigura 3. Escalando: 5 lotes → 40 filas después de la eliminación de duplicados exactos.
Cero duplicados exactos en 5 lotes — una buena señal de que el modelo no se está repitiendo.
\nunique_by(.ticket) solo captura texto idéntico. Dos tickets \"el servidor está caído\" redactados de manera diferente son duplicados semánticos y se deslizarán — capturarlos requiere agrupamiento basado en incrustaciones, un paso más avanzado. Para un conjunto de datos inicial, la deduplicación exacta está bien.
Nota el // empty en el filtro jq. Si una llamada falla (clave revocada, tiempo de espera del modelo), la\nrespuesta no tiene contenido y .choices[0].message.content es null — un simple jq -r escribiría la palabra literal null en tu conjunto de datos, envenenándolo silenciosamente. // empty elimina esos,\nasí que una llamada fallida agrega nada en lugar de una fila basura. Siempre verifica el conteo de filas después.\nConsulta Solución de problemas.
Valida las 40 completas de la misma manera que en el Paso 2 (jq -e ., la verificación del enum, y ambas distribuciones).\nLas nuestras resultaron equilibradas: técnico 15 · cuenta 10 · facturación 10 · otro 5; prioridad alta 13 ·\nmedia 14 · baja 13.
Ahora tienes un pipeline repetible para datos de prueba reales — 40 filas etiquetadas, validadas y deduplicadas\ndonde antes tenías dos.
Promptfoo lee casos de prueba desde un CSV: cada columna se convierte en una variable, y la columna especial\n__expected contiene una afirmación por fila. Mapeamos ticket → la variable de prompt y\n__expected → icontains:<la categoría correcta>. jq @csv maneja las comas y comillas\ndentro del texto del ticket:
{ echo 'ticket,__expected'; jq -r '[.ticket, (\"icontains:\" + .category)] | @csv' tickets_dataset.jsonl; } > tests.csv
wc -l tests.csv # 41 = encabezado + 40 filas
El conjunto de datos es el entregable — todo desde aquí es lo que desbloquea. Primer beneficio: una comparación de modelos\nen la que realmente puedes confiar. En dos casos escritos a mano, un ranking es ruido; en 40 filas reales,\netiquetadas es una medición. Agrega cada modelo WEC como proveedor y ejecuta todo el conjunto:
\ncat > promptfooconfig.yaml <<'EOF'
description: \"Clasificador de tickets — matriz de modelos sobre el conjunto de datos sintético de 40 filas\"
providers:
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen3.5-122B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"category\" (uno de: billing, technical, account, other),
\"priority\" (uno de: low, medium, high),
\"summary\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
const m = output.match(/\\{[\\s\\S]*?\\}/);
return m ? m[0] : output;
assert:
- type: is-json
value:
type: object
required: [category, priority, summary]
properties:
category: { type: string, enum: [billing, technical, account, other] }
priority: { type: string, enum: [low, medium, high] }
summary: { type: string }
tests: file://tests.csv
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
El resultado es lo opuesto a lo que \"más grande es mejor\" predeciría:
\n| Modelo | Precisión | Tokens de finalización / ticket |
|---|---|---|
Qwen2.5-3B-Instruct (no razonador) | 85% (34/40) | ~30 |
Qwen3.5:9B (razonador) | 47.5% (19/40) | ~965 |
Qwen3.5-122B (razonador) | 15% (6/40) | ~1,013 |
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-eval-matrix-9ffe20345f2040803fce117f6803a6ff.png\")
\nFigura 4. Mismo conjunto de datos, tres modelos — el pequeño modelo no razonador gana por mucho.
El pequeño modelo no razonador gana decisivamente — y cuanto más grande es el modelo razonador, peor\nlo hace. Los modelos razonadores no son más tontos al clasificar; enterraron el JSON en su\ncadena de pensamiento. Qwen3.5:9B filtra Thinking: … en la salida; Qwen3.5-122B a menudo devuelve\nuna respuesta vacía por completo — todos los ~1,000 tokens gastados razonando, nada parseable queda. También\nqueman ~30× más tokens por ticket, razón por la cual la matriz completa tomó 12m 31s, casi todo\nel tiempo esperando a los dos grandes modelos. Para salida estructurada, pensar en voz alta es una desventaja,\nno una ventaja — un hallazgo contraintuitivo que nunca obtendrías de una tabla de clasificación.
Pero nota lo que realmente hizo posible ese hallazgo: el conjunto de datos. Con dos casos escritos a mano esos\nporcentajes serían lanzamientos de moneda; 40 filas etiquetadas son lo que convierte \"¿qué modelo?\" de una suposición en una\nmedición. La comparación es la recompensa por construir los datos — no un sustituto de ellos.
\nAhora puedes elegir un modelo con evidencia en lugar de sensaciones — algo que ninguna tabla de clasificación puede hacer por\nti, porque no conoce tu tarea.
(El transform captura el primer bloque {…} con una coincidencia no codiciosa *? — un seguro barato para\nmodelos que envuelven JSON en prosa, exactamente como en parte 2.)
category aquí — priority es tu próxima afirmaciónLa columna __expected califica solo la categoría predicha contra la etiqueta. El conjunto de datos también\nlleva una etiqueta de priority que aún no calificamos. Para calificar ambos campos a la vez, agrega una\nafirmación de javascript que analice la salida JSON y compare también priority — el mismo patrón exacto, una verificación más.\nCalificar más de lo que generaste es la forma más barata de hacer una evaluación más estricta.
Toma el ganador — Qwen2.5-3B con 85% (34/40) — y extrae sus 6 tickets fallidos, comparando cada uno\ncon su etiqueta. (__expected no se almacena como una variable — Promptfoo lo consume como la afirmación —\nasí que lee la verdad de la fuente de datos). Debido a que los datos son recién generados, tus fallas exactas\ndiferirán, pero se dividen consistentemente en dos tipos reconocibles — y ninguno es solo \"el modelo es tonto\". Ejemplos representativos:
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-report-541b1a9921d846d5338c1b1547c49bd5.png\")
\nFigura 5. El informe web facilita escanear qué filas fallaron y abrir cada una.
| Ticket | Etiqueta | Por qué es complicado |
|---|---|---|
| \"descuentos educativos para startups…\" | other | Debatible — se trata de precios, así que billing es defensible |
| \"otorgar acceso IAM a S3 a un desarrollador junior…\" | account | Debatible — control de acceso vs infraestructura |
| \"comentarios sobre la documentación de la API…\" | other | Debatible — comentarios vs technical |
| \"actualizar la tarjeta y agregar un usuario…\" | account | Multi-intención — genuinamente dos categorías a la vez |
El resto son malas clasificaciones ordinarias. Las lecciones reales, del día a día:
\nCompromete tickets_dataset.jsonl y tests.csv junto a tu configuración de evaluación, y regenera/crece\nel conjunto de datos a medida que tu producto cambia.
{ \"error\": { \"message\": \"Error de autenticación, clave de API inválida\", \"code\": \"401\" } }
La clave ha expirado, ha sido revocada o está mal formada. Genera una nueva en Inferencia → Claves de API,\nreexporta y vuelve a sanear (tr -cd '[:print:]') en caso de que el pegado haya llevado un carácter invisible.
Esto proviene de [\"billing\", ...] | index(.category) — dentro del pipe, . es el array, así que\n.category indexa el array. Usa el idiom IN() en su lugar:
jq -c 'select((.category|IN(\"billing\",\"technical\",\"account\",\"other\")|not))' tickets.jsonl
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/dataset-ts-jq-index-ec85a2581780363d791db73ff2f03fd0.png\")
\nFigura 6. El error de index(.field) — dentro del pipe, jq intenta indexar el array con una cadena.
nullUna fila null significa que una llamada de generación falló pero el bucle aún escribió su resultado (vacío). Causas habituales: una clave de API expirada/revocada, o el modelo que se agota. Soluciones: extraer con\n.choices[0].message.content // empty para que una llamada fallida escriba nada en lugar de null;\nvuelve a verificar wc -l después de cada ejecución de generación; y si las llamadas se cuelgan, agrega un tiempo de espera por solicitud\n(curl -m 60) y considera un modelo más ligero y rápido para la generación masiva.
__expected es null en el JSON de resultadosEso es esperado — Promptfoo consume la columna __expected del CSV como la afirmación de la fila, así que\nno se mantiene como una variable. Para inspeccionar las etiquetas de verdad para las filas que fallan, léelas de tu\nconjunto de datos fuente (tickets_dataset.jsonl) en lugar del archivo de resultados.
Ahora tienes un conjunto de datos real — pero se ejecuta en CI, fuera de línea. El siguiente paso es observar tu aplicación en\nproducción: autoalojar Langfuse para rastrear cada llamada, seguir la latencia y el costo, y ejecutar\nevaluaciones (usando este conjunto de datos) contra el tráfico en vivo. Ahí es donde las pruebas fuera de línea se convierten en\nuna verdadera observabilidad — y es la próxima publicación de la serie.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/synthetic-eval-datasets-wiline-inference/", "title": "Deja de escribir casos de prueba a mano: genera un conjunto de evaluación con la API de WEC", "summary": "Dos casos de prueba escritos a mano no son una evaluación. Usa la API de Inferencia de WEC para generar un conjunto de datos de evaluación etiquetado — luego valídalo y curátalo, porque las etiquetas generadas no son automáticamente correctas. El resultado es datos de prueba reales a gran escala; aliméntalo a tu arnés y la cobertura revela las malas clasificaciones y las etiquetas debatibles que dos casos ocultarían. Cada comando y resultado es real.", "date_modified": "2026-07-06T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "evals", "promptfoo", "inferencia", "datasets", "synthetic-data", "observabilidad" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/structured-output-evals-wiline-inference/", "content_html": "++\"Devuelve solo JSON\" es una de las instrucciones más comunes en aplicaciones LLM en producción — y una de las menos fiables. Los modelos envuelven JSON en cercas de markdown, añaden una frase amigable, o (si son modelos de razonamiento) narran todo su proceso de pensamiento alrededor de ello. Cualquiera de esos casos rompe un estricto JSON.parse, y tu pipeline se cae.
En esta guía construimos una evaluación de Promptfoo que hace que los modelos de API de Inferencia WEC clasifiquen tickets de soporte en JSON validado por esquema, luego lo endurecemos contra el desorden del mundo real — y lo usamos para elegir un modelo en el que realmente puedes confiar. Esta es la parte 2 de la serie de evaluaciones (consulta parte 1 para la configuración inicial). Todo aquí se ejecutó en vivo contra https://inference.wiline.com.
Cada prueba pasa por el mismo pipeline. El detalle que más importa: el transform se ejecuta en la salida del modelo antes de que la afirmación la vea — eso es lo que nos permite recuperar JSON desordenado antes de validarlo.
Una clave de API de Inferencia WEC — consulta Inferencia → Claves de API.
\nLos nombres de los modelos utilizados aquí (GLM-5.2, gemma4, Qwen2.5-3B-Instruct, qwen3.5:9B) provienen del Hub de Modelos — intercambia por lo que hayas habilitado.
Node.js 22+ y tu clave exportada (Promptfoo se ejecuta a través de npx):
nvm use 24
export WEC_API_KEY='sk-tu-clave'
Si tu primera ejecución da error con Cannot convert argument to a ByteString, tu clave pegada tiene un carácter invisible — consulta Solución de problemas al final.
Haremos algo más cercano a una carga de trabajo real que \"capital de Francia\": clasificar un ticket de soporte en categoría, prioridad y un breve resumen. La mejora clave sobre una verificación básica es el Esquema JSON — impone enums, por lo que un modelo que inventa una categoría falla.
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — salida estructurada (esquema JSON)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
El resultado — 50%, y el fallo es instructivo:
\nticket [zai-org/GLM-5.2]
Me cobraron dos veces por mi instancia… [FALLIDO] ```json
{ \"categoría\": \"facturación\", \"prioridad\": \"alta\", … }
```
Mi VM no arranca después de la última… [APROBADO] { \"categoría\": \"técnica\", … }
✓ 1 aprobado (50%) ✗ 1 fallido (50%)
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-step1-schema-fail-dc2b9c12c0ee29b0086499d5c76f2fd6.png\")
\nFigura 1. Mismo modelo, mismo aviso, temperatura 0 — una respuesta es limpia, la otra está envuelta en ```json cercas, por lo que is-json no puede analizarla.
El contenido es correcto; el formato no lo es. is-json valida tanto \"¿es JSON analizable?\" como \"¿cumple con el esquema?\" — y la salida cercada falla la primera prueba.
transformUn transform se ejecuta en la salida del modelo antes de las afirmaciones. Aquí eliminamos las cercas.\n(Este bloque utiliza cuatro comillas porque la configuración en sí contiene tres comillas).
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — transformación de eliminación de cercas\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
return output.replace(/```json\\n?|\\n?```/g, '').trim();
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Ahora ambos pasan — 2/2. Las cercas se eliminan antes de que is-json vea la salida.
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-step2-transform-pass-14cb388c6725d0aacffeee1bb320f553.png\")
\nFigura 2. El transform elimina las cercas de código, por lo que el ticket que antes fallaba se analiza.
transform necesita un return explícitoUn transform de varias líneas es un cuerpo de función, no una expresión — omite return y obtienes Transform function did not return a value. Consulta Solución de problemas.
En lugar de limpiar después del modelo, pide a la API que emita solo JSON válido a través de response_format. Sin transform esta vez:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — modo JSON (response_format)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
response_format: { type: json_object }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
2/2 APROBADO sin transformación — parece que el modo JSON funciona.
\n![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-step3-jsonmode-6cabcc01d214aaa3b14b1a0842eeb720.png\")
\nFigura 3. Con response_format: json_object, GLM-5.2 devuelve JSON limpio, sin necesidad de transformación.
Pero antes de confiar en response_format, necesitamos probarlo en todos los modelos — porque un solo resultado verde puede ser suerte, no cumplimiento.
Ejecuta la configuración en modo JSON contra los cuatro modelos de chat. Este es el beneficio — una comparación de fiabilidad específica de WEC que no puedes obtener de una tabla de clasificación genérica.
\ncat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — fiabilidad en modo JSON entre modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
4/8. GLM-5.2 y Qwen2.5-3B pasan limpiamente; gemma4 y qwen3.5:9B vierten su razonamiento\n(\"Proceso de Pensamiento…\") en lugar de JSON — a pesar de que response_format está configurado.
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-matrix-responseformat-d227b3a1ca8bffbf85f89ca2da11eb87.png\")
\nFigura 4. response_format configurado en los cuatro — pero los dos modelos orientados al razonamiento lo ignoran.
| Modelo | Resultado | Tokens (2 llamadas) |
|---|---|---|
zai-org/GLM-5.2 | ✅✅ | 202 |
Qwen2.5-3B-Instruct | ✅✅ | 243 |
gemma4 | ❌❌ (razonamiento) | 251 |
qwen3.5:9B | ❌❌ (razonamiento) | 1,757 |
Ahora puedes medir qué modelos realmente honran el modo JSON — en lugar de confiar en la bandera.
response_format haciendo algo?No asumas que el razonamiento fue causado por el modo JSON. Vuelve a ejecutar la misma matriz sin\nresponse_format (usando la transformación de eliminación de cercas en su lugar) y compara:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — matriz sin response_format\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
return output.replace(/```json\\n?|\\n?```/g, '').trim();
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Sigue siendo 4/8 — los mismos modelos fallan. Así que response_format no cambió nada: en WEC hoy es efectivamente un no-op (el backend no está haciendo cumplir el modo JSON). El comportamiento de razonamiento pertenece a los modelos, no a la bandera.
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-matrix-transform-77179c366ad47c9eb5b00fe2b5d92381.png\")
\nFigura 5. Resultado idéntico sin modo JSON — la bandera no estaba haciendo nada.
Lección que merece su propio llamado: no atribuyas un resultado a un cambio hasta que hayas probado el cambio en aislamiento. Una ejecución adicional convirtió una conclusión incorrecta en la correcta.
Los modelos de razonamiento sí emiten JSON — simplemente está enterrado en prosa. En lugar de eliminar cercas,\nextrae el primer bloque { … } de cualquier parte de la salida:
cat > promptfooconfig.yaml <<'EOF'
description: \"API de Inferencia WEC — transformación de extracción de JSON\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- |
Clasifica este ticket de soporte. Devuelve SOLO JSON con claves:
\"categoría\" (una de: facturación, técnica, cuenta, otra),
\"prioridad\" (una de: baja, media, alta),
\"resumen\" (cadena, máximo 12 palabras).
Ticket: {{ticket}}
defaultTest:
options:
transform: |
const m = output.match(/\\{[\\s\\S]*\\}/);
return m ? m[0] : output;
assert:
- type: is-json
value:
type: object
required: [categoría, prioridad, resumen]
properties:
categoría: { type: string, enum: [facturación, técnica, cuenta, otra] }
prioridad: { type: string, enum: [baja, media, alta] }
resumen: { type: string }
tests:
- vars: { ticket: \"Me cobraron dos veces por mi instancia este mes.\" }
assert: [{ type: icontains, value: facturación }]
- vars: { ticket: \"Mi VM no arranca después de la última restauración de instantánea.\" }
assert: [{ type: icontains, value: técnica }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
7/8 — un gran salto. gemma4 y Qwen2.5 recuperan completamente; qwen3.5:9B recupera uno de dos. El\núnico fallo restante es revelador: esa respuesta emitió JSON y luego siguió razonando (con\nmás llaves), por lo que la coincidencia codiciosa { … } capturó en exceso y produjo JSON inválido.
![\"Paso](\"https://development-wec.wiline.com/docs/es/assets/images/json-matrix-extraction-3b34ee4a32f6990e447d9590d51d8911.png\")
\nFigura 6. Extraer el bloque JSON recupera los modelos habladores — pero es una heurística, no una garantía (nota el único fallo por captura excesiva).
La tabla del terminal está bien para una lectura rápida, pero el informe web es donde una matriz como esta cobra vida:
\nnpx -y promptfoo@latest view
El panel en la parte superior te da la imagen de fiabilidad del modelo de un vistazo — las barras de Tasa de Aprobación (%) son las que debes observar aquí: tres modelos altos, qwen3.5:9B sentado en 50%.\nA continuación, cada proveedor es una columna que puedes expandir para ver la salida completa (así es como obtuvimos el fallo por captura excesiva en Figura 10 — el terminal lo trunca).
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/json-view-report-3739e5abd8419ffc8ece8271ff559851.png\")
\nFigura 7. El panel del informe — las barras de Tasa de Aprobación convierten la matriz de modelos en un ranking de un vistazo, y cualquier celda se expande a la salida completa.
Los otros gráficos del informe (el dispersor de aviso frente a aviso) brillan cuando estás A/B-testando\navisos, no modelos — un buen tema para una publicación posterior. Para una ejecución de un solo aviso y múltiples modelos como esta, las barras de Tasa de Aprobación son el gráfico que importa.
Promptfoo sale con un código no cero cuando las pruebas fallan, así que una línea es una puerta (ponlo en un script o\nMakefile, nunca en tu shell interactivo):
npx -y promptfoo@latest eval -c promptfooconfig.yaml \\
&& echo \"✅ aprobado\" \\
|| { echo \"❌ evaluación fallida — bloqueando\"; exit 1; }
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/json-ci-gate-71912b506157c96cfd7daa8e5c81f300.png\")
\nFigura 8. Un fallo real bloquea: 7/8 aprobados, pero la captura excesiva de qwen3.5:9B (del Paso 6)\ndispara la puerta — el código de salida no cero es la señal que CI usa para bloquear un PR.
En GitLab:
\neval:
image: node:22
script:
- npx -y promptfoo@latest eval -c promptfooconfig.yaml
# WEC_API_KEY configurada como una variable CI/CD enmascarada — nunca comprometida.
JSON validado por esquema es ahora una puerta CI — un cambio en el modelo o aviso que rompe el análisis nunca se envía.
GLM-5.2 y Qwen2.5-3B producen JSON válido por esquema de manera fiable\ny son ~8× más baratos que los modelos de razonamiento. Para salida estructurada en WEC, comienza allí.qwen3.5:9B, y gemma4 en el día que probamos) narran su pensamiento\ny cuestan mucho más — malas opciones para JSON estricto.transform es tu red de seguridad — la eliminación de cercas recupera el caso común; la extracción de JSON\nrecupera la mayoría de las salidas habladoras — pero la extracción es una heurística que puede capturar en exceso.response_format es un no-op en WEC hoy — verificado al aislarlo. No confíes en ello;\nvalida en su lugar.Un transform de varias líneas se compila como un cuerpo de función, por lo que necesita un return explícito. output.replace(...) por sí solo no devuelve nada.
options:
transform: |
return output.replace(/.../g, '').trim(); # nota el `return`
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/json-ts-transform-return-764896c26bc05d65d37eac7808ee06fb.png\"){kind=spacer}
\nFigura 9. Sin return, Promptfoo da error en lugar de transformar.
Si is-json falla con \"Se esperaba que la salida fuera JSON válido\" y la respuesta contiene una\nnarración de \"Proceso de Pensamiento…\" / \"Revisión Final…\", estás usando un modelo de razonamiento. A veces emite solo razonamiento; a veces — como a continuación — emite JSON válido y luego sigue hablando, por lo que incluso la extracción del Paso 6 captura en exceso y el análisis falla. Opciones: cambia a\nGLM-5.2 / Qwen2.5-3B, o acepta que la transformación de extracción es un esfuerzo de buena fe, no una garantía.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/json-ts-reasoning-dump-dbfebf9e8d4f5f89e6b2e14b8e0edf50.png\")
\nFigura 10. El caso fallido expandido en el informe: qwen3.5:9B devolvió JSON válido y\ndespués siguió razonando (\"7. Revisión Final…\"), por lo que la extracción capturó en exceso y la afirmación informa \"Se esperaba que la salida fuera JSON válido.\"
Tu clave de API pegada contiene un carácter Unicode invisible. Elimínalo:
\nexport WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/json-ts-bytestring-0bb4979ce94f0775f1fe314315b38e01.png\")
\nFigura 11. Un carácter extraño en la clave activa el encabezado HTTP antes de que se envíe cualquier solicitud.
¿Tienes un caso de salida estructurada que aún se escapa? Esa es la próxima prueba que agregar.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/structured-output-evals-wiline-inference/", "title": "JSON confiable: valida el esquema de la salida estructurada de tu modelo", "summary": "Los LLM prometen JSON y entregan cercas de markdown y razonamiento. Construye una evaluación de Promptfoo que clasifique tickets de soporte en JSON validado por esquema en la API de Inferencia WEC — con transformaciones para recuperar salidas desordenadas, una matriz de fiabilidad del modelo y una puerta CI. Cada comando y resultado es real.", "date_modified": "2026-07-01T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "evals", "promptfoo", "inferencia", "json", "structured-output", "observabilidad" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/eval-models-promptfoo-wiline-inference/", "content_html": "\n+No enviarías código sin pruebas — pero la mayoría de los equipos envían funciones LLM con \"se ve bien para mí.\" Evaluaciones (evals) solucionan eso: defines casos de prueba y criterios de aprobación/fallo, luego mides tu modelo objetivamente — detectando regresiones, comparando modelos y bloqueando despliegues.
\nEn esta guía construirás un verdadero arnés de evaluación con Promptfoo apuntando a la API de Inferencia WEC — el mismo punto final compatible con OpenAI que llamas desde tus aplicaciones. Todo aquí se ejecutó en vivo contra https://inference.wiline.com; las salidas son reales.
Una cuenta de WEC (WiLine Edge Cloud) y una clave API de Inferencia — consulta Inferencia → Claves API.
\nNode.js 22+. Promptfoo considera que Node 20 está al final de su vida útil; con nvm:
nvm install 24 # 24 LTS preferido
nvm use 24
node -v # v24.x
Ejecutaremos Promptfoo con npx — nada que instalar globalmente.
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-api-key-a1aca6bfffa7335651ab59ec1c07d8f4.png\")
\nFigura 1. Crea una clave en Inferencia → Claves API, luego cópiala.
Pon tu clave en la terminal:
\nexport WEC_API_KEY='sk-your-key-here'
Si tu primera evaluación falla con Cannot convert argument to a ByteString, consulta Solución de problemas #1 a continuación.
La API es compatible con OpenAI, por lo que la lista de modelos es un simple GET /v1/models:
curl -s https://inference.wiline.com/v1/models \\
-H \"Authorization: Bearer $WEC_API_KEY\" | jq -r '.data[].id'
zai-org/GLM-5.2
gemma4
Qwen2.5-3B-Instruct
qwen3.5:9B
whisper-large-v3
whisper-medium
whisper-base
Los modelos whisper-* son de voz a texto; el resto son modelos de chat. Evaluaremos los modelos de chat, comenzando con zai-org/GLM-5.2.
Crea una configuración. apiBaseUrl apunta Promptfoo a WEC; apiKeyEnvar le dice qué variable de entorno contiene tu clave:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-first-eval-42c0a9a515e6a1e5af7a6cf5c6a30118.png\")
\nFigura 4. Tu primera evaluación aprobada contra la API de Inferencia WEC.
icontains es una afirmación determinista — una verificación de subcadena que no distingue entre mayúsculas y minúsculas. Barata, rápida y perfecta para hechos con una respuesta conocida.
npx -y promptfoo@latest view
Esto abre una interfaz web local con cada aviso, salida y aprobación/fallo — mucho más fácil de escanear que la terminal una vez que tienes más de unos pocos casos.
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-view-report-b93aa9bcadc4c60e008df1bb5effcd3c.png\")
\nFigura 5. promptfoo view — los mismos resultados en el navegador.
Agregar un proveedor es un bloque adicional. Aquí agregamos Qwen2.5-3B-Instruct junto a GLM-5.2 y ejecutamos los mismos dos casos de prueba contra ambos:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — comparación de modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
- id: openai:chat:Qwen2.5-3B-Instruct
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-two-model-3c6c51ea8839c03dd51d270c78648ec9.png\")
\nFigura 6. Ambos modelos aprueban. Los resultados de GLM-5.2 se sirven desde caché (0 nuevas solicitudes); solo Qwen2.5 realiza llamadas en vivo.
Las verificaciones de subcadenas no pueden juzgar una respuesta abierta. Una afirmación llm-rubric calificada por el modelo utiliza un modelo para puntuar la salida contra criterios — y el calificador puede ejecutarse en WEC también, por lo que no necesitas un proveedor externo:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — calificación por modelo (rúbrica LLM)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
defaultTest:
options:
provider: # el modelo calificador
id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
prompts:
- \"Explica qué es un {{topic}} en dos oraciones, para un principiante.\"
tests:
- vars: { topic: VPC }
assert:
- type: llm-rubric
value: \"Describe una VPC como una red virtual privada e aislada en la nube, y es comprensible para un principiante.\"
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-llm-rubric-f969ad98a43427eacf9f83f13f2e6dde.png\")
\nFigura 7. La ejecución muestra dos líneas de tokens — Eval (75) y Grading (350) — porque la verificación de rúbrica es en sí misma una llamada de modelo.
Las verificaciones calificadas por el modelo son poderosas, pero no son gratuitas.
\nUna respuesta correcta que toma 30 segundos sigue siendo un problema de producción. Agrega un límite de latencia a defaultTest (se aplica a cada caso). Siempre ejecuta con --no-cache — las respuestas en caché informan ~0 ms y pasarían la puerta gratis:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — límite de latencia\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
defaultTest:
assert:
- type: latency
threshold: 5000 # fallar cualquier cosa más lenta que 5 s
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
Esto falló — las respuestas eran correctas (Paris, Tokyo) pero ambas llamadas tomaron ~33 s, activando la puerta de 5 s:
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-latency-fail-ab40e8dc4386c6acd496942ee3a490aa.png\")
\nFigura 8. La línea de defensa se activa: respuestas correctas, latencia incorrecta. Duración: 33s.
Aumenta el umbral a algo realista y vuelve a ejecutar:
\nsed -i 's/threshold: 5000/threshold: 60000/' promptfooconfig.yaml
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-latency-pass-f3fa1a1c9cb0a11a87328b2a15ef1f31.png\")
\nFigura 9. Con un umbral de 60 s, las mismas llamadas pasan fácilmente — Duración: 2s.
Las llamadas consecutivas al mismo modelo variaron de ~2 s a ~33 s en el mismo día. Ejecuta algunos pases --no-cache para obtener una línea base realista antes de fijar tu umbral.
La afirmación de cost no funciona contra WEC (consulta Solución de problemas #2). Usa latencia + max_tokens juntos como tu línea de defensa de producción en su lugar:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — líneas de defensa (latencia + límite de tokens)\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
max_tokens: 16
defaultTest:
assert:
- type: latency
threshold: 30000
prompts:
- \"Responde en una sola palabra. ¿Cuál es la capital de {{country}}?\"
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-latency-token-cap-968bf5b53dd3edf6d77129f011e4a66f.png\")
\nFigura 11. Con un umbral de 30 s y un límite de 16 tokens, ambos casos aprueban.
Las aplicaciones reales quieren JSON, no prosa. is-json verifica que la salida sea un JSON válido y coincida con un esquema en una afirmación:
cat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — validación de esquema JSON\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config:
apiBaseUrl: https://inference.wiline.com/v1
apiKeyEnvar: WEC_API_KEY
temperature: 0
prompts:
- 'Devuelve SOLAMENTE un objeto JSON (sin markdown, sin prosa) con claves \"capital\" (cadena) y \"population_millions\" (número) para el país {{country}}.'
defaultTest:
assert:
- type: is-json
value:
type: object
required: [capital, population_millions]
properties:
capital: { type: string }
population_millions: { type: number }
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-json-schema-82dcc59881029f9bc0134dcf5a5c5ea2.png\")
\nFigura 12. GLM-5.2 devuelve JSON compacto y válido según el esquema en el primer intento.
Aquí está lo que no puedes obtener en ningún otro lugar — la misma prueba estricta de JSON a través de todos los modelos de chat en tu cuenta:
\ncat > promptfooconfig.yaml <<'EOF'
description: \"Evaluación de API de Inferencia WEC — matriz de modelos\"
providers:
- id: openai:chat:zai-org/GLM-5.2
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:gemma4
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:Qwen2.5-3B-Instruct
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
- id: openai:chat:qwen3.5:9B
config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
- 'Devuelve SOLAMENTE un objeto JSON (sin markdown, sin prosa) con claves \"capital\" (cadena) y \"population_millions\" (número) para el país {{country}}.'
defaultTest:
assert:
- type: is-json
value:
type: object
required: [capital, population_millions]
properties:
capital: { type: string }
population_millions: { type: number }
tests:
- vars: { country: France }
assert: [{ type: icontains, value: Paris }]
- vars: { country: Japan }
assert: [{ type: icontains, value: Tokyo }]
- vars: { country: Brazil }
assert: [{ type: icontains, value: Bras }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-model-matrix-table-fcebe135ddd276ef881fc83a726c6b96.png\")
\nFigura 13a. 12 casos de prueba a través de 4 modelos — 9 aprobados, 3 fallidos. qwen3.5:9B emite su cadena de pensamiento en lugar de JSON.
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-model-matrix-summary-96e3ce6b439ae8d487aef486120dbe97.png\")
\nFigura 13b. La descomposición de tokens cuenta la verdadera historia: el modelo de razonamiento costó 13× más para la misma tarea.
| Modelo | ¿JSON Estricto? | Notas | Tokens (3 llamadas) |
|---|---|---|---|
zai-org/GLM-5.2 | ✅ todos aprueban | JSON compacto | 177 |
gemma4 | ✅ todos aprueban | poblaciones enteras | 207 |
Qwen2.5-3B-Instruct | ✅ todos aprueban | JSON bien formateado, preciso | 262 |
qwen3.5:9B | ❌ todos fallan | modelo de razonamiento — emite su \"pensamiento\" en lugar de JSON crudo | 2,650 |
Dos lecciones se desprenden de inmediato:
\nqwen3.5:9B es un modelo de razonamiento. \"Piensa en voz alta\", por lo que rompe el JSON estricto a menos que elimines el razonamiento o uses una restricción de formato de respuesta. Elegirlo para salida estructurada fallaría silenciosamente.Esa es una decisión de selección de modelo que ahora puedes defender con datos — para tus cargas de trabajo, no una tabla de clasificación genérica.
\nAhora puedes comparar cada modelo en tu punto final con números objetivos y repetibles — precisión, latencia y costo lado a lado.
Promptfoo sale no cero (100) cuando cualquier prueba falla. Verifica esto primero:
npx -y promptfoo@latest eval -c promptfooconfig.yaml > /dev/null 2>&1; echo \"código de salida: $?\"
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-exit-code-a3471bde65e7ebf24feaf0d964a3b7eb.png\")
\nFigura 14. El código de salida 100 confirma que Promptfoo señala fallos de manera confiable — exactamente lo que necesita CI.
Conéctalo como una puerta:
\nnpx -y promptfoo@latest eval -c promptfooconfig.yaml \\
&& echo \"✅ evaluación aprobada\" \\
|| { echo \"❌ evaluación fallida — bloqueando\"; exit 1; }
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-ci-gate-table-7067b62a9b737ed79e3906b6da54ea2a.png\")
\nFigura 15a. La puerta vuelve a ejecutar la evaluación de matriz desde caché — mismo resultado 9/3.
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-ci-gate-result-8765593b4f037c480e7fcef844ff6eb4.png\")
\nFigura 15b. Promptfoo sale no cero, se activa la rama ||, y la puerta bloquea.
Nunca ejecutes la variante exit 1 en tu terminal interactiva — consulta Solución de problemas #3.
En CI, ni siquiera necesitas el exit 1 — la salida no cero falla el trabajo. En GitLab:
eval:
image: node:22
script:
- npx -y promptfoo@latest eval -c promptfooconfig.yaml
# WEC_API_KEY se establece como una variable CI/CD enmascarada — nunca la cometas.
Ahora un cambio de aviso que silenciosamente rompe la salida JSON, o un cambio de modelo que duplica la latencia, falla la canalización antes de que llegue a los usuarios.
\nTu evaluación es ahora una puerta de despliegue — las regresiones fallan CI en lugar de llegar a los usuarios.
Error de llamada a la API: TypeError: Cannot convert argument to a ByteString because
the character at index 32 has a value of 8232 which is greater than 255.
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-invisible-char-error-540ad4b2ab9242c120ae80870319df01.png\")
\nFigura 2. Cada llamada a la API falla antes de llegar al servidor — la clave nunca siquiera sale de la máquina.
Causa: La clave pegada contiene un carácter Unicode invisible — U+2028 (separador de línea). Algunos terminales y administradores de portapapeles lo insertan silenciosamente al copiar de ciertas fuentes.
\nSolución: Elimina los caracteres no imprimibles de la clave:
\nexport WEC_API_KEY=$(printf '%s' \"$WEC_API_KEY\" | LC_ALL=C tr -cd '[:print:]')
printf 'len=%s\\n' \"$(printf %s \"$WEC_API_KEY\" | wc -c)\"
# len=25
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-key-strip-1a9c78d8c230c69db3e89eecfdfa24ca.png\")
\nFigura 3. Después de eliminar, la longitud de la clave confirma que no quedan caracteres adicionales. Vuelve a ejecutar la evaluación — pasa.
Error: La afirmación de costo no admite proveedores que no devuelven costo
![\"Terminal:](\"https://development-wec.wiline.com/docs/es/assets/images/promptfoo-cost-error-1615b4a5c8b0973274d32c6d658a2e12.png\")
\nFigura 10. La API de Inferencia WEC no devuelve un campo de costo en sus respuestas.
Causa: Promptfoo calcula el costo buscando un precio por token para el modelo en su lista de precios incorporada y multiplicando por los tokens utilizados. Tiene precios para los grandes modelos alojados pero no para los nombres de modelos autoalojados de WEC, por lo que no tiene un precio que aplicar y la afirmación falla. (La mayoría de las API, incluida OpenAI, no devuelven un costo en dólares en la respuesta — las herramientas lo calculan).
\nSolución: Omite la afirmación de cost por completo. Realiza un seguimiento del gasto desde la línea Total Tokens que Promptfoo imprime al final de cada ejecución, y usa max_tokens en la configuración del proveedor para limitar el uso de tokens por llamada.
exit 1 cierra tu sesión SSH❌ evaluación fallida — bloqueando
logout
Conexión a 10.80.4.212 cerrada.
Causa: Ejecutar || { echo \"❌ evaluación fallida — bloqueando\"; exit 1; } directamente en una terminal interactiva cierra el proceso de la terminal en sí — lo que, a través de SSH, cierra la conexión.
Solución: Coloca la puerta en un contexto no interactivo: un objetivo de Makefile, un script de npm, un gancho pre-commit de git, o un trabajo de CI. En esos entornos, exit 1 falla el trabajo sin tocar tu terminal. Si necesitas probar la puerta localmente, usa || echo \"❌ evaluación fallida\" (sin exit 1) para ver la salida de forma segura.
Has pasado de \"se ve bien para mí\" a un verdadero arnés de evaluación automatizable en WEC — con verificaciones deterministas, líneas de defensa, validación de esquemas, rúbricas calificadas por modelos, una matriz de modelos, y una puerta CI.
\nPróximamente en esta serie:
\nllm-rubric, puntuación de factualidad, y verificaciones de múltiples jueces para que tu calificador sea confiable.+A través de Partes 1–4 implementaste\nOpenClaw, lo aseguraste con HTTPS, añadiste Telegram y lo hiciste privado a través de una\nmalla NetBird — todo apuntando a OpenAI. Esta parte intercambia el modelo por debajo:\napunta el mismo agente a Modelos WEC — la inferencia compatible con OpenAI de WiLine —\ny ejecútalo en un modelo de peso abierto, Llama 3.1 8B Instruct. Misma caja, sin reconstrucción\n— solo un cambio de base-URL, clave y modelo a través de la CLI de OpenClaw.
\n\nContinúa en la misma Instancia WEC de las Partes 1–4. Modelos WEC es un\npunto final compatible con OpenAI en https://inference.wiline.com/v1; cada comando\na continuación se ejecutó contra un contenedor de puerta de enlace OpenClaw en vivo\n(openclaw-openclaw-gateway-1).
Si autoalojaste el agente para empezar, ya te importa el control — no\ndepender de la nube de otra persona, no estar a un correo de la página de precios de\nreconstrucción. Pero hay una brecha en esa historia: el agente se ejecuta en tu caja, y cada\nmensaje que maneja todavía se envía a OpenAI para que lo procese. Autoalojar\nel agente y externalizar el modelo es solo la mitad del trabajo. Esta parte lo cierra.
\nTambién es más barato. El catálogo propio de WEC fija el precio de Llama3.1-8B-Instruct en\n$0.15 / 1M tokens de entrada · $0.20 / 1M tokens de salida. OpenAI no publica una\ntarifa independiente para gpt-5.5 (el modelo que OpenClaw utiliza por defecto en\nParte 1) más, pero su miembro familiar más cercano\nactual — GPT-5.6 \"Terra\", presentado por OpenAI como\n\"competitivo en rendimiento con GPT-5.5\" — se lista en\n$2.50 / 1M en · $15 / 1M fuera. Esa es una comparación aproximada, no un\nbenchmark de manzanas a manzanas — el movimiento honesto, como siempre en este blog, es\nevalúalo en tu propia carga de trabajo\nen lugar de confiar en el número de ningún proveedor. Pero la dirección es lo suficientemente clara como para valer los diez minutos que esto toma.
openclaw-openclaw-gateway-1.Consulta Inferencia → Claves API si no\ntienes una (la misma clave de\nParte 1 de la serie de evaluaciones\nfunciona bien aquí).
\n\nFigura 1. Crea una clave en Inferencia → Claves API, luego cópiala.
Mantenla fuera de tu historial de terminal — ponla en un archivo en lugar de exportarla\ndirectamente:
\necho 'WEC_API_KEY=sk-wec-...' >> env.local
source <(grep -v '^#' env.local | sed 's/^/export /')
Consulta el punto final compatible con OpenAI /v1/models para ver qué está activo en tu Instancia WEC:
curl -s -H \"Authorization: Bearer $WEC_API_KEY\" https://inference.wiline.com/v1/models
La respuesta lista cada modelo disponible para tu clave, junto con el id que\nutiliza este tutorial:
\n{\"data\":[
...,
{\"id\":\"Llama3.1-8B-Instruct\",\"object\":\"model\",\"created\":1677610602,\"owned_by\":\"openai\"},
...
]}
Los ids de modelo en WEC no siempre son el nombre de visualización mostrado en el portal — siempre toma\nel id exacto de esta respuesta, no una suposición.
No edites manualmente openclaw.json — usa openclaw config set. Valida el\narchivo completo en cada escritura, por lo que un error tipográfico falla ruidosamente en lugar de romper\nsilenciosamente la puerta de enlace. Un proveedor personalizado necesita su base URL, su estilo de API y su lista de modelos declarados juntos, en una sola escritura — el esquema rechaza un proveedor que\nfalta alguno de los tres, así que construye el objeto completo desde el principio:
docker exec openclaw-openclaw-gateway-1 openclaw config set models.providers.wec '{
\"baseUrl\": \"https://inference.wiline.com/v1\",
\"api\": \"openai-completions\",
\"models\": [
{\"id\": \"Llama3.1-8B-Instruct\", \"name\": \"Llama 3.1 8B Instruct\"}
]
}' --strict-json
Updated models.providers.wec. Change will apply without restarting the gateway.
Eso registra WEC como un proveedor, pero aún no está autenticado. No pongas la\nclave directamente en ese JSON — la configuración de composición de OpenClaw mantiene las claves API fuera de\nlas variables de entorno por completo y las almacena en un directorio de secretos dedicado respaldado por archivos en su lugar (OPENCLAW_AUTH_PROFILE_SECRET_DIR, montado en el\ncontenedor). Pasa la clave al propio almacén de autenticación de OpenClaw y deja que haga la conexión:
echo \"$WEC_API_KEY\" | docker exec -i openclaw-openclaw-gateway-1 openclaw models auth paste-api-key --provider wec
Updated config: $OPENCLAW_HOME/.openclaw/openclaw.json
Backup: $OPENCLAW_HOME/.openclaw/openclaw.json.bak
Auth profile: wec:manual (wec/api_key)
Verifica que el proveedor y su autenticación se resolvieron juntos, luego haz que el modelo\nsea el predeterminado para que cada agente lo recoja sin configuración adicional:
\ndocker exec openclaw-openclaw-gateway-1 openclaw models list
docker exec openclaw-openclaw-gateway-1 openclaw models set wec/Llama3.1-8B-Instruct
Modelo Entrada Ctx Autenticación Local Etiquetas
wec/Llama3.1-8B-Instruct texto 200k no sí configurado
openai/gpt-5.5 texto 200k no sí configurado,alias:GPT
...
Updated config: $OPENCLAW_HOME/.openclaw/openclaw.json
Backup: $OPENCLAW_HOME/.openclaw/openclaw.json.bak
Modelo predeterminado: wec/Llama3.1-8B-Instruct
![\"Terminal](\"https://development-wec.wiline.com/docs/es/assets/images/openclaw-wec-models-list-bb96e6c9a1dfe7d0c98be4a6b5b40ae6.png\")
\nFigura 2. wec/Llama3.1-8B-Instruct, autenticado y establecido como el modelo predeterminado.
OpenClaw puede ejecutar más de un agente por puerta de enlace, así que cada mensaje necesita un\nobjetivo — pasa --agent, coincidiendo con lo que openclaw agents list llama tu\nagente (main, a menos que lo hayas renombrado):
docker exec openclaw-openclaw-gateway-1 openclaw agents list
Agentes:
- main (predeterminado)
Espacio de trabajo: $OPENCLAW_HOME/.openclaw/workspace
Modelo: wec/Llama3.1-8B-Instruct
Reglas de enrutamiento: 0
Envíale un mensaje y ve quién responde:
\ndocker exec openclaw-openclaw-gateway-1 openclaw agent --agent main --message \"¿Cuál es la capital de Francia?\"
París es la capital de Francia.
Eso es WEC, en Llama 3.1, sin OpenAI en el circuito.
\n![\"Terminal](\"https://development-wec.wiline.com/docs/es/assets/images/openclaw-wec-agent-verified-e5125e1d417f258ba73f9d11b78244ff.png\")
\nFigura 3. El agente, ejecutándose en Llama 3.1 8B Instruct a través de WEC.
¿Quieres que sea más rápido? Desactiva el modo de pensamiento — es un comando de barra dentro del\nchat, no un comando de terminal:
\ndocker exec openclaw-openclaw-gateway-1 openclaw agent --agent main --message \"/think off\"
El modo de pensamiento ha sido desactivado.
O haz que se mantenga para cada sesión:
\ndocker exec openclaw-openclaw-gateway-1 openclaw config set agents.defaults.thinkingDefault \"off\"
Updated agents.defaults.thinkingDefault. No se necesita reiniciar la puerta de enlace.
\"los proveedores de modelos personalizados deben declarar modelos\" — declara baseUrl, api,\ny models juntos, en una sola llamada config set. Un proveedor personalizado que\nfalta alguno de los tres es rechazado; no puedes añadir models en una escritura posterior.
\"models.providers.wec.apiKey no está resuelto en la instantánea de tiempo de ejecución activa\"\n— no establezcas apiKey en el objeto del proveedor; deja que models auth paste-api-key\nlo posea (Paso 3). ¿Ya estableciste uno? Elimínalo:
docker exec openclaw-openclaw-gateway-1 openclaw config unset models.providers.wec.apiKey
\"No se seleccionó ninguna sesión de destino\" — siempre pasa --agent <id> con\nopenclaw agent. Verifica el id con openclaw agents list primero si no estás\nseguro (main, a menos que lo hayas renombrado).
-bash: /think: No such file or directory — /think es un comando de barra\npara dentro del chat, no un comando de terminal. Pásalo a través de --message en su lugar,\ncomo en el Paso 5.
Con el agente ejecutándose en nuestro propio modelo, el siguiente paso es medirlo —\nevaluando la calidad de las respuestas con Promptfoo + Modelos WEC.
\n+![\"SQLite\"](\"https://development-wec.wiline.com/docs/es/assets/images/SQLite370-e02c30e84f9e098787bb57701b0b7232.png\")
Hermes Agent es el agente de IA de código abierto\n(MIT) de Nous Research — \"el agente que crece contigo.\" Su característica destacada es\nmemoria persistente: aprende sobre tus proyectos y no olvida entre reinicios. Esta guía lo despliega en la misma Instancia WEC que ya usas para\nOpenClaw, lo apunta a un modelo y prueba que la memoria sobrevive a un reinicio completo.
\n\nFunciona en la misma Instancia WEC de la serie OpenClaw — sin nueva VM. El instalador\ndescarga su propio Python (a través de uv), herramientas de navegador Node.js y un Chromium\nde Playwright automáticamente. El estado se guarda en ~/.hermes/. La puerta de enlace de mensajería se ejecuta como un servicio de usuario systemd, por lo que coexiste con la pila Docker de OpenClaw. Capturado en vivo en Ubuntu\n22.04 con hermes v0.17.0.
Un agente que olvida en cada reinicio es un juguete. Hermes mantiene un almacenamiento duradero en\ndisco bajo ~/.hermes/:
~/.hermes/memories/MEMORY.md — un archivo legible por humanos de hechos que el agente ha\ndecidido recordar.~/.hermes/state.db — una base de datos SQLite que contiene cada sesión y mensaje,\ncon índices de búsqueda de texto completo FTS5 superpuestos para que el agente pueda buscar su propia\nhistoria.Un despliegue, un fallo o un reinicio no borran lo que aprendió. Esa es la diferencia entre\nuna demostración de chat y un agente en el que puedes confiar día a día — y es exactamente lo que probamos al\nfinal.
\nTodo se ejecuta en una Instancia WEC. Hermes se comunica con un modelo a través de la API de Inferencia WEC,\nmantiene su memoria en disco local y se ejecuta como un servicio de usuario systemd — por lo que se reinicia solo\ndespués de un reinicio y su memoria sigue ahí:
\n\nglm-5.2 también funcionan).curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
![\"Ejecutando](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-install-start-1f3d29fcdd9d66dd1e5c1bc28b3c9e5d.png\")
El instalador resuelve un entorno virtual de Python con uv, instala las herramientas de navegador de Node.js, descarga un Chromium de Playwright, sincroniza las habilidades empaquetadas y coloca un\nlanzador hermes en ~/.local/bin:
✓ Paquete principal instalado (verificado por hash a través de uv.lock)
✓ Todas las dependencias instaladas
✓ Configuración del motor de navegador completa
✓ Lanzador hermes instalado → ~/.local/bin/hermes
✓ Directorio de configuración listo: ~/.hermes/
→ Iniciando asistente de configuración...
Luego lanza automáticamente el asistente de configuración. Recarga tu shell después para que el\ncomando hermes esté en tu PATH:
source ~/.bashrc
El asistente guía a través del tipo de configuración, backend de terminal y mensajería. En una caja que\nya ejecutó OpenClaw, ofrece importar la configuración antigua primero — puedes previsualizar\nlo que se migraría antes de que cambie algo.
\nLa primera elección es cómo configurar Hermes:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-setup-choice-0db3a3f64faec3d72e3477b075af1901.png\")
Elegimos Configuración Rápida primero. El inicio de sesión en el Portal mostró un código de dispositivo y se quedó en\n\"Esperando aprobación (sondeando)\" — necesita una suscripción activa al Portal, que esta\ncuenta no tenía. Presionamos Ctrl+C para cancelar y en su lugar trajimos nuestro propio\nmodelo en el Paso 3 (a continuación) con una clave de OpenAI. Si tienes un plan de Portal, completa\nel inicio de sesión aquí y puedes omitir el Paso 3.
Para el resto del asistente:
\nhermes setup gateway).El asistente aplica valores predeterminados sensatos para el agente (máximo de iteraciones, un umbral de compresión de contexto del 50%) y termina con un resumen de disponibilidad de herramientas.
\nFuera de la caja, el modelo predeterminado se enruta a través del Nous Portal / OpenRouter y necesita\nuna clave. Para usar tu propio proveedor en su lugar, ejecuta:
\nhermes setup model
Luego selecciona OpenAI ▸ OpenAI API, pega tu clave de API cuando se te pida (se escribe en\n~/.hermes/.env — nunca se muestra), acepta la URL base predeterminada\nhttps://api.openai.com/v1, y elige un modelo — usamos gpt-5.5:
Clave de API guardada.
URL base [https://api.openai.com/v1]:
Seleccionar modelo predeterminado:
→ (●) gpt-5.5
![\"Eligiendo](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-model-select-2b0c5452d2e217ff8692c022badd9b28.png\")
Para ejecutar inferencias en el propio endpoint de WiLine, elige Endpoint personalizado, establece la URL base\nen https://inference.wiline.com/v1, pega tu clave de API de WEC y usa un modelo como\nglm-5.2. Mismo flujo compatible con OpenAI.
Confirma que el modelo y la clave están saludables:
\nhermes doctor
◆ Archivos de configuración
✓ El archivo ~/.hermes/.env existe
✓ Clave de API o endpoint personalizado configurado
...
◆ Proveedor de memoria
✓ Memoria incorporada activa (no se configuró proveedor externo — esto está bien)
Las líneas restantes ⚠ en doctor son integraciones de herramientas opcionales (búsqueda web,\nDiscord, generación de imágenes) — no necesarias para esta guía.
Inicia una sesión interactiva:
\nhermes
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-tui-welcome-842b22f5c733599e17b84cde75db4933.png\")
Envíale un hecho y pídele que lo recuerde — observa cómo se activa la herramienta 🧠 memory:
● Por favor guarda en tu memoria a largo plazo: mi nombre en clave del proyecto WEC es
Bluefin-7, ejecutándose en la caja de OpenClaw.
┊ 🧠 memory ? 0.0s
╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
Guardado en la memoria a largo plazo: tu nombre en clave del proyecto WEC es Bluefin-7,
ejecutándose en la caja de OpenClaw.
╰─────────────────────────────────────────────────────────────────────╯
![\"Hermes](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-memory-save-458cefa8aaf46e0d1cc554418a3acc38.png\")
Esa escritura crea ~/.hermes/memories/MEMORY.md. Sal con /exit o Ctrl+D.
El TUI envía al presionar enter, por lo que pegar texto de varias líneas puede enviar un mensaje medio escrito.\nSi un prompt solo captura un fragmento, escríbelo en una línea a mano.
Este es el objetivo principal. La puerta de enlace de Hermes está instalada como un servicio de usuario systemd\ncon linger habilitado, por lo que vuelve automáticamente después de un reinicio — sin necesidad de iniciar sesión.\nReinicia el servicio y luego reinicia toda la caja para hacer la prueba a prueba de fallos:
\nsystemctl --user restart hermes-gateway # reinicia solo el servicio de puerta de enlace
sudo reboot # luego reinicia toda la caja
![\"Reiniciando](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-reboot-ae228254579427ae3018547803f83c62.png\")
Reconéctate una vez que la caja esté activa y confirma que el servicio se reinició por sí mismo:
\nsystemctl --user status hermes-gateway --no-pager
● hermes-gateway.service - Puerta de enlace del Agente Hermes - Integración de Plataforma de Mensajería
Loaded: loaded (...; enabled; vendor preset: enabled)
Active: active (running) since Thu 2026-06-25 21:21:54 UTC; 1min 36s ago
![\"systemctl](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-gateway-status-4da5472c10ec41fe81cfc64298589f10.png\")
Ahora abre una sesión nueva y pregunta — sin contexto previo, ID de sesión completamente nuevo:
\nhermes
● ¿Cuál es mi nombre en clave del proyecto WEC, y en qué caja se ejecuta?
╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
Tu nombre en clave del proyecto WEC es Bluefin-7, y se ejecuta en la
caja de OpenClaw.
╰─────────────────────────────────────────────────────────────────────╯
![\"Una](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-reboot-recall-eac2b093a48d12569fa730340f5751d3.png\")
Recordó el hecho desde el disco después de un reinicio completo. Inspecciona dónde vive ese estado duradero:
\ncat ~/.hermes/memories/MEMORY.md
file ~/.hermes/state.db && du -h ~/.hermes/state.db
El nombre en clave del proyecto WEC del usuario es Bluefin-7, ejecutándose en la caja de OpenClaw.
/home/ubuntu/.hermes/state.db: base de datos SQLite 3.x, ...
176K\t/home/ubuntu/.hermes/state.db
Un MEMORY.md en texto plano que puedes leer y editar, respaldado por un state.db de SQLite para\nsesiones. Esa es la memoria persistente — y acaba de sobrevivir a un reinicio.
Cuando le pides a Hermes que recuerde algo, escribe el hecho en\n~/.hermes/memories/MEMORY.md — Markdown plano que puedes abrir, leer e incluso editar a mano. Por separado, tu historial completo de conversación se guarda en\n~/.hermes/state.db, una base de datos SQLite. Ambos viven en disco, por lo que un\nreinicio no los pierde.
La forma más sencilla de ver lo que sabe el agente es simplemente leer el Markdown:
cat ~/.hermes/memories/MEMORY.md
Para mirar dentro de la base de datos, ten en cuenta que el motor de SQLite está integrado en Python, por lo que Hermes\nlo usa sin ninguna instalación adicional. La opcional herramienta de línea de comandos sqlite3 — para\nnavegar por la base de datos a mano — no está instalada por defecto. Si la quieres:
sudo apt install -y sqlite3
sqlite3 ~/.hermes/state.db '.tables'
![\"Salida](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-sqlite-tables-dbdc5016a3514137534038cac3f6298d.png\")
Verás tablas sessions y messages que contienen la conversación, además de una familia de\ntablas messages_fts*. Esos son índices de texto completo FTS5 de SQLite — incluyendo una\nvariante de trigramas para coincidencias difusas — que permiten a Hermes buscar sus propias conversaciones pasadas:
CREATE VIRTUAL TABLE messages_fts USING fts5(content);
CREATE VIRTUAL TABLE messages_fts_trigram USING fts5(content, tokenize='trigram');
Y cada sesión es una fila que puedes inspeccionar — aquí están las dos de esta guía, la\nsegunda creada después del reinicio:
sqlite3 -header -column ~/.hermes/state.db \\
\"SELECT substr(id,1,15) AS id, model, message_count FROM sessions ORDER BY started_at;\"
id model message_count
--------------- ------- -------------
20260625_211227 gpt-5.5 8
20260625_212333 gpt-5.5 2
Nunca necesitas la CLI para que Hermes funcione — es solo para inspeccionar la base de datos\ntú mismo. Día a día, el MEMORY.md legible por humanos es todo lo que tienes que mirar.
Ahora ejecutas un agente cuya memoria sobrevive a los reinicios — y sabes exactamente dónde vive esa\nmemoria en disco.
La tabla messages contiene el texto real de cada turno. Cada fila tiene un role —\nuser (lo que escribiste), assistant (la respuesta de Hermes), o tool (el resultado de una herramienta) — para que\npuedas reproducir todo el intercambio:
sqlite3 -header -column ~/.hermes/state.db \\
\"SELECT substr(session_id,10,6) AS sess, role, substr(content,1,55) AS content
FROM messages ORDER BY timestamp;\"
sess role content
------ --------- -------------------------------------------------------
211227 user hello, can you hear me?
211227 assistant Yes — I can hear you. How can I help?
211227 user Please save to your long-term memory: my WEC project...
211227 tool {\"success\": true, \"done\": true, \"target\": \"memory\", ...
211227 assistant Saved to long-term memory: your WEC project codename...
212333 user What's my WEC project codename, and which box does...
212333 assistant Your WEC project codename is Bluefin-7, and it runs...
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-sqlite-messages-12ab80eeb7db27fbf02d5c73b075d553.png\")
La parte interesante es cómo se escribió la memoria. El asistente no editó un archivo\ndirectamente — emitió una llamada a la herramienta memory, y esa herramienta es la que escribió\nMEMORY.md. Puedes ver la llamada exacta registrada en el historial:
sqlite3 ~/.hermes/state.db \\
\"SELECT tool_calls FROM messages WHERE tool_calls LIKE '%memory%' LIMIT 1;\"
{\"function\": {\"name\": \"memory\", \"arguments\":
\"{\\\"target\\\":\\\"memory\\\",\\\"operations\\\":[
{\\\"action\\\":\\\"add\\\",
\\\"content\\\":\\\"El nombre en clave del proyecto WEC del usuario es Bluefin-7, ejecutándose en la caja de OpenClaw.\\\"}]}\"}}
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/hermes-sqlite-memory-toolcall-53bc3762b14f9ca8e30715118341b792.png\")
Así que la cadena completa es: tú escribes → el agente decide que vale la pena mantenerlo → llama a la\nherramienta memory con action: add → eso escribe el hecho en MEMORY.md, mientras que\ntoda la conversación se mantiene en state.db, completamente buscable a través de FTS5. Dos almacenes, una\nmemoria duradera.
Una memoria que sobrevive a los reinicios solo importa por lo que el agente hace con ella.\nCon Hermes en funcionamiento, la misma instalación ofrece estas capacidades (las viste en la\nlista de herramientas de hermes doctor) — aquí está lo que desbloquean día a día:
terminal y code_execution le permiten actuar,\nno solo chatear — por ejemplo, \"clona este repositorio, instala dependencias y ejecuta las pruebas,\" o \"verifica\npor qué se está llenando el disco.\" Lo hace en la Instancia WEC y reporta de vuelta.cronjob ejecuta trabajos recurrentes: un informe matutino,\nun informe semanal de uso del disco, o vigila un servicio y avísame cuando falle — entregado a tu canal de mensajería. (Parte 3.)hermes setup tools.)El resto de esta serie convierte cada una de estas en una guía práctica (consulta ¿Qué sigue?).
\nLa Configuración Rápida (Nous Portal) se queda colgada en \"Esperando aprobación (sondeando)\". El inicio de sesión en el Portal\nnecesita una suscripción/crédito activo. Si no tienes uno, Ctrl+C y usa\nConfiguración completa con tu propia clave en su lugar (Paso 3).
doctor muestra \"No se encontró clave de API en ~/.hermes/.env\". El modelo predeterminado apunta a\nPortal/OpenRouter. Ejecuta hermes setup model, elige tu proveedor y pega la\nclave — doctor luego informa \"Clave de API o endpoint personalizado configurado.\"
Advertencia de .env obsoleta al iniciar la puerta de enlace (por ejemplo, MESSAGING_CWD). Inofensiva;\nsigue la sugerencia para mover la configuración a config.yaml cuando sea conveniente.
Repetidos WARNING [Telegram] … en los registros de la puerta de enlace. Si seguiste las partes anteriores\nde OpenClaw y agregaste un canal de Telegram, la configuración de Hermes detectó OpenClaw y\nimportó esas configuraciones de mensajería en ~/.hermes/.env. Como omitimos\nterminar la mensajería aquí, la puerta de enlace tiene un token pero no una configuración completa, por lo que sigue\nreintentando y registrando esta advertencia. (Una caja nueva sin configuración de Telegram de OpenClaw no\nlo verá.) Elimina las entradas sobrantes y reinicia:
sed -i '/^TELEGRAM_ALLOWED_USERS=/d; /^TELEGRAM_BOT_TOKEN=/d' ~/.hermes/.env
systemctl --user restart hermes-gateway
Si ese token alguna vez fue expuesto, revócalo en @BotFather de Telegram y emite uno nuevo.
\nAhora que Hermes está funcionando con memoria duradera, el resto de la serie convierte cada\ncapacidad anterior en una guía práctica:
\nhermes setup gateway, listas de permitidos, verifica que el bot\nresponda), para que puedas darle tareas desde tu teléfono.Los enlaces aparecerán aquí a medida que cada parte se publique.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/self-host-hermes-agent/", "title": "Autoalojar el Agente Hermes con memoria persistente", "summary": "Despliega el Agente Hermes de código abierto de Nous Research en tu Instancia WEC — con memoria persistente respaldada por SQLite que sobrevive a un reinicio completo. Instalación real, configuración del modelo y una prueba de memoria que sobrevive al reinicio.", "date_modified": "2026-06-25T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "hermes", "agentes", "memoria" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/netbird-mesh-vpn-openclaw/", "content_html": "+![\"NetBird\"](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-dark-0d2ba9c783792904def84b7e687b8f95.png\")
En Artículo 2 colocamos Caddy frente a\nOpenClaw para HTTPS, y en Artículo 3\nagregamos un canal de Telegram. La puerta de enlace funciona — pero Caddy sigue escuchando en\n0.0.0.0, accesible por cualquier cosa que pueda enrutar hacia la caja. Este es el proyecto final\nde la serie: unimos el servidor y tu laptop a una malla NetBird,\nredirigimos openclaw.local a la IP de la malla y cerramos los puertos públicos. La misma\nURL https://openclaw.local/chat sigue funcionando — pero solo para tus dispositivos.\nCada comando y error a continuación proviene de la ejecución real.
Continúa desde los Artículos 1–3 en la misma Instancia WEC — Ubuntu, OpenClaw detrás de\nCaddy 2. Usamos NetBird gestionado (el nivel gratuito en\napp.netbird.io) con el agente 0.73.2 tanto en el\nservidor (Linux, núcleo WireGuard) como en el cliente (macOS, espacio de usuario). NetBird es\nWireGuard-basado y de código abierto; también puedes\nautoalojar el plano de control, que es un tema más amplio para otro día.
NetBird tiene dos partes, y la distinción es el punto principal:
\nAsí que estás construyendo una malla donde Peer A (tu laptop) alcanza a Peer B (la caja OpenClaw) por su dirección privada 100.x — y openclaw.local apunta allí, con Caddy vinculado solo a esa interfaz. El lado público/LAN no tiene nada escuchando.
La idea clave para más adelante: la malla no está limitada a dos pares. Autentica una vez, y cada nuevo servicio — Ollama, un VDI, WordPress — se une como otro par con su propia dirección 100.x, accesible de forma privada sin puertos públicos que abrir. Configuras el modelo de autenticación una vez; agregas servicios para siempre.
El internet público solo llega a el plano de control de NetBird — y eso solo\nautentica pares, nunca transporta tu tráfico de aplicación. Tus servicios no están\n\"protegidos\" tanto como invisibles: OpenClaw no tiene IP pública, así que simplemente\nno hay ruta hacia él desde internet. La única forma de entrar es ser un\npar autenticado en la malla.
\nEn este tutorial conectamos los primeros dos pares — tu laptop y la\ncaja OpenClaw. Los otros servicios hacen el punto: una vez que la autenticación está configurada,\nOllama, un VDI, WordPress simplemente se unen a la misma malla como otro par 100.x\n— sin puertos públicos, sin exposición por servicio.
Cada malla de NetBird tiene dos roles: pares — tus máquinas, es decir, la caja OpenClaw\nde las Partes 1–3 y tu laptop — y un plano de control que autentica esos\npares y emite sus claves de unión. Ya tienes el par (tu caja OpenClaw);\nahora necesitas un plano de control al que unirse. Dos formas de obtener uno:
\nCon la Opción A ejecutarás dos instancias: tu caja OpenClaw (Partes 1–3,\nsin cambios) y una segunda caja de plano de control dedicada (esta plantilla). Esa es la\ntopología correcta — un plano de control debe ser su propia máquina, nunca compartiendo con una\ncarga de trabajo. Con la Opción B solo hay tu una caja OpenClaw. De cualquier manera nunca\nreconstruyes la caja OpenClaw — en Inscribir tus máquinas\nsolo instalas el agente de NetBird en ella y se une a la malla como un par.
Los pasos a continuación configuran la Opción A. WEC ejecuta la instalación; le das un correo electrónico y una\nIP pública, y unos minutos después tienes tu propio panel de NetBird en\nhttps://<your-ip>.apps.wiline.cloud con un certificado válido.
El panel necesita una dirección pública. Bajo Redes → IPs Elásticas, asigna una\nnueva IP o elige una libre, y anota su valor (la nuestra: 108.60.112.165). Debe estar\nen la VPC y zona en la que desplegarás. Pasos completos:\nConfigurar IPs Elásticas.
![\"Una](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-eip-available-b4ec56b4c4946226b7c9e199bd540f61.png\")
Esta nueva instancia se convierte en tu plano de control de NetBird — una caja separada de tu\ninstancia OpenClaw, que permanece intacta. Abre Desplegar → Desplegar una VM (guía completa:\nDesplegar una Máquina Virtual).\nLas elecciones que importan aquí:
\nSubred Local en Princeton-VPC), para que la IP pueda adjuntarse después.![\"Configuración](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-template-config-e03939727bf27b7f6ce4ceb4fc5acdf1.png\")
Termina el asistente y despliega.
\nLa IP no está vinculada en el momento del despliegue — la adjuntas una vez que la VM esté activa. Ve a\nRedes → IPs Elásticas → tu IP → ⋯ → Asignar, y selecciona tu nueva instancia\n(netbird-tutorial). Solo las VMs en la misma VPC aparecen en la lista.
![\"Asignando](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-eip-allocate-620e7b57084f55e9e8ca3323494cda6d.png\")
La instancia muestra Ejecutándose en Cómputo → Instancias en un minuto — pero la\nplantilla sigue trabajando durante unos minutos después de eso, descargando e iniciando los\ncontenedores de NetBird y levantando el panel. No esperes que la URL responda\ninmediatamente.
\nVerifica desde tu laptop a través de HTTPS (no ping — ICMP está bloqueado, así que un\nping fallido no significa que esté caída):
curl -skS -m 10 -o /dev/null -w \"%{http_code}\\n\" https://<your-ip>.apps.wiline.cloud
000 / conexión rechazada → aún en provisión; espera un minuto y vuelve a intentar.301 luego 200 → está activa (HTTP redirige a HTTPS).Para verlo directamente, accede por SSH (ssh ubuntu@<your-ip>) y confirma que los contenedores están\nejecutándose y los puertos están vinculados:
cloud-init status
sudo docker ps
sudo ss -tlnp | grep -E ':(80|443)'
Está listo una vez que netbird-dashboard, netbird-traefik, y netbird-server muestran\nArriba y 80/443 están escuchando.
Abre https://<your-ip>.apps.wiline.cloud — haz clic en la advertencia del certificado\nsi recibes una (el mismo clic de paso de certificado autofirmado que en\nArtículo 2).
Este es tu propio plano de control de NetBird, ejecutándose en tu Instancia WEC. En la\nprimera visita te pide que crees la cuenta de administrador — ingresa un nombre, correo\nelectrónico y contraseña, haz clic en Crear, luego inicia sesión con esas mismas credenciales.\n(Esa pantalla de configuración aparece solo una vez; después el panel muestra una página normal de\nIniciar sesión.)
\nLlegas al panel de NetBird — tu plano de control privado en tu propio dominio:
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-dashboard-c98eca329c445df75fee98ca55f230e9.png\")
Haz clic en Agregar Par y NetBird te entrega el comando de inscripción para tu servidor —\nnota el --management-url apuntando a tu propio dominio:
![\"Agregar](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-add-peer-09fd78007bcc0279cae91217c1786221.png\")
curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --management-url https://<your-ip>.apps.wiline.cloud
(Ese segundo comando abre un inicio de sesión SSO en el navegador. Para un servidor sin cabeza,\nagrega --setup-key <KEY> desde la página de Claves de Configuración de tu panel en su lugar — igual que el flujo gestionado, solo que con --management-url agregado.)
Este es el panel donde creas las claves de configuración que inscriben máquinas — que es exactamente lo que hacemos a continuación.
\nTienes un plano de control (tu propio panel de plantilla, o NetBird gestionado). Ahora coloca\nlas dos máquinas en la malla — la caja OpenClaw de las Partes 1–3 y tu\nlaptop — y luego cierra los puertos públicos de la caja. Estos pasos son los mismos sin importar qué plano de control elegiste.
\nLos comandos a continuación utilizan NetBird gestionado (app.netbird.io) como ejemplo. Si\ndesplegaste la plantilla de WEC en su lugar, es idéntico excepto: crea la clave de configuración\nen tu propio panel (https://<your-ip>.apps.wiline.cloud) y agrega\n--management-url https://<your-ip>.apps.wiline.cloud a netbird up, para que el\nagente apunte a tu servidor en lugar de a la nube gestionada.
Requisitos previos: OpenClaw ejecutándose detrás de Caddy de\nArtículos 1–3 (accesible en\nhttps://openclaw.local), un plano de control del paso anterior, y acceso a la shell en\nla caja más administrador en tu laptop.
Esta es la caja de las Partes 1–3 (una Instancia WEC) — la estamos inscribiendo como un par,\nque es separado de cualquier servidor de plano de control. NetBird envía un instalador de una línea:
\ncurl -fsSL https://pkgs.netbird.io/install.sh | sh
Problema (real): en Ubuntu la instalación activa el diálogo needrestart —\nuna caja azul \"¿Qué servicios deberían reiniciarse?\". Tab entre botones puede ser\nabsorbido por algunas configuraciones de SSH/terminal; usa las teclas de flecha para moverte,\nEspacio para alternar, Enter para confirmar (<Ok> es el predeterminado). El paquete ya está\nen su lugar para cuando aparece esta caja, así que incluso si sales con Ctrl+C, el agente\nestá instalado — volver a ejecutar el instalador solo te lo dirá:
NetBird parece estar ya instalado, por favor elimínalo antes de continuar
(Si vuelves a ejecutar el instalador después de este tutorial, verás en su lugar\nEl servicio de NetBird está en ejecución, por favor deténlo antes de continuar — el agente ya está\nactivo, así que no hay nada que reinstalar.)
Confirma la versión:
\nnetbird version
# 0.73.2
Una clave de configuración es el token que inscribe un dispositivo en tu malla — ideal para un\nservidor sin cabeza (sin necesidad de SSO en el navegador).
\nAlgunas cosas intentarán enviarte en la dirección equivocada en una cuenta nueva — aquí está la\nlínea directa:
https://app.netbird.io/setup-keys.https://app.netbird.io/setup-keys.openclaw-tutorial, alterna Reutilizable (para que funcione también para la laptop), por defecto de otro modo.![\"Creando](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-setup-key-ade9af748bded2998a18890a1ebde93b.png\")
Conecta la VM (reemplaza con tu clave):
\nsudo netbird up --setup-key <YOUR_SETUP_KEY>
Cualquiera con una clave reutilizable puede agregar dispositivos a tu red. No la pegues en\nchats o commits, y elimínala del panel una vez que tus dispositivos estén\ninscritos (los pares existentes permanecen conectados).
Verifica la conexión:
\nnetbird status
![\"estado](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-vm-status-8e8088e406d7392203f1eb5da63b4258.png\")
Esa IP de NetBird (100.87.239.229) es la dirección a la que apunta todo lo que sigue.\nConteo de Pares: 0/0 es esperado — nada más se ha unido aún.
Instala el cliente de NetBird en lo que estés usando, luego conéctate con la\nmisma clave de configuración reutilizable. El comando de conexión (netbird up --setup-key …) es\nidéntico en cada SO — solo la instalación difiere.
La salida capturada a continuación es de un Mac. Las pestañas de Windows y Linux dan la\ninstalación equivalente; los pasos de netbird up, netbird status, y ping son los\nmismos en todas partes (Windows usa ping -n en lugar de -c).
Instala a través de Homebrew, luego inicia el servicio y conéctate:
brew install netbirdio/tap/netbird
sudo netbird service install
sudo netbird service start
netbird up --setup-key <YOUR_SETUP_KEY>
Puede que veas una advertencia de gRPC única mientras el socket del daemon se activa un momento después\nde que el cliente lo llama — termina en Conectado, así que es inofensivo:
WARNING: ... dial unix /var/run/netbird.sock: connect: no such file or directory
Connected
Descarga y ejecuta el instalador de NetBird para Windows desde\napp.netbird.io (Agregar Par → Windows) o\npkgs.netbird.io. Instala una aplicación en la bandeja del sistema y el\nCLI netbird. Luego, en PowerShell como Administrador, conéctate con tu clave:
netbird up --setup-key <YOUR_SETUP_KEY>
(También puedes hacer clic en Conectar desde el icono de la bandeja y autenticarte a través de SSO, pero\nla clave de configuración es el mismo flujo de un solo uso que en las otras plataformas.)
El mismo instalador de una línea que la VM, luego conéctate:
curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key <YOUR_SETUP_KEY>
Verifica que los dos nodos se vean entre sí, y que el túnel transporte tráfico:
\nnetbird status
ping -c 3 100.87.239.229 # Windows: ping -n 3 100.87.239.229
![\"Estado](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-mac-status-857d291924930e23af4e6550b1845ec7.png\")
Conteo de Pares: 1/1 — ese par es la VM. En el panel, ambas máquinas ahora\naparecen bajo Pares (porque las inscribimos con una clave de configuración en lugar de un\ninicio de sesión SSO, aparecen bajo Servidores en lugar de Dispositivos de Usuario):
![\"La](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-peers-a54440db77e8715febacc8d410c24da5.png\")
Este camino está pasando por un relay de NetBird (nota Tipo de Interfaz: Espacio de Usuario\nen el Mac). Está bien para una interfaz web, y NetBird a menudo actualizará a un enlace directo\nde par a par cuando las redes lo permitan. La latencia a un par retransmitido no es una\nbandera roja.
openclaw.local a la IP de la mallaDesde Artículo 2, tu archivo de hosts mapea\nopenclaw.local a la IP LAN de la VM (10.80.4.212). Cámbiala por la IP de la malla\n(100.87.239.229). La ruta del archivo y el comando de edición difieren según el SO:
sed en macOS necesita el vacío -i '':
grep openclaw /etc/hosts
# 10.80.4.212 openclaw.local
sudo sed -i '' 's/^10\\.80\\.4\\.212 openclaw\\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local
GNU sed toma -i sin argumento:
grep openclaw /etc/hosts
sudo sed -i 's/^10\\.80\\.4\\.212 openclaw\\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local
El archivo de hosts está en C:\\Windows\\System32\\drivers\\etc\\hosts y necesita admin.\nEn PowerShell como Administrador:
$h = \"$env:WINDIR\\System32\\drivers\\etc\\hosts\"
(Get-Content $h) -replace '^10\\.80\\.4\\.212 openclaw\\.local','100.87.239.229 openclaw.local' | Set-Content $h
Select-String openclaw $h
(O abre ese archivo en Notepad ejecutado como Administrador y cambia la IP a mano.)
Prueba a través de la malla — antes de tocar ningún puerto:
\ncurl -kI https://openclaw.local/
HTTP/2 200
...
via: 1.1 Caddy
via: 1.1 Caddy a través de la IP de la malla — el chat ahora fluye a través de NetBird. Carga\nhttps://openclaw.local/chat?session=main en el navegador para confirmar que se comporta\nexactamente como antes. El certificado TLS sigue coincidiendo porque el nombre de host no ha cambiado;\nsolo la IP detrás de él se movió.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-chat-mesh-409321edd81ea8d59656891246bc0558.png\")
Aquí está el estado que estamos corrigiendo. En la VM:
\nsudo ss -tlnp | grep -E ':(80|443)'
LISTEN 0 4096 0.0.0.0:443 ... docker-proxy
LISTEN 0 4096 0.0.0.0:80 ... docker-proxy
Caddy escucha en 0.0.0.0 — todas las interfaces, incluyendo la LAN (y cualquier NAT\ndelante de ella).
Tu primer instinto es ufw deny 443. No funcionará. Los puertos de Caddy son\npublicados por Docker, que escribe sus propias reglas de iptables que evitan la\ncadena INPUT de ufw. Agregarías reglas de ufw, te sentirías seguro, y 443 seguiría abierto. En\nesta caja ufw estaba incluso inactivo — y habilitarlo no habría cambiado nada\npara los puertos publicados por Docker.
La solución confiable es vincular los puertos publicados a la IP de la malla en lugar de\n0.0.0.0, para que Caddy solo escuche en wt0. Edita el servicio de Caddy en\ndocker-compose.override.yml (la sobreescritura del Artículo 2):
cd /home/ubuntu/openclaw
cp docker-compose.override.yml docker-compose.override.yml.bak
Cambia el bloque de puertos de:
\n ports:
- \"80:80\"
- \"443:443\"
a vincular a la IP de la malla:
\n ports:
- \"100.87.239.229:80:80\"
- \"100.87.239.229:443:443\"
Recrea solo Caddy y vuelve a verificar:
\ndocker compose up -d caddy
sudo ss -tlnp | grep -E ':(80|443)'
![\"ss](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-ss-after-0172e6fc62bc667a141b1f6528526e73.png\")
Los puertos han desaparecido de 0.0.0.0 — ahora viven solo en la interfaz de malla.
Debido a que el enlace apunta a la IP de la malla, NetBird debe estar activo antes de que Caddy inicie\n(por ejemplo, después de un reinicio, wt0 necesita su IP antes de que Docker se vincule a ella). La\npolítica restart: unless-stopped ya cubre esto — Caddy reintenta hasta que\nla interfaz exista — pero vale la pena saberlo si alguna vez ves a Caddy en un bucle de\ncrash justo después del arranque.
Ambas direcciones, de la ejecución real.
\nAún accesible a través de la malla (laptop):
\ncurl -kI https://openclaw.local/
# HTTP/2 200 ... via: 1.1 Caddy
Ya no accesible en la LAN (VM, golpeando su propia IP LAN):
\ncurl -kI --connect-timeout 5 --resolve openclaw.local:443:10.80.4.212 https://openclaw.local/
![\"En](\"https://development-wec.wiline.com/docs/es/assets/images/netbird-refused-0944b25666489470ae7b961e2d6243c8.png\")
Ese es el resultado: la misma URL, accesible solo a través de tu malla, rechazada\nen todas partes.
\nAhora puedes sacar cualquier servicio autoalojado de internet público sin romper cómo lo\nusas.
Elimina la clave de configuración reutilizable ahora que ambos dispositivos están inscritos —\nClaves de Configuración → eliminar en el panel. Tus pares permanecen conectados; solo\nestás cerrando la puerta que usaste para agregarlos. Para eliminar un dispositivo más tarde, elimínalo bajo\nPares → Dispositivos de Usuario y ejecuta netbird down en esa máquina.
needrestart no acepta Tab. Usa teclas de flecha / Espacio / Enter. El paquete ya está instalado para cuando aparece la caja.netbird.sock en el primer up. El socket del daemon se retrasa un momento respecto al cliente. Si termina en Conectado, ignórala.ufw no bloquean la puerta de enlace. Los puertos publicados por Docker evitan ufw — vincula el puerto a una IP específica (como arriba) o usa la propia cadena DOCKER-USER de Docker.wt0 tuviera la IP de la malla. restart: unless-stopped lo recupera; o ordena Docker después de netbird.service.Tipo de Interfaz y el detalle del par de NetBird para el tipo de conexión.Eso cierra la serie de Autoalojamiento de OpenClaw:
\nAhora tienes un agente autoalojado que está cifrado en tránsito, emparejado con tus\ndispositivos, accesible desde tu teléfono, e invisible para el internet público — todo en\nuna pequeña Instancia WEC.
\n¿Listo para un agente que recuerda? Comienza la serie de Autoalojamiento de Hermes —\nAutoalojar el Agente Hermes con memoria persistente —\ndesplegado en esta misma Instancia WEC, con contexto que sobrevive a los reinicios.
", "url": "https://development-wec.wiline.com/docs/es/tutorials/netbird-mesh-vpn-openclaw/", "title": "Haz que OpenClaw sea privado con una VPN de malla NetBird", "summary": "Coloca OpenClaw en una malla privada con NetBird, redirige tu nombre de host a la IP de la malla y cierra los puertos públicos — así la misma URL de chat funciona solo para tus dispositivos. Comandos reales y problemas de una ejecución en vivo.", "date_modified": "2026-06-24T00:00:00.000Z", "author": { "name": "Rafael Fernandes", "url": "https://www.linkedin.com/in/rafaelmacariofernandes/" }, "tags": [ "ai", "autoalojamiento", "openclaw", "netbird", "vpn", "malla", "seguridad" ] }, { "id": "https://development-wec.wiline.com/docs/es/tutorials/add-telegram-channel-openclaw/", "content_html": "+Has desplegado OpenClaw y\nlo has asegurado detrás de HTTPS. Ahora hazlo\nutilizable — habla con tu agente desde tu teléfono a través de Telegram. Creamos un bot,\nlo conectamos, limpiamos la puerta de emparejamiento de OpenClaw y obtenemos una respuesta real. Cada comando y\ndetalle a continuación proviene de una ejecución real.
\n\nContinúa desde las Partes 1–2 en la misma Instancia WEC — OpenClaw 2026.6.8. Telegram\nusa polling (la puerta de enlace consulta la API de Telegram), por lo que no se requiere un webhook o dominio público — esto funciona en una caja privada.
Tu teléfono habla con un bot de Telegram; la puerta de enlace de OpenClaw consulta Telegram para\nmensajes, los procesa a través de tu modelo y responde — no se necesitan puertos de entrada.
\n\n~/openclawweb.telegram.org. (No puedes crear un bot desde la página web pública t.me; consulta Solución de problemas.)En la aplicación de Telegram, toca buscar y escribe BotFather, luego abre la cuenta oficial — la que tiene el check azul.
![\"Buscando](\"https://development-wec.wiline.com/docs/es/assets/images/tg-step1a-search-922bcf2cacaf250ac10c1a03546f240b.png\")
Toca Iniciar — BotFather responde con los comandos que entiende (verás\nopciones como /newbot, /mybots, /token, y más). Envía /newbot, luego\nsigue sus dos indicaciones:
Mi Agente OpenClawbot, por ejemplo, wiline_openclaw_botBotFather confirma con \"¡Listo! Felicitaciones por tu nuevo bot\" y te da el\ntoken — la línea después de Usa este token para acceder a la API HTTP:, como\n1234567890:AA....
![\"BotFather](\"https://development-wec.wiline.com/docs/es/assets/images/tg-step1c-token-0bec47ec554ad66500f6d053bd0a4810.png\")
Cualquiera que lo tenga controla tu bot. Difumínalo en la captura de pantalla anterior, y /revoke\nen BotFather si alguna vez se filtra.
En la VM, en ~/openclaw, registra el canal con tu token:
docker compose run --rm openclaw-cli channels add --channel telegram --token \"<tu-token-de-bot>\"
# Cuenta de Telegram \"default\" añadida.
Reinicia la puerta de enlace para que reconozca el canal, luego verifica el estado:
\ndocker compose restart openclaw-gateway
docker compose run --rm openclaw-cli channels status
# - Telegram default: habilitado, configurado, en ejecución, modo:polling, token:config
modo:polling significa que la puerta de enlace está consultando activamente Telegram — no se requiere puerto de entrada o webhook.
![\"estado](\"https://development-wec.wiline.com/docs/es/assets/images/tg-step3-status-6393f1690ec9b270312c2f5e3a25f137.png\")
Abre tu bot (t.me/<tu-nombre-de-bot>), toca Iniciar, y envía un mensaje.
OpenClaw trata a los remitentes desconocidos como no confiables — así que en lugar de responder, el bot\ndevuelve un código de emparejamiento y tu id de usuario de Telegram. Este es el mismo patrón de seguridad\nque el emparejamiento de dispositivos en la Parte 2.
\n![\"Bot](\"https://development-wec.wiline.com/docs/es/assets/images/tg-step4-pairing-94e777f1790fbeadab0cd42be384b80b.png\")
En la VM, aprueba el código del mensaje del bot:
\ndocker compose run --rm openclaw-cli pairing approve telegram <código-de-emparejamiento>
# Remitente de telegram aprobado <id>.
# Propietario del comando configurado telegram:<id> (commands.ownerAllowFrom estaba vacío).
Aprobar al primer usuario como propietario del comando cambia la configuración que requiere un\nreinicio de la puerta de enlace — OpenClaw lo hace automáticamente (verás\ncambio de configuración requiere reinicio de la puerta de enlace luego el reinicio del proveedor de Telegram en los\nregistros). Espera unos segundos para que vuelva antes de enviar otro mensaje.
De vuelta en Telegram, simplemente habla con él — no se necesita configuración adicional; OpenClaw con tu modelo\nresponde de manera conversacional desde el principio. Prueba algo como:
\nEn una oración, ¿cuál es el objetivo de poner un proxy inverso frente a mi agente?
Responde con una respuesta real — la cadena completa está activa: tu teléfono → Telegram →\npuerta de enlace → OpenAI → respuesta. Tu agente autoalojado ahora está en tu bolsillo. (Proporcionarle\nherramientas y habilidades vendrá en guías posteriores; el chat conversacional funciona de inmediato.)
\n![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/tg-step6-working-7acac4effbd1c03d0657534125e3ea3b.png\")
Tu agente ahora está en tu bolsillo — una línea privada de Telegram a tu propia IA, sin necesidad de un webhook público.
Abrir t.me/BotFather en un navegador web simple muestra un botón de Iniciar que no hace\nnada — esa página es solo la tarjeta pública del bot y necesita un cliente de Telegram conectado\npara poder transferir. Usa la aplicación de escritorio/teléfono, o inicia sesión en\nweb.telegram.org (vincula un dispositivo de escritorio escaneando el QR desde tu teléfono:\nConfiguración → Dispositivos → Vincular dispositivo de escritorio), luego envía un mensaje a BotFather allí.
No es un error — es la puerta de emparejamiento. Los remitentes desconocidos deben ser aprobados primero\n(Paso 5). Después de la aprobación, el bot chatea normalmente.
\nProxy headers detected from untrusted addressSi seguiste la Parte 2, la puerta de enlace registra esto porque Caddy está delante de ella.\nEs una advertencia, no un fallo. Para silenciarlo y restaurar la detección correcta del cliente,\nconfigura gateway.trustedProxies a la red de tu proxy.
event loop degraded bajo carga.\nPara un bot ocupado, dale más CPU/RAM.Has terminado Parte 3 de la serie Autoalojamiento de OpenClaw. A continuación:
\nLuego comienza la serie Autoalojamiento de Hermes — Autoalojar el Agente Hermes con memoria persistente — para un agente cuyo contexto sobrevive a los reinicios.
\nLos archivos complementarios para la serie se encuentran en el repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
\nElimina el canal de Telegram (mantiene el resto de OpenClaw en funcionamiento):
\ndocker compose run --rm openclaw-cli channels remove --channel telegram
docker compose restart openclaw-gateway
Y /revoke el token del bot en BotFather si has terminado con él.
+En Artículo 1 hicimos funcionar OpenClaw —\npero solo a través de HTTP sin cifrar, con un workaround allowInsecureAuth. Aquí colocamos\nCaddy frente a él como un proxy inverso: verdadero HTTPS,\nautenticación emparejada por dispositivo, y los puertos del gateway cerrados para que el proxy sea la única\nforma de acceso. Cada comando y error a continuación proviene de la implementación real.
Continúa desde el Artículo 1 en la misma instancia WEC — Ubuntu 22.04.5 LTS, OpenClaw\n2026.6.8. Usamos Caddy 2 (caddy:2). Debido a que esta máquina no tiene un dominio público,\nusamos la CA interna de Caddy (tls internal) para HTTPS autofirmado; la\nsección Pasando a producción muestra el cambio de una línea a certificados reales de\nLet's Encrypt una vez que tengas un dominio.
Caddy termina HTTPS y hace un proxy inverso al gateway de OpenClaw a través de la\nred interna de Docker. El gateway deja de publicar sus propios puertos — el único punto de entrada\nse convierte en Caddy en :443.
~/openclawopenclaw.local + una entrada en hosts.cd ~/openclaw
docker compose ps
Deberías ver openclaw-gateway Up (healthy), publicando 18789/18790/3978.\nEse es nuestro estado inicial: funcionando, pero solo HTTP.
La configuración de Caddy: servir HTTPS y hacer proxy a todo al gateway. tls internal\nusa la propia CA local de Caddy — no se necesita un dominio público.
cat > Caddyfile <<'EOF'
# Caddy selecciona su certificado por SNI (el nombre de host en el apretón de manos TLS).
# Una IP desnuda no envía SNI, así que usamos un nombre de host. Con un dominio público, coloca tu
# dominio aquí y elimina `tls internal` para Let's Encrypt automático.
openclaw.local {
tls internal
reverse_proxy openclaw-gateway:18789
}
EOF
El objetivo del proxy es openclaw-gateway:18789 — Caddy accede al gateway por su\nnombre de servicio de Compose a través de la red compartida de Docker.
docker compose fusiona automáticamente un docker-compose.override.yml, así que agregamos un servicio caddy\nsin tocar el archivo de compose oficial de OpenClaw:
cat > docker-compose.override.yml <<'EOF'
services:
caddy:
image: caddy:2
restart: unless-stopped
ports:
- \"80:80\"
- \"443:443\"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
EOF
caddy_data persiste la CA local + certificados a través de reinicios.
docker compose up -d
docker compose ps
Caddy se inicia junto al gateway con 443 publicado, y genera su\nCA interna + un certificado en la primera ejecución.
![\"Contenedor](\"https://development-wec.wiline.com/docs/es/assets/images/caddy-step4-up-d53a3b63c4e346428a8e733249b2049a.png\")
docker compose up -d también inicia el ayudante de un solo uso openclaw-cli; su inactividad\naquí es inofensiva — lo invocamos con docker compose run --rm cuando es necesario.
Accede al endpoint de salud del gateway a través de Caddy. --resolve hace que curl envíe\nel nombre de host (SNI) mientras apunta a la máquina:
curl -k --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz
# {\"ok\":true,\"status\":\"live\"}
tlsv1 alert internal error?Eso sucede si usaste una IP desnuda como dirección del sitio — consulta\nSolución de problemas #1. Usa un nombre de host.
Ahora el tráfico llega a través de https://openclaw.local. Dos cambios de configuración:
allowedOrigins (la UI de Control rechaza orígenes desconocidos).allowInsecureAuth — HTTPS es un contexto seguro, por lo que el\nworkaround del Artículo 1 ya no es necesario.docker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js config set --batch-json '[{\"path\":\"gateway.controlUi.allowedOrigins\",\"value\":[\"https://openclaw.local\"]},{\"path\":\"gateway.controlUi.allowInsecureAuth\",\"value\":false}]'
docker compose restart openclaw-gateway
Abre https://openclaw.local/ en tu navegador (en una máquina privada, primero mapea\n10.80.4.212 openclaw.local en el archivo hosts de tu máquina — /etc/hosts en\nmacOS/Linux, o C:\\Windows\\System32\\drivers\\etc\\hosts editado como Administrador\nen Windows).
Primero recibirás una advertencia de certificado — \"Tu conexión no es privada\"\n(NET::ERR_CERT_AUTHORITY_INVALID). Esto es esperado con tls internal: el\ncertificado está firmado por la CA local de Caddy, que tu sistema operativo no\nconfía. Haz clic en Avanzado → Proceder a openclaw.local (inseguro) para continuar. (Con un\ndominio real + Let's Encrypt, el certificado es públicamente confiable y esta advertencia\nnunca aparece — consulta Pasando a producción.)
![\"Advertencia](\"https://development-wec.wiline.com/docs/es/assets/images/caddy-step7-cert-warning-f6015d4f4498bdd7f495c01e08e91cf5.png\")
Ahora la página se carga — pero con allowInsecureAuth desactivado, el gateway requiere\nemparejamiento de dispositivo antes de que este navegador pueda usar la UI de Control. Ese es el flujo seguro haciendo su trabajo. La pantalla muestra un id de solicitud; apruébalo en el host:
docker compose run --rm openclaw-cli devices approve <request-id-from-the-screen>
![\"Pantalla](\"https://development-wec.wiline.com/docs/es/assets/images/caddy-step7-pairing-95202988ec2160fdef5dcd2e33fce67f.png\")
De vuelta en el navegador, haz clic en Conectar nuevamente — se empareja y carga el panel.
\nEl gateway aún publica 18789 al host, por lo que http://<vm-ip>:18789 es\ntodavía accesible en HTTP sin cifrar, eludiendo a Caddy. Ciérralo: deja de publicar los\npuertos del gateway para que Caddy en :443 sea la única puerta. Caddy aún puede acceder a él a través\nde la red interna.
cat > docker-compose.override.yml <<'EOF'
services:
openclaw-gateway:
# Deja de publicar los puertos del host del gateway — Caddy accede a él internamente, así que el
# único punto de entrada es HTTPS en :443.
ports: !reset []
caddy:
image: caddy:2
restart: unless-stopped
ports:
- \"80:80\"
- \"443:443\"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
caddy_data:
caddy_config:
EOF
docker compose up -d
ports: !reset [] limpia los puertos que el compose base publicó.
curl -s -m 5 http://<vm-ip>:18789/healthz ; echo \" <- HTTP directo (debería FALLAR)\"
curl -sk --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz ; echo \" <- a través de Caddy (debería funcionar)\"
El primero no devuelve nada (conexión rechazada) — la puerta insegura ha desaparecido. El\nsegundo aún devuelve {\"ok\":true,\"status\":\"live\"}.
Tu OpenClaw ahora es accesible solo a través de HTTPS, emparejado por dispositivo.
\n![\"UI](\"https://development-wec.wiline.com/docs/es/assets/images/caddy-control-ui-https-814c25fc8dd38568d2226856190421ba.png\")
Ahora puedes poner verdadero HTTPS y autenticación frente a cualquier servicio autoalojado — y probar que\nla puerta trasera está cerrada.
tlsv1 alert internal errorOcurre cuando la dirección del sitio en el Caddyfile era una IP desnuda (https://10.80.4.212):
curl: (35) error:0A000438:SSL routines::tlsv1 alert internal error
Los registros de Caddy mostraron que el certificado se obtuvo correctamente. Causa: TLS selecciona un certificado\npor SNI (el nombre de host en el apretón de manos), pero las conexiones a una IP desnuda no envían SNI — así que Caddy no puede\ncoincidir un certificado y aborta. Solución: usa una dirección de sitio con nombre de host\n(Paso 2). Un lector con un dominio real nunca enfrenta esto — el dominio es el SNI.
\nEn la primera conexión HTTPS después de desactivar allowInsecureAuth:
Se requiere emparejamiento de dispositivo — Este navegador necesita una aprobación única del host del Gateway
antes de que pueda usar la UI de Control.
Causa: este es el flujo seguro correcto — con la autenticación insegura desactivada, cada nuevo\nnavegador debe ser aprobado. Solución: docker compose run --rm openclaw-cli devices approve <request-id>. (El CLI puede registrar scope upgrade pending approval … using local fallback pero aún completa la aprobación.)
NET::ERR_CERT_AUTHORITY_INVALIDEsperado con tls internal — el certificado está firmado por la CA local de Caddy, que tu\nsistema operativo no confía. Haz clic para continuar en una máquina privada. Con un dominio público + Let's\nEncrypt (a continuación), el certificado es confiable y no hay advertencia.
Con un dominio real, intercambia dos líneas en el Caddyfile — apúntalo a tu dominio y\nelimina tls internal:
- openclaw.local {
- tls internal
+ openclaw.example.com {
reverse_proxy openclaw-gateway:18789
}
Luego apunta el registro A del dominio a la IP pública de la VM y abre 80 + 443\na Internet. Caddy automáticamente provisiona y renueva un certificado de Let's Encrypt\n— confiable, sin advertencias, sin --resolve o /etc/hosts necesarios. Actualiza\nallowedOrigins a https://openclaw.example.com.
:443 de Caddy está expuesto; el gateway no tiene puertos de host\n(Paso 8).openclaw devices).https://openclaw.local.OPENCLAW_GATEWAY_TOKEN si alguna vez ha sido\nmostrado (capturas de pantalla, comparticiones de pantalla).Has terminado Parte 2 de la serie Autoalojamiento de OpenClaw. A continuación:
\nLos archivos complementarios (Caddyfile, docker-compose.override.yml) se encuentran en el repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
Para eliminar solo Caddy y reabrir los puertos directos, elimina docker-compose.override.yml\ny Caddyfile, luego docker compose up -d. Para detener todo:
docker compose down
Tu asistente de IA no tiene que vivir en la nube de otra persona.
\nDespliega un agente de IA OpenClaw autoalojado en una instancia WEC con\nDocker Compose — desde iniciar la VM hasta un agente que realmente responde, usando\ntu propia clave de API de modelo. Cada comando, versión y error a continuación fue capturado\nde un despliegue real en una instancia WEC.
\n\nTraes tu propia clave de API de modelo (OpenAI en esta guía); WiLine maneja el\nalojamiento. Esto se reprodujo en una instancia WEC — Ubuntu 22.04.5 LTS, 8 vCPU,\n15 GiB RAM, 25 GB de disco libre. Versión de OpenClaw 2026.6.8, imagen\nghcr.io/openclaw/openclaw:latest.
Un único contenedor gateway de OpenClaw, configurado con tu proveedor de modelo,\naccesible a través de su interfaz de Control UI web y CLI.
\n\n~/.ssh/id_ed25519 o similar)Inicia una VM de WiLine que cumpla con estos requisitos:
\n| Requisito | Valor |
|---|---|
| SO | Ubuntu 22.04 LTS (o 24.04 LTS) |
| Cómputo | ≥ 2 vCPU / 4 GB RAM — OpenClaw necesita ≥ 2 GB; la primera ejecución puede ser OOM-killed (salida 137) en hosts de 1 GB |
| Disco | 30 GB NVMe — 10 GB se llena rápido una vez que las imágenes de Docker y los registros se almacenan |
| Acceso | Tu clave pública SSH añadida en el momento del despliegue, para que puedas iniciar sesión sin contraseña |
La guía del portal ya está documentada — sigue estos pasos y vuelve:
\n\nUna vez que esté en funcionamiento, inicia sesión por SSH:
\nssh ubuntu@<tu-ip-vm>
Antes de instalar cualquier cosa, confirma con qué estás trabajando — la versión del SO y\nlos recursos disponibles. Toma nota de estos números; son útiles cuando compares\nel rendimiento o abras un ticket de soporte.
\nlsb_release -a
nproc
free -h
df -h /
En nuestra instancia WEC: Ubuntu 22.04.5 LTS, 8 vCPU, ~15 GiB RAM, 25 GB de disco libre.
![\"Terminal](\"https://development-wec.wiline.com/docs/es/assets/images/step2-box-specs-c821280774bf4f5ec9205092f6646004.png\")
Verifica si Docker ya está presente:
\ndocker --version
docker compose version
Si no está instalado, sigue la guía oficial de Docker para tu distribución —\nInstalar Docker Engine en Ubuntu.\nEl camino más rápido es el\nscript de conveniencia de Docker,\nseguido de añadir tu usuario al grupo docker para que puedas ejecutarlo sin\nsudo:
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
Necesitas Docker Compose v2 (el subcomando docker compose, no el binario legado\ndocker-compose).
Si Docker ya está presente, el script get.docker.com lo detecta y advierte\nen lugar de reinstalar — no lo fuerces en una máquina con contenedores en ejecución. En una\nVM limpia se instala desde cero. Este despliegue se realizó en un host donde Docker\n29.1.3 / Compose v5.0.2 ya estaba instalado.
Crea un directorio de proyecto y descarga el docker-compose.yml oficial de OpenClaw:
mkdir openclaw && cd openclaw
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -o docker-compose.yml
El archivo define dos servicios — openclaw-gateway (el gateway de agente de larga duración)\ny openclaw-cli (una CLI de un solo uso que comparte la red del gateway).\nPor defecto, se construye desde el código fuente; en su lugar, lo apuntaremos a la imagen preconstruida.
.envCrea un .env junto al archivo compose. Fija la imagen preconstruida y establece un\ntoken de panel:
OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<pega la salida de: openssl rand -hex 32>
.env fuera de gitContiene tu token de gateway (y cualquier clave). Agrégalo a .gitignore. En su lugar, compromete un\n.env.example con valores de marcador de posición.
Descarga la imagen:
\ndocker compose pull
OpenClaw monta ~/.openclaw en el contenedor. Créalo como tu propio\nusuario primero — de lo contrario, Docker lo crea como root y el contenedor (que\nse ejecuta como usuario node, uid 1000) no puede escribir en él:
mkdir -p ~/.openclaw ~/.openclaw-auth-profile-secrets
Si omites esto, recibirás un error de permisos en la primera ejecución — consulta\nSolución de problemas.
\nAquí es donde traes tu propio modelo — la incorporación solicita tu proveedor y\nclave de API. Esta guía utiliza OpenAI, pero Anthropic y modelos locales funcionan de la misma manera.
\nEjecuta la incorporación de OpenClaw a través del contenedor gateway. Es interactivo — solicita\ntu proveedor y clave de API y escribe la configuración:
\ndocker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js onboard --mode local --no-install-daemon
Sigue los pasos:
\nopenai/gpt-5.5)skip → Saltar por ahora (los canales de mensajería son una guía posterior)openclaw configure)Termina con Incorporación completa.
La incorporación escribió tu proveedor y modelo. Ahora establece las opciones de tiempo de ejecución del gateway —\nmodo de ejecución, enlace de red y los orígenes de Control UI que aceptará — y luego inícialo\ncomo un servicio en segundo plano.
\ndocker compose run --rm --no-deps --entrypoint node openclaw-gateway \\
dist/index.js config set --batch-json '[{\"path\":\"gateway.mode\",\"value\":\"local\"},{\"path\":\"gateway.bind\",\"value\":\"lan\"},{\"path\":\"gateway.controlUi.allowedOrigins\",\"value\":[\"http://localhost:18789\",\"http://127.0.0.1:18789\"]}]'
docker compose up -d openclaw-gateway
Salud del contenedor:
\ndocker compose ps
Quieres Up ... (healthy). Luego accede al endpoint de salud:
curl http://127.0.0.1:18789/healthz
# {\"ok\":true,\"status\":\"live\"}
![\"docker](\"https://development-wec.wiline.com/docs/es/assets/images/step9-health-2a25a28bc6b53dd20c385259373d72a5.png\")
Confirma que tu clave de proveedor es utilizable:
\ndocker compose run --rm openclaw-cli models status
# openai ... api_key=1 ... status=usable
models status imprime un prefijo de clave enmascarado (sk-proj-…). Recorta o difumina antes de\npublicar la captura de pantalla.
Ahora la verdadera prueba de extremo a extremo. El comando agent necesita un objetivo, así que lista los agentes\nprimero, luego envía un mensaje al predeterminado (main):
docker compose run --rm openclaw-cli agents list
# - main (predeterminado)
docker compose run --rm openclaw-cli agent --agent main \\
--message \"Responde con exactamente una palabra: funcionando\"
# funcionando
Si responde funcionando, toda la cadena — gateway → OpenAI → respuesta — está activa.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/step9-agent-working-91514c6b42235714c1348d5ce9f6e9b9.png\")
La Control UI está en http://<tu-ip-instancia>:18789/; pega tu\nOPENCLAW_GATEWAY_TOKEN en Configuración para iniciar sesión.
Los navegadores bloquean la Control UI a través de HTTP simple en una IP remota (\"Se requiere contexto de navegador seguro\"). Accede a ella a través de un túnel SSH para que se cargue como 127.0.0.1 — consulta\nSolución de problemas #3.
![\"Interfaz](\"https://development-wec.wiline.com/docs/es/assets/images/step9-control-ui-fe1df8b0971ad1a8192ff40d2ea6856e.png\")
Estos son errores que realmente encontramos durante este despliegue — no hipotéticos.
\nEACCES: permiso denegado, mkdir '/home/node/.openclaw/state'Ocurrió en la primera ejecución de incorporación cuando ~/.openclaw no existía previamente:
[openclaw] El comando CLI falló.
[openclaw] Razón: Falló al abrir la base de datos de estado del plugin.
| EACCES: permiso denegado, mkdir '/home/node/.openclaw/state' | EACCES
Causa: Docker creó automáticamente la fuente de montaje vinculada ~/.openclaw propiedad de\nroot (0:0). El contenedor se ejecuta como usuario node (uid 1000), por lo que no puede escribir\ndentro de ese directorio de propiedad de root.
Solución: da el directorio al uid 1000 (que también es tu usuario ubuntu):
sudo chown -R 1000:1000 ~/.openclaw
Precrear el directorio tú mismo (Paso 6) evita esto por completo.
\n![\"Error](\"https://development-wec.wiline.com/docs/es/assets/images/error1-eacces-fbbf355224203ecfccd68552fcf0bcb3.png\")
No se seleccionó sesión de destinoLa primera vez que ejecutamos agent sin especificar a quién hablar:
Error: No se seleccionó sesión de destino. Usa --agent <id>, --session-key <key>,
--session-id <id>, o --to <E.164>. Ejecuta openclaw agents list para ver agentes.
Causa: openclaw agent ejecuta un turno contra un agente/sesión específica; sin\nun canal configurado no hay un objetivo implícito.
Solución: lista los agentes y pasa el id explícitamente:
\ndocker compose run --rm openclaw-cli agents list # muestra: main (predeterminado)
docker compose run --rm openclaw-cli agent --agent main --message \"...\"
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/error2-no-session-c405ca89ca87bd411080165c514046e5.png\")
Abrir la Control UI desde otra máquina (por ejemplo, macOS) en la IP de la VM a través de\nHTTP simple, la página se niega a conectar:
\nSe requiere contexto de navegador seguro
Esta página se está ejecutando a través de HTTP simple, por lo que el navegador no puede crear la
identidad del dispositivo que espera el Gateway.
Causa: los navegadores solo exponen las API criptográficas que OpenClaw necesita en un contexto seguro — HTTPS, o localhost/127.0.0.1. Un http://<ip>:18789 remoto no es ninguno de los dos, por lo que está bloqueado en el navegador, independientemente de la bandera del lado del servidor\ngateway.controlUi.allowInsecureAuth.
Solución: tunela el puerto a través de SSH para que el navegador hable con 127.0.0.1 (un contexto seguro). En tu máquina local:
ssh -L 18789:127.0.0.1:18789 ubuntu@<tu-ip-vm>
Luego abre http://127.0.0.1:18789/#token=<tu-token> localmente. La solución adecuada a largo plazo es HTTPS a través de un proxy inverso — la próxima guía.
![\"El](\"https://development-wec.wiline.com/docs/es/assets/images/error3-secure-context-3e5792a56fae6a2ea2a8f9e0f0aa4c3f.png\")
Al iniciar, el gateway registró advertencias que vale la pena actuar antes de cualquier exposición pública:
\ngateway.controlUi.allowInsecureAuth=true — marcado como peligroso. Ejecuta\ndocker compose run --rm openclaw-cli security audit.plugins.allow está vacío — los plugins no empaquetados (por ejemplo, codex) pueden\ncargarse automáticamente. Establece una lista de permitidos explícita de ids de plugins de confianza.Endurecer esto detrás de un proxy inverso con HTTPS es el tema de la próxima guía.
\nAhora puedes desplegar y operar tu propio agente de IA en una máquina que controlas.
Pasaste de una instancia WEC vacía a un agente de IA autoalojado en funcionamiento:
\nEl agente es tuyo: tu clave, tu máquina, tus datos. A partir de aquí se trata de hacerlo\nseguro, accesible y útil.
\nOpenClaw no es un chatbot — es un agente autónomo que puede actuar en tu máquina. Ahora\nque está en funcionamiento, aquí hay lo que desbloquea (algunas funciones necesitan configuración adicional, y\ncubrimos las más importantes más adelante en esta serie):
\nUsos reales típicos que la gente realiza: gestión de bandejas de entrada y calendarios, procesamiento de documentos,\ntareas de infraestructura en la máquina, tuberías de contenido y pruebas de código autónomas.
\nEsta es Parte 1 de la serie Autoalojamiento de OpenClaw sobre cómo ejecutar infraestructura de IA de calidad de producción en una instancia WEC. Próximamente:
\nallowInsecureAuth y acceder a la Control UI desde cualquier lugar, de forma segura.Los archivos complementarios para esta guía — docker-compose.yml y .env.example — se encuentran en\nel repositorio de manifiestos de WiLine (enlace que vendrá con el repositorio).
docker compose down # detener + eliminar contenedores
docker compose down --rmi all -v # también eliminar la imagen y volúmenes
Para eliminar la configuración/estado en el host:\nrm -rf ~/.openclaw ~/.openclaw-auth-profile-secrets. Para detener la facturación por completo,\nelimina la VM desde el portal de WiLine.