Especificación de Agentes IA - Calmia Nexus¶

Versión: 1.0 Última Actualización: 2026-02-01 Audiencia: Prompt Engineers, Configuradores de Agentes, Desarrolladores IA

Índice¶

1. Arquitectura de Agentes
2. Entidades del Sistema
3. System Prompts
4. Skills y Competencias
5. Sistema de Triggers
6. Modos de Orquestación
7. Agentes Remotos
8. Sugerencias Automáticas
9. API de Gestión
10. Mejores Prácticas
11. Ejemplos de Configuración
Glosario

1. Arquitectura de Agentes¶

1.1 Visión General¶

graph TB
    subgraph "Capa de Entrada"
        U[Usuario] --> |Prompt| W[Workspace]
        W --> |Ctrl+Enter| SS[AgentSuggestionService]
    end

    subgraph "Capa de Orquestación"
        SS --> |Sugiere| A[Agente Recomendado]
        W --> |Ejecuta| MO[MultiAgentOrchestrator]
        MO --> |Sequential| SEQ[Ejecución Secuencial]
        MO --> |Parallel| PAR[Ejecución Paralela]
        MO --> |Debate| DEB[Modo Debate]
        MO --> |Consultation| CON[Modo Consulta]
    end

    subgraph "Capa de Ejecución"
        SEQ --> CS[CopilotService]
        PAR --> CS
        DEB --> CS
        CON --> CS
        CS --> |API| Claude[Claude API]
        CS --> |SignalR| RA[Remote Agents]
    end

    subgraph "Capa de Datos"
        A --> DB[(PostgreSQL)]
        RA --> DB
        Claude --> |Logs| DB
    end

1.2 Componentes Principales¶

Componente	Responsabilidad	Archivo
Agent	Entidad principal de agente	`Entities/Agent.cs`
AgentSkill	Relación agente-skill	`Entities/AgentSkill.cs`
AgentTrigger	Activadores de agente	`Entities/AgentTrigger.cs`
RemoteAgent	Agente remoto (Claude CLI)	`Entities/RemoteAgent.cs`
CopilotService	Ejecución de prompts	`Services/CopilotService.cs`
MultiAgentOrchestrator	Orquestación multi-agente	`Services/MultiAgentOrchestrator.cs`
AgentSuggestionService	Sugerencias inteligentes	`Services/AgentSuggestionService.cs`

1.3 Flujo de Datos¶

sequenceDiagram
    participant U as Usuario
    participant W as Workspace
    participant S as SuggestionService
    participant C as CopilotService
    participant A as Agent (DB)
    participant AI as Claude API

    U->>W: Escribe prompt
    W->>S: Shift+Enter (sugerir agente)
    S->>A: Buscar agentes relevantes
    A-->>S: Lista de agentes
    S->>S: Calcular scores
    S-->>W: Agente recomendado

    U->>W: Enter (ejecutar)
    W->>C: SendMessageAsync(prompt, agentId)
    C->>A: Obtener SystemPrompt
    A-->>C: Agent config
    C->>C: Construir contexto
    C->>AI: API Request
    AI-->>C: Streaming response
    C-->>W: Chunks en tiempo real

2. Entidades del Sistema¶

2.1 Agent (Agente Principal)¶

public class Agent
{
    public Guid Id { get; set; }
    public string Slug { get; set; }              // "backend-architect"
    public string Name { get; set; }              // "Backend Architect"
    public string? Description { get; set; }      // Descripción corta
    public string Model { get; set; }             // "sonnet", "opus", "haiku"
    public string SystemPrompt { get; set; }      // Prompt de sistema completo
    public string Source { get; set; }            // "custom" | "upstream"
    public bool IsActive { get; set; }            // Habilitado/deshabilitado
    public DateTime CreatedAt { get; set; }
    public DateTime UpdatedAt { get; set; }

    // Relaciones
    public ICollection<AgentSkill> Skills { get; set; }
    public ICollection<AgentTrigger> Triggers { get; set; }
    public ICollection<PluginAgent> PluginAgents { get; set; }
}

Modelos Disponibles:

