Incorporación del agente de IA, no del humano

Pídale a Claude Code que configure un SaaS típico para usted. Abre un navegador, encuentra un formulario de registro que no puede completar, elimina los documentos, elige la ruta de instalación incorrecta entre tres opciones, copia una configuración de ejemplo obsoleta, edita un archivo en ~/.config/, le solicita que reinicie su editor y luego no sabe para qué sirven las herramientas que acaba de registrar.

Veinte minutos. Unos cuantos miles de fichas. Una instalación a medio funcionar.

El problema no es el agente. El problema es que el flujo de incorporación fue diseñado para que un humano lea una página web. Reconstruimos el nuestro desde cero con el supuesto opuesto: un agente es quien ejecuta esto, no un humano. Esta publicación analiza los seis cambios concretos que surgen de esa decisión.

Todo el flujo es un comando, no una página

El cambio más importante: no existe el paso "ir a esta página y hacer clic en registrarse". Todo el flujo es un comando:

npx @agentled/cli setup

El agente ejecuta esto en su propio shell. Bash se ejecuta en la máquina del usuario, por lo que el navegador se abre en la máquina del usuario; el agente nunca necesita representar HTML ni hacer clic en nada. Esto suena obvio en retrospectiva. No es así como la mayoría de los SaaS integrados.

Por qué es importante: cada paso que requiere que el agente "observe" una interfaz de usuario es un sumidero de tokens y un modo de falla. Cada paso que es un comando de shell es una primitiva que el agente ya conoce. El humano todavía tiene que hacer una cosa: iniciar sesión cuando aparece el navegador, pero esa es la única acción que el agente no puede realizar por sí mismo.

Herramientas sin un manual significan un agente confundido

El flujo instala dos cosas, no una:

• El servidor MCP: las herramientas. create_workflow, add_step, upsert_knowledge_text, start_workflow, el resto.
• La habilidad AgentLed: el libro de jugadas. Protocolo de ejecución en seco, reglas de creación incrementales, tipos de pasos válidos, patrones de prueba con eficiencia crediticia.

Este es el cambio que la mayoría de las plataformas pasan por alto. Darle a un agente herramientas sin un manual es como colocar a un ingeniero junior en su base de código con acceso API y sin README. Harán algo. Será costoso y probablemente equivocado.

La habilidad enruta automáticamente al lugar correcto por cliente: ~/.claude/skills/agentled/ para Claude Code o Claude Desktop, ~/.codex/instructions/agentled/ para Codex. Los clientes sin una superficie de habilidades nativa (Cursor, Windsurf hoy) son omitidos con una pista, MCP todavía está conectado. El agente adquiere la habilidad en su próxima sesión y ahora tiene opiniones sobre cómo usar las herramientas: cuándo realizar un ensayo antes de publicar, qué tipos de pasos son válidos para cada caso de uso, cómo realizar pruebas incrementales sin quemar créditos.

Esta es la diferencia entre un agente que tiene más de 100 integraciones disponibles y un agente que sabe cuál buscar en su primer mensaje.

Crea una carpeta de trabajo, no hagas que el agente invente una

El flujo crea agentled_<workspace-slug>/ en el directorio actual con subcarpetas documentadas:

agentled_<workspace-slug>/
  README.md
  worklog.md
  decisions/                 # YYYY-MM-DD-<slug>.md
  workflows/                 # local pipeline JSON drafts
  groups/                    # WorkflowGroup specs
  kg/                        # local mirrors of KG schemas and text drafts
  executions/                # debug bundles for failed runs
  drafts/                    # scratch space

Una carpeta por espacio de trabajo, por lo que un agente que hace malabarismos con dos espacios de trabajo nunca cruza secuencias.

Por qué es importante: los agentes escribirán artefactos en alguna parte. Sin una convención andamiada, dispersan borradores JSON y registros de trabajo en la raíz del repositorio, los mezclan con el código base real y los pierden en la siguiente sesión. La carpeta es un contrato: "este es su espacio temporal, aquí está la estructura, el archivo README explica la regla de sincronización". El agente lee el archivo README al inicio de la sesión y se inserta en la convención.

Bonificación: las carpetas por espacio de trabajo significan que un agente que ha estado trabajando en el espacio de trabajo A y se le pregunta sobre el espacio de trabajo B no tiene que adivinar qué registro de decisiones se aplica. Mira agentled_<active-workspace>/ y esa es la fuente de la verdad.

Una sonda de conocimientos en lugar de un formulario de "describe tu negocio"

El paso seis del flujo lee knowledge.company.profile en el gráfico de conocimiento del espacio de trabajo. Si está configurado, imprime un resumen de una línea y continúa. Si falta, solicita al usuario una vez el nombre de la empresa, el sitio web y el caso de uso, luego escribe el perfil de formato largo en la misma clave a través de upsert_knowledge_text.

Esta es la parte en la que la mayoría de los flujos de incorporación se equivocan dos veces:

