172 lines
5.1 KiB
Markdown
172 lines
5.1 KiB
Markdown
# ✅ Resumen: Implementación del Patrón Registry para Tools
|
|
|
|
## 📋 Qué se hizo
|
|
|
|
Se implementó el **patrón Registry** para gestionar las herramientas del agente Naliia de forma centralizada, escalable y fácil de mantener.
|
|
|
|
### Archivos modificados:
|
|
|
|
| Archivo | Cambio | Estado |
|
|
|---------|--------|--------|
|
|
| `src/naliiabot/bot/tools/tools.py` | Removidas tools de ejemplo (Calculator, Greeter, Weather, Time) | ✅ Limpio |
|
|
| `src/naliiabot/bot/tools/__init__.py` | Removidas importaciones de tools de ejemplo | ✅ Actualizado |
|
|
|
|
### Archivos ya existentes (infraestructura):
|
|
|
|
| Archivo | Descripción |
|
|
|---------|-----------|
|
|
| `src/naliiabot/bot/tools/tool_registry.py` | Patrón Registry: `BaseTool` + `ToolRegistry` |
|
|
|
|
### Archivos de documentación y ejemplos creados:
|
|
|
|
| Archivo | Contenido |
|
|
|---------|-----------|
|
|
| **TOOLS_GUIDE.md** | Guía completa con ejemplos de uso |
|
|
| **AGENDA_TOOLS_EXAMPLE.py** | 5 herramientas reales para gestión de agenda |
|
|
| **CHANGES_SUMMARY.md** | Resumen de cambios |
|
|
|
|
## 🎯 Estado actual
|
|
|
|
El proyecto está listo para que **definas tus propias herramientas** en:
|
|
|
|
```
|
|
src/naliiabot/bot/tools/tools.py ← Aquí van TUS tools
|
|
```
|
|
|
|
## 📚 Cómo empezar
|
|
|
|
### 1. Lee la documentación
|
|
|
|
```bash
|
|
# Abre estos archivos en orden:
|
|
1. CHANGES_SUMMARY.md # Resumen rápido
|
|
2. TOOLS_GUIDE.md # Guía detallada
|
|
3. AGENDA_TOOLS_EXAMPLE.py # Ejemplos prácticos
|
|
```
|
|
|
|
### 2. Define una herramienta simple
|
|
|
|
En `src/naliiabot/bot/tools/tools.py`:
|
|
|
|
```python
|
|
from typing import Any, Dict
|
|
from .tool_registry import BaseTool
|
|
|
|
class MiPrimeraHerramienta(BaseTool):
|
|
@property
|
|
def name(self) -> str:
|
|
return "mi_herramienta"
|
|
|
|
@property
|
|
def description(self) -> str:
|
|
return "Descripción de qué hace"
|
|
|
|
@property
|
|
def args_schema(self) -> Dict[str, Any]:
|
|
return {
|
|
"type": "object",
|
|
"properties": {
|
|
"param1": {
|
|
"type": "string",
|
|
"description": "Un parámetro"
|
|
}
|
|
},
|
|
"required": ["param1"]
|
|
}
|
|
|
|
def invoke(self, **kwargs) -> str:
|
|
param = kwargs.get("param1")
|
|
return f"Resultado para {param}"
|
|
```
|
|
|
|
### 3. Registra y usa
|
|
|
|
```python
|
|
from src.naliiabot.bot.tools import ToolRegistry
|
|
from src.naliiabot.bot.tools.tools import MiPrimeraHerramienta
|
|
|
|
registry = ToolRegistry()
|
|
registry.register(MiPrimeraHerramienta())
|
|
tools = registry.get_all_tools_as_langchain()
|
|
|
|
# Usar con el Agent
|
|
agent = Agent(model=modelo, tools=tools)
|
|
```
|
|
|
|
## 🔍 Inspeccionar el ToolRegistry
|
|
|
|
```python
|
|
registry = ToolRegistry()
|
|
registry.register(MiHerramienta())
|
|
|
|
# Ver todas las tools
|
|
tools = registry.get_all_tools()
|
|
|
|
# Ver nombres disponibles
|
|
nombres = registry.list_tool_names() # ['mi_herramienta', ...]
|
|
|
|
# Obtener una específica
|
|
herramienta = registry.get_tool("mi_herramienta")
|
|
|
|
# Verificar si existe
|
|
existe = registry.has_tool("mi_herramienta") # True
|
|
|
|
# Obtener descripción
|
|
desc = registry.get_tool_description("mi_herramienta")
|
|
```
|
|
|
|
## ✨ Ventajas
|
|
|
|
✅ **Centralizado** - Una única fuente de verdad para todas las tools
|
|
✅ **Extensible** - Agregar nuevas tools sin tocar código existente
|
|
✅ **Testeable** - Cada tool se prueba de forma independiente
|
|
✅ **Mantenible** - Cambios aislados en cada tool
|
|
✅ **Validado** - Schema automático de argumentos
|
|
✅ **Documentado** - Fácil inspeccionar tools disponibles
|
|
✅ **Seguro** - Sin tools de ejemplo conflictivas
|
|
|
|
## 📁 Estructura de directorios
|
|
|
|
```
|
|
NaliiaBot/
|
|
├── src/naliiabot/bot/tools/
|
|
│ ├── __init__.py # Exporta ToolRegistry, BaseTool
|
|
│ ├── tool_registry.py # Infraestructura (BaseTool + ToolRegistry)
|
|
│ └── tools.py # ← TUS HERRAMIENTAS AQUÍ (vacío y listo)
|
|
│
|
|
├── tests/
|
|
│ └── test_naliia_agent_tools.py # Tests de tools (ya creados)
|
|
│
|
|
├── TOOLS_GUIDE.md # Guía completa
|
|
├── AGENDA_TOOLS_EXAMPLE.py # Ejemplos reales para agenda
|
|
├── CHANGES_SUMMARY.md # Resumen de cambios
|
|
└── README.md
|
|
```
|
|
|
|
## 🚀 Próximos pasos sugeridos
|
|
|
|
1. **Lee TOOLS_GUIDE.md** para entender completamente el patrón
|
|
2. **Copia ejemplos de AGENDA_TOOLS_EXAMPLE.py** si necesitas tools de agenda
|
|
3. **Crea tus propias herramientas** en `src/naliiabot/bot/tools/tools.py`
|
|
4. **Escribe tests** para tus tools (usa test_naliia_agent_tools.py como referencia)
|
|
5. **Integra con el API** en `src/naliiabotapi/main.py`
|
|
|
|
## ❓ Preguntas frecuentes
|
|
|
|
**P: ¿Cómo agrego una nueva herramienta?**
|
|
R: Define una clase que herede de `BaseTool` en `tools.py` y registra en `ToolRegistry`
|
|
|
|
**P: ¿Puedo usar varias registries?**
|
|
R: Sí, puedes crear múltiples `ToolRegistry` si necesitas diferentes conjuntos de tools
|
|
|
|
**P: ¿Cómo conecto una tool con una BD real?**
|
|
R: En el método `invoke()`, hace la consulta a tu BD. Los ejemplos aquí usan datos simulados.
|
|
|
|
**P: ¿Necesito modificar agent.py?**
|
|
R: No, `agent.py` ya soporta tools. Solo necesitas crear las tools y pasar a `Agent(tools=...)`
|
|
|
|
---
|
|
|
|
**Última actualización:** 15 Feb 2026
|
|
**Status:** ✅ Implementación completada y documentada
|