Modelo	ID API	Uso Recomendado	Tokens/Min
Haiku	`claude-3-5-haiku-20241022`	Tareas rápidas, clasificación	~150K
Sonnet	`claude-sonnet-4-20250514`	Propósito general, código	~90K
Opus	`claude-opus-4-20250514`	Tareas complejas, arquitectura	~60K

2.2 AgentSkill (Competencias)¶

public class AgentSkill
{
    public Guid AgentId { get; set; }
    public string Skill { get; set; }         // ID del skill (ej: "api-design")
    public int Proficiency { get; set; }      // 1-10 (nivel de dominio)
    public Agent Agent { get; set; }
}

Escala de Proficiency:

Nivel	Descripción	Ejemplo
1-3	Básico	Conocimiento introductorio
4-6	Intermedio	Puede aplicar en proyectos
7-8	Avanzado	Conocimiento profundo
9-10	Experto	Autoridad en el tema

2.3 AgentTrigger (Activadores)¶

public class AgentTrigger
{
    public Guid Id { get; set; }
    public Guid AgentId { get; set; }
    public string TriggerType { get; set; }   // keyword | pattern | intent | schedule | event
    public string Pattern { get; set; }       // Patrón de activación
    public int Priority { get; set; }         // Prioridad (menor = más alta)
    public Agent Agent { get; set; }
}

2.4 RemoteAgent (Agente Remoto)¶

public class RemoteAgent
{
    public Guid Id { get; set; }
    public string Name { get; set; }              // "Laptop-Dev-Juan"
    public string ApiKey { get; set; }            // Clave única (enmascarada)
    public string ApiKeyHash { get; set; }        // Hash SHA256
    public Guid OrganizationId { get; set; }
    public RemoteAgentStatus Status { get; set; } // Offline | Connecting | Online | Busy | Error
    public string? ConnectionId { get; set; }     // ID SignalR
    public DateTime? LastHeartbeat { get; set; }
    public string? SystemInfo { get; set; }       // JSON con info del sistema
    public string? AgentVersion { get; set; }     // Versión del cliente
    public string? DefaultWorkingDirectory { get; set; }
    public string? CapabilitiesJson { get; set; } // ["claude_cli", "git", "docker"]

    // Métricas
    public int TotalCommandsExecuted { get; set; }
    public int TotalErrors { get; set; }
    public long TotalTokensUsed { get; set; }

    // Telemetría
    public int? CpuUsagePercent { get; set; }
    public int? MemoryUsagePercent { get; set; }
    public int? DiskUsagePercent { get; set; }
}

public enum RemoteAgentStatus
{
    Offline = 0,     // Sin conexión
    Connecting = 1,  // Intentando conectar
    Online = 2,      // Listo para comandos
    Busy = 3,        // Ejecutando
    Error = 4        // Error en conexión
}

3. System Prompts¶

3.1 Estructura Recomendada¶

Un System Prompt efectivo sigue esta estructura:

## Identidad
Eres [NOMBRE_AGENTE], un especialista en [DOMINIO].

## Contexto
Trabajas en el proyecto [PROYECTO] usando [TECNOLOGÍAS].

## Capacidades
- [Capacidad 1]
- [Capacidad 2]
- [Capacidad 3]

## Limitaciones
- [Limitación 1]
- [Limitación 2]

## Formato de Respuesta
Siempre responde siguiendo este formato:
1. [Paso 1]
2. [Paso 2]
3. [Paso 3]

## Ejemplos
### Ejemplo 1: [Título]
**Input:** [entrada]
**Output:** [salida esperada]

3.2 Plantilla Base¶

Eres un agente especializado en: {description}

Tu rol es asistir con tareas relacionadas a este dominio, proporcionando:
- Análisis técnico detallado
- Recomendaciones basadas en mejores prácticas
- Soluciones específicas para el contexto

Cuando recibas una tarea:
1. Analiza el contexto completo
2. Identifica los requisitos clave
3. Proporciona una respuesta estructurada
4. Incluye ejemplos cuando sea apropiado

Siempre sigue las mejores prácticas del dominio y mantén un enfoque profesional.

