atendentepro 0.3.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

atendentepro/README.md

@@ -77,8 +77,119 @@ if is_activated():
 ### Obter um Token
 
 Entre em contato para obter seu token de licença:
-- 📧 **Email:** contato@bemonkai.com
-- 🌐 **Site:** https://bemonkai.com
+- 📧 **Email:** contato@monkai.com.br
+- 🌐 **Site:** https://www.monkai.com.br
+
+---
+
+## 🔐 Configurar API Key do OpenAI/Azure
+
+A biblioteca precisa de uma chave de API para funcionar. Existem várias formas de configurar:
+
+### Opção 1: Variáveis de Ambiente (Recomendado)
+
+```bash
+# Criar arquivo .env na raiz do projeto
+ATENDENTEPRO_LICENSE_KEY=ATP_seu-token
+OPENAI_API_KEY=sk-sua-chave-openai
+```
+
+```python
+from dotenv import load_dotenv
+load_dotenv()  # Carrega o .env
+
+from atendentepro import create_standard_network
+# ✅ API key carregada automaticamente!
+```
+
+### Opção 2: Função `configure()`
+
+```python
+from atendentepro import activate, configure, create_standard_network
+
+# 1. Ativar licença
+activate("ATP_seu-token")
+
+# 2. Configurar API key programaticamente
+configure(
+    openai_api_key="sk-sua-chave-openai",
+    default_model="gpt-4o-mini"  # Opcional: mudar modelo padrão
+)
+
+# 3. Usar normalmente
+network = create_standard_network(...)
+```
+
+### Opção 3: Configuração Completa com `AtendentProConfig`
+
+```python
+from atendentepro import activate, configure, AtendentProConfig
+
+activate("ATP_seu-token")
+
+# Configuração detalhada
+config = AtendentProConfig(
+    provider="openai",
+    openai_api_key="sk-sua-chave-openai",
+    default_model="gpt-4o",
+)
+
+configure(config)
+```
+
+### Opção 4: Configurar Azure OpenAI
+
+```python
+from atendentepro import activate, configure, AtendentProConfig
+
+activate("ATP_seu-token")
+
+config = AtendentProConfig(
+    provider="azure",
+    azure_api_key="sua-chave-azure",
+    azure_api_endpoint="https://seu-recurso.openai.azure.com",
+    azure_api_version="2024-02-15-preview",
+    azure_deployment_name="gpt-4o",  # Nome do deployment
+)
+
+configure(config)
+```
+
+### Opção 5: Variáveis de Ambiente para Azure
+
+```bash
+# .env
+ATENDENTEPRO_LICENSE_KEY=ATP_seu-token
+OPENAI_PROVIDER=azure
+AZURE_API_KEY=sua-chave-azure
+AZURE_API_ENDPOINT=https://seu-recurso.openai.azure.com
+AZURE_API_VERSION=2024-02-15-preview
+AZURE_DEPLOYMENT_NAME=gpt-4o
+```
+
+### Verificar Configuração Atual
+
+```python
+from atendentepro import get_config
+
+config = get_config()
+print(f"Provider: {config.provider}")
+print(f"Model: {config.default_model}")
+print(f"API Key configurada: {'Sim' if config.openai_api_key else 'Não'}")
+```
+
+### Tabela de Variáveis de Ambiente
+
+| Variável | Descrição | Obrigatório |
+|----------|-----------|-------------|
+| `ATENDENTEPRO_LICENSE_KEY` | Token de licença | ✅ Sim |
+| `OPENAI_API_KEY` | Chave API OpenAI | ✅ (se OpenAI) |
+| `OPENAI_PROVIDER` | `openai` ou `azure` | Não (padrão: openai) |
+| `DEFAULT_MODEL` | Modelo padrão | Não (padrão: gpt-4.1) |
+| `AZURE_API_KEY` | Chave API Azure | ✅ (se Azure) |
+| `AZURE_API_ENDPOINT` | Endpoint Azure | ✅ (se Azure) |
+| `AZURE_API_VERSION` | Versão API Azure | ✅ (se Azure) |
+| `AZURE_DEPLOYMENT_NAME` | Nome do deployment | Não |
 
 ---
 
