Desarrollo Técnico
Guía práctica en tres fases de implementación, siguiendo el modelo «Crawl, Walk, Run» que emerge de la literatura más reciente sobre el escalado de sistemas agénticos.
Fase 1: Crawl – Cimientos (Semanas 1-2)
Objetivo: Conectar agentes a herramientas reales y establecer memoria persistente
Paso 1.1: Instalación y verificación de Claude Code
Acción: Asegúrate de tener la versión correcta de Claude Code instalada.
# Verifica la versión (requiere 2.1.138 o superior para algunos plugins)
claude –version
# Si es necesario, actualiza
claude update
Paso 1.2: Conectar tu primer servidor MCP
Acción: Registra un servidor MCP básico. El servidor de documentación de Claude Code es el punto de partida ideal porque no requiere autenticación .
# Añade el servidor de documentación (prueba de concepto)
claude mcp add –transport http claude-code-docs https://code.claude.com/docs/mcp
# Verifica que está conectado
claude mcp list
# Deberías ver: ✓ Connected para claude-code-docs
Explicación: Este paso verifica que el ecosistema MCP funciona correctamente en tu entorno . La conexión exitosa confirma que Claude Code puede comunicarse con servidores externos.
Paso 1.3: Añadir servidores MCP esenciales
Acción: Configura los servidores MCP más útiles para uso diario. Recomiendo comenzar con estos :
# 1. Acceso al sistema de archivos (el más utilizado)
claude mcp add filesystem -s user — npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects
# 2. Servidor de memoria (guarda información entre sesiones)
claude mcp add memory -s user — npx -y @modelcontextprotocol/server-memory
# 3. Pensamiento secuencial (para problemas complejos)
claude mcp add thinking -s user — npx -y @modelcontextprotocol/server-sequential-thinking
# 4. GitHub (gestión de repositorios)
claude mcp add github -s user -e GITHUB_TOKEN=tu-token — npx -y @modelcontextprotocol/server-github
# Verifica todos los servidores
claude mcp list
Sobre el flag -s user: Registra los servidores a nivel global, disponibles en todos tus proyectos . Si prefieres compartir la configuración con tu equipo, usa -s project para crear un archivo .mcp.json en la raíz del proyecto que puede subirse al control de versiones .
Paso 1.4: Configurar memoria persistente (agd-memory)
Acción: Instala el plugin agd-memory, que proporciona memoria persistente por proyecto con un consumo de tokens hasta 14 veces menor que cargar el archivo completo .
# Requisito previo: instalar el CLI de agd
cargo install –git https://github.com/Pinperepette/agd –tag v0.3.1
agd –version # Debe mostrar v0.3.1 o superior
# Dentro de una sesión de Claude Code
/plugin marketplace add Pinperepette/agd-memory
/plugin install agd-memory@agd-memory
# Reinicia la sesión para que el hook y el servidor MCP se carguen
¿Qué hace este plugin?
Hook SessionStart: Inyecta la tabla de contenido de la memoria en el contexto del sistema al inicio.
Skill /agd-memory:memory: Permite leer y escribir en la memoria del proyecto.
Servidor MCP: Expone cuatro herramientas (agd_memory_toc, agd_memory_search, agd_memory_get, agd_memory_save).
Uso básico:
# Dentro de Claude Code, guarda información
«Recuerda que usamos pnpm en este proyecto, no npm»
# Recupera información
«¿Qué sabes sobre el gestor de paquetes de este proyecto?»
Paso 1.5: Integrar memoria Memoria (opcional pero recomendado)
Acción: Instala el bridge de Memoria para memoria a largo plazo con capacidades avanzadas .
# Instala el paquete
npm install @aria-cli/memoria-bridge
# Desde la raíz del proyecto, enlaza el plugin
ln -s path/to/packages/memoria-bridge/.claude-plugin .claude-plugin
Skills disponibles :
Memoria: /remember, /recall, /search, /forget, /reflect
Aprendizaje: /learn-tool, /learn-skill, /create-tool, /create-skill
Gestión de tareas: /quest-update, /quest-list
Fase 2: Walk – Estructurar y automatizar (Semanas 3-4)
Objetivo: Crear agentes especializados y automatizar flujos de trabajo
Paso 2.1: Implementar skills reutilizables con ECC
Acción: Instala «Everything Claude Code» (ECC), que proporciona más de 260 skills predefinidas y 66 agentes especializados .
# Añade la colección de skillsnpx skills
anpx skills add https://github.com/affaan-m/ECC
Skills de mayor utilidad inicial:
TDD (Test-Driven Development): Guía el desarrollo con pruebas primero.
Code Review: Revisión sistemática de código.
Security Review: Análisis de seguridad integrado.
Django/Next.js: Skills específicas para frameworks.
Uso: Cuando inicies una sesión, el agente puede invocar estas skills automáticamente según el contexto .
Paso 2.2: Crear un flujo de trabajo multi-agente simple
Acción: Diseña un sistema de orquestación con un agente líder y agentes especializados. La arquitectura «agente como herramienta» es el patrón más transparente y auditable para empezar .
Estructura recomendada:
Agente Líder (Planificador)
├── Worker A (Análisis)
├── Worker B (Implementación)
└── Worker C (Validación)
Implementación práctica con OpenAI Agents SDK:
from agents import Agent, Runner, function_tool
import asyncio
# 1. Define los agentes especializados
analista_agent = Agent(
name=»Analista»,
instructions=»Analiza requisitos y genera especificaciones claras.»,
model=»gpt-4o»,
)
implementador_agent = Agent(
name=»Implementador»,
instructions=»Implementa código según las especificaciones proporcionadas.»,
model=»gpt-4o»,
)
# 2. Crea herramientas que invoquen a los agentes
@function_tool
async def analizar_requisitos(descripcion: str) -> str:
«»»Analiza requisitos y genera especificaciones.»»»
result = await Runner.run(analista_agent, descripcion)
return result.final_output
@function_tool
async def implementar_codigo(especificacion: str) -> str:
«»»Implementa código según especificación.»»»
result = await Runner.run(implementador_agent, especificacion)
return result.final_output
# 3. Agente líder que orquesta el flujo
lider_agent = Agent(
name=»Líder»,
instructions=»»»
Eres el coordinador del proyecto.
1. Primero, analiza los requisitos usando la herramienta analizar_requisitos.
2. Luego, implementa el código usando implementar_codigo con la especificación generada.
3. Finalmente, presenta el resultado completo.
«»»,
tools=[analizar_requisitos, implementar_codigo],
)
# 4. Ejecución
async def main():
resultado = await Runner.run(
lider_agent,
«Necesito una función que valide direcciones de correo electrónico»
)
print(resultado.final_output)
asyncio.run(main())
Ventaja de este enfoque: El agente líder mantiene un único hilo de control, lo que simplifica la auditoría y permite la ejecución paralela de subtareas .
Paso 2.3: Implementar control de calidad con «gated handoffs»
Acción: Para flujos más complejos, implementa el patrón de handoff con puertas de control .
Arquitectura:
Project Manager (PM)
├── Crea REQUIREMENTS.md y AGENT_TASKS.md
├── Handoff al Designer (con puerta: verifica existencia de documentos)
├── Designer produce /design/design_spec.md
├── PM verifica archivo → Handoff a Frontend y Backend (en paralelo)
├── PM verifica archivos de ambos → Handoff a Tester
└── Tester valida contra criterios de aceptación
Implementación simplificada:
from agents import Agent, function_tool
import os
# Función de verificación de archivos
@function_tool
def verificar_archivo(ruta: str) -> bool:
«»»Verifica si existe un archivo en la ruta especificada.»»»
return os.path.exists(ruta)
# Agente Project Manager con reglas de puerta
pm_agent = Agent(
name=»ProjectManager»,
instructions=»»»
Coordinas el desarrollo del proyecto.
Reglas estrictas:
1. Antes de handoff al Designer, verifica que REQUIREMENTS.md y AGENT_TASKS.md existen.
2. Antes de handoff a Frontend, verifica que design_spec.md existe.
3. Antes de handoff a Tester, verifica que los archivos de Frontend y Backend existen.
4. Si falta algún archivo, solicita al agente correspondiente que lo genere.
«»»,
tools=[verificar_archivo],
handoffs=[designer_agent, frontend_agent, backend_agent, tester_agent],
)
Valor estratégico: Este patrón reduce drásticamente los errores de integración en sistemas multi-agente, garantizando que cada paso tiene los artefactos necesarios antes de proceder
Fase 3: Run – Escalar y gobernar (Semanas 5+)
Objetivo: Producción con observabilidad, gobernanza y cumplimiento
Paso 3.1: Establecer observabilidad con trazabilidad de decisiones
Acción: Implementa el marco de trazabilidad de tres planos para cada decisión del agente :
# Estructura de traza de decisión
def registrar_decision(agente, accion, contexto, resultado):
traza = {
# Plano de evidencia
«evidencia»: {
«fuentes»: contexto.get(«fuentes», []),
«actualidad»: contexto.get(«timestamp»),
«cobertura»: contexto.get(«cobertura»)
},
# Plano de decisión
«decision»: {
«agente»: agente,
«accion»: accion,
«herramientas_utilizadas»: contexto.get(«tools_used», []),
«politicas_aplicadas»: contexto.get(«policies», [])
},
# Plano de resultados
«resultado»: {
«output»: resultado,
«kpi_impacto»: calcular_impacto(resultado),
«intervencion_humana»: contexto.get(«human_override», False)
}
}
guardar_traza(traza)
Preguntas clave que el sistema debe poder responder :
1.¿Qué vio el agente? (evidencia disponible)
2. ¿Qué hizo el agente? (acciones ejecutadas)
3. ¿Qué restricciones se verificaron? (controles aplicados)
4. ¿Cómo se supervisaron los resultados? (monitorización posterior)
Paso 3.2: Política como código y guardarraíles
Acción: Implementa reglas de gobernanza incrustadas en el comportamiento del agente.
from agents import Agent, function_tool
# Definición de políticas como código
POLITICAS = {
«acceso_datos»: {
«permisos»: [«read», «write»] # Sin «delete» por defecto
},
«confianza»: {
«umbral_minimo»: 0.8, # Decisiones con confianza < 0.8 requieren aprobación humana
«escalacion_automatica»: True
},
«auditoria»: {
«log_todas_decisiones»: True,
«retencion_dias»: 90
}
}
@function_tool
def verificar_politica(accion: str, confianza: float) -> bool:
«»»Verifica si una acción cumple con las políticas establecidas.»»»
if accion == «delete» and «delete» not in POLITICAS[«acceso_datos»][«permisos»]:
return False
if confianza < POLITICAS[«confianza»][«umbral_minimo»]:
return POLITICAS[«confianza»][«escalacion_automatica»] # Escala a humano
return True
Principio fundamental: «Las reglas fallan en el prompt, tienen éxito en el límite» . La política debe aplicarse en la capa de orquestación, no confiar en que el LLM se auto-regule.
Paso 3.3: Escalamiento con arquitectura de flujo de eventos
Acción: Evoluciona de procesamiento por lotes a arquitectura basada en eventos, clave para agentes autónomos de producción .
Componentes recomendados:
Colas de mensajes (Redis, RabbitMQ): Para comunicación entre agentes sin bloqueo.
Streaming de eventos (Kafka): Para capturar todas las decisiones en tiempo real.
Almacenamiento de trazas (Elasticsearch/OpenSearch): Para consultas y auditoría.
Comando para añadir el servidor MCP de observabilidad:
# Añade servidor de logging estructurado
claude mcp add observability -s user — npx -y @modelcontextprotocol/server-observability
Paso 3.4: Simplicidad y determinismo antes que complejidad
Principio crítico: Comienza con agentes deterministas (reglas predefinidas, predecibles) antes de evolucionar a no-deterministas (LLM con razonamiento contextual) .
Cuando avanzar a no-determinista:
La observabilidad está madura (trazas completas, consultables).
La gobernanza está establecida (políticas como código, escalación humana).
La confianza organizacional está construida (equipos entienden los límites).
Resumen: Hoja de ruta en comandos
# === SEMANA 1: Crawl ===
# 1. Verificar instalación
claude –version
# 2. Servidores esenciales
claude mcp add filesystem -s user — npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects
claude mcp add memory -s user — npx -y @modelcontextprotocol/server-memory
claude mcp add thinking -s user — npx -y @modelcontextprotocol/server-sequential-thinking
# 3. Memoria persistente (agd-memory)
cargo install –git https://github.com/Pinperepette/agd –tag v0.3.1
/plugin marketplace add Pinperepette/agd-memory
/plugin install agd-memory@agd-memory
# === SEMANA 2-3: Walk ===
# 4. Skills (ECC)
npx skills add https://github.com/affaan-m/ECC
# 5. Memoria avanzada (opcional)
npm install @aria-cli/memoria-bridge
ln -s path/to/packages/memoria-bridge/.claude-plugin .claude-plugin
# === SEMANA 4+: Run ===
# 6. Observabilidad
claude mcp add observability -s user — npx -y @modelcontextprotocol/server-observability
# 7. Verificación completa
claude mcp list # Debería mostrar todos los servidores activos
Referencias rápidas por recurso
| Recurso | Propósito principal | Comando de instalación |
| MCP Filesystem | Leer/escribir archivos | claude mcp add filesystem -s user — npx -y @modelcontextprotocol/server-filesystem ~/Documents |
| MCP Memory | Guardar información entre sesiones | claude mcp add memory -s user — npx -y @modelcontextprotocol/server-memory |
| agd-memory | Memoria persistente por proyecto (eficiencia tokens) | /plugin install agd-memory@agd-memory |
| memoria-bridge | Memoria con aprendizaje y gestión de tareas | npm install @aria-cli/memoria-bridge |
| ECC | 260+ skills y 66 agentes predefinidos | npx skills add https://github.com/affaan-m/ECC |
| OpenAI Agents SDK | Orquestación multi-agente | pip install openai-agents |
Manu Duque
AI Visibility Specialist
ai-visibility.es
Te puede interesar;
De la Experimentación a la Revolución de la IA Agéntica