3.3 Ejemplos por Tipo de Agente¶

Backend Architect¶

## Identidad
Eres Backend Architect, un experto en diseño y arquitectura de sistemas backend.

## Especialización
- Arquitectura de microservicios
- Patrones de diseño (Repository, CQRS, Event Sourcing)
- .NET 8/9, ASP.NET Core, Entity Framework Core
- PostgreSQL, Redis, RabbitMQ

## Contexto del Proyecto
{project_context}

## Proceso de Trabajo
1. **Análisis**: Comprende el problema y los requisitos
2. **Diseño**: Propón arquitectura con diagramas cuando sea útil
3. **Implementación**: Proporciona código C# siguiendo mejores prácticas
4. **Validación**: Incluye consideraciones de testing

## Formato de Código
- Usa nullable reference types
- Aplica principios SOLID
- Incluye comentarios XML para APIs públicas
- Sigue convenciones de naming de .NET

## Restricciones
- No expongas secretos o credenciales
- Prefiere inyección de dependencias
- Evita código acoplado

Security Specialist¶

## Identidad
Eres Security Specialist, un experto en seguridad de aplicaciones.

## Especialización
- OWASP Top 10
- Análisis de vulnerabilidades
- Revisión de código seguro
- Autenticación y autorización

## Proceso de Análisis
1. **Identificar**: Detecta posibles vulnerabilidades
2. **Clasificar**: Severidad (Critical/High/Medium/Low)
3. **Remediar**: Proporciona soluciones específicas
4. **Verificar**: Incluye tests de seguridad

## Checklist de Seguridad
- [ ] Inyección SQL/NoSQL
- [ ] XSS (Cross-Site Scripting)
- [ ] CSRF (Cross-Site Request Forgery)
- [ ] Autenticación rota
- [ ] Exposición de datos sensibles
- [ ] Configuración de seguridad incorrecta

## Output Esperado
```json
{
  "vulnerabilities": [
    {
      "id": "SEC-001",
      "severity": "HIGH",
      "category": "Injection",
      "description": "...",
      "location": "file:line",
      "remediation": "..."
    }
  ]
}

### 3.4 Construcción Dinámica de Contexto

El sistema construye el contexto final combinando:

```mermaid
graph LR
    SP[SystemPrompt Base] --> C[Contexto Final]
    PC[Project Context] --> C
    SC[Session Context] --> C
    SK[Skills Relevantes] --> C
    MEM[Memorias] --> C
    HIST[Historial Optimizado] --> C
    C --> AI[Claude API]

Código de construcción (DevSessionService):

// 1. Base: System prompt del agente
if (agent != null && !string.IsNullOrEmpty(agent.SystemPrompt))
{
    systemBuilder.AppendLine(agent.SystemPrompt);
}

// 2. Contexto del proyecto (README, estructura, etc.)
if (!string.IsNullOrEmpty(projectContext))
{
    systemBuilder.AppendLine("\n## Contexto del Proyecto");
    systemBuilder.AppendLine(projectContext);
}

// 3. Memorias persistentes de la sesión
if (memories.Any())
{
    systemBuilder.AppendLine("\n## Memorias Relevantes");
    foreach (var memory in memories)
    {
        systemBuilder.AppendLine($"- {memory.Content}");
    }
}

// 4. Historial optimizado (resumen + mensajes recientes)
var optimizedHistory = await _historyManager.GetOptimizedHistoryAsync(sessionId);

4. Skills y Competencias¶

4.1 Estructura de un Skill¶

public class Skill
{
    public string Id { get; set; }           // "api-design-principles"
    public string Name { get; set; }         // "API Design Principles"
    public string? Description { get; set; } // Descripción breve
    public string? Category { get; set; }    // "backend", "security", etc.
    public string ContentMd { get; set; }    // Contenido completo
    public string Source { get; set; }       // "custom" | "upstream"
    public bool IsActive { get; set; }
}

4.2 Categorías de Skills¶

