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

```go
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:**

```yaml
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:**
```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:
   ```bash
   ./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):
   ```bash
   SSSS_RECOVERY_KEY_<ID_UPPER>="EsXX YYYY ZZZZ ..."
   ```
7. Añadir `recovery_key_env` al config.yaml:
   ```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:**
```go
<agentpkg>agent "github.com/enmanuel/agents/agents/<agent-id>"
```

**rulesRegistry:**
```go
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:
```bash
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