egutierrez
bff41b9ccd
Se actualizan todas las referencias a dev-scripts para usar los nuevos paths con subdirectorios server/ y agent/ en: - .claude/CLAUDE.md — sección de dev-scripts y guía rápida - .claude/policies/create_agent.md — simplificada y reorganizada como guía ejecutable - README.md — sección de uso y estructura de directorios - docs/creating-agents.md — todos los pasos del flujo La policy create_agent.md se reduce de ~230 a ~140 líneas, eliminando secciones redundantes y reorganizando como checklist práctico con ruta rápida via create-full.sh. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
301 lines
8.8 KiB
Markdown
301 lines
8.8 KiB
Markdown
# agents_and_robots
|
|
|
|
Plataforma en Go para gestionar bots Matrix autónomos. Cada bot combina un **core puro** (personalidad, reglas de decisión, transformaciones) con un **shell impuro** (conexión Matrix, SSH, LLM, side effects), conectados a un servidor Matrix self-hosted.
|
|
|
|
---
|
|
|
|
## Inicio rápido
|
|
|
|
```bash
|
|
# 1. Compilar todo
|
|
./build.sh
|
|
|
|
# 2. Cargar variables de entorno
|
|
source .env
|
|
|
|
# 3. Lanzar la TUI interactiva (dashboard)
|
|
./bin/dashboard
|
|
```
|
|
|
|
### Dashboard TUI
|
|
|
|
El dashboard es una interfaz de terminal interactiva (bubbletea) para gestionar los bots del servidor:
|
|
|
|
```
|
|
./bin/dashboard
|
|
```
|
|
|
|
Desde la TUI puedes:
|
|
|
|
- **Agents** — ver estado de cada agente, iniciar/detener/reiniciar/kill individual, ver logs
|
|
- **Server** — operaciones masivas: start all, stop all, restart all, kill all con resumen de estado
|
|
|
|
### Otros binarios
|
|
|
|
| Binario | Uso |
|
|
|---------|-----|
|
|
| `./bin/launcher` | Inicia uno o varios agentes como procesos |
|
|
| `./bin/agentctl` | CLI: `list`, `start`, `stop`, `remove` |
|
|
| `./bin/register` | Registra bots en Synapse via admin API |
|
|
| `./bin/dashboard` | TUI interactiva para gestión de bots |
|
|
|
|
---
|
|
|
|
## Principio de diseño
|
|
|
|
El proyecto usa el patrón **pure core / impure shell**:
|
|
|
|
```
|
|
Mensaje Matrix
|
|
│
|
|
▼
|
|
Parse() ← puro: produce MessageContext
|
|
│
|
|
▼
|
|
Evaluate() ← puro: produce []Action (solo datos, sin efectos)
|
|
│
|
|
▼
|
|
Runner.Execute() ← impuro: interpreta las acciones → envía mensajes, ejecuta SSH, llama LLM
|
|
```
|
|
|
|
Nada dentro de `pkg/` tiene efectos secundarios. Todo el I/O vive en `shell/`.
|
|
|
|
---
|
|
|
|
## Estructura
|
|
|
|
```
|
|
agents_and_robots/
|
|
│
|
|
├── pkg/ ← PURE CORE — sin side effects
|
|
│ ├── decision/ engine de reglas: Evaluate(), Rule, Action, MatchFunc
|
|
│ ├── llm/ tipos LLM: CompleteFunc, CompletionRequest
|
|
│ ├── tools/ specs declarativas: SSHCommandSpec, HTTPCallSpec...
|
|
│ ├── message/ parse y format de mensajes
|
|
│ └── personality/ tipos de personalidad del bot
|
|
│
|
|
├── shell/ ← IMPURE SHELL — todo el I/O
|
|
│ ├── llm/ clientes reales: Anthropic, OpenAI/Ollama
|
|
│ ├── matrix/ cliente mautrix-go: envío, sync, listener
|
|
│ ├── ssh/ ejecución SSH real (golang.org/x/crypto/ssh)
|
|
│ ├── effects/ Runner: interpreta []Action → side effects
|
|
│ ├── bus/ mensajería inter-agente via Go channels
|
|
│ └── protocols/ MCP server/client (mark3labs/mcp-go)
|
|
│
|
|
├── agents/ ← definición de cada bot
|
|
│ ├── runtime.go Agent{}: ensambla core + shell
|
|
│ └── assistant/ reglas + config del assistant-bot
|
|
│
|
|
├── internal/config/ esquema YAML completo + loader con env vars
|
|
│
|
|
├── cmd/
|
|
│ ├── launcher/ inicia uno o varios agentes
|
|
│ ├── agentctl/ CLI: list, start, stop, remove
|
|
│ └── register/ registra bots en Synapse via admin API
|
|
│
|
|
├── dev-scripts/ scripts bash para el día a día
|
|
│ ├── server/ gestión del launcher (start, stop, restart, ps, logs, dashboard)
|
|
│ └── agent/ gestión de agentes (new, register, verify, avatar, remove, list)
|
|
├── config/ configuración global (matrix.yaml, servers.yaml)
|
|
└── .env.example plantilla de variables de entorno
|
|
```
|
|
|
|
---
|
|
|
|
## Requisitos
|
|
|
|
- Go 1.23+
|
|
- Servidor Matrix (Synapse) con acceso admin
|
|
- API key de OpenAI o Anthropic (según el bot)
|
|
|
|
---
|
|
|
|
## Setup inicial
|
|
|
|
```bash
|
|
# 1. Clonar y entrar al repo
|
|
git clone <repo-url>
|
|
cd agents_and_robots
|
|
|
|
# 2. Copiar y rellenar variables de entorno
|
|
cp .env.example .env
|
|
# Editar .env con: MATRIX_HOMESERVER, OPENAI_API_KEY, etc.
|
|
|
|
# 3. Descargar dependencias
|
|
go mod tidy
|
|
```
|
|
|
|
---
|
|
|
|
## Registrar y arrancar un bot
|
|
|
|
```bash
|
|
# Registrar el bot en el servidor Matrix (necesita MATRIX_ADMIN_TOKEN en .env)
|
|
./dev-scripts/agent/register.sh assistant-bot "Assistant"
|
|
# → imprime el token, copiarlo a .env como MATRIX_TOKEN_ASSISTANT
|
|
|
|
# Ver todos los bots y su estado
|
|
./dev-scripts/agent/list.sh
|
|
|
|
# Iniciar
|
|
./dev-scripts/server/start.sh assistant-bot
|
|
|
|
# Ver logs en vivo
|
|
./dev-scripts/server/logs.sh assistant-bot
|
|
|
|
# Detener
|
|
./dev-scripts/server/stop.sh assistant-bot
|
|
```
|
|
|
|
---
|
|
|
|
## CLI — agentctl
|
|
|
|
```bash
|
|
go run ./cmd/agentctl list # ver todos los bots
|
|
go run ./cmd/agentctl start assistant-bot # iniciar
|
|
go run ./cmd/agentctl stop # detener todos
|
|
go run ./cmd/agentctl remove assistant-bot # deshabilitar (sin borrar datos)
|
|
```
|
|
|
|
O compilando los binarios:
|
|
|
|
```bash
|
|
make build # genera bin/launcher, bin/agentctl, bin/register
|
|
./bin/agentctl list
|
|
```
|
|
|
|
---
|
|
|
|
## Crear un bot nuevo
|
|
|
|
```bash
|
|
# 1. Generar el scaffold completo
|
|
./dev-scripts/agent/new-agent.sh monitor-bot "Monitor Agent"
|
|
```
|
|
|
|
Genera:
|
|
```
|
|
agents/monitor-bot/
|
|
├── config.yaml ← configuración completa, lista para editar
|
|
├── agent.go ← reglas puras con help + LLM fallback
|
|
└── prompts/
|
|
└── system.md ← system prompt del LLM
|
|
```
|
|
|
|
El script imprime los dos pasos manuales que quedan:
|
|
|
|
```bash
|
|
# 2. Añadir al registro en cmd/launcher/main.go:
|
|
import monitoragent "github.com/enmanuel/agents/agents/monitor-bot"
|
|
|
|
var rulesRegistry = map[string]func() []decision.Rule{
|
|
"monitor-bot": monitoragent.Rules, // ← añadir aquí
|
|
...
|
|
}
|
|
|
|
# 3. Registrarlo en Matrix y arrancar
|
|
./dev-scripts/agent/register.sh monitor-bot "Monitor Agent"
|
|
# → añadir token a .env
|
|
./dev-scripts/server/start.sh monitor-bot
|
|
```
|
|
|
|
---
|
|
|
|
## Configuración de agentes
|
|
|
|
Cada `agents/<id>/config.yaml` soporta:
|
|
|
|
| Sección | Qué controla |
|
|
|---------|--------------|
|
|
| `agent` | identidad, versión, tags, enabled |
|
|
| `personality` | tono, verbosidad, idioma, emoji, templates de respuesta, comportamiento |
|
|
| `llm` | provider (anthropic/openai/ollama), modelo, fallback, rate limits, tool use |
|
|
| `tools` | SSH, HTTP, scripts, file_ops, MCP (habilitados por bot) |
|
|
| `matrix` | homeserver, user_id, rooms, filtros de mensajes, E2EE |
|
|
| `agents` | peers con los que colabora, delegación, protocolo |
|
|
| `ssh` | inventario de targets con hosts, users, jump host |
|
|
| `security` | RBAC por roles, audit log, gestión de secrets |
|
|
| `schedules` | tareas cron automáticas con acciones SSH/script |
|
|
| `observability` | logging, métricas Prometheus, health check, tracing |
|
|
| `resilience` | circuit breaker, retry, graceful shutdown, queue |
|
|
| `storage` | estado SQLite/Redis, caché, historial de conversación |
|
|
|
|
Las variables del sistema se referencian como `${NOMBRE_VAR}` y se expanden en tiempo de carga.
|
|
|
|
---
|
|
|
|
## Reglas de decisión
|
|
|
|
Las reglas de cada bot se definen como datos puros en `agents/<id>/agent.go`:
|
|
|
|
```go
|
|
func Rules() []decision.Rule {
|
|
return []decision.Rule{
|
|
{
|
|
Name: "deploy-staging",
|
|
Match: decision.And(
|
|
decision.MatchCommand("deploy"),
|
|
func(ctx decision.MessageContext) bool {
|
|
return len(ctx.Args) > 0 && ctx.Args[0] == "staging"
|
|
},
|
|
),
|
|
Actions: []decision.Action{{
|
|
Kind: decision.ActionKindSSH,
|
|
SSH: &tools.SSHCommandSpec{Target: "staging", Command: "..."},
|
|
}},
|
|
},
|
|
// catch-all: DMs y menciones van al LLM
|
|
{
|
|
Name: "llm-fallback",
|
|
Match: func(ctx decision.MessageContext) bool {
|
|
return ctx.IsDirectMsg || ctx.IsMention
|
|
},
|
|
Actions: []decision.Action{{Kind: decision.ActionKindLLM, LLM: &decision.LLMAction{}}},
|
|
},
|
|
}
|
|
}
|
|
```
|
|
|
|
Predicados disponibles: `MatchCommand`, `MatchPrefix`, `MatchMinPowerLevel`, `MatchAny`, `And`, `Or`.
|
|
|
|
Tipos de acción: `reply`, `ssh`, `http`, `script`, `file_ops`, `mcp`, `llm`, `delegate`.
|
|
|
|
---
|
|
|
|
## Bots incluidos
|
|
|
|
### assistant-bot
|
|
|
|
Asistente general con GPT-4o. Responde a DMs y menciones. Sin acceso a herramientas — solo LLM.
|
|
|
|
```
|
|
@assistant-bot:matrix-af2f3d.organic-machine.com
|
|
```
|
|
|
|
---
|
|
|
|
## Dependencias
|
|
|
|
| Librería | Versión | Uso |
|
|
|----------|---------|-----|
|
|
| `maunium.net/go/mautrix` | v0.21.1 | Cliente Matrix, sync, E2EE |
|
|
| `github.com/sashabaranov/go-openai` | v1.36.1 | OpenAI API y compatibles (Ollama) |
|
|
| `github.com/mark3labs/mcp-go` | v0.44.1 | MCP protocol server/client |
|
|
| `golang.org/x/crypto` | v0.31.0 | SSH |
|
|
| `github.com/spf13/cobra` | v1.8.1 | CLI |
|
|
| `gopkg.in/yaml.v3` | v3.0.1 | Config |
|
|
|
|
---
|
|
|
|
## Makefile
|
|
|
|
```bash
|
|
make build # compila todos los binarios en bin/
|
|
make list # agentctl list
|
|
make start # start todos (AGENT=id para uno)
|
|
make stop # stop todos (AGENT=id para uno)
|
|
make tidy # go mod tidy
|
|
make clean # elimina bin/ y run/
|
|
```
|