Categoría	Descripción	Ejemplos
`security`	Seguridad de aplicaciones	OWASP, auditoría, secrets
`database`	Bases de datos	SQL, índices, PostgreSQL
`api`	Diseño de APIs	REST, GraphQL, versioning
`frontend`	Desarrollo frontend	React, Vue, CSS
`backend`	Desarrollo backend	.NET, patrones, servicios
`devops`	Operaciones	CI/CD, Docker, K8s
`test`	Testing	Unit, integration, e2e
`performance`	Rendimiento	Optimización, profiling
`documentation`	Documentación	README, ADR, changelog

4.3 Asignación de Skills a Agentes¶

API Endpoints:

# Agregar skill a agente
POST /api/agents/{agentId}/skills
Content-Type: application/json

{
  "skill": "api-design-principles",
  "proficiency": 8
}

# Actualizar proficiency
PUT /api/agents/{agentId}/skills/api-design-principles
Content-Type: application/json

{
  "proficiency": 9
}

# Eliminar skill
DELETE /api/agents/{agentId}/skills/api-design-principles

# Reemplazar todos los skills
PUT /api/agents/{agentId}/skills
Content-Type: application/json

[
  { "skill": "api-design-principles", "proficiency": 9 },
  { "skill": "dotnet-patterns", "proficiency": 8 },
  { "skill": "security-best-practices", "proficiency": 7 }
]

4.4 Skill Content (SKILL.md)¶

# API Design Principles

## Descripción
Principios fundamentales para diseño de APIs REST.

## Contenido

### 1. Versionado
- Usar prefijo de versión en URL: `/api/v1/`
- O header: `Accept: application/vnd.api+json;version=1`

### 2. Naming Conventions
- Sustantivos en plural: `/users`, `/orders`
- Kebab-case para recursos: `/user-profiles`
- camelCase para JSON

### 3. HTTP Methods
| Método | Uso | Idempotente |
|--------|-----|-------------|
| GET | Obtener | Sí |
| POST | Crear | No |
| PUT | Reemplazar | Sí |
| PATCH | Actualizar parcial | No |
| DELETE | Eliminar | Sí |

### 4. Status Codes
- 2xx: Éxito
- 4xx: Error del cliente
- 5xx: Error del servidor

## Ejemplos
[Ver ejemplos en código]

5. Sistema de Triggers¶

5.1 Tipos de Triggers¶

Tipo	Descripción	Ejemplo de Pattern
keyword	Palabra clave simple	`security`
pattern	Expresión regular	`^bug:.*database`
intent	Detección de intención (NLP)	`check for vulnerabilities`
schedule	Cronograma (CRON)	`0 9 * * 1`
event	Evento del sistema	`sentry:error`

5.2 Configuración de Triggers¶

Keyword Trigger:

{
  "triggerType": "keyword",
  "pattern": "security",
  "priority": 1
}

Activa el agente cuando el prompt contiene "security".

Pattern Trigger (Regex):

{
  "triggerType": "pattern",
  "pattern": "^(bug|fix|error):.*",
  "priority": 2
}

Activa cuando el prompt comienza con "bug:", "fix:", o "error:".

Intent Trigger:

{
  "triggerType": "intent",
  "pattern": "revisar código seguridad",
  "priority": 3
}

Usa NLP para detectar intenciones similares.

Schedule Trigger:

{
  "triggerType": "schedule",
  "pattern": "0 9 * * 1",
  "priority": 5
}

Ejecuta todos los lunes a las 9:00 AM.

Event Trigger:

{
  "triggerType": "event",
  "pattern": "sentry:new_issue",
  "priority": 1
}

Activa cuando Sentry detecta un nuevo issue.

5.3 Prioridad de Triggers¶

Menor número = Mayor prioridad
Si múltiples triggers coinciden, gana el de menor prioridad
Triggers del mismo agente se evalúan en orden de prioridad

5.4 API de Triggers¶

# Agregar trigger
POST /api/agents/{agentId}/triggers
Content-Type: application/json

{
  "triggerType": "keyword",
  "pattern": "database",
  "priority": 2
}

# Actualizar trigger
PUT /api/agents/{agentId}/triggers/{triggerId}
Content-Type: application/json

{
  "triggerType": "pattern",
  "pattern": "^optimize:.*db",
  "priority": 1
}

