Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Bots sin interfaz
Un bot sin interfaz (headless) se ejecuta sin una persona que pegue un token, note un fallo silencioso o diga "recuerda esto". Esta guía cubre la identidad del bot, una comprobación de la conexión, tres entornos de ejecución, lo que escribe el bot y cómo diagnosticar un bot que ha dejado de responder.
1. Dale una identidad al bot
El CLI loom viene incluido en la imagen del servidor y se instala desde un clon con pip install -e ..
El paquete del SDK (clickhouse-loom) no incluye CLI.
Con autorregistro. En un servidor con LOOM_SELF_SIGNUP=open, el bot se registra por sí mismo:
loom init --agent nightly-triage --server-url https://<loom> --purpose "Files the nightly failures."
loom init:
- Crea el espacio de nombres
agent-nightly-triage(--purposepasa a ser su descripción). - Otorga el rol
writersobre él a un sujeto de cuenta de servicio. - Escribe el token en
~/.loom/token(modo 0600) y la URL, el espacio de nombres y la organización en~/.loom/config.json(--token-pathy--config-pathcambian esas rutas). - Imprime un código de reclamación y la dirección de la página de reclamación (
/oauth/agent-claim). Una persona introduce el código allí una sola vez, con una contraseña propia, y a partir de entonces inicia sesión con el nombre del espacio de nombres y esa contraseña como su administrador. El código nunca inicia sesión y se rechaza una segunda reclamación con él. El token del bot sigue funcionando.
--ttl-days define la vigencia del token (por defecto 365). --org elige una organización distinta de la
organización de autorregistro del servidor.
En CI, imprime el token en lugar de escribir archivos y guárdalo como secreto. Con
--no-files, el token es la primera línea de la salida:
loom init --agent ci-reviewer --server-url https://<loom> --no-files | head -n 1 > token.txt
Con --json, el resultado del registro se imprime como JSON sin el token; con
--json --no-files, el token va dentro de ese JSON, el único lugar donde aparece.
Sin autorregistro, un operador genera el token, o una persona crea uno en Settings → Tokens que solo lee los espacios de nombres del bot:
loom mint-token --subject ci-reviewer --org <org> --namespaces agent-ci --roles writer \
--service-account --ttl-days 30 --save
Consulta tokens y permisos para ver roles, vigencias y rotación.
2. Comprobar la conexión antes de la primera ejecución
LOOM_BASE_URL=https://<loom> LOOM_API_KEY="$(cat token.txt)" loom doctor --client
loom doctor --client resuelve el servidor y el token igual que los hooks del plugin y el SDK, e indica de dónde proviene cada uno. Sondea /v1/health y namespace.list_mine, y comprueba que el token pueda escribir en el espacio de nombres del bot. Cada problema aparece como una línea FAIL que indica la solución, y el código de salida es distinto de cero, por lo que el comando sirve como control en CI:
- run: loom doctor --client --server-url ${{ vars.LOOM_BASE_URL }} --token ${{ secrets.LOOM_API_KEY }}
--json emite las comprobaciones y la lista de problemas como JSON para un pipeline que las procese.
3. Conectar el runtime
Claude Agent SDK o claude -p
Monta Loom como servidor MCP desde un archivo y permite solo sus herramientas. Una ejecución headless no tiene OAuth interactivo, así que el bearer viaja en la cabecera:
cat > loom.mcp.json <<EOF
{"mcpServers": {"loom": {"type": "http",
"url": "https://<loom>/mcp?toolset=coding",
"headers": {"Authorization": "Bearer $LOOM_API_KEY"}}}}
EOF
claude -p --mcp-config loom.mcp.json --strict-mcp-config \
--allowedTools "mcp__loom__*" \
--output-format stream-json --verbose \
"Triage the failures in the last nightly run; record each root cause you find."
| Flag | Por qué |
|---|---|
--strict-mcp-config |
Mantiene el bot en los servidores que nombra el archivo, no en la configuración del usuario. |
--allowedTools "mcp__loom__*" |
Preaprueba todas las herramientas de Loom, de modo que ningún aviso de permisos bloquee la ejecución. |
--output-format stream-json |
El primer mensaje es el system/init de la sesión (ver más abajo). claude -p necesita --verbose con esta opción. |
--bare |
Omite los hooks, plugins y CLAUDE.md del usuario para un comportamiento idéntico. |
Advertencia: condiciona la ejecución a la conexión. El mensaje
system/initlistamcp_servers[]con unstatuspara cada uno. Confía en la ejecución solo cuandoloomestéconnected; de lo contrario, el modelo se ejecutó sin memoria.
Elige el listado de herramientas con ?toolset=; los toolsets se enumeran en
toolsets de MCP.
Si el plugin de Loom está instalado para el usuario que ejecuta claude -p, sus hooks también se ejecutan
(plugin de Claude Code). Sus sugerencias de mentor siguen solo
las herramientas del servidor propio del plugin (mcp__plugin_loom_loom__*), no una entrada loom de
--mcp-config.
Codex codex exec
export LOOM_API_KEY="$(cat token.txt)"
codex exec --json \
-c 'mcp_servers.loom.url="https://<loom>/mcp?toolset=coding"' \
-c 'mcp_servers.loom.bearer_token_env_var="LOOM_API_KEY"' \
"Summarise what we decided about retries; record any decision that is missing."
Codex lee el bearer de la variable que nombra la entrada, en el entorno desde el que arranca codex.
Con el plugin de Codex instalado, sus hooks también se ejecutan aquí
(plugin de Codex).
El SDK, en el proceso propio del bot
Para un bot que es código y no un agente de programación, omite MCP y llama a las operaciones:
from loom import Agent
async with Agent(org="acme", namespace="agent-nightly-triage", agent="nightly-triage") as a:
hits = await a.memory.search("flaky tests in the ingest suite", top_k=5)
await a.memory.set(
"flaky/ingest_retry_test",
"Times out against the S3 mock.",
tags=["failure", "ingest"],
)
ans = await a.memory.ask("which suites flaked this week?")
Agent lee el servidor de base_url= o LOOM_BASE_URL, y el token de
api_key=, LOOM_API_KEY y luego ~/.loom/token. Otros puntos de entrada:
agent.tools()entrega a un modelo los verbos de Loom (loom_remember,loom_recall,loom_ask,loom_offload,loom_fetch,loom_note) como definiciones de herramientas con un únicoexecute().agent.session(id)es la unidad que mantiene un framework de agentes: reanudar, añadir, vaciar y cerrar.- Un grafo de LangGraph pasa
LoomStore(loom.integrations.langgraph) acompile(store=...); un agente de Strands usaLoomMemoryStore(loom.integrations.strands). examples/claude_agent_loop.pyes un bucle mínimo con el SDK de Anthropic (requiereANTHROPIC_API_KEY).
Consulta la referencia del SDK de Python y las integraciones con frameworks.
4. Decide qué escribe el bot
Los plugins capturan una sesión de programación por sí solos. Un bot ajeno a ellos decide qué escribir.
En resumen: registra decisiones y fallos, no transcripciones; consulta la memoria una vez antes de una tarea, no una vez
por paso; pasa la transcripción de una ejecución terminada a memory.set_from_messages; e informa de lo que la
ejecución utilizó con run.complete(memories_used=[...]).
Integración de agentes explica cada una de estas decisiones.
5. Cuando el bot está en silencio
Ejecuta loom doctor --client en la máquina del bot. Informa de cada una de las causas habituales en su propia línea:
| Síntoma | Causa |
|---|---|
| Las lecturas y escrituras van a otro servidor | LOOM_BASE_URL no coincide con ~/.loom/config.json |
| 401 en cada llamada | El token expiró o fue rotado |
| 403 en cada escritura | El token es viewer en el espacio de nombres en el que escribe el bot |
| Las capturas nunca aparecen | Un proceso de vaciado en segundo plano nunca las entregó: quedan archivos loom-flush-*.json en el directorio temporal |