Gestión de Credenciales

Las credenciales son información confidencial (como claves de API, tokens o contraseñas) que tus herramientas necesitan para conectarse de forma segura a servicios externos.

La gestión correcta de las credenciales es fundamental en dos momentos clave del ciclo de vida de tu agente:

1. Durante el desarrollo, para realizar pruebas locales de tus herramientas.
2. En producción, para que tu agente funcione de manera segura en los canales integrados con la Plataforma Weni.

Estructura en agent_definition.yaml

Primero, debes declarar todas las credenciales que tu agente necesitará en la sección credentials de tu archivo de definición.

agents:
  mi_agente:
    credentials:
      API_KEY:
        label: "API Key del Servicio"
        placeholder: "Ingresa tu API Key aquí"
        is_confidential: true
      API_SECRET:
        label: "API Secret del Servicio"
        placeholder: "your-api-secret-here"
      BASE_URL:
        label: "URL Base de la API"
        placeholder: "https://api.example.com"
        is_confidential: false

Cada credencial tiene los siguientes atributos:

• label: El nombre legible que se mostrará en la interfaz de la Plataforma Weni.
• placeholder: Un texto de ayuda que aparece en el campo de entrada para guiar al usuario.
• is_confidential: Un booleano (true/false) que indica si la credencial contiene información sensible. Por defecto es true.

Credenciales en Producción

Cuando despliegas tu agente en la Plataforma Weni, las credenciales se gestionan a través de la interfaz de usuario para garantizar la máxima seguridad.

Flujo de Trabajo en Producción

1. Definición en el YAML: Declara las credenciales en tu agent_definition.yaml, por ejemplo, usando el ejemplo del agente del CEP, imaginemos que configuramos las credenciales de esta manera:

   agents:
       cep_agent:
           credentials:
               api_key:
                   label: "API Key"
                   placeholder: "Enter your API key"
           name: "CEP Agent"
           description: "Weni's CEP agent with components"
           instructions:
        # Resto del agent_definition...

2. Despliega tu Agente: Ejecuta weni project push agent_definition.yaml. La plataforma detectará automáticamente las credenciales que definiste.
3. Configura en la Interfaz: Un administrador podrá configurar los valores reales de las credenciales a través de la interfaz de la Plataforma Weni, sin necesidad de modificar el código.

Al asignar tu agente desde la galería de "Agentes Personalizados", la plataforma te pedirá que completes los valores para cada credencial definida.

Acceso a Credenciales en el Código

El acceso a las credenciales desde el código de tu herramienta siempre se hace de la misma manera: a través del objeto context.

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

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        # Obtiene parámetros del contexto
        cep = context.parameters.get("cep", "")

        # Obtiene credenciales del contexto de forma segura
        api_key = context.credentials.get("api_key")

        address_response = self.get_address_by_cep(cep=cep, api_key=api_key)

        return TextResponse(data=address_response)

    #... Resto del código...

La línea clave es api_key = context.credentials.get("api_key"), que recupera el valor de la credencial que fue definido en tu YAML y proporcionado ya sea en la Plataforma Weni o en tus archivos de prueba locales.

Credenciales para Pruebas Locales

Durante el desarrollo, necesitas una forma de proporcionar valores de prueba a tus herramientas para poder ejecutarlas localmente con weni run.

Usando .env

Para ello, crea un archivo llamado .env dentro del directorio de tu herramienta (el especificado en source.path).

Por ejemplo, si tu agente de CEP tiene las siguientes credenciales:

agents:
  cep_agent:
    credentials:
      api_key:
        label: "API Key"
        placeholder: "Enter your API key"
    # Resto del agent_definition...

El .env debería ir en esta ruta tools/get_address/.env y manejar la siguiente estructura:

api_key=your-development-api-key

La CLI leerá este archivo automáticamente y hará que estos valores estén disponibles en context.credentials durante la ejecución de weni run.

Usando test_definition.yaml

Para pruebas rápidas o para usar credenciales distintas en cada caso de prueba, existe la opción de definirlas directamente dentro de tu archivo test_definition.yaml.

Este método te permite anidar un bloque de credentials dentro de un test específico, así:

tests:
  test_con_credencial_especifica:
    parameters:
      cep: "57160000"
    credentials:
      API_KEY: "valor_de_prueba_solo_para_este_test"

Este método es menos recomendado que el atnerior, por lo que, si decides utilizar este método, ten mucho cuidado con el manejo de repositorios, ya que si no lo manejas correctamente y cargas el test_definition.yaml, podrías filtrar las credenciales.

Aunque este método puede ser útil, es menos seguro y no se recomienda como práctica habitual en comparación con el uso de un archivo .env.

El principal riesgo es que podrías exponer tus credenciales accidentalmente si subes este archivo a un repositorio de código como Git. Un archivo .env suele estar ignorado por defecto en los proyectos, pero no siempre es el caso para los archivos de prueba.

Consejo Profesional: Si decides utilizar este enfoque, es crucial que te asegures de que el archivo test_definition.yaml esté añadido a tu archivo .gitignore para evitar filtraciones de seguridad.