# Eliminar trigger
DELETE /api/agents/{agentId}/triggers/{triggerId}

6. Modos de Orquestación¶

6.1 OrchestrationMode¶

public enum OrchestrationMode
{
    Sequential,    // Uno tras otro
    Parallel,      // Simultáneo
    Debate,        // Pro vs Con + Árbitro
    Consultation   // Múltiples especialistas
}

6.2 Modo Sequential (Default)¶

graph LR
    P[Prompt] --> A1[Agente 1]
    A1 --> A2[Agente 2]
    A2 --> A3[Agente 3]
    A3 --> R[Resultado]

Características: - Ejecución ordenada - Cada agente recibe el contexto anterior - Ideal para workflows lineales

Uso:

{
  "goal": "Implementar feature de login",
  "mode": "Sequential"
}

6.3 Modo Parallel¶

graph TB
    P[Prompt] --> H[Haiku: Dividir]
    H --> T1[Sub-tarea 1]
    H --> T2[Sub-tarea 2]
    H --> T3[Sub-tarea 3]
    T1 --> I[Integración]
    T2 --> I
    T3 --> I
    I --> R[Resultado]

Características: - Haiku divide la tarea en sub-tareas - Máximo 4 sub-tareas paralelas - Integración automática de resultados

Uso:

{
  "goal": "Revisar seguridad de todo el proyecto",
  "mode": "Parallel"
}

Estructura de División:

href="#__codelineno-22-1">{ "subtasks": [ { "name": "review-auth", "description": "Revisar autenticación", "dependencies": [] }, { "name": "review-api", "description": "Revisar endpoints API", "dependencies": [] }, { "name": "review-data", "description": "Revisar acceso a datos", "dependencies": [] } ], "integration_strategy": "Consolidar hallazgos por severidad" }

6.4 Modo Debate¶

graph TB
    P[Prompt/Decisión] --> PRO[Agente PRO]
    P --> CON[Agente CON]
    PRO --> |Argumentos a favor| ARB[Árbitro Sonnet]
    CON --> |Argumentos en contra| ARB
    ARB --> V[Veredicto]

Características: - Dos perspectivas opuestas - Árbitro imparcial (Sonnet) - Ideal para decisiones arquitectónicas

Uso:

{
  "goal": "¿Deberíamos usar microservicios o monolito?",
  "mode": "Debate",
  "debateConfig": {
    "proPosition": "Microservicios",
    "conPosition": "Monolito"
  }
}

Criterios del Árbitro: - Rendimiento - Mantenibilidad - Escalabilidad - Curva de aprendizaje - Ecosistema - Costos - Contexto específico del proyecto

6.5 Modo Consultation¶

graph TB
    P[Prompt] --> S1[Security Specialist]
    P --> S2[Performance Expert]
    P --> S3[DevOps Engineer]
    S1 --> I[Integración]
    S2 --> I
    S3 --> I
    I --> R[Plan Consolidado]

Características: - Consulta a múltiples especialistas en paralelo - Cada uno aporta su perspectiva - Integración priorizada por impacto/urgencia

Uso:

{
  "goal": "Planificar migración a la nube",
  "mode": "Consultation",
  "specialists": [
    { "role": "cloud-architect", "focus": "Arquitectura AWS" },
    { "role": "security", "focus": "Compliance y seguridad" },
    { "role": "devops", "focus": "CI/CD y automatización" }
  ]
}

6.6 OrchestrationResult¶

public class OrchestrationResult
{
    public OrchestrationMode Mode { get; set; }
    public string Goal { get; set; }
    public List<AgentResult> AgentResults { get; set; }
    public string FinalResult { get; set; }
    public string? ArbitrationSummary { get; set; }  // Solo para Debate
    public int TotalTokensUsed { get; set; }
}

public class AgentResult
{
    public string AgentRole { get; set; }
    public string Result { get; set; }
    public int TokensUsed { get; set; }
    public long DurationMs { get; set; }
}

7. Agentes Remotos¶

7.1 Arquitectura¶