• Se saltan por completo el paso "cuéntenos sobre su negocio", y luego cada flujo de trabajo posterior tiene que volver a obtenerlo del usuario, mal, en medio de un trabajo no relacionado.
• O lo solicitan como un formulario de registro y la respuesta desaparece en una pestaña de "configuración de la empresa" a la que el agente no puede acceder.

Almacenarlo como una clave de gráfico de conocimiento conocida significa que cada flujo de trabajo que el agente cree para este espacio de trabajo puede leer el mismo contexto canónico. ICP, tono, integraciones que le interesan al equipo, mercado objetivo: todo ahí, estructurado y consultable. La próxima vez que el agente redacte una secuencia de divulgación, no es necesario que vuelva a preguntar al usuario qué hace su empresa.

La sonda es idempotente: lee lo que escribe el mensaje, por lo que la pregunta nunca se repite en ejecuciones posteriores. Volver a ejecutar la configuración tres veces no significa responder el mismo cuestionario tres veces.

Informe al agente sobre el reinicio, no al usuario

El último paso del flujo imprime algo como: "Reinicie su cliente MCP para seleccionar este espacio de trabajo". El agente lee ese resultado, lo comprende y se lo muestra al usuario explícitamente: "Debe reiniciar Claude Code (reconexión de /mcp o nueva sesión) antes de que aparezcan las nuevas herramientas".

El usuario no tiene que darse cuenta de que faltan herramientas MCP y descubrir por qué por sí solo.

Cosita pequeña. Enorme delta de UX. El modo de falla predeterminado de cada instalación de MCP es "Ejecuté el sistema, ¿por qué no veo las herramientas?"; se resuelve informándole al agente en texto estándar sin formato y confiando en que lo transmitirá.

Idempotente y con versión comprobada, porque el agente se volverá a ejecutar

El primer paso del flujo es una verificación de versión que advierte si la CLI está desactualizada. Todo el flujo es idempotente: ejecutarlo dos veces no vuelve a solicitar información de la empresa, no altera la configuración MCP, no restablece la autenticación.

El agente puede ejecutarlo cada vez que sospeche que algo anda mal. Esto es importante porque el agente a menudo volverá a ejecutar la configuración de manera defensiva; es el paso de depuración más económico. Un script de configuración no idempotente castiga ese instinto y entrena al agente para evitar volver a ejecutarlo, que es lo contrario de lo que desea.

El patrón: cada suposición de que "un humano está leyendo esto" es reemplazada

Seis turnos. Un patrón en todos ellos: cada suposición de que "un humano está leyendo esto" se reemplaza por "un agente está ejecutando esto".

• Comando único, no una página.
• Herramientas enviadas con su propio libro de jugadas.
• Una carpeta temporal con un archivo README que el agente lee al inicio.
• Contexto empresarial como clave consultable, no como pestaña de configuración.
• Instrucciones de reinicio en stdout, no una notificación de banner.
• Idempotente, porque el agente volverá a intentarlo.

Ninguna de estas son características de IA. Son cambios de superficie. Pero la diferencia entre un agente que obtiene su producto en 30 segundos y uno que se da por vencido después de gastar $0,40 en tokens es exactamente la brecha entre estos seis y un asistente de registro tradicional.

El usuario todavía tiene un trabajo, solo uno más pequeño.

Para ser claros: el usuario no se ha ido. El usuario aún inicia sesión cuando aparece el navegador y aún describe su negocio en inglés sencillo la primera vez que se activa la sonda de conocimiento.

Esa es toda la superficie humana. Todo lo demás (instalar la CLI, conectar el servidor MCP al archivo de configuración correcto para el editor detectado, estructurar la carpeta del espacio de trabajo, escribir el perfil empresarial en el gráfico de conocimiento, indicarle al usuario que reinicie) es trabajo del agente, porque el agente es el que tiene acceso al shell y una ventana contextual. El trabajo del flujo es facilitarle al agente hacer todo eso sin inventar nada.

Pruébalo

Abra Claude Code, Codex o Cursor. Dígale a su agente:

Run npx @agentled/cli setup and then build me a workflow that scores
my last 50 inbound leads against our ICP.

Esa es toda la incorporación. El agente instala, autentica, conecta MCP, aprende su manual, escribe el perfil de su empresa en el gráfico de conocimiento del espacio de trabajo, le solicita una entrada de prueba, ejecuta en seco el flujo de trabajo, le muestra el resultado e itera hasta que el resultado sea el que desea. Inicia sesión una vez y describe el trabajo. Eso es todo.

Los patrones descritos anteriormente (comando único, herramientas más manual, carpeta estructurada, sonda de conocimiento, reinicio retransmitido por el agente, repetición idempotente) son convenciones abiertas, no bloqueos de plataforma. La versión que enviamos en AgentLed es una implementación. El punto es la forma: cuando su usuario es un agente, su incorporación deja de ser una página web y se convierte en una función que el agente puede llamar.

La forma a la que llegamos se encuentra en PR #37 si desea leer el conjunto de cambios, y el repositorio de mejores prácticas más amplio en github.com/Agentled/agentic-ops recopila los patrones que la habilidad instala junto con las herramientas.