@@ -138,44 +249,50 @@ asyncio.run(main())
 Imagine o **AtendentePro** como um **restaurante sofisticado** onde cada funcionário tem uma função específica:
 
 ```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                    🍽️  RESTAURANTE ATENDENTEPRO                        │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                         │
-│   👤 CLIENTE chega e é recebido pelo:                                  │
-│                                                                         │
-│   🚪 RECEPCIONISTA (Triage Agent)                                      │
-│      └─ "Boa noite! Você quer jantar, fazer reserva ou tirar dúvida?"  │
-│         Ele IDENTIFICA a intenção e DIRECIONA para o setor certo.      │
-│                                                                         │
-│   ┌────────────────┬────────────────┬────────────────┬───────────────┐ │
-│   │                │                │                │               │ │
-│   ▼                ▼                ▼                ▼               ▼ │
-│                                                                         │
-│   📋 MAITRE        📚 SOMMELIER     ✅ CONFIRMA      ❓ CONCIERGE     │
-│   (Flow Agent)     (Knowledge)      (Confirmation)   (Usage)          │
-│   "Temos 3        "Nosso vinho     "Confirma a     "Deixa eu         │
-│   opções de       premiado é       reserva para    te explicar       │
-│   menu hoje"      o Malbec 2019"   2 pessoas?"     como funciona"    │
-│                                                                         │
-│   │                                                                     │
-│   ▼                                                                     │
-│                                                                         │
-│   📝 GARÇOM (Interview Agent)                                          │
-│      └─ Coleta as informações: "Quantas pessoas? Alguma alergia?"      │
-│                                                                         │
-│   │                                                                     │
-│   ▼                                                                     │
-│                                                                         │
-│   🍳 CHEF (Answer Agent)                                               │
-│      └─ Prepara a resposta final com todas as informações              │
-│                                                                         │
-│   │                                                                     │
-│   ▼                                                                     │
-│                                                                         │
-│   🎉 PRATO ENTREGUE (Resposta ao usuário)                              │
-│                                                                         │
-└─────────────────────────────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                       🍽️  RESTAURANTE ATENDENTEPRO                           │
+├──────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   👤 CLIENTE chega e é recebido pelo:                                       │
+│                                                                              │
+│   🚪 RECEPCIONISTA (Triage Agent)                                           │
+│      └─ "Boa noite! Você quer jantar, fazer reserva ou tirar dúvida?"       │
+│         Ele IDENTIFICA a intenção e DIRECIONA para o setor certo.           │
+│                                                                              │
+│   ┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐       │
+│   │          │          │          │          │          │          │       │
+│   ▼          ▼          ▼          ▼          ▼          ▼          ▼       │
+│                                                                              │
+│   📋 MAITRE  📚 SOMME   ✅ CONFIRMA ❓ CONCI   📞 GERENTE 📝 SUGEST  🆕 VIP  │
+│   (Flow)     (Knowledge) (Confirm)  (Usage)   (Escalat)  (Feedback) (Onb.)  │
+│   "3 opções" "Malbec     "Confirma  "Deixa eu "Chamo o   "Quer      "Novo   │
+│              2019"       2 pessoas?" explicar" gerente"  registrar?" aqui?"  │
+│                                                                              │
+│   │                                                                          │
+│   ▼                                                                          │
+│                                                                              │
+│   📝 GARÇOM (Interview Agent)                                               │
+│      └─ Coleta as informações: "Quantas pessoas? Alguma alergia?"           │
+│                                                                              │
+│   │                                                                          │
+│   ▼                                                                          │
+│                                                                              │
+│   🍳 CHEF (Answer Agent)                                                    │
+│      └─ Prepara a resposta final com todas as informações                   │
+│                                                                              │
+│   │                                                                          │
+│   ▼                                                                          │
+│                                                                              │
+│   🎉 PRATO ENTREGUE (Resposta ao usuário)                                   │
+│                                                                              │
+│ ═══════════════════════════════════════════════════════════════════════════ │
+│                                                                              │
+│   📞 GERENTE (Escalation) ──► Transfere para atendimento humano IMEDIATO    │
+│   📝 SUGESTÕES (Feedback) ──► Registra reclamações/sugestões para DEPOIS    │
+│                                                                              │
+│   💡 Qualquer agente pode chamar o Gerente ou enviar para Sugestões!        │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 **Traduzindo para o código:**
@@ -190,6 +307,8 @@ Imagine o **AtendentePro** como um **restaurante sofisticado** onde cada funcion
 | ✅ Confirmador | **Confirmation Agent** | Valida com sim/não |
 | ❓ Concierge | **Usage Agent** | Explica como funciona |
 | 🆕 Recepção VIP | **Onboarding Agent** | Cadastra novos clientes |
+| 📞 Gerente | **Escalation Agent** | Chama o gerente quando precisa |
+| 📝 Caixa de Sugestões | **Feedback Agent** | Registra elogios, reclamações e sugestões |
 | 🚫 Segurança | **Guardrails** | Define o que pode/não pode ser feito |
 | 📖 Menu/Cardápio | **YAML Configs** | Configurações de cada "funcionário" |
 
@@ -262,6 +381,8 @@ flowchart TB
         CONFIRMATION["Confirmation Agent<br/>Validacao"]
         USAGE["Usage Agent<br/>Ajuda"]
         ONBOARDING["Onboarding Agent<br/>Cadastro"]
+        ESCALATION["Escalation Agent<br/>Transfer. humana"]
+        FEEDBACK["Feedback Agent<br/>Tickets/SAC"]
     end
 
     subgraph TOOLS["TOOLS"]
@@ -317,15 +438,19 @@ flowchart LR
     C["Confirmation"]
     U["Usage"]
     O["Onboarding"]
+    E["Escalation"]
+    FB["Feedback"]
     
-    T --> F & K & C & U & O
-    F --> I & T
-    I --> A
-    A --> T & I
-    K --> T
-    C --> T
-    U --> T
-    O --> T
+    T --> F & K & C & U & O & E & FB
+    F --> I & T & E & FB
+    I --> A & E & FB
+    A --> T & I & E & FB
+    K --> T & E & FB
+    C --> T & E & FB
+    U --> T & E & FB
+    O --> T & E & FB
+    E --> T & FB
+    FB --> T & E
 ```
 
 ### Estrutura de Componentes
