agents_and_robots/dev/issues/completed/0001-bot-tools.md

Plan: Herramientas para los bots

Objetivo

Permitir que los bots ejecuten herramientas reales (funciones Go) como respuesta a decisiones del LLM — patrón function calling / tool use.

Estado: COMPLETADO

---

Diseño

Capa pura (pkg/tools/)

• Definir ToolSpec con nombre, descripción y esquema JSON de parámetros
• Definir ToolCallAction en pkg/decision/ — acción pura que contiene ToolName string y Args map[string]any
• El motor de reglas puede emitir ToolCallAction como cualquier otra acción

Capa shell (shell/tools/)

• Executor que mapea nombre → función Go real
• Ejecuta la herramienta y devuelve ToolResult{Output string, Err error}
• El Runner de shell/effects/ llama al Executor cuando recibe ToolCallAction

Integración LLM

• shell/llm/anthropic.go y openai.go ya soportan tool_use / function_calling
• Mapear []ToolSpec al formato nativo de cada proveedor
• Parsear la respuesta del LLM para extraer llamadas a herramientas

Herramientas iniciales a implementar

Herramienta	Descripción	Shell
http_get	GET a una URL, devuelve body	shell/tools/
http_post	POST JSON a una URL	shell/tools/
ssh_command	Ejecutar comando remoto por SSH	shell/ssh/
read_file	Leer archivo local	shell/tools/
matrix_send	Enviar mensaje a una sala Matrix	shell/matrix/

---

Archivos a crear/modificar

• pkg/tools/spec.go — ToolSpec, ToolResult
• pkg/decision/actions.go — añadir ToolCallAction
• shell/tools/executor.go — registro y ejecución de herramientas
• shell/effects/runner.go — manejar ToolCallAction
• shell/llm/anthropic.go — emitir tools en el request, parsear tool_use blocks
• shell/llm/openai.go — idem para function_calling
• agents/<id>/agent.go — registrar herramientas por agente

Notas

• Las herramientas se declaran en pkg/ (pure spec) pero se implementan en shell/
• Un agente solo tiene acceso a las herramientas declaradas en su config
• Respetar security.allowed_tools del config YAML