graph TB
    subgraph "Servidor (Orchestrator API)"
        API[REST API]
        HUB[SignalR Hub]
        DB[(PostgreSQL)]
    end

    subgraph "Máquinas Remotas"
        RA1[Remote Agent 1<br/>Claude CLI]
        RA2[Remote Agent 2<br/>Claude CLI]
        RA3[Remote Agent 3<br/>Claude CLI]
    end

    API --> HUB
    HUB <--> |WebSocket| RA1
    HUB <--> |WebSocket| RA2
    HUB <--> |WebSocket| RA3
    HUB --> DB

7.2 Ciclo de Vida de Conexión¶

stateDiagram-v2
    [*] --> Offline
    Offline --> Connecting: Connect()
    Connecting --> Online: Authenticated
    Connecting --> Error: Auth Failed
    Online --> Busy: Execute Command
    Busy --> Online: Command Complete
    Busy --> Error: Command Failed
    Online --> Offline: Disconnect
    Error --> Connecting: Retry
    Error --> Offline: Give Up

7.3 Flujo de Ejecución Remota¶

sequenceDiagram
    participant C as Cliente
    participant API as API
    participant Hub as SignalR Hub
    participant RA as Remote Agent
    participant CLI as Claude CLI

    C->>API: POST /remote-agents/{id}/execute
    API->>API: Crear RemoteAgentCommand (Pending)
    API->>Hub: SendCommandAsync
    Hub->>RA: RemoteCommandMessage
    RA->>CLI: Ejecutar prompt

    loop Streaming
        CLI-->>RA: Chunk de respuesta
        RA-->>Hub: StreamChunk
        Hub-->>API: Update response
    end

    RA->>Hub: CommandComplete
    Hub->>API: Update status, tokens, duration
    API-->>C: RemoteCommandResult

7.4 Configuración de Agente Remoto¶

Crear agente:

POST /api/remote-agents
Content-Type: application/json

{
  "name": "Dev-Laptop-Juan",
  "defaultWorkingDirectory": "C:\\Projects"
}

Respuesta:

{
  "id": "guid-here",
  "name": "Dev-Laptop-Juan",
  "apiKey": "ra_xxxx...xxxx",  // Mostrar solo una vez!
  "status": "Offline",
  "defaultWorkingDirectory": "C:\\Projects"
}

7.5 Ejecutar Comando Remoto¶

POST /api/remote-agents/{id}/execute
Content-Type: application/json

{
  "prompt": "Analiza el código en src/Services y sugiere mejoras",
  "systemPrompt": "Eres un experto en C# y .NET...",
  "workingDirectory": "C:\\Projects\\MyApp",
  "timeoutSeconds": 300
}

7.6 Capacidades del Agente¶

{
  "capabilitiesJson": [
    "claude_cli",      // Claude CLI instalado
    "git",             // Git disponible
    "docker",          // Docker disponible
    "dotnet",          // .NET SDK
    "node",            // Node.js
    "python"           // Python
  ]
}

8. Sugerencias Automáticas¶

8.1 AgentSuggestionService¶

Sugiere agentes, plugins y skills basándose en el prompt.

8.2 Algoritmo de Scoring¶

graph LR
    P[Prompt] --> N[Nombre Match<br/>0.3 pts]
    P --> D[Descripción Match<br/>0.15 pts]
    P --> S[SystemPrompt Match<br/>0.05 pts]
    P --> B[Booster Temático<br/>0.4 pts]
    N --> T[Total Score]
    D --> T
    S --> T
    B --> T
    T --> |>0.3| R[Recomendado]

8.3 Boosters por Tema¶

Tema	Palabras Clave	Boost
security	security, audit, owasp, vulnerability, seguridad	+0.4
database	database, sql, query, index, postgres	+0.4
api	api, endpoint, rest, graphql	+0.4
frontend	frontend, react, vue, angular, css, ui	+0.4
backend	backend, .net, dotnet, csharp, c#	+0.4
devops	deploy, ci/cd, docker, kubernetes	+0.4
test	test, testing, unit, integration	+0.4
performance	performance, rendimiento, slow, optimize	+0.4
documentation	document, readme, changelog, adr	+0.4