@@ -417,6 +542,8 @@ client_templates/
 | **Confirmation** | Valida hipóteses com respostas sim/não |
 | **Usage** | Responde dúvidas sobre uso do sistema |
 | **Onboarding** | Acolhe novos usuários e guia cadastro |
+| **Escalation** | Transfere para atendimento humano quando necessário |
+| **Feedback** | Registra dúvidas, feedbacks, reclamações e sugestões |
 
 ---
 
@@ -427,6 +554,7 @@ from atendentepro import (
     create_triage_agent,
     create_flow_agent,
     create_interview_agent,
+    create_escalation_agent,
 )
 
 # Criar agente de triagem customizado
@@ -440,8 +568,23 @@ flow = create_flow_agent(
     flow_keywords="- Vendas: 'preço'\n- Suporte: 'erro'",
 )
 
-# Configurar handoffs
-triage.handoffs = [flow]
+# Criar agente de escalação para transferência humana
+escalation = create_escalation_agent(
+    escalation_channels="Telefone: 0800-123-456 (Seg-Sex 8h-18h)",
+)
+
+# Criar agente de feedback para registrar tickets
+feedback = create_feedback_agent(
+    protocol_prefix="SAC",
+    email_brand_color="#660099",
+    email_brand_name="Minha Empresa",
+)
+
+# Configurar handoffs (todos podem escalar ou registrar feedback)
+triage.handoffs = [flow, escalation, feedback]
+flow.handoffs = [triage, escalation, feedback]
+escalation.handoffs = [triage, feedback]
+feedback.handoffs = [triage, escalation]
 ```
 
 ---
@@ -456,12 +599,15 @@ mkdir -p client_templates/meu_cliente
 
 ### Passo 2: Criar os Arquivos de Configuração YAML
 
-Copie do `standard/` e customize:
+Copie do template `standard/` (localizado em `templates/standard/`) e customize:
 
 ```bash
