Conceptos de Agentes

Archivos y conceptos fundamentales que hacen que tus agentes sean persistentes, personalizados y efectivos entre sesiones.

SOUL.md — Identidad del Agente

SOUL.md define quien ES tu agente. Su personalidad, reglas, estilo de comunicacion y comportamientos fundamentales. Sin esto, obtienes una personalidad diferente cada sesion.

Piensa en el como el ADN de tu agente — los rasgos innegociables que persisten en cada conversacion.

Que incluir:

• Nombre y rol — "Eres Tars, un asistente de investigacion especializado en analisis de mercado"
• Estilo de comunicacion — formal vs casual, detallado vs conciso, uso de emojis
• Reglas y restricciones — cosas que el agente debe hacer o nunca hacer
• Guias de decision — cuando actuar autonomamente vs pedir aprobacion
• Experiencia de dominio — en que se especializa el agente

Tu nombre es "Tars". Tu rol es: Analista Senior de Investigacion.

## Reglas
- Siempre cita fuentes al hacer afirmaciones
- Nunca inventes estadisticas — di "No tengo esos datos"
- Haz preguntas de clarificacion antes de iniciar tareas grandes
- Escribe de forma directa y concisa — sin palabras de relleno

## Personalidad
- Profesional pero accesible
- Proactivo para senalar riesgos o problemas
- Cuando haya incertidumbre, dilo explicitamente

## Experiencia
- Investigacion de mercado y analisis competitivo
- Interpretacion de datos e identificacion de tendencias
- Redaccion de informes y resumenes ejecutivos

En Autonomis, SOUL.md se gestiona desde la pagina de Plantillas de Agente en el dashboard. Se escribe en el workspace de tu agente en cada inicio del contenedor y persiste en el volumen.

USER.md — Contexto del Propietario

USER.md es todo sobre TI que tu agente necesita saber. Imagina que tu asistente tuviera una libreta en el bolsillo con tu nombre, tu trabajo, tus proyectos y como te gusta que se hagan las cosas.

• Quien eres — nombre, rol, empresa, industria
• Proyectos actuales — en que estas trabajando ahora
• Preferencias — como te gustan los reportes, canales de comunicacion, zona horaria
• Relaciones clave — miembros del equipo, clientes, stakeholders que el agente debe conocer

## Sobre Mi
- Nombre: Alex Chen
- Rol: Fundador, Acme Analytics
- Industria: SaaS B2B, analisis de datos
- Zona horaria: EST (UTC-5)

## Proyectos Actuales
- Lanzamiento de v2.0 del dashboard de analytics (fecha limite: 15 de marzo)
- Recaudacion Serie A — preparando pitch deck y data room
- Contratacion: buscando ingeniero backend senior

## Preferencias
- Prefiero viñetas sobre parrafos
- Siempre incluye proximos pasos accionables en los reportes
- Avisa inmediatamente sobre cosas urgentes, agrupa lo no urgente diariamente

USER.md se comparte entre todos tus agentes por defecto. Tambien puedes establecer sobreescrituras por agente si diferentes agentes necesitan diferente contexto sobre ti.

MEMORY.md — Memoria a Largo Plazo

MEMORY.md es el diario de tu agente. A diferencia de SOUL.md y USER.md (que tu escribes), MEMORY.md es mantenido por el agente mismo. Despues de cada conversacion importante, el agente escribe decisiones clave, lecciones aprendidas y actualizaciones de proyectos.

La proxima sesion, el agente lo relee. Memoria restaurada.

Para activarlo, simplemente dile a tu agente:

Empieza a mantener un archivo MEMORY.md. Despues de cada conversacion
importante, actualizalo con decisiones clave, lecciones aprendidas y
cambios en el estado de los proyectos.

Que debe rastrear el agente:

• Decisiones tomadas — "Se decidio usar Stripe para pagos en lugar de Paddle"
• Lecciones aprendidas — "El estilo de hook X supero a Y por 3x en TikTok"
• Estado de proyectos — "Dashboard v2.0: modulo de auth completo, iniciando vistas de analytics"
• Preferencias descubiertas — "Alex prefiere mockups en modo oscuro"

TOOLS.md — Instrucciones de Herramientas

TOOLS.md enseña a tu agente COMO usar sus herramientas efectivamente. Mientras los permisos de herramientas controlan que PUEDE usar un agente, TOOLS.md controla como DEBERIA usarlas.

• Patrones de uso de API — como llamar APIs especificas, limites de tasa a respetar
• Preferencias de herramientas — cuando usar cual herramienta, flujos preferidos
• Detalles de integracion — endpoints especificos, patrones de autenticacion, formatos de datos
• Manejo de errores — que hacer cuando una llamada a herramienta falla

## API de Postiz
- Siempre publicar como BORRADOR, nunca publicar directamente
- Usar modo batch para publicaciones programadas (mitad del costo)
- Limite de tasa: maximo 10 solicitudes por minuto

## RevenueCat
- Verificar diariamente a las 9am EST durante el heartbeat
- Comparar MRR semana a semana, marcar caidas > 5%
- Cruzar timestamps de transacciones con tiempos de publicacion en TikTok

## Generacion de Imagenes
- Siempre usar gpt-image-1.5 a 1024x1536 (retrato)
- Fijar la arquitectura de la escena en las 6 slides
- Solo cambiar el estilo entre slides

