233 lines
8.6 KiB
Markdown
233 lines
8.6 KiB
Markdown
# Cómo crear un nuevo agente
|
|
|
|
Guía para LLMs que asisten en la creación de agentes en este proyecto.
|
|
|
|
## Flujo completo automatizado
|
|
|
|
```bash
|
|
# 1. Scaffold — crea config.yaml (E2EE habilitado), agent.go, prompts/, data/
|
|
./dev-scripts/new-agent.sh <agent-id> "Display Name"
|
|
|
|
# 2. Registrar en Matrix — genera y guarda en .env:
|
|
# MATRIX_TOKEN_<NORM>, MATRIX_PASSWORD_<NORM>, PICKLE_KEY_<NORM>
|
|
./dev-scripts/register.sh <agent-id> "Display Name"
|
|
|
|
# 3. Verificar E2EE — genera cross-signing keys, firma el device,
|
|
# guarda SSSS_RECOVERY_KEY_<NORM> en .env
|
|
./dev-scripts/verify.sh <agent-id>
|
|
|
|
# 4. Arrancar — ya verificado desde el primer arranque
|
|
./dev-scripts/start.sh <agent-id>
|
|
```
|
|
|
|
Los scripts automatizan todo. Solo intervenir manualmente si un paso falla.
|
|
|
|
## Convención de nombres de env vars — REGLA CRÍTICA
|
|
|
|
**Normalización**: agent ID → mayúsculas, guiones → underscores. **Sin eliminar sufijos.**
|
|
|
|
Función canónica en `dev-scripts/_common.sh`:
|
|
```bash
|
|
normalize_id() { echo "$1" | tr '[:lower:]-' '[:upper:]_'; }
|
|
```
|
|
|
|
| Agent ID | Sufijo normalizado | Env vars |
|
|
|---|---|---|
|
|
| `assistant-bot` | `ASSISTANT_BOT` | `MATRIX_TOKEN_ASSISTANT_BOT`, `MATRIX_PASSWORD_ASSISTANT_BOT`, `PICKLE_KEY_ASSISTANT_BOT`, `SSSS_RECOVERY_KEY_ASSISTANT_BOT` |
|
|
| `asistente-2` | `ASISTENTE_2` | `MATRIX_TOKEN_ASISTENTE_2`, `MATRIX_PASSWORD_ASISTENTE_2`, `PICKLE_KEY_ASISTENTE_2`, `SSSS_RECOVERY_KEY_ASISTENTE_2` |
|
|
| `monitor-bot` | `MONITOR_BOT` | `MATRIX_TOKEN_MONITOR_BOT`, ... |
|
|
|
|
**NUNCA** usar `sed 's/_BOT$//'` ni transformaciones que eliminen partes del ID.
|
|
|
|
## 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)
|
|
├── data/ # Runtime data (crypto, logs) — en .gitignore
|
|
│ └── crypto/ # Crypto store E2EE — NUNCA compartir entre agentes
|
|
└── 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
|
|
|
|
`new-agent.sh` genera esto automáticamente. Campos que 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_<NORM>
|
|
device_id: "" # se resuelve automáticamente via whoami
|
|
```
|
|
|
|
### Sección E2EE en config.yaml (generada por new-agent.sh)
|
|
|
|
```yaml
|
|
encryption:
|
|
enabled: true # SIEMPRE true para agentes nuevos
|
|
store_path: "./agents/<agent-id>/data/crypto/" # SIEMPRE por agente, nunca compartida
|
|
pickle_key_env: PICKLE_KEY_<NORM> # generada por register.sh
|
|
trust_mode: tofu
|
|
recovery_key_env: SSSS_RECOVERY_KEY_<NORM> # generada por verify.sh
|
|
```
|
|
|
|
### 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
|
|
|
|
`new-agent.sh` hace esto automáticamente. 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.
|
|
|
|
## E2EE — Cómo funciona la verificación
|
|
|
|
### Flujo al arrancar (agents/runtime.go)
|
|
|
|
```
|
|
InitCrypto → crea/carga el device y Olm account del crypto store
|
|
FetchCrossSigningKeys → obtiene private keys de SSSS usando recovery key
|
|
SignOwnDevice → fetch device keys del servidor + firma con self-signing key
|
|
```
|
|
|
|
### Qué hace cada script
|
|
|
|
| Script | Qué genera | Dónde se guarda |
|
|
|---|---|---|
|
|
| `register.sh` | Token, password, pickle key (32 bytes hex) | `.env` |
|
|
| `verify.sh` | Cross-signing keys (master, self-signing, user-signing) + recovery key | Server (keys) + `.env` (recovery key) |
|
|
|
|
### Por qué cada credential importa
|
|
|
|
| Credential | Para qué | Si falta |
|
|
|---|---|---|
|
|
| `MATRIX_TOKEN_*` | Autenticación del bot con el homeserver | Bot no arranca |
|
|
| `MATRIX_PASSWORD_*` | UIA al subir cross-signing keys (verify.sh) | verify.sh intenta dummy auth (MSC3967) |
|
|
| `PICKLE_KEY_*` | Cifrar el crypto store en disco | Usa sha256(token) como fallback — inseguro |
|
|
| `SSSS_RECOVERY_KEY_*` | Recuperar private keys de cross-signing al arrancar | Device no se firma → "not verified by its owner" |
|
|
|
|
### Problemas comunes y soluciones
|
|
|
|
**"Encrypted by a device not verified by its owner"**
|
|
→ Ejecutar `./dev-scripts/verify.sh <agent-id>` y reiniciar
|
|
|
|
**"self-signing private key not in cache"**
|
|
→ La recovery key en `.env` no corresponde a las cross-signing keys actuales. Re-ejecutar verify.sh.
|
|
|
|
**"received update for device with different signing key"**
|
|
→ Bug resuelto: `SignOwnDevice` ahora hace `FetchKeys` antes de firmar. Si reaparece, recompilar el launcher: `go build -tags goolm -o bin/launcher ./cmd/launcher`
|
|
|
|
**"data is not encrypted for given key ID"**
|
|
→ Las cross-signing keys fueron regeneradas pero la recovery key en `.env` es la vieja. Re-ejecutar verify.sh (actualiza .env automáticamente).
|
|
|
|
**Recovery key sin comillas en .env**
|
|
→ Causan `command not found` al hacer `source .env`. Las recovery keys tienen espacios y DEBEN ir entre comillas: `SSSS_RECOVERY_KEY_*="EsXX YYYY ZZZZ ..."`
|
|
|
|
## Después de crear los archivos
|
|
|
|
Verificar compilación:
|
|
```bash
|
|
go build -tags goolm ./...
|
|
```
|
|
|
|
Luego seguir con registro, verificación y arranque usando los dev-scripts.
|
|
|
|
## 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
|
|
- **Siempre** usar `normalize_id()` de `_common.sh` para nombres de env vars
|
|
- **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`
|
|
- **No** compartir crypto stores entre agentes — cada uno tiene su `store_path`
|
|
- 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
|