Diagnosticar un agente

Esta guía te muestra cómo averiguar por qué un agente no está generando ejecuciones.

Trabaja de arriba hacia abajo: primero las ejecuciones del propio agente, luego su backend, después el servidor y al final el host.

1. Revisa el historial de ejecuciones del agente

Ajustes → Espacio de trabajo → Agentes → selecciona el agente → Registros.

Cada ejecución muestra una insignia de estado, una duración («Running…» mientras está en curso), sus horas de inicio y fin, su PID y el adaptador que usó. Vista abre el flujo de eventos sin procesar de esa ejecución. Detener mata un proceso en ejecución y marca la ejecución como «Killed by user»; Detener en ejecución en el encabezado hace lo mismo con todas las ejecuciones en curso de ese agente.

Léelo así:

Ninguna ejecución — el despacho nunca ocurrió. Las menciones del compositor son @ más caracteres de palabra (letras, dígitos, guion bajo). La resolución es una coincidencia exacta o por prefijo con el nombre del agente, así que @code-reviewer se interpreta como code y aun así puede despertar a un agente llamado code-reviewer. Un nombre con un espacio no se puede mencionar como un solo token. Si es tu caso, pasa al paso 2.
Una ejecución que terminó de inmediato con error — abre Vista. Una falla al lanzar el backend aparece aquí como un error de proceso.
Una ejecución atascada en «Running…» — deténla y luego revisa el Tiempo de silencio (minutos) del agente en la pestaña Ajustes. Un tiempo de espera sin definir usa el valor predeterminado de cada modo.
Una ejecución completada sin salida útil — el estado del registro de ejecuciones se queda en completed para una ejecución que terminó sin su entregable declarado; la señal confiable es el texto del resumen, no la insignia.

La pestaña Registros no muestra ningún costo. Para ver el gasto, usa la tabla por agente de Observabilidad → Resumen.

2. Revisa el backend del agente

Ajustes → Servidor → Proveedores de modelos (/settings/server/providers).

La lista Ejecutores detectados muestra cada adaptador con el resultado de su sonda —una versión instalada, «Comprobando…» o «No encontrado»— además de la ruta resuelta y los chips de capacidades de una CLI encontrada. Haz clic en Actualizar en el encabezado de la página para volver a sondear.

La sonda se ejecuta en la máquina que aloja cc_server, no en la máquina que estás viendo. Si estás en el cliente web o en un dispositivo emparejado, «No encontrado» significa que falta la CLI en el host del servidor.

Dos cosas que debes confirmar:

Que el agente tenga un adaptador configurado. Un agente con el adaptador vacío se despacha a Control Center (built-in) y el registro de ejecuciones anota cc-harness, así que la transcripción indica qué se ejecutó. Si tampoco tiene modelo, le pide a Anthropic el suyo predeterminado, lo que falla con No credential for provider "anthropic" a menos que hayas conectado una cuenta de Anthropic. Los especialistas sembrados vienen sin adaptador.
Que el adaptador integrado tenga un modelo. Su lista de modelos llega en vivo desde los proveedores conectados más abajo en esta misma página, así que un proveedor sin credencial almacenada aporta cero modelos.

El catálogo de adaptadores es fijo: no hay forma de registrar un adaptador nuevo. Lo que sí puedes cambiar por adaptador aquí son sus argumentos de lanzamiento y sus variables de entorno. Ten en cuenta que una anulación de entorno por adaptador se impone en silencio a una cuenta de proveedor conectada cuando se resuelven las credenciales.

3. Revisa el servidor

Ajustes → Servidor → Conexión y estado (/settings/server/connection) muestra con qué servidor está hablando este cliente y qué reporta.

Para un servidor headless, GET /healthz es la misma información sin necesidad de un cliente. No requiere autenticación y tiene CORS abierto por diseño:

curl http://localhost:9030/healthz

Devuelve el estado del servidor, el tiempo de actividad en segundos, el número de conexiones activas, el puerto enlazado, la versión de compilación y el SHA de git, la versión del esquema del espacio de trabajo, la versión del catálogo de RPC, el id, el nombre y la huella de identidad del servidor, si el enlace es inseguro y un bloque codeGraph con los conteos de watching / indexing / pending. Cuando una caché ha visto tráfico, también incluye un bloque caches; un servidor de demostración añade demo: true.