HEARTBEAT.md — Rutinas Automatizadas

HEARTBEAT.md define que hace tu agente automaticamente segun un horario. Los heartbeats son chequeos en segundo plano que se ejecutan a intervalos regulares — revisando emails, escaneando analytics, monitoreando menciones y señalando cualquier cosa que necesite tu atencion.

La mayoria de usuarios no saben que los heartbeats existen. Configuralos una vez y corren para siempre.

## Horario
- Ejecutar cada 30 minutos durante horas activas (8am-10pm EST)
- Ejecutar cada 2 horas fuera de horas activas

## Chequeos
1. Revisar email por mensajes urgentes — marcar de clientes o inversores
2. Revisar analytics de TikTok via Postiz — registrar vistas de las ultimas 24h
3. Revisar RevenueCat — comparar MRR con ayer, marcar anomalias
4. Revisar calendario — recordarme reuniones 15 minutos antes

## Reportes
- Items urgentes: notificar inmediatamente
- Resumen diario: compilar a las 9am con actividad nocturna
- Reporte semanal: cada lunes con tendencias y recomendaciones

Compactacion de Contexto

Cuando las conversaciones se alargan, Autonomis resume los mensajes antiguos para ahorrar espacio de contexto. Esto se llama compactacion de contexto. Piensa en ello como escribir instrucciones detalladas en una pizarra, luego alguien la fotografía, la borra y escribe un resumen de un parrafo.

La esencia es correcta, pero los detalles se pierden. Si tus reglas solo existian en la conversacion — tambien desaparecen.

La solucion: pon las reglas importantes en ARCHIVOS, no en mensajes.

• Los archivos sobreviven la compactacion — SOUL.md, USER.md, TOOLS.md se releen cada vez
• Los mensajes de conversacion no — cualquier cosa dicha hace 30+ minutos puede ser resumida
• Las reglas criticas pertenecen a SOUL.md, no al chat

Gestion de Secretos

Las API keys, tokens y credenciales se almacenan encriptados en Vault usando encriptacion Transit (AES-256-GCM96). Nunca se almacenan en texto plano en archivos de configuracion o variables de entorno en reposo.

• Agregar secretos desde la pagina de Secretos en el dashboard
• Recarga en caliente — no se necesita reinicio del contenedor al agregar o cambiar secretos
• Auditoria — ejecuta openclaw secrets audit dentro del contenedor para verificar cero exposicion de texto plano
• Aislamiento por usuario — las politicas de Vault aseguran que los agentes solo pueden acceder a los secretos de su propio usuario

Sobreescrituras por Agente

Por defecto, las plantillas (SOUL.md, USER.md, TOOLS.md, HEARTBEAT.md) se comparten entre todos los agentes. Pero puedes establecer sobreescrituras por agente para cualquier archivo de plantilla.

Esto es util cuando los agentes tienen diferentes roles:

• Agente manager — SOUL.md amplio con reglas de orquestacion, TOOLS.md completo
• Agente investigador — SOUL.md especializado en analisis, TOOLS.md para APIs de busqueda
• Agente de marketing — SOUL.md creativo, TOOLS.md para Postiz y generacion de imagenes

Configura las sobreescrituras desde la pagina de detalle del agente en el dashboard bajo Sobreescrituras de Plantilla.

Seleccion de Modelo y Optimizacion de Costos

Cada agente puede usar un modelo LLM diferente. Esto te permite optimizar costo vs capacidad en tu equipo de agentes:

Configura el modelo por agente desde la pagina de configuracion del agente. Cambiar de Opus-para-todo a seleccion de modelo dirigida puede reducir costos de $150-300/mes a $30-60/mes.

Servicio de Archivos del Workspace

Los agentes pueden crear archivos en su workspace (imagenes, SVGs, codigo, reportes). Estos archivos se sirven por HTTP y se renderizan en linea en la interfaz del chat.

Cuando un agente devuelve markdown como ![grafico](output.svg), el chat resuelve automaticamente las rutas relativas al workspace del agente y renderiza la imagen en linea.

• Reescritura automatica de URLs — las rutas relativas de imagenes en markdown se resuelven al proxy de archivos
• Deteccion de Content-Type — SVG, PNG, PDF y otros formatos servidos con headers correctos
• Seguridad de ruta — solo los archivos dentro del workspace del agente son accesibles, el path traversal esta bloqueado

Uniendo Todo

Asi es como todas las piezas encajan para un agente bien configurado:

~/.openclaw/
├── openclaw.json          ← config del gateway (auto-gestionado)
├── workspace/             ← workspace del agente por defecto
│   ├── SOUL.md            ← identidad y reglas
│   ├── USER.md            ← contexto del propietario
│   ├── TOOLS.md           ← instrucciones de herramientas
│   ├── HEARTBEAT.md       ← rutinas automatizadas
│   ├── MEMORY.md          ← diario mantenido por el agente
│   └── (archivos...)      ← creados por el agente
├── workspace-researcher/  ← workspace de agente especialista
│   ├── SOUL.md            ← sobreescritura por agente
│   └── ...
└── agents/
    ├── manager/agent/auth-profiles.json
    └── researcher/agent/auth-profiles.json