{"section":"tutorials","requestedLocale":"pt","requestedSlug":"criando-agentes-ativos","locale":"pt","slug":"criando-agentes-ativos","path":"docs/pt/tutorials/weni-by-vtex/weni-agentic-ai/criando-agentes-ativos.md","branch":"main","content":"Agentes ativos são projetados para agir de forma proativa com base em regras e condições predefinidas. Ao contrário dos agentes passivos, que reagem apenas às interações dos usuários, os agentes ativos podem iniciar ações ou comunicações quando determinados critérios são atendidos, muitas vezes desencadeadas por mudanças em dados ou eventos do sistema. O comando para fazer o deploy de um agente ativo é o mesmo utilizado para outros agentes: `weni project push agent_definition.yaml`\n\n## Conceitos básicos e estrutura yaml\n\nA definição de um agente ativo é feita em um arquivo `agent_definition.yaml`. Os principais campos são:\n\n- **agents.<id_do_agente>**: identifica o agente\n- **name**: nome de exibição do agente, com limite de 55 caracteres\n- **description**: descrição do propósito e capacidades do agente\n- **rules**: dicionário de regras que disparam as ações do agente\n- Dentro de **rules.<id_da_regra>**:\n  - **display_name**: nome legível da regra\n  - **template**: template de mensagem HSM a ser usado\n  - **start_condition**: descrição da condição que deve ser atendida para acionar a regra\n  - **source**: define o código a ser executado quando a regra é disparada, com `entrypoint` apontando para a classe/método e `path` para o diretório onde está o código\n- **pre_processing**: define uma etapa de pré‑processamento para preparar dados antes de avaliar as regras com `source` especificando o código e `result_examples_file` apontando para um JSON com exemplos de saída.\n\nO arquivo `result_example.json` deve ser um array de objetos. Cada objeto contém:\n\n- `urn`: identificador único do contato (por exemplo, número de telefone ou ID de usuário).\n- `data`: um dicionário com os dados relevantes para a regra. A estrutura desse dicionário depende das informações que seu agente precisa processar\n\n## Estrutura do projeto\n\nUm agente ativo segue uma organização de pastas clara\n\n```\nyour-project-name/\n├── rules/\n│   ├── status_aprovado/\n│   │   ├── main.py\n│   │   └── requirements.txt\n│   └── status_invoiced/\n│       ├── main.py\n│       └── requirements.txt\n├── pre_processors/\n│   └── processor/\n│       ├── processing.py\n│       └── requirements.txt\n├── agent_definition.yaml\n└── result_example.json\n```\n\nEssa estrutura ajuda a organizar as diferentes partes do agente. Na pasta `rules/` ficam as regras separadas por status, cada uma com seu próprio arquivo `main.py` e `requirements.txt`. A pasta `pre_processors/processor` contém o código de pré‑processamento e seu `requirements.txt`, enquanto os arquivos `agent_definition.yaml` e `result_example.json` ficam na raiz.\n\n## Exemplo de definição yaml\n\nAbaixo está um exemplo de `agent_definition.yaml` com um agente chamado `active_order_status` que gerencia o status de pedidos:\n\n```yaml\nagents:\n  active_order_status:\n    name: \"Active Order Status\"\n    description: \"Agente responsável por disparar templates de status de pedidos, com base no status recebido da VTEX - Order Status\"\n    language: \"pt_BR\"\n    rules:\n      PaymentApproved:\n        display_name: \"Payment Approved\"\n        template: \"payment_confirmation_2\"\n        start_condition: \"When the status is Payment Approved\"\n        source:\n          entrypoint: \"main.PaymentApproved\"\n          path: \"rules/status_payment_approved\"\n      OrderInvoiced:\n        display_name: \"Order Invoiced\"\n        template: \"order_update_no_cta_1\"\n        start_condition: \"When the status is Invoiced\"\n        source:\n          entrypoint: \"main.StatusInvoiced\"\n          path: \"rules/status_invoiced\"\n      OrderCanceled:\n        display_name: \"Order Canceled\"\n        template: \"order_canceled_3\"\n        start_condition: \"When the status is Canceled\"\n        source:\n          entrypoint: \"main.Canceled\"\n          path: \"rules/status_canceled\"\n      OrderCreated:\n        display_name: \"Order Created\"\n        template: \"order_management_no_cta_5\"\n        start_condition: \"When the status is Order Created\"\n        source:\n          entrypoint: \"main.OrderCreated\"\n          path: \"rules/status_order_created\"\n    pre_processing:\n      source:\n        entrypoint: \"processing.PreProcessor\"\n        path: \"pre_processors/processor\"\n      result_examples_file: \"result_example.json\"\n```\n\nEste arquivo define quatro regras vinculadas aos diferentes status do pedido. Para cada regra são configurados o nome de exibição, o template HSM associado, a condição de início e o caminho para o código Python que será executado. O bloco `pre_processing` indica a classe e o diretório que serão usados para preparar os dados antes de avaliar as regras.\n\n## Pré‑processamento\n\nA etapa de pré‑processamento é responsável por coletar todos os dados necessários que serão utilizados pelas regras. Somente nesta etapa é permitido realizar requisições HTTP ou outras chamadas externas; por isso, existe um único `requirements.txt` dentro de `pre_processors`. O objeto `PreProcessorContext` contém o payload do webhook e informações do projeto. Os dados do webhook são acessados via `context.payload.get(\"campo\")`. Por exemplo, para obter o `orderId` em um payload como o abaixo, utiliza‑se `context.payload.get(\"orderId\")`\n\n```json\n{\n  \"recorder\": {\n    \"_record\": {\n      \"x-vtex-meta\": {},\n      \"x-vtex-meta-bucket\": {}\n    }\n  },\n  \"domain\": \"Marketplace\",\n  \"orderId\": \"1544102600592-01\",\n  \"currentState\": \"payment-approved\",\n  \"lastState\": \"canceled\",\n  \"currentChangeDate\": \"2025-02-07T13:54:54.7438532Z\",\n  \"lastChangeDate\": \"2025-02-07T13:54:54.6657558Z\",\n  \"vtexAccount\": \"leoamaral\"\n}\n```\n\nAlém de acessar campos do payload, é possível obter informações do projeto, como o identificador (`uuid`) e a conta VTEX, via `context.project.get(\"uuid\")` e `context.project.get(\"vtex_account\")`. O método `process` do pré‑processador deve retornar um objeto `ProcessedData`, composto por uma `urn` (identificador do contato) e um dicionário com os dados que serão repassados para as regras. A `urn` deve seguir o padrão `whatsapp:5582900000000`.\n\nAbaixo está um exemplo simplificado de pré‑processador:\n\n```python\nfrom weni.context.preprocessor_context import PreProcessorContext\nfrom weni.preprocessor import PreProcessor as BasePreProcessor, ProcessedData\n\nclass PreProcessor(BasePreProcessor):\n    def process(self, context: PreProcessorContext) -> ProcessedData:\n        # Obter dados do webhook\n        order_id = context.payload.get(\"orderId\", \"\")\n        phone_number = context.payload.get(\"phone_number\", \"\")\n        state = context.payload.get(\"currentState\", \"\")\n\n        # Obter dados do projeto\n        project_id = context.project.get(\"uuid\")\n        vtex_account = context.project.get(\"vtex_account\")\n\n        # Lógica de negócio (chamadas externas podem ser feitas aqui)\n        # ...\n\n        # Retornar o contato e dados para as regras\n        urn = f\"whatsapp:{phone_number}\"\n        return ProcessedData(urn, {\"orderId\": order_id, \"status\": state})\n```\n\n## Implementação de regra: Paymentapproved\n\nCada regra do agente é implementada como uma classe que herda de `Rule`. A função `execute` verifica se a condição é atendida e retorna `True` caso a mensagem deva ser enviada. A função `get_template_variables` monta um dicionário com as variáveis do template. Abaixo está a implementação da regra **PaymentApproved**:\n\n```python\nfrom weni.preprocessor import ProcessedData\nfrom weni.rules import Rule\n\nclass PaymentApproved(Rule):\n    def execute(self, data: ProcessedData) -> bool:\n        status = data.data.get(\"status\")\n        # Verifica se o status recebido no pré-processamento é 'payment-approved'\n        return status == \"payment-approved\"\n\n    def get_template_variables(self, data: ProcessedData) -> dict:\n        name = data.data.get(\"name\")\n        price = int(data.data.get(\"price\", 0))\n        order_id = data.data.get(\"orderId\")\n        # Retorna variáveis na ordem do template HSM\n        return {\"1\": f\"R$ {price / 100}\", \"2\": order_id}\n```\n\n## Uso de templates (hsm)\n\nOs templates de mensagem (HSM) cadastrados no WhatsApp Business podem conter marcadores como `{{1}}`, `{{2}}`, etc. Quando `execute` retorna `True`, a Weni CLI chama `get_template_variables` para preencher essas variáveis. Por exemplo, considerando um template `Olá {{1}}, seu pedido {{2}} está em fase de {{3}}`, a função deve retornar:\n\n```json\n{ \"1\": \"Leonardo\", \"2\": \"12345\", \"3\": \"Entrega\" }\n```\n\n## Lógica de execução das regras e casos de uso\n\nApós o pré‑processamento, o agente percorre as regras definidas no YAML em ordem. A primeira regra cujo método `execute` retornar `True` será executada, e as demais são ignoradas. Portanto, é importante organizar as regras de forma hierárquica e garantir que o pré‑processamento retorne dados suficientes para as condições de cada regra. Casos de uso comuns incluem notificações de pedidos (aprovados, faturados, cancelados, criados), mas você pode criar regras para qualquer evento relevante dentro da VTEX ou do seu fluxo de negócios.\n\n## Conclusão\n\nAgentes ativos permitem automatizar notificações e interações com seus clientes com base em eventos da VTEX. Ao estruturar seu projeto conforme este guia — definindo claramente o YAML, o pré‑processamento e as regras — você garante uma integração segura e escalável entre Weni e VTEX para informar seus clientes no momento certo.\n\n> [Aqui](https://github.com/weni-ai/weni-active-agents-example) você encontrará um exemplo de código de agente ativo."}