8.4 Uso en Workspace¶

Activar sugerencia: Shift + Enter

Respuesta:

{
  "suggestedAgent": {
    "id": "guid",
    "slug": "security-specialist",
    "name": "Security Specialist",
    "confidence": 0.85,
    "reason": "El prompt menciona 'security', 'audit', 'OWASP'"
  },
  "suggestedPlugin": {
    "id": "security-toolkit",
    "name": "Security Toolkit",
    "confidence": 0.80
  },
  "suggestedSkills": [
    { "id": "owasp-top10", "name": "OWASP Top 10", "relevance": 0.9 },
    { "id": "secure-coding", "name": "Secure Coding", "relevance": 0.75 }
  ],
  "alternativeAgents": [
    { "slug": "code-reviewer", "confidence": 0.45 }
  ]
}

9. API de Gestión¶

9.1 Endpoints de Agentes¶

Método	Endpoint	Descripción
GET	`/api/agents`	Listar todos
GET	`/api/agents/{id}`	Obtener por ID
GET	`/api/agents/by-slug/{slug}`	Obtener por slug
GET	`/api/agents/{slug}/prompt`	Obtener SystemPrompt (JSON)
GET	`/api/agents/{slug}/prompt/raw`	Obtener SystemPrompt (text/plain)
POST	`/api/agents`	Crear agente
PUT	`/api/agents/{id}`	Actualizar agente
DELETE	`/api/agents/{id}`	Eliminar agente

9.2 Endpoints de Skills¶

Método	Endpoint	Descripción
POST	`/api/agents/{id}/skills`	Agregar skill
PUT	`/api/agents/{id}/skills/{skill}`	Actualizar proficiency
DELETE	`/api/agents/{id}/skills/{skill}`	Eliminar skill
PUT	`/api/agents/{id}/skills`	Reemplazar todos

9.3 Endpoints de Triggers¶

Método	Endpoint	Descripción
POST	`/api/agents/{id}/triggers`	Agregar trigger
PUT	`/api/agents/{id}/triggers/{triggerId}`	Actualizar trigger
DELETE	`/api/agents/{id}/triggers/{triggerId}`	Eliminar trigger

9.4 Endpoints de Sincronización¶

Método	Endpoint	Descripción
POST	`/api/agents/sync/from-files`	Sincronizar desde archivos .md
POST	`/api/agents/sync/upstream`	Sincronizar desde upstream
POST	`/api/agents/{id}/export`	Exportar a archivo .md
POST	`/api/agents/export/all`	Exportar todos

9.5 Endpoints de Agentes Remotos¶

Método	Endpoint	Descripción
GET	`/api/remote-agents`	Listar todos
GET	`/api/remote-agents/online`	Solo online
POST	`/api/remote-agents`	Crear agente
PUT	`/api/remote-agents/{id}`	Actualizar
DELETE	`/api/remote-agents/{id}`	Eliminar
POST	`/api/remote-agents/{id}/regenerate-key`	Nueva API key
POST	`/api/remote-agents/{id}/execute`	Ejecutar comando
GET	`/api/remote-agents/commands`	Historial de comandos

10. Mejores Prácticas¶

10.1 Diseño de System Prompts¶

DO: - Ser específico sobre el dominio y capacidades - Incluir formato de salida esperado - Proporcionar ejemplos concretos - Definir limitaciones claramente - Usar markdown para estructura

DON'T: - Prompts genéricos sin contexto - Instrucciones ambiguas - Prompts demasiado largos (>4000 tokens) - Mezclar responsabilidades - Olvidar casos de error

10.2 Asignación de Skills¶

Recomendaciones: 1. Máximo 5-7 skills por agente (enfoque) 2. Proficiency realista (no todo es 10) 3. Skills complementarios (no redundantes) 4. Categorías coherentes (security con security)

10.3 Configuración de Triggers¶

Recomendaciones: 1. Prioridades claras (evitar conflictos) 2. Patterns específicos (no muy amplios) 3. Keywords únicos (evitar solapamiento) 4. Testear regex antes de usar en producción

10.4 Orquestación Multi-Agente¶

