Anatomía de un Agente: Agentes Pasivos

José David Updated by José David

Un Agente Pasivo es un trabajador de IA que reacciona a las entradas del usuario para resolver problemas. Su definición se realiza en un archivo YAML, que actúa como su plano de construcción.

Estructura General

El archivo agent_definition.yaml comienza con la clave agents, que contiene uno o más agentes, cada uno identificado por un slug único.

agents:
  cep_agent: # <--- Este es el slug del agente
    name: "CEP Agent"
    description: "Weni's CEP agent"
    instructions:
      - "You are an expert in providing addresses to the user based on a postal code provided by the user"
      - "The user will send a ZIP code (postal code) and you must provide the address corresponding to this code."
    guardrails:
      - "Don't talk about politics, religion or any other sensitive topic. Keep it neutral."
    tools:
      - get_address:
          name: "Get Address"
          source: 
            path: "tools/get_address"
            entrypoint: "main.GetAddress"
            path_test: "test_definition.yaml"
          description: "Function to get the address from the postal code"
          parameters:
            - cep:
                description: "postal code of a place"
                type: "string"
                required: true
                contact_field: true

slug del Agente (cep_agent): Es el ID único de tu agente. Se utiliza para actualizar el agente en futuros despliegues (push). Si el slug no existe, se crea un nuevo agente; si ya existe, se actualiza.

Propiedades Principales del Agente

Estas claves definen las características y la personalidad del agente.

  • name (string) El nombre de tu agente que se mostrará en la interfaz de la Plataforma Weni. Límite: 55 caracteres.
  • description (string) Una descripción breve sobre el propósito del agente, también visible en la interfaz.
  • instructions (list of strings) Directivas y guías que el agente debe seguir. Define su rol, personalidad y forma de operar. Límite: Mínimo 40 caracteres.
  • guardrails (list of strings) Límites y temas que el agente debe evitar para mantener la conversación enfocada y segura. Límite: Mínimo 40 caracteres.
  • credentials (dict) Define las credenciales que las herramientas del agente pueden necesitar para interactuar con servicios externos.

    Para una explicación detallada, consulta la guía de Gestión de Credenciales.

Definición de la herramienta

    tools:
      - get_address: # <--- Este es el slug de la herramienta
          name: "Get Address"
          # ... resto de la configuración de la herramienta

slug de la Herramienta (get_address): Es el ID único de la herramienta dentro del agente.
Propiedades de la Herramienta
  • name (string): El nombre de la herramienta que se mostrará en la plataforma. Límite: 40 caracteres.
  • description (string): Una explicación sobre lo que hace la herramienta.
  • source (dict): Conecta la definición con el código Python que ejecuta la lógica.
    • path: La ruta al directorio que contiene el código de la herramienta (ej: tools/get_address).
    • entrypoint: El punto de entrada, en formato nombre_archivo.NombreDeLaClase (ej: main.GetAddress).
    • path_test: La ruta al archivo YAML que contiene los casos de prueba para weni run.
Parámetros de la Herramienta (parameters)

Define los datos de entrada que la herramienta necesita para funcionar.

  • description (string): Explica qué es el parámetro.
  • type (string): El tipo de dato (string, number, integer, boolean, array).
  • required (boolean): Si es true, el agente se asegurará de obtener este dato del usuario antes de ejecutar la herramienta.
  • contact_field (boolean): Si es true, el valor del parámetro se guardará en el perfil del contacto en la Plataforma Weni.

    Para más detalles, lee la guía sobre Campos de contacto.

How did we do?

Tutorial: Creando un Agente de Consulta de CEP

Anatomía de un Agente: Agentes Activos

Contact