Herramientas (Tools)

José David Updated by José David

Las herramientas son el corazón funcional de tu agente. Son las capacidades que le permiten interactuar con el mundo exterior: APIs, bases de datos o cualquier lógica de negocio personalizada.

¿Por qué son importantes las Herramientas?

Las herramientas transforman a tu agente de un simple conversador a un potente solucionador de problemas capaz de:

  • Obtener datos en tiempo real desde APIs externas.
  • Realizar cálculos complejos y procesamiento de datos.
  • Interactuar con bases de datos y sistemas de almacenamiento.
  • Ejecutar lógica de negocio personalizada y específica para tus necesidades.
  • Integrarse con servicios de terceros y otras plataformas.
  • Automatizar tareas y flujos de trabajo.

Ejemplo de una Herramienta: GetAddress

Esta es la estructura básica de una herramienta en Python. Volvamos al ejemplo de la Tool que consulta una dirección a partir de un código postal (CEP).

from weni import Tool, Context
from weni.responses import TextResponse
import requests

class GetAddress(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        address_response = self.get_address_by_cep(cep=cep)
        return TextResponse(data=address_response)

    def get_address_by_cep(self, cep):
        url = f"https://viacep.com.br/ws/{cep}/json/"
        response = requests.get(url)
        if response.status_code == 200:
            return response.json()
        return {"error": f"No se pudo encontrar la dirección para el CEP {cep}"}

Explicación del Código

Aquí tienes un desglose simple de lo que hace el código:

  • Imports: Primero, importamos las "piezas" que necesitamos:
    • Tool, Context, TextResponse: Componentes base de Weni CLI.
    • requests: Librería popular de Python para hacer peticiones a sitios web.
  • Definición de la Clase: Creamos una nueva herramienta llamada GetAddress que sabe cómo buscar direcciones.
  • Método execute: Esta es la parte principal que se ejecuta cuando el agente usa la herramienta.
  1. Obtiene el código postal (cep) que el usuario proporcionó.
  2. Llama a otra función (get_address_by_cep) para encontrar la dirección.
  3. Devuelve la información de la dirección al agente.
  • Método get_address_by_cep: Es una función auxiliar que:
  1. Recibe un código postal.
  2. Construye una URL para consultar una API externa.
  3. Obtiene la respuesta y la devuelve.

Pasos para Crear tu Propia Herramienta

Aquí tienes un flujo de trabajo recomendado para crear tus herramientas:

  1. Define tu Clase: Crea una nueva clase Python que herede de Tool.
  2. Implementa el Método execute: Escribe tu lógica de negocio principal dentro de este método.
  3. Añade Métodos Auxiliares: Separa lógicas complejas en funciones más pequeñas y claras para mantener tu código organizado.
  4. Implementa Manejo de Errores: Utiliza try...except para manejar posibles fallos en llamadas a APIs o procesamiento de datos.
  5. Escribe Pruebas: Crea casos de prueba en tu archivo test_definition.yaml para validar tu herramienta localmente con weni run.
  6. Configura la Herramienta en el YAML: Añade tu nueva herramienta a la lista tools de tu agent_definition.yaml.

Uso de Credenciales en Herramientas

Nunca debes escribir claves de API o contraseñas directamente en tu código. Para eso, utiliza context.credentials.

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        # Accede a la credencial de forma segura
        api_key = context.credentials.get("mi_api_key")

        headers = {"Authorization": f"Bearer {api_key}"}
        # ...lógica para hacer una petición autenticada...

Para una guía completa sobre cómo configurar esto, consulta el artículo Gestión de Credenciales.

Buenas Prácticas Generales para Herramientas

  • Responsabilidad Única: Cada herramienta debe tener un propósito claro y enfocado.
  • Manejo de Errores Exhaustivo: Controla posibles fallos en todas las llamadas externas y casos borde.
  • Validación de Entradas: Valida todos los parámetros de entrada antes de procesarlos.
  • Consideraciones de Seguridad: Maneja los datos sensibles adecuadamente y sigue las mejores prácticas de seguridad.
  • Testeabilidad: Diseña tus herramientas para que sean fáciles de probar.
  • Control de Versiones: Utiliza un repositorio (ej. GitHub) para versionar tus herramientas.

How did we do?

Gestión de Credenciales

Contact