Sincronización de agentes¶

La sincronización permite mantener los agentes actualizados con los archivos de configuración del repositorio.

¿Por qué sincronizar?¶

Los agentes pueden definirse en dos lugares:

Base de datos: Configuración editable desde la UI
Archivos: Definiciones en el repositorio (.md files)

La sincronización mantiene ambos en línea:

graph LR
    F[Archivos .md] -->|Sync| DB[(Base de datos)]
    DB -->|UI muestra| UI[Interfaz]
    UI -->|Edición| DB

Cuándo sincronizar¶

Sincroniza cuando:

Se han añadido nuevos agentes al repositorio
Se han modificado system prompts en archivos
Quieres restaurar la configuración original
Después de un git pull con cambios en agentes

Ejecutar sincronización¶

Desde la UI¶

Ve a Agentes
Haz clic en Sync
Confirma la acción
Espera a que termine el proceso

┌─────────────────────────────────────────────────────────────────┐
│ Sincronización de Agentes                                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Procesando archivos...                                         │
│  ████████████████████████░░░░░░  75%                           │
│                                                                 │
│  ✓ documentation-engineer       Actualizado                    │
│  ✓ dotnet-architect             Sin cambios                    │
│  ✓ devops-troubleshooter        Actualizado                    │
│  + database-optimizer           Nuevo                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Resultado de sincronización¶

Estado	Significado
✓ Actualizado	El agente existía y se actualizó
✓ Sin cambios	El agente está igual que el archivo
+ Nuevo	Se creó un agente nuevo
⚠ Advertencia	Hay diferencias que revisar
✗ Error	Falló la sincronización

Archivos de agentes¶

Los agentes se definen en archivos Markdown con esta estructura:

docs/.ai/agents/
├── dotnet-architect.md
├── documentation-engineer.md
├── devops-troubleshooter.md
├── database-optimizer.md
└── ...

Formato del archivo¶

---
slug: documentation-engineer
name: Documentation Engineer
description: Ingeniero especializado en documentación técnica
active: true
skills:
  - markdown
  - technical-writing
  - diátaxis
---

# Documentation Engineer

Eres un ingeniero especializado en documentación técnica...

## Responsabilidades
- Mantener documentación actualizada
- ...

Frontmatter¶

El bloque YAML al inicio define metadatos:

Campo	Descripción	Requerido
`slug`	Identificador único	Sí
`name`	Nombre descriptivo	Sí
`description`	Descripción breve	No
`active`	Estado activo/inactivo	No (default: true)
`skills`	Lista de skills asignadas	No

Contenido¶

Todo el contenido después del frontmatter se usa como system prompt.

Resolución de conflictos¶

Archivo vs Base de datos¶

Si hay diferencias entre el archivo y la base de datos:

Por defecto: El archivo tiene prioridad
Opción manual: Se muestra un diálogo para elegir

┌─────────────────────────────────────────────────────────────────┐
│ Conflicto detectado: documentation-engineer                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  El archivo y la base de datos tienen diferencias:              │
│                                                                 │
│  ┌──────────────────────┐    ┌──────────────────────┐          │
│  │ ARCHIVO              │    │ BASE DE DATOS        │          │
│  │ Línea 15: "nuevo"    │ vs │ Línea 15: "antiguo"  │          │
│  └──────────────────────┘    └──────────────────────┘          │
│                                                                 │
│  ¿Qué versión mantener?                                         │
│                                                                 │
│  [Usar Archivo]  [Usar BD]  [Omitir]                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Agente en BD pero no en archivo¶

Se mantiene en la base de datos
Se marca como "sin archivo fuente"
Considera eliminar o crear el archivo

Archivo nuevo sin agente en BD¶

Se crea el agente automáticamente
Aparece como "+ Nuevo" en el resultado

Sincronización selectiva¶

Sincronizar un solo agente¶

Abre el agente
En la página de detalles, haz clic en Sync desde archivo
Se actualizará solo ese agente

Sincronizar por categoría¶

En la lista de agentes, filtra por categoría
Selecciona los agentes deseados
Haz clic en Sync seleccionados

Exportar a archivos¶

Si has hecho cambios en la UI y quieres guardarlos como archivos:

Abre el agente modificado
Haz clic en Exportar a archivo
El sistema genera/actualiza el archivo .md
Haz commit de los cambios en git

Control de versiones

Recuerda hacer commit de los archivos exportados para mantener el repositorio actualizado.

Automatización¶

Sync automático en deploy¶

Puedes configurar sincronización automática después de cada deploy:

# En tu script de deploy
dotnet run --project Orchestrator.Api -- sync-agents

Webhook de Git¶

Configura un webhook que ejecute sync cuando hay cambios en docs/.ai/agents/:

Crea un trigger de webhook
Apunta a la URL de sync de Nexus
Configura el webhook en GitHub/GitLab

Mejores prácticas¶

Workflow recomendado¶

Desarrollo: Edita agentes en la UI para probar rápido
Estabilización: Exporta cambios a archivos
Code Review: Revisa cambios en PR
Merge: Fusiona cambios al main
Deploy: Sync automático actualiza producción

Mantén archivos como fuente de verdad¶

Los archivos son versionables en Git
Permiten code review de cambios
Facilitan rollback
Documentan la evolución

Documenta los cambios¶

Incluye comentarios en los commits:

feat(agents): actualiza system prompt de documentation-engineer

- Añade sección de formato de respuesta
- Actualiza reglas de estilo
- Añade ejemplos de uso

Siguiente: Tareas - Aprende a programar y ejecutar tareas.