Dos cosas que conviene saber cuando un cambio «funciona en las pruebas pero no en la aplicación»:

El escritorio lanza un binario cc_server precompilado con preferencia sobre el código fuente. Una operación RPC o una herramienta MCP nueva no aparece hasta que se recompila el binario, y el arranque registra un aviso cuando el SHA de git del proceso hijo difiere del de la aplicación.
El escritorio mata un servidor lanzado que no haya impreso su aviso de preparado en 20 segundos y pasa a una pantalla de error.

4. Revisa el host

Ajustes → Servidor → Diagnóstico y privacidad (/settings/server/diagnostics) es la página de nivel de host. Incluye:

Aislamiento — el interruptor maestro, el backend detectado y una sugerencia de instalación. Del servidor solo procede el backend detectado; consulta la advertencia de abajo. No hay ningún control de restablecimiento.
Búsqueda semántica — el ciclo de vida del modelo de embeddings en el dispositivo: instalado, descargándose con un porcentaje, no instalado o un error de instalación. Hasta que esté instalado, la memoria y la búsqueda de código siguen siendo solo por palabras clave.
Comportamiento del sistema — mantener la computadora despierta mientras se ejecutan agentes.
Nivel de registro — súbelo antes de reproducir una falla.
Privacidad — si el contenido de los diffs sin procesar puede reenviarse al modelo del agente y si se envían reportes de fallas.

La detección y la aplicación ahora coinciden: cuando el detector reporta un backend nativo, las ejecuciones de agentes en ese host realmente van envueltas en él. Pero el detector es lo único vivo de esta sección. El interruptor maestro y el selector de backend son preferencias almacenadas en tu dispositivo, y el servidor no lee ninguno de ellos: el interruptor propio del servidor es --sandbox (on por defecto, off para desactivarlo).

Así que una advertencia aquí vale la pena atenderla, pero no suele ser la razón por la que un agente está fallando. Para confirmar en qué estado está el servidor, lee su registro de arranque: imprime agent sandbox ON con la nota del backend, no OS-native agent sandbox on this host con una sugerencia de instalación, o agent sandbox DISABLED by --sandbox off. GET /healthz no incluye ningún campo de sandbox.

Donde no hay backend —Windows siempre, Linux o WSL2 sin bwrap y socat— las ejecuciones no están dentro de un sandbox, y lo que las limita es el propio checkout de la conversación, su token de forja de solo lectura y la pasarela de push, las barandillas de acciones, la sanitización del entorno y la superficie de herramientas que permite su modo.

Fallas comunes

La ejecución nunca empieza y el adaptador muestra «No encontrado»

Instala la CLI en el host del servidor y luego haz clic en Actualizar en la página Proveedores de modelos. O cambia el agente al adaptador integrado, que no necesita ninguna CLI, y conecta un proveedor en esa misma página.

El agente no puede hacer push ni abrir una pull request

Lee lo que han mostrado git o el agente. Control Center policy: … significa que una regla de acción lo denegó o que una aprobación quedó sin respuesta: revisa Enviar a un remoto y Abrir una pull request en Ajustes → Espacio de trabajo → Permisos de agentes. Si git dice que Control Center no tiene ninguna credencial de GitHub que pueda hacer push, instala la GitHub App en ese repositorio o conecta GitHub.

La búsqueda semántica no devuelve nada útil

Consulta Ajustes → Servidor → Diagnóstico y privacidad → Búsqueda semántica. Hasta que el modelo de embeddings esté instalado, la búsqueda es solo por palabras clave. Las filas escritas antes de instalar el modelo nunca se rellenan de forma retroactiva, así que siguen siendo solo por palabras clave incluso después.

El servidor no arranca en absoluto

Las bibliotecas nativas son obligatorias y no existe ningún modo degradado. Si falta una dylib, cc_server se niega a arrancar y señala el archivo problemático en el error. Prepara los nativos con scripts/natives/build_natives.sh y recompila el binario del servidor.

Una acción se deniega en silencio

Una decisión de barandilla prompt sin ningún aprobador conectado se deniega, por diseño. Consulta las reglas del espacio de trabajo en Ajustes → Espacio de trabajo → Permisos de agentes.