Anatomia de um Agente: Agentes Ativos

José David Atualizado por José David

Diferente dos Agentes Passivos, que reagem à interação do usuário, os Agentes Ativos são projetados para iniciar ações de forma proativa. Eles atuam com base em regras e condições predefinidas, como mudanças de estado em um sistema ou eventos agendados, sem que o usuário precise iniciar a conversa.

Estrutura Geral

A definição de um Agente Ativo também é feita no arquivo agent_definition.yaml, mas sua estrutura se concentra em rules (regras) e pre_processing (pré-processamento) em vez de tools.

agents:
  my_active_agent: # <--- Slug do agente ativo
    name: "Notificador de Status de Pedido"
    description: "Um agente que notifica proativamente os clientes sobre o status de seus pedidos."
    rules:
      status_aprobado:
        display_name: "Status Aprovado"
        template: "template_status_aprobado"
        start_condition: "Quando o status do pedido for 'aprovado'"
        source:
          entrypoint: "main.StatusAprovado"
          path: "rules/status_aprobado"
      status_facturado:
        display_name: "Status Faturado"
        template: "template_status_facturado"
        start_condition: "Quando o status do pedido for 'faturado'"
        source:
          entrypoint: "main.StatusFacturado"
          path: "rules/status_facturado"
    pre_processing:
      source:
        entrypoint: "processing.PreProcessor"
        path: "pre_processors/processor"
      result_examples_file: "result_example.json"

Definição de Regras (rules)

A seção rules é um dicionário que define os gatilhos que ativam as ações do agente. Cada chave dentro de rules é um slug ou ID único para cada regra.

rules:
  status_aprobado: # <--- Este é o slug da regra
    display_name: "Status Aprovado"
    template: "template_status_aprobado"
    start_condition: "Quando o status do pedido for 'aprovado'"
    source:
      entrypoint: "main.StatusAprovado"
      path: "rules/status_aprobado"
Propriedades de uma Regra
  • display_name (string): Nome legível da regra, exibido na interface da plataforma.
  • template (string): Modelo de mensagem usado quando a regra é acionada.
  • start_condition (string): Descrição em linguagem natural da condição que deve ser atendida para ativar a regra.
  • source (dict): Define o código Python executado quando a regra é disparada.
    • entrypoint: Ponto de entrada no formato nome_arquivo.NomeDaClasse (ex: main.StatusAprovado).
    • path: Caminho para o diretório que contém o código da regra.

Pré-Processamento de Dados (pre_processing)

Esta seção (opcional, mas muito poderosa) define uma etapa de lógica executada antes da avaliação das regras. É útil para transformar, enriquecer ou preparar dados.

pre_processing:
      source:
        entrypoint: "processing.PreProcessor"
        path: "pre_processors/processor"
      result_examples_file: "result_example.json"
Propriedades de pre_processing
  • source (dict): Define o código da lógica de pré-processamento.
    • entrypoint: Classe e método usados para o pré-processamento (ex: processing.PreProcessor).
    • path: Caminho para o diretório que contém o código de pré-processamento.
  • result_examples_file (string) (Obrigatório): Caminho para um arquivo JSON contendo exemplos da saída do pré-processamento.
    Este arquivo é essencial para que a plataforma compreenda a estrutura dos dados que serão manipulados pelas regras.

Formato do Arquivo de Exemplos (result_example.json)

O arquivo de exemplos de resultados deve ser um array de objetos JSON, onde cada objeto representa um possível cenário ou caso de teste.

[
    {
        "urn": "tel:+5511999998888",
        "data": {
            "pedido_id": "12345",
            "status_actual": "aprobado",
            "cliente_nombre": "Ana"
        }
    },
    {
        "urn": "tel:+5521888889999",
        "data": {
            "pedido_id": "67890",
            "status_actual": "enviado",
            "cliente_nombre": "Carlos",
            "codigo_rastreo": "BR123456789"
        }
    }
]
  • urn: Um identificador único do contato (por exemplo, um número de telefone no formato E.164 ou um ID de usuário).
  • data: Um objeto que contém os dados relevantes para esse exemplo específico.
    A estrutura desse objeto dependerá das necessidades do seu agente.

Estrutura de Pastas Sugerida

Para manter o projeto organizado, recomenda-se separar a lógica das regras e do pré-processamento em suas próprias pastas.

seu-projeto/
├── rules/
│   ├── status_aprovado/
│   │   ├── main.py
│   │   └── requirements.txt
│   └── status_enviado/
│       ├── main.py
│       └── requirements.txt
├── pre_processors/
│   └── processor/
│       ├── processing.py
│       └── requirements.txt
├── agent_definition.yaml
└── result_example.json

Como a gente se saiu?

Anatomia de um Agente: Agentes Passivos

Contato