agents_and_robots/.claude/policies/create_agent.md

Cómo crear un nuevo agente

Guía para LLMs que asisten en la creación de agentes en este proyecto.

Estructura requerida

Cada agente vive en agents/<agent-id>/ con esta estructura:

agents/<agent-id>/
├── agent.go                # Package propio, exporta Rules() []decision.Rule
├── config.yaml             # Configuración completa (ver schema en internal/config/schema.go)
└── prompts/
    └── system.md           # System prompt del LLM

Archivos a crear

1. agents/<agent-id>/agent.go — Reglas puras

package <agentpkg>

import "github.com/enmanuel/agents/pkg/decision"

func Rules() []decision.Rule {
    return []decision.Rule{
        // Regla help explícita
        {
            Name:  "help",
            Match: decision.MatchCommand("help"),
            Actions: []decision.Action{{
                Kind:  decision.ActionKindReply,
                Reply: &decision.ReplyAction{Content: "Descripción de capacidades del bot."},
            }},
        },
        // Catch-all → LLM
        {
            Name: "llm-all",
            Match: func(ctx decision.MessageContext) bool {
                return ctx.IsDirectMsg || ctx.IsMention
            },
            Actions: []decision.Action{{
                Kind: decision.ActionKindLLM,
                LLM:  &decision.LLMAction{},
            }},
        },
    }
}

Reglas del archivo de reglas:

• PURO: sin imports de I/O, sin side effects, solo pkg/decision
• El package name debe ser Go-valid (sin guiones): agents/mi-bot/ → package mibot
• Las reglas se evalúan en orden — poner las específicas antes del catch-all
• El catch-all debe cubrir ctx.IsDirectMsg || ctx.IsMention como mínimo
• ActionKindReply para respuestas estáticas, ActionKindLLM para respuestas dinámicas

2. agents/<agent-id>/config.yaml — Configuración

Usar como plantilla agents/assistant/config.yaml o agents/asistente2/config.yaml.

Campos que SIEMPRE hay que personalizar:

agent:
  id: <agent-id>                    # DEBE coincidir con el directorio y rulesRegistry
  name: "Display Name"
  description: "Qué hace este agente"

llm:
  primary:
    provider: openai                # o anthropic
    model: gpt-4o                   # o claude-sonnet-4-20250514
    api_key_env: OPENAI_API_KEY     # o ANTHROPIC_API_KEY
  tool_use:
    enabled: true/false             # true si el agente usa herramientas

matrix:
  user_id: "@<agent-id>:matrix-af2f3d.organic-machine.com"
  access_token_env: MATRIX_TOKEN_<AGENT_UPPER>
  device_id: "<se actualiza después del registro>"

Convención de nombres de env vars:

• Token: MATRIX_TOKEN_<ID_UPPER> donde ID se convierte a mayúsculas y guiones a underscores
• Ejemplo: asistente-2 → MATRIX_TOKEN_ASISTENTE2
• Password: MATRIX_PASSWORD_<ID_UPPER> con la misma convención
• Pickle key E2EE: PICKLE_KEY_<ID_UPPER> — clave fija hex de 32 bytes

Sección encryption en config.yaml:

  encryption:
    enabled: true
    store_path: "./agents/<agent-id>/data/crypto/"   # SIEMPRE por agente, nunca compartida
    pickle_key_env: PICKLE_KEY_<ID_UPPER>             # env var con clave hex
    trust_mode: tofu
    recovery_key_env: SSSS_RECOVERY_KEY_<ID_UPPER>   # env var con base58 recovery key

Al crear un nuevo agente con E2EE:

1. Generar pickle key: openssl rand -hex 32
2. Añadir a .env: PICKLE_KEY_<ID_UPPER>=<hex>
3. Añadir a .env.example: PICKLE_KEY_<ID_UPPER>=
4. Usar store_path propio del agente (no compartir entre agentes)
5. Ejecutar cmd/verify con --store y --pickle-key del agente:

   ./bin/verify --homeserver "$MATRIX_HOMESERVER" --username "<id>" \
     --password "$MATRIX_PASSWORD_<AGENT>" --token "$MATRIX_TOKEN_<AGENT>" \
     --store "./agents/<id>/data/crypto/" --pickle-key "$PICKLE_KEY_<AGENT>"
   

6. Guardar el recovery key en .env (con comillas por los espacios):

   SSSS_RECOVERY_KEY_<ID_UPPER>="EsXX YYYY ZZZZ ..."
   

7. Añadir recovery_key_env al config.yaml:

   encryption:
     recovery_key_env: SSSS_RECOVERY_KEY_<ID_UPPER>
   

Sin el recovery key, el agente arranca pero los mensajes muestran "Encrypted by a device not verified by its owner".

3. agents/<agent-id>/prompts/system.md — System prompt

Debe incluir:

• Identidad del bot (quién es, qué hace)
• Capacidades y limitaciones
• Herramientas disponibles (si tool_use.enabled: true)
• Estilo de respuesta (idioma, tono, formato)
• Instrucciones de uso de herramientas (cuándo y cómo usarlas)

Archivos a modificar

4. cmd/launcher/main.go — Registro en el launcher

Dos cambios:

Import:

<agentpkg>agent "github.com/enmanuel/agents/agents/<agent-id>"

rulesRegistry:

var rulesRegistry = map[string]func() []decision.Rule{
    // ... agentes existentes ...
    "<agent-id>": <agentpkg>agent.Rules,   // ← nuevo
}

El ID en rulesRegistry DEBE coincidir exactamente con agent.id del config.yaml.

5. agents/runtime.go — Registro de herramientas (solo si hay tools nuevas)

Si el agente necesita una herramienta nueva (no existente), ver la policy create_tool.md.

Las herramientas "siempre disponibles" (current_time, matrix_send) ya están registradas para todos los agentes.

Después de crear los archivos

Verificar compilación:

go build -tags goolm ./...

Luego seguir con registro, avatar, verificación y arranque (ver docs/creating-agents.md).

Reglas generales

• Nunca poner side effects en agent.go — es código puro
• Siempre verificar que agent.id coincide entre config.yaml, rulesRegistry y el directorio
• Siempre compilar con -tags goolm para soporte E2EE
• Idioma: español en configs, prompts y descripciones de dominio; inglés en código Go
• No crear archivos data/ — se generan automáticamente al arrancar
• No commitear tokens ni passwords — solo van en .env
• Si el agente usa tool_use, asegurarse de que llm.tool_use.enabled: true en el config
• Usar agents/asistente2/ como referencia completa de un agente con tools habilitadas