Utilice el servidor CLI y MCP juntos
El servidor AgentLed MCP es la superficie de razonamiento en vivo. El AgentLed CLI es la superficie de construcción disk-backed. Utilice ambos en el mismo espacio de trabajo para crear, probar y publicar flujos de trabajo sin gastar créditos en cada edición.
TL;DR
- •MCP = decisiones en vivo. Los resultados de Tool llegan directamente al contexto del agente y alimentan el siguiente paso de razonamiento.
- •CLI = estado materializado. La salida va a la salida estándar o al disco, por lo que el agente puede leer solo los archivos y campos que necesita.
- •Mismo espacio de trabajo, misma autenticación. Ambos usan
AGENTLED_API_KEY, opcionalAGENTLED_URL, y lo mismo@agentled/corecomportamiento bajo el capó.
Instalar + Autenticar
Instale CLI globalmente si esta máquina funcionará con frecuencia en proyectos AgentLed. Usar npx para llamadas estilo one-off o CI.
npm i -g @agentled/cli # or run without installing npx -y @agentled/cli help
Registre el servidor MCP con su cliente. Claude Code usa esta forma:
claude mcp add agentled \ -e AGENTLED_API_KEY=wsk_... \ -- npx -y @agentled/mcp-server
Codex y otros clientes MCP utilizan el mismo proceso de servidor:
codex mcp add agentled \ -e AGENTLED_API_KEY=wsk_... \ -- npx -y @agentled/mcp-server
Cree una clave API en el espacio de trabajo Workspace Settings > Developer. Exportarlo para llamadas CLI y pasarlo a la configuración de su cliente MCP.
export AGENTLED_API_KEY=wsk_... export AGENTLED_URL=https://www.agentled.app agentled workspace inspect --format json
AGENTLED_URL es opcional para la plataforma administrada. Configúrelo solo cuando su espacio de trabajo utilice una base AgentLed API URL personalizada.
Cuándo usar cuál
Regla general: si la respuesta debe caber en un párrafo sobre el que razona el agente, utilice MCP. Si la respuesta es "hacer que aparezca este archivo", utilice el archivo CLI.
| Situación | Usar | Por qué |
|---|---|---|
| Necesita el siguiente paso de razonamiento para utilizar el resultado. | MCP | El resultado ya está en contexto. |
| Consulta de un solo registro | MCP | Un objeto JSON es lo suficientemente pequeño como para inspeccionarlo en línea. |
| Listar más de 50 registros | CLI | Canalice JSON a un archivo y fíltrelo sin completar el contexto. |
| Producir flujo de trabajo JSON, elementos fijos, informes o instantáneas | CLI | La salida pertenece al árbol de trabajo. |
| Chat en mitad de una conversación con un agente AgentLed | MCP | El estado conversacional pertenece al ciclo del agente activo. |
| Orquestación interactiva multi-step | MCP | El resultado de cada herramienta debe orientar la siguiente llamada. |
| Construir, ejecutar, capturar y afirmar iteraciones | CLI | Las pruebas y los accesorios se guardan en el disco y se reproducen sin créditos. |
| Orientación del espacio de trabajo de una sola vez | CLI | workspace inspect devuelve el mapa del espacio de trabajo una vez. |
# Bulk data: keep it out of the model context. agentled workflows list --format json > /tmp/agentled-workflows.json # Then inspect only what matters. rg '"status": "live"|outbound|scoring' /tmp/agentled-workflows.json
El bucle canónico
Esta es la ruta de iteración zero-credit. Ejecute el flujo de trabajo una vez, capture salidas de pasos reales y luego reproduzca pruebas de dispositivos mientras edita. El paso 6 es el desbloqueo: una vez que los dispositivos están en el disco, el bucle de prueba normal no cuesta créditos.
# 1. Create the local workspace folder once. agentled init acme # 2. Orient and pick a workflow. agentled workspace inspect --format json > agentled_acme/workspace.inspect.json
# 3. Pull a workflow into the local workspace. agentled workflows pull <wfId> # This writes the workflow JSON and a test skeleton. # Edit tests/<wfId>.test.json before the first replay.
# 4. Use MCP for the one live execution. # Call start_workflow with representative sample input. # Save the returned execution id as <execId>.
# 5. Capture real step outputs from that execution. agentled fixture capture <execId> --wf <wfId> # Fixtures land in fixtures/step-outputs/<execId>/. # They become local, replayable test inputs.
# 6. Replay assertions with zero credits. agentled test <wfId> # 7. Edit pipeline JSON, prompts, mappings, or test assertions. # 8. Replay the full test suite again. agentled test <wfId>
# 9. When one step needs a live check, spend narrowly. agentled test <wfId> --step score-lead --live # 10. Validate before publishing. agentled workflows lint examples/live/<workflow>.json agentled dryrun examples/live/<workflow>.json agentled workflows validate <wfId>
# 11. Use MCP to publish when validation is clean. # Call publish_workflow with workflowId=<wfId> and status=live.
Utilice MCP durante este ciclo para tomar decisiones que pertenecen a la conversación: elegir el flujo de trabajo, iniciar la ejecución en vivo única, editar un paso con update_step, comprobar los resultados de la validación y publicarlos. Utilice CLI para todo lo que cree o lea el estado local.
Realice el vuelo antes de gastar créditos
Ejecute estas comprobaciones antes start_workflow o cualquier vivo agentled test --live. Los códigos de salida son estables: 0 limpio, 1 advertencia, 2 error.
agentled workflows lint examples/live/<workflow>.json agentled dryrun examples/live/<workflow>.json agentled workflows validate <wfId>
workflows lint detecta errores estáticos en el archivo. dryrun recorre el gráfico, resuelve referencias de plantillas frente a resultados simulados o capturados y estima créditos. workflows validate <id>ejecuta el validador server-side después de que el flujo de trabajo exista en AgentLed.
Referencias protegidas por respaldo, como {{x || 'default'}} son advertencias, no errores. El tiempo de ejecución puede resolverlos mediante el recurso alternativo, pero la advertencia le indica al agente que es posible que no exista la ruta principal.
Operaciones reflejadas versus operaciones solo de superficie
reflejado
| Operación | MCP | CLI |
|---|---|---|
| Listar flujos de trabajo | list_workflows | agentled workflows list |
| Obtener flujo de trabajo | get_workflow | agentled workflows get <id> |
| Validar flujo de trabajo | validate_workflow | agentled workflows validate <id> |
| Iniciar ejecución | start_workflow | agentled workflows start <id> |
| Aplicación de prueba o acción AI | test_app_action, test_ai_action | agentled apps, agentled ai |
| Knowledge Graph lee y escribe | Herramientas de conocimiento | agentled knowledge |
CLI-solo
| Operación | Dominio | Por qué |
|---|---|---|
| Iniciar un espacio de trabajo de repositorio | agentled init | Crea el árbol de carpetas locales. |
| Actualizar caché local | agentled workspace sync | Actualiza documentos, aplicaciones y modelos almacenados en caché. |
| Extraer flujo de trabajo | agentled workflows pull <wfId> | Escribe el flujo de trabajo JSON y un esqueleto de prueba. |
| Capturar accesorios | agentled fixture capture <execId> --wf <wfId> | Guarda las salidas de los pasos en el disco. |
| Lista de partidos | agentled fixture list | Lee conjuntos de accesorios locales. |
| Repetir pruebas | agentled test <wfId> | Realiza afirmaciones contra partidos locales. |
| Pelusa estática | agentled workflows lint <file> | Comprueba un archivo de canalización local. |
MCP-solo
| Operación | Tool | Por qué |
|---|---|---|
| Chat en el espacio de trabajo | chat, chat_with_agent | Regresa directamente a la conversación activa. |
| Edición de pasos incrementales | add_step, update_step, remove_step, move_step | Cada edición devuelve una validación que informa la siguiente edición. |
| Parche de línea de tiempo | patch_timeline_fields | Operación de administrador incident-response. |
| Parcheo de ejecución | patch_execution_fields | Operación de administrador incident-response. |
Orientación en un repositorio nuevo
Cuando un agente llega a un repositorio, debe buscar un agentled_*/ carpeta en el directorio actual o cualquier antecesor primero. Esa carpeta es la memoria de trabajo persistente del espacio de trabajo. Contiene flujos de trabajo extraídos, pruebas, accesorios, metadatos de aplicaciones en caché y documentos locales.
Si no existe ninguna carpeta del espacio de trabajo, ejecute agentled init [slug] una vez. Entonces corre agentled workspace inspectpara una orientación single-shot: identidad, perfil de empresa, flujos de trabajo, listas Knowledge Graph, aplicaciones conectadas y agentes. Para un trabajo profundo en un flujo de trabajo, siga con agentled workflows pull <wfId>.
# From the repo root: find .. -maxdepth 3 -type d -name 'agentled_*' 2>/dev/null # If none exists: agentled init acme # Orient once, then pull the workflow you are changing. agentled workspace inspect --format json > agentled_acme/workspace.inspect.json agentled workflows pull <wfId>
Modelo de error
Ambas superficies hablan JSON. El CLI proporciona a los agentes señales de proceso estables. MCP ofrece a los agentes resultados de herramientas estructurados.
| Superficie | Forma de error | Comportamiento del agente |
|---|---|---|
| CLI | {"error":"...","code":"..."} más código de salida | Rama en 0, 1, o 2 en bucles de concha. |
| MCP | { error, code } en el resultado de la herramienta | Lea el error como cualquier otra respuesta de herramienta y decida la siguiente llamada. |
Tratar 1 como advertencia o falla recuperable y 2 como un error estructural o de validación. En guiones desatendidos, deténgase 2 e imprima la salida del validador.
Parche de administrador Tools
patch_timeline_fields y patch_execution_fields existen para la respuesta a incidentes. Requieren una clave API con la admin:patch alcance. No los utilice para operaciones rutinarias de flujo de trabajo, reintentos normales, generación de dispositivos o ediciones de pasos. Si los busca repetidamente, el flujo de trabajo está mal configurado y debe corregirse en la fuente.
Próximos pasos
- MCP Connection — conecte su cliente MCP.
- MCP Tools Reference — inspeccionar las herramientas disponibles.
- agentled create - crear flujos de trabajo a partir de lenguaje natural.