Saltar a contenido

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:

  1. Crea el espacio de nombres agent-nightly-triage (--purpose pasa a ser su descripción).
  2. Otorga el rol writer sobre él a un sujeto de cuenta de servicio.
  3. Escribe el token en ~/.loom/token (modo 0600) y la URL, el espacio de nombres y la organización en ~/.loom/config.json (--token-path y --config-path cambian esas rutas).
  4. 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/init lista mcp_servers[] con un status para cada uno. Confía en la ejecución solo cuando loom esté 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 único execute().
  • 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) a compile(store=...); un agente de Strands usa LoomMemoryStore (loom.integrations.strands).
  • examples/claude_agent_loop.py es un bucle mínimo con el SDK de Anthropic (requiere ANTHROPIC_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

Relacionado