Escenario	Modo Recomendado
Tarea simple	Sequential
Revisión de código grande	Parallel
Decisión arquitectónica	Debate
Análisis cross-funcional	Consultation
Implementación paso a paso	Sequential
Auditoría completa	Parallel + Consultation

10.5 Agentes Remotos¶

Seguridad: - Rotar API keys periódicamente - Usar working directories específicos - Monitorear métricas de uso - Limitar capabilities necesarias

Performance: - Timeouts razonables (default 300s) - Evitar comandos bloqueantes - Monitorear heartbeats - Limpiar comandos antiguos

11. Ejemplos de Configuración¶

11.1 Agente: Backend Architect¶

{
  "slug": "backend-architect",
  "name": "Backend Architect",
  "description": "Especialista en arquitectura de sistemas backend con .NET",
  "model": "sonnet",
  "systemPrompt": "## Identidad\nEres Backend Architect...",
  "isActive": true,
  "skills": [
    { "skill": "dotnet-patterns", "proficiency": 9 },
    { "skill": "api-design", "proficiency": 8 },
    { "skill": "database-design", "proficiency": 8 },
    { "skill": "microservices", "proficiency": 7 }
  ],
  "triggers": [
    { "triggerType": "keyword", "pattern": "arquitectura", "priority": 1 },
    { "triggerType": "keyword", "pattern": "backend", "priority": 2 },
    { "triggerType": "pattern", "pattern": "^diseñar:.*api", "priority": 1 }
  ]
}

11.2 Agente: Security Auditor¶

{
  "slug": "security-auditor",
  "name": "Security Auditor",
  "description": "Auditor de seguridad especializado en OWASP",
  "model": "sonnet",
  "systemPrompt": "## Identidad\nEres Security Auditor...",
  "isActive": true,
  "skills": [
    { "skill": "owasp-top10", "proficiency": 10 },
    { "skill": "secure-coding", "proficiency": 9 },
    { "skill": "penetration-testing", "proficiency": 7 }
  ],
  "triggers": [
    { "triggerType": "keyword", "pattern": "security", "priority": 1 },
    { "triggerType": "keyword", "pattern": "vulnerability", "priority": 1 },
    { "triggerType": "event", "pattern": "sentry:security_issue", "priority": 0 }
  ]
}

11.3 Configuración de Orquestación¶

Debate: Monolito vs Microservicios

{
  "goal": "Decidir arquitectura para nuevo proyecto de e-commerce",
  "mode": "Debate",
  "context": {
    "team_size": 5,
    "deadline": "6 meses",
    "traffic_expected": "10k usuarios/día"
  },
  "debateConfig": {
    "proPosition": "Microservicios con contenedores",
    "conPosition": "Monolito modular"
  }
}

Consultation: Migración a Cloud

{
  "goal": "Planificar migración de on-premise a AWS",
  "mode": "Consultation",
  "specialists": [
    {
      "role": "cloud-architect",
      "focus": "Diseño de infraestructura AWS"
    },
    {
      "role": "security-specialist",
      "focus": "Compliance y seguridad en la nube"
    },
    {
      "role": "devops-engineer",
      "focus": "CI/CD y automatización"
    },
    {
      "role": "cost-analyst",
      "focus": "Optimización de costos"
    }
  ]
}

Glosario¶

Término	Definición
Agent	Entidad de IA especializada con SystemPrompt y Skills
Skill	Conocimiento específico que puede asignarse a agentes
Trigger	Condición que activa un agente automáticamente
SystemPrompt	Instrucciones base que definen el comportamiento del agente
Remote Agent	Cliente que ejecuta Claude CLI en una máquina remota
Orchestration	Coordinación de múltiples agentes para una tarea
Proficiency	Nivel de competencia (1-10) de un skill en un agente
Plugin	Agrupación de agentes, skills y commands relacionados
Upstream	Configuraciones predefinidas del sistema
Custom	Configuraciones creadas por el usuario

Historial de Cambios¶

Fecha	Versión	Cambios
2026-02-01	1.0	Versión inicial

Siguiente documento sugerido: Guía de Desarrolladores