-cp client_templates/standard/*.yaml client_templates/meu_cliente/
+cp templates/standard/*.yaml client_templates/meu_cliente/
 ```
 
+> **Nota:** O template `standard` está em `templates/standard/` e serve como exemplo genérico.
+> Suas configurações de cliente devem ficar em `client_templates/`.
+
 ### Passo 3: Configurar o Triage (triage_config.yaml)
 
 Define as palavras-chave para identificar a intenção do usuário:
@@ -640,7 +786,412 @@ def buscar_produto(codigo: str = "", nome: str = "") -> str:
     return "\n".join([f"- {r['nome']} (Cód: {r['codigo']})" for r in resultados])
 ```
 
-### Passo 9: Criar Rede Específica (Opcional)
+### Passo 9: Configurar Escalation (Opcional - escalation_config.yaml)
+
+O **Escalation Agent** permite transferir para atendimento humano quando:
+- O usuário solicita explicitamente ("quero falar com um humano")
+- O tópico não é coberto pelo sistema
+- O agente não consegue resolver após múltiplas tentativas
+- O usuário demonstra frustração
+
+#### Configuração YAML Completa
+
+```yaml
+# escalation_config.yaml
+name: "Escalation Agent"
+
+description: >
+  Transfere para atendimento humano quando necessário.
+
+# =============================================================================
+# Triggers - Situações que ativam a escalação
+# =============================================================================
+triggers:
+  # Quando o usuário pede explicitamente
+  explicit_request:
+    - "quero falar com um humano"
+    - "atendente humano"
+    - "falar com uma pessoa"
+    - "transferir para atendimento"
+    - "pessoa de verdade"
+  
+  # Indicadores de frustração
+  frustration:
+    - "você não está me ajudando"
+    - "isso não resolve"
+    - "já tentei isso"
+    - "não funciona"
+    - "estou perdendo tempo"
+  
+  # Tópicos que requerem humano
+  topics_requiring_human:
+    - "questão jurídica"
+    - "cancelar contrato"
+    - "dados pessoais"
+    - "LGPD"
+    - "emergência"
+
+# =============================================================================
+# Canais de Atendimento
+# =============================================================================
+channels:
+  phone:
+    enabled: true
+    number: "0800-123-4567"
+    description: "Telefone"
+    hours: "Seg-Sex 8h-18h"
+  
+  email:
+    enabled: true
+    address: "atendimento@empresa.com"
+    description: "Email"
+    sla: "Resposta em até 24h úteis"
+  
+  whatsapp:
+    enabled: true
+    number: "(11) 99999-9999"
+    description: "WhatsApp"
+    hours: "Seg-Sex 9h-18h"
+  
+  chat:
+    enabled: false
+    url: ""
+    description: "Chat ao vivo"
+
+# =============================================================================
+# Horário de Atendimento
+# =============================================================================
+business_hours:
+  start: 8
+  end: 18
+  days:
+    - monday
+    - tuesday
+    - wednesday
+    - thursday
+    - friday
+  timezone: "America/Sao_Paulo"
+
+# =============================================================================
+# Classificação de Prioridade Automática
+# =============================================================================
+priority:
+  urgent:
+    - "urgente"
+    - "emergência"
+    - "crítico"
+    - "bloqueado"
+  high:
+    - "reclamação"
+    - "insatisfeito"
+    - "problema grave"
+  default: "normal"
+
+# =============================================================================
+# Notificações
+# =============================================================================
+notifications:
+  webhook:
+    enabled: false
+    url: ""  # Configure via ESCALATION_WEBHOOK_URL
+  email_team:
+    enabled: true
+    recipients:
+      - "equipe@empresa.com"
+
+# =============================================================================
+# Mensagens Customizadas
+# =============================================================================
+messages:
+  greeting: >
+    Entendo que você precisa de um atendimento mais especializado.
+    Vou transferir para um de nossos atendentes.
+  
+  collecting_info: >
+    Para agilizar o atendimento, preciso de algumas informações.
+  
+  confirmation: >
+    Pronto! Um atendente humano entrará em contato em breve.
+    Guarde o protocolo para acompanhamento.
+  
+  out_of_hours: >
+    Nosso atendimento humano funciona de Segunda a Sexta, das 8h às 18h.
+    Você pode deixar seus dados que retornaremos no próximo dia útil.
+  
+  apology: >
+    Peço desculpas se não consegui resolver sua questão.
+    Um atendente especializado poderá ajudá-lo melhor.
+```
+
+#### Variáveis de Ambiente para Escalation
+
+| Variável | Descrição |
+|----------|-----------|
+| `ESCALATION_WEBHOOK_URL` | URL para notificar sistemas externos (Slack, Teams) |
+| `ESCALATION_HOUR_START` | Hora de início do atendimento (padrão: 8) |
+| `ESCALATION_HOUR_END` | Hora de fim do atendimento (padrão: 18) |
+
+#### Uso Programático
+
+```python
+# Com configuração via parâmetros
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    include_escalation=True,
+    escalation_channels="""
+📞 **Telefone:** 0800-123-4567 (Seg-Sex 8h-18h)
+📧 **Email:** atendimento@empresa.com
+💬 **WhatsApp:** (11) 99999-9999
+""",
+)
+
+# Sem escalação
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    include_escalation=False,
+)
+
+# Criar agente standalone
+from atendentepro import create_escalation_agent
+
+escalation = create_escalation_agent(
+    escalation_channels="Telefone: 0800-123-4567",
+    name="Suporte Humano",
+)
+```
+
+### Passo 10: Configurar Feedback (Opcional - feedback_config.yaml)
+
+O **Feedback Agent** permite registrar:
+- ❓ **Dúvidas** que precisam de pesquisa
+- 💬 **Feedbacks** sobre produtos/serviços
+- 📢 **Reclamações** formais
+- 💡 **Sugestões** de melhoria
+- ⭐ **Elogios** e agradecimentos
+- ⚠️ **Problemas** técnicos
+
+#### Configuração YAML Completa
+
+```yaml
+# feedback_config.yaml
+name: "Feedback Agent"
+
+description: >
+  Registra dúvidas, feedbacks, reclamações, sugestões e elogios
+  através de tickets com protocolo de acompanhamento.
+
+# =============================================================================
+# Configuração de Protocolo
+# =============================================================================
+
+# Prefixo do protocolo (ex: SAC-20240106-ABC123, TKT-20240106-XYZ789)
+protocol_prefix: "SAC"
+
+# =============================================================================
+# Tipos de Ticket Habilitados
+# =============================================================================
+ticket_types:
+  - name: "duvida"
+    label: "Dúvida"
+    icon: "❓"
+    description: "Pergunta que precisa de pesquisa ou análise"
+    default_priority: "normal"
+  
+  - name: "feedback"
+    label: "Feedback"
+    icon: "💬"
+    description: "Opinião sobre produto ou serviço"
+    default_priority: "normal"
+  
+  - name: "reclamacao"
+    label: "Reclamação"
+    icon: "📢"
+    description: "Reclamação formal"
+    default_priority: "alta"
+  
+  - name: "sugestao"
+    label: "Sugestão"
+    icon: "💡"
+    description: "Sugestão de melhoria"
+    default_priority: "baixa"
+  
+  - name: "elogio"
+    label: "Elogio"
+    icon: "⭐"
+    description: "Elogio ou agradecimento"
+    default_priority: "baixa"
+  
+  - name: "problema"
+    label: "Problema"
+    icon: "⚠️"
+    description: "Problema técnico ou bug"
+    default_priority: "alta"
+
+# =============================================================================
+# Níveis de Prioridade
+# =============================================================================
+priorities:
+  - name: "baixa"
+    label: "Baixa"
+    icon: "🟢"
+    sla_hours: 72
+    description: "Pode aguardar alguns dias"
+  
+  - name: "normal"
+    label: "Normal"
+    icon: "🟡"
+    sla_hours: 24
+    description: "Atendimento padrão"
+  
+  - name: "alta"
+    label: "Alta"
+    icon: "🟠"
+    sla_hours: 8
+    description: "Requer atenção prioritária"
+  
+  - name: "urgente"
+    label: "Urgente"
+    icon: "🔴"
+    sla_hours: 2
+    description: "Crítico, ação imediata"
+
+# =============================================================================
+# Categorias (opcional)
+# =============================================================================
+categories:
+  - "Produto"
+  - "Serviço"
+  - "Atendimento"
+  - "Sistema"
+  - "Financeiro"
+  - "Outro"
+
+# =============================================================================
+# Configuração de Email
+# =============================================================================
+email:
+  enabled: true
+  brand_color: "#660099"           # Cor da marca (hexadecimal)
+  brand_name: "Minha Empresa"      # Nome no email
+  sla_message: "Retornaremos em até 24h úteis."
+  notify_team: true                # Enviar cópia para equipe
+
+# =============================================================================
+# Mensagens Customizadas
+# =============================================================================
+messages:
+  greeting: >
+    Posso ajudá-lo a registrar sua solicitação.
+    Qual tipo de ticket você gostaria de abrir?
+  
+  confirmation: >
+    Seu chamado foi registrado com sucesso!
+    Guarde o protocolo para acompanhamento.
+  
+  email_sent: >
+    Enviamos um email de confirmação para você.
+  
+  validation_error_email: >
+    Por favor, informe um email válido para que possamos responder.
+
+# =============================================================================
+# Campos Obrigatórios vs Opcionais
+# =============================================================================
+fields:
+  required:
+    - tipo
+    - descricao
+    - email_usuario
+  optional:
+    - nome_usuario
+    - telefone_usuario
+    - prioridade
+    - categoria
+
+# =============================================================================
+# Regras de Priorização Automática
+# =============================================================================
+auto_priority:
+  urgent:
+    - "urgente"
+    - "emergência"
+    - "parou de funcionar"
+  high:
+    - "reclamação"
+    - "problema grave"
+    - "prejuízo"
+  high_priority_types:
+    - "reclamacao"
+    - "problema"
+```
+
+#### Variáveis de Ambiente para Feedback
+
+| Variável | Descrição |
+|----------|-----------|
+| `SMTP_HOST` | Servidor SMTP (padrão: smtp.gmail.com) |
+| `SMTP_PORT` | Porta SMTP (padrão: 587) |
+| `SMTP_USER` | Usuário SMTP |
+| `SMTP_PASSWORD` | Senha SMTP |
+| `SMTP_FROM` | Email remetente |
+| `FEEDBACK_EMAIL_DESTINO` | Email da equipe para receber notificações |
+
+#### Uso Programático
+
+```python
+# Com configuração via parâmetros
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    include_feedback=True,
+    feedback_protocol_prefix="SAC",
+    feedback_brand_color="#660099",
+    feedback_brand_name="Minha Empresa",
+)
+
+# Sem feedback
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    include_feedback=False,
+)
+
+# Criar agente standalone
+from atendentepro import create_feedback_agent
+
+feedback = create_feedback_agent(
+    protocol_prefix="SAC",
+    email_brand_color="#660099",
+    email_brand_name="Minha Empresa",
+    email_sla_message="Retornaremos em até 24h úteis.",
+    name="SAC",
+)
+```
+
+---
+
+### Diferença entre Escalation e Feedback
+
+| Aspecto | Escalation | Feedback |
+|---------|------------|----------|
+| **Propósito** | Transferir para humano **agora** | Registrar para resposta **posterior** |
+| **Urgência** | Imediata | Pode aguardar |
+| **Canal** | Telefone, chat ao vivo | Email, ticket |
+| **Protocolo** | ESC-YYYYMMDD-XXXXXX | TKT/SAC-YYYYMMDD-XXXXXX |
+| **Quando usar** | "Quero falar com alguém" | "Tenho uma dúvida/sugestão" |
+| **Horário** | Respeita horário comercial | 24/7 (registro) |
+
+```mermaid
+flowchart LR
+    USER[Usuário] --> |"Problema urgente<br/>Falar com humano"| ESC[Escalation Agent]
+    USER --> |"Dúvida, sugestão<br/>Feedback"| FEED[Feedback Agent]
+    ESC --> |Protocolo ESC| HUMANO[Atendente Humano]
+    FEED --> |Protocolo TKT| EMAIL[Email + Ticket]
+```
+
+### Passo 11: Criar Rede Específica (Opcional)
 
 Se precisar de lógica customizada:
 
@@ -719,26 +1270,47 @@ network = create_meu_cliente_network(
 
 ```
 client_templates/meu_cliente/
-├── __init__.py              # (Opcional) Pacote Python
-├── network.py               # (Opcional) Rede específica
-├── tools.py                 # (Opcional) Tools customizadas
-├── triage_config.yaml       # ✅ Obrigatório
-├── flow_config.yaml         # ✅ Recomendado
-├── interview_config.yaml    # ✅ Recomendado
-├── answer_config.yaml       # Opcional
-├── knowledge_config.yaml    # Opcional
-├── confirmation_config.yaml # Opcional
-├── onboarding_config.yaml   # Opcional
-├── guardrails_config.yaml   # ✅ Recomendado
-├── data/                    # Opcional (dados estruturados)
+├── __init__.py                # (Opcional) Pacote Python
+├── network.py                 # (Opcional) Rede específica
+├── tools.py                   # (Opcional) Tools customizadas
+│
+│   # Configurações de Agentes (YAML)
+├── triage_config.yaml         # ✅ Obrigatório - Classificação inicial
+├── flow_config.yaml           # ✅ Recomendado - Opções/menu
+├── interview_config.yaml      # ✅ Recomendado - Coleta de dados
+├── answer_config.yaml         # Opcional - Resposta final
+├── knowledge_config.yaml      # Opcional - Base de conhecimento
+├── confirmation_config.yaml   # Opcional - Validação sim/não
+├── onboarding_config.yaml     # Opcional - Cadastro novos usuários
+├── escalation_config.yaml     # ✅ Recomendado - Transferência humana
+├── feedback_config.yaml       # ✅ Recomendado - Tickets/SAC
+├── guardrails_config.yaml     # ✅ Recomendado - Políticas de segurança
+│
+│   # Dados (opcionais)
+├── data/                      # Dados estruturados
 │   └── produtos.csv
-└── knowledge_documentos/    # Opcional (RAG)
+└── knowledge_documentos/      # Documentos para RAG
     ├── docs/
     │   └── manual.pdf
     └── embedding/
         └── embeddings.pkl
 ```
 
+#### Arquivos YAML por Agente
+
+| Arquivo | Agente | Obrigatório | Descrição |
+|---------|--------|-------------|-----------|
+| `triage_config.yaml` | Triage | ✅ Sim | Keywords para classificação |
+| `flow_config.yaml` | Flow | Recomendado | Opções de menu/tópicos |
+| `interview_config.yaml` | Interview | Recomendado | Perguntas para coleta |
+| `answer_config.yaml` | Answer | Opcional | Template de resposta |
+| `knowledge_config.yaml` | Knowledge | Opcional | Docs RAG + fontes dados |
+| `confirmation_config.yaml` | Confirmation | Opcional | Validação de hipóteses |
+| `onboarding_config.yaml` | Onboarding | Opcional | Campos de cadastro |
+| `escalation_config.yaml` | Escalation | Recomendado | Canais e triggers |
+| `feedback_config.yaml` | Feedback | Recomendado | Tipos ticket e email |
+| `guardrails_config.yaml` | Todos | Recomendado | Escopo e restrições |
+
 ---
 
 ## 🌐 Redes Pré-configuradas
@@ -754,14 +1326,19 @@ network = create_standard_network(
 )
 ```
 
-Configuração padrão de handoffs:
-- Triage → Flow, Confirmation, Knowledge, Usage
-- Flow → Interview, Triage
-- Interview → Answer
-- Answer → Triage, Interview
-- Confirmation → Triage
-- Knowledge → Triage
-- Usage → Triage
+Configuração padrão de handoffs (com Escalation e Feedback habilitados):
+- Triage → Flow, Confirmation, Knowledge, Usage, Onboarding, **Escalation**, **Feedback**
+- Flow → Interview, Triage, **Escalation**, **Feedback**
+- Interview → Answer, **Escalation**, **Feedback**
+- Answer → Triage, **Escalation**, **Feedback**
+- Confirmation → Triage, **Escalation**, **Feedback**
+- Knowledge → Triage, **Escalation**, **Feedback**
+- Usage → Triage, **Escalation**, **Feedback**
+- Onboarding → Triage, **Escalation**, **Feedback**
+- **Escalation → Triage, Feedback**
+- **Feedback → Triage, Escalation**
+
+> 💡 **Todos os agentes** podem escalar para atendimento humano ou registrar feedback!
 
 ### Rede Customizada