atendentepro 0.7.0

Framework de orquestração de agentes IA com tom e estilo customizáveis. Integra documentos (RAG), APIs e bancos de dados em uma plataforma inteligente multi-agente.

AtendentePro

Framework de orquestração de agentes IA para interações complexas

Plataforma que unifica múltiplos agentes especializados para resolver demandas que envolvem diferentes fontes de dados, sistemas e fluxos de decisão — tudo orquestrado em um único lugar. Baseado no OpenAI Agents SDK.

Principais Capacidades

Capacidade	Descrição
Classificação Inteligente	Identifica a intenção e direciona para o agente especializado
Integração de Dados	Conecta documentos (RAG), CSVs, bancos de dados SQL e APIs externas
Orquestração de Fluxos	Handoffs automáticos entre agentes conforme a complexidade da demanda
Tom e Estilo Customizáveis	AgentStyle para personalizar linguagem, tom e formato de respostas
Escalonamento Controlado	Transferência para atendimento humano com contexto preservado
Gestão de Feedbacks	Sistema de tickets para reclamações, sugestões e acompanhamento
Configuração Declarativa	Personalização completa via arquivos YAML
Tuning (Post-Training)	Melhoria dos YAMLs com base em feedback e conversas (módulo opcional)
Memória de contexto longo	GRKMemory para buscar e injetar memórias e persistir turnos (módulo opcional)

---

📋 Índice

• Instalação
• Ativação (Licença)
• Configurar API Key
• Início Rápido
• Arquitetura
• Agentes Disponíveis
• Criar Templates Customizados
• Configurações YAML
• Escalation Agent
• Feedback Agent
• Fluxo de Handoffs
• Estilo de Comunicação
• Single Reply Mode
• Filtros de Acesso
• Carregamento de Usuários
• Múltiplos Agentes
• Tracing e Monitoramento
• Tuning (Post-Training)
• Memória de contexto longo (GRKMemory)
• Segurança em Produção
• Suporte

---

📦 Instalação

# Via PyPI
pip install atendentepro

# Com monitoramento (recomendado)
pip install atendentepro[tracing]

---

🔑 Ativação (Licença)

A biblioteca requer um token de licença para funcionar.

Opção 1: Variável de Ambiente (Recomendado)

export ATENDENTEPRO_LICENSE_KEY="ATP_seu-token-aqui"

Opção 2: Via Código

from atendentepro import activate

activate("ATP_seu-token-aqui")

Opção 3: Arquivo .env

ATENDENTEPRO_LICENSE_KEY=ATP_seu-token-aqui
OPENAI_API_KEY=sk-sua-chave-openai

Obter um Token

Entre em contato para obter seu token:

• 📧 Email: [e-mail]
• 🌐 Site: https://www.monkai.com.br

---

🔐 Configurar API Key

OpenAI

# .env
OPENAI_API_KEY=sk-sua-chave-openai

Azure OpenAI

# .env
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

Via Código

from atendentepro import activate, configure

activate("ATP_seu-token")

configure(
    openai_api_key="sk-sua-chave-openai",
    default_model="gpt-4o-mini"
)

---

⚡ Início Rápido

import asyncio
from pathlib import Path
from atendentepro import activate, create_standard_network
from agents import Runner

# 1. Ativar
activate("ATP_seu-token")

async def main():
    # 2. Criar rede de agentes
    network = create_standard_network(
        templates_root=Path("./meu_cliente"),
        client="config"
    )
    
    # 3. Executar conversa
    result = await Runner.run(
        network.triage,
        [{"role": "user", "content": "Olá, preciso de ajuda"}]
    )
    
    print(result.final_output)

asyncio.run(main())

---

🏗️ Arquitetura

┌────────────────────────────────────────────────────────────────────────────┐
│                              ATENDENTEPRO                                  │
├────────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│   👤 Usuário                                                               │
│       │                                                                    │
│       ▼                                                                    │
│   ┌─────────────┐                                                         │
│   │   Triage    │──► Classifica intenção do usuário                       │
│   └─────────────┘                                                         │
│         │                                                                  │
│    ┌────┴────┬─────────┬─────────┬─────────┬─────────┬─────────┐          │
│    ▼         ▼         ▼         ▼         ▼         ▼         ▼          │
│ ┌──────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐     │
│ │ Flow │ │Knowl. │ │Confirm│ │ Usage │ │Onboard│ │Escala.│ │Feedbk.│     │
│ └──────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘     │
│    │                                                                       │
│    ▼                                                                       │
│ ┌─────────────┐                                                           │
│ │  Interview  │──► Coleta informações estruturadas                        │
│ └─────────────┘                                                           │
│       │                                                                    │
│       ▼                                                                    │
│ ┌─────────────┐                                                           │
│ │   Answer    │──► Sintetiza resposta final                               │
│ └─────────────┘                                                           │
│                                                                            │
│ ══════════════════════════════════════════════════════════════════════    │
│  📞 Escalation → Transfere para atendimento humano IMEDIATO               │
│  📝 Feedback   → Registra tickets para resposta POSTERIOR                 │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘

---

🤖 Agentes Disponíveis

Agente	Descrição	Quando Usar
Triage	Classifica intenção e direciona	Sempre (ponto de entrada)
Flow	Apresenta opções/menu ao usuário	Múltiplas opções disponíveis
Interview	Coleta informações através de perguntas	Precisa de dados do usuário
Answer	Sintetiza resposta final	Após coletar informações
Knowledge	Consulta RAG e dados estruturados	Perguntas sobre documentos/dados
Confirmation	Valida com respostas sim/não	Confirmar ações
Usage	Responde dúvidas sobre o sistema	"Como funciona?"
Onboarding	Cadastro de novos usuários	Novos usuários
Escalation	Transfere para humano	Urgente/não resolvido
Feedback	Registra tickets	Dúvidas/reclamações/sugestões

---

📁 Criar Templates Customizados

Estrutura de Pastas

meu_cliente/
├── triage_config.yaml       # ✅ Obrigatório
├── flow_config.yaml         # Recomendado
├── interview_config.yaml    # Recomendado
├── answer_config.yaml       # Opcional
├── knowledge_config.yaml    # Opcional
├── escalation_config.yaml   # Recomendado
├── feedback_config.yaml     # Recomendado
├── guardrails_config.yaml   # Recomendado
├── style_config.yaml        # Opcional - Tom e estilo
└── data/                    # Dados estruturados (CSV, etc.)

Usar o Template

from pathlib import Path
from atendentepro import create_standard_network

network = create_standard_network(
    templates_root=Path("./"),
    client="meu_cliente",
    include_escalation=True,
    include_feedback=True,
)

---

⚙️ Configurações YAML

triage_config.yaml (Obrigatório)

Define palavras-chave para classificação:

agent_name: "Triage Agent"

keywords:
  - agent: "Flow Agent"
    keywords:
      - "produto"
      - "serviço"
      - "preço"
  
  - agent: "Knowledge Agent"
    keywords:
      - "documentação"
      - "manual"
      - "como funciona"
  
  - agent: "Escalation Agent"
    keywords:
      - "falar com humano"
      - "atendente"

flow_config.yaml

Define opções/menu:

agent_name: "Flow Agent"

topics:
  - id: 1
    label: "Vendas"
    keywords: ["comprar", "preço", "orçamento"]
    
  - id: 2
    label: "Suporte"
    keywords: ["problema", "erro", "ajuda"]
    
  - id: 3
    label: "Financeiro"
    keywords: ["pagamento", "boleto", "fatura"]

answer_config.yaml (Opcional)

Define o template de resposta final do Answer Agent:

agent_name: "Answer Agent"

answer_template: |
  Com base nas informações coletadas, prepare uma resposta clara e objetiva.
  Inclua um resumo do que foi solicitado e os próximos passos.

interview_config.yaml

Define perguntas para coleta:

agent_name: "Interview Agent"

interview_questions: |
  Para cada tópico, faça as seguintes perguntas:
  
  ## Vendas
  1. Qual produto você tem interesse?
  2. Qual quantidade desejada?
  3. Qual seu email para contato?
  
  ## Suporte
  1. Descreva o problema
  2. Quando começou?
  3. Já tentou alguma solução?

guardrails_config.yaml

Define escopo e restrições:

scope: |
  Este assistente pode ajudar com:
  - Informações sobre produtos
  - Suporte técnico
  - Dúvidas sobre serviços

forbidden_topics:
  - "política"
  - "religião"
  - "conteúdo adulto"

out_of_scope_message: |
  Desculpe, não posso ajudar com esse assunto.
  Posso ajudar com produtos, suporte ou serviços.

---

📞 Escalation Agent

Transfere para atendimento humano quando:

• Usuário solicita explicitamente
• Tópico não coberto pelo sistema
• Usuário demonstra frustração
• Agente não consegue resolver

escalation_config.yaml

name: "Escalation Agent"

triggers:
  explicit_request:
    - "quero falar com um humano"
    - "atendente humano"
    - "falar com uma pessoa"
  
  frustration:
    - "você não está me ajudando"
    - "isso não resolve"

channels:
  phone:
    enabled: true
    number: "0800-123-4567"
    hours: "Seg-Sex 8h-18h"
  
  email:
    enabled: true
    address: "[e-mail]"
    sla: "Resposta em até 24h"
  
  whatsapp:
    enabled: true
    number: "(11) 99999-9999"

business_hours:
  start: 8
  end: 18
  days: [monday, tuesday, wednesday, thursday, friday]

messages:
  greeting: "Entendo que você precisa de um atendimento especializado."
  out_of_hours: "Nosso atendimento funciona de Seg-Sex, 8h-18h."

Usar Escalation

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    include_escalation=True,
    escalation_channels="""
📞 Telefone: 0800-123-4567 (Seg-Sex 8h-18h)
📧 Email: [e-mail]
💬 WhatsApp: [phone]
""",
)

---

📝 Feedback Agent

Registra tickets para:

• ❓ Dúvidas - Perguntas que precisam de pesquisa
• 💬 Feedback - Opinião sobre produto/serviço
• 📢 Reclamação - Insatisfação formal (prioridade alta)
• 💡 Sugestão - Ideia de melhoria
• ⭐ Elogio - Agradecimento
• ⚠️ Problema - Bug/erro técnico (prioridade alta)

feedback_config.yaml

name: "Feedback Agent"

protocol_prefix: "SAC"  # Formato: SAC-20240106-ABC123

ticket_types:
  - name: "duvida"
    label: "Dúvida"
    default_priority: "normal"
    
  - name: "reclamacao"
    label: "Reclamação"
    default_priority: "alta"
    
  - name: "sugestao"
    label: "Sugestão"
    default_priority: "baixa"

email:
  enabled: true
  brand_color: "#660099"
  brand_name: "Minha Empresa"
  sla_message: "Retornaremos em até 24h úteis."

priorities:
  - name: "baixa"
    sla_hours: 72
  - name: "normal"
    sla_hours: 24
  - name: "alta"
    sla_hours: 8
  - name: "urgente"
    sla_hours: 2

Usar Feedback

As configurações (tipos de ticket, prefixo de protocolo, email, etc.) são carregadas automaticamente do feedback_config.yaml do template. Os tickets são persistidos em arquivo JSON (caminho configurável via FEEDBACK_STORAGE_PATH).

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    include_feedback=True,
    # Opcional: sobrescrever configs do YAML via parâmetros
    # feedback_protocol_prefix="SAC",
    # feedback_brand_color="#660099",
    # feedback_brand_name="Minha Empresa",
)

Diferença: Escalation vs Feedback

Aspecto	Escalation	Feedback
Propósito	Atendimento IMEDIATO	Registro para DEPOIS
Urgência	Alta	Pode aguardar
Canal	Telefone, chat	Email, ticket
Protocolo	ESC-XXXXXX	SAC-XXXXXX
Quando usar	"Quero falar com alguém"	"Tenho uma sugestão"

---

🔄 Fluxo de Handoffs

Triage ──► Flow, Knowledge, Confirmation, Usage, Onboarding, Escalation, Feedback
Flow ────► Interview, Triage, Escalation, Feedback
Interview► Answer, Escalation, Feedback
Answer ──► Triage, Escalation, Feedback
Knowledge► Triage, Escalation, Feedback
Escalation► Triage, Feedback
Feedback ► Triage, Escalation

Configuração de Agentes

Você pode escolher exatamente quais agentes incluir na sua rede:

from pathlib import Path
from atendentepro import create_standard_network

# Todos os agentes habilitados (padrão)
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
)

# Sem Knowledge Agent (para clientes sem base de conhecimento)
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    include_knowledge=False,
)

# Rede mínima (apenas fluxo principal)
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    include_knowledge=False,
    include_confirmation=False,
    include_usage=False,
    include_escalation=False,
    include_feedback=False,
)

# Apenas captura de leads (sem Knowledge nem Usage)
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    include_knowledge=False,
    include_usage=False,
)

Parâmetros Disponíveis

Parâmetro	Padrão	Descrição
include_flow	True	Agente de fluxo conversacional
include_interview	True	Agente de entrevista/coleta
include_answer	True	Agente de resposta final
include_knowledge	True	Agente de base de conhecimento
include_confirmation	True	Agente de confirmação
include_usage	True	Agente de instruções de uso
include_onboarding	False	Agente de boas-vindas
include_escalation	True	Agente de escalonamento humano
include_feedback	True	Agente de tickets/feedback
user_loader	None	Função para carregar dados do usuário (User Loader)
auto_load_user	False	Carregar usuário automaticamente no início da sessão

---

🎨 Estilo de Comunicação (AgentStyle)

Personalize o tom e estilo de resposta dos agentes:

Via Código

from pathlib import Path
from atendentepro import create_standard_network, AgentStyle

# Estilo global (aplicado a todos os agentes)
global_style = AgentStyle(
    tone="profissional e consultivo",
    language_style="formal",      # formal, informal, neutro
    response_length="moderado",   # conciso, moderado, detalhado
    custom_rules="Sempre cumprimente o usuário pelo nome.",
)

# Estilos específicos por agente
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    global_style=global_style,
    agent_styles={
        "escalation": AgentStyle(
            tone="empático e acolhedor",
            custom_rules="Demonstre compreensão pela situação.",
        ),
        "knowledge": AgentStyle(
            tone="didático e paciente",
            response_length="detalhado",
        ),
    },
)

Via YAML (style_config.yaml)

# Estilo Global
global:
  tone: "profissional e cordial"
  language_style: "formal"
  response_length: "moderado"
  custom_rules: |
    - Seja objetivo e claro nas respostas
    - Use linguagem inclusiva

# Estilos por Agente
agents:
  escalation:
    tone: "empático e tranquilizador"
    custom_rules: |
      - Demonstre compreensão pela situação
      - Assegure que o problema será resolvido

  knowledge:
    tone: "didático e paciente"
    response_length: "detalhado"
    custom_rules: |
      - Explique conceitos de forma acessível
      - Cite as fontes das informações

  feedback:
    tone: "solícito e atencioso"
    custom_rules: |
      - Agradeça o feedback recebido
      - Confirme o registro da solicitação

Opções Disponíveis

Parâmetro	Valores	Descrição
tone	Texto livre	Tom da conversa (ex: "profissional", "empático")
language_style	formal, informal, neutro	Nível de formalidade
response_length	conciso, moderado, detalhado	Tamanho das respostas
custom_rules	Texto livre	Regras personalizadas

---

🔧 Dependências

• Python 3.9+
• openai-agents >= 0.3.3
• openai >= 1.107.1
• pydantic >= 2.0.0
• PyYAML >= 6.0
• python-dotenv >= 1.0.0

---

📄 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
DEFAULT_MODEL	Modelo padrão	Não
AZURE_API_KEY	Chave API Azure	✅ (se Azure)
AZURE_API_ENDPOINT	Endpoint Azure	✅ (se Azure)
SMTP_HOST	Servidor SMTP	Para emails
SMTP_USER	Usuário SMTP	Para emails
SMTP_PASSWORD	Senha SMTP	Para emails
FEEDBACK_STORAGE_PATH	Caminho do arquivo JSON de tickets	Persistência do Feedback Agent
ATENDENTEPRO_PRODUCTION	1/true/yes: validação online obrigatória; exige ATENDENTEPRO_VALIDATION_URL	Produção
ATENDENTEPRO_VALIDATION_URL	URL do endpoint de validação de licença (obrigatória em produção)	Produção
ATENDENTEPRO_REQUIRE_USER_CONTEXT	1/true/yes: exige user_context quando há filtros de acesso	Produção
ATENDENTEPRO_REQUIRE_GUARDRAILS	1/true/yes: log ERROR se guardrails do Triage não configurados	Produção
ATENDENTEPRO_LOG_FORMAT	json para logs estruturados JSON; padrão: text	Não
ATENDENTEPRO_LOG_LEVEL	Nível de log (DEBUG, INFO, WARNING, ERROR); padrão: INFO	Não
ATENDENTEPRO_GUARDRAIL_CACHE_TTL	TTL do cache de guardrails em segundos; padrão: 300	Não
PROXY_TRUSTED_IPS	Lista CSV de IPs de proxies confiáveis para X-Forwarded-For (servidor)	Não

Segurança em Produção

Para uso em grande corporação, recomenda-se:

1. Licença: ATENDENTEPRO_PRODUCTION=1 e ATENDENTEPRO_VALIDATION_URL configurada; segredo apenas no servidor de validação.
2. Acesso: user_context (ou user_loader) sempre fornecido ao criar a rede quando há filtros; opcionalmente ATENDENTEPRO_REQUIRE_USER_CONTEXT=1.
3. Guardrails: guardrails_config.yaml com escopo e blocklist; opcionalmente ATENDENTEPRO_REQUIRE_GUARDRAILS=1.
4. Secrets: API keys, SMTP etc. apenas em variáveis de ambiente ou vault; não logar config/env com segredos; logs de conteúdo em DEBUG apenas.

Ver docs/PRODUCTION_SECURITY.md para checklist completo e variáveis.

---

🔁 Single Reply Mode

O Single Reply Mode permite configurar agentes para responderem apenas uma vez e automaticamente transferirem de volta para o Triage. Isso evita que a conversa fique "presa" em um agente específico.

📂 Exemplos completos: docs/examples/single_reply/

Quando Usar

Cenário	Recomendação
Chatbots de alto volume	✅ Ativar para respostas rápidas
FAQ simples	✅ Knowledge com single_reply
Coleta de dados	❌ Interview precisa múltiplas interações
Onboarding	❌ Precisa guiar o usuário em etapas
Confirmações	✅ Confirma e volta ao Triage

Exemplo 1: FAQ Bot (Via Código)

Chatbot otimizado para perguntas frequentes:

from pathlib import Path
from atendentepro import create_standard_network

# FAQ Bot: Knowledge e Answer respondem uma vez
network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    global_single_reply=False,
    single_reply_agents={
        "knowledge": True,  # FAQ: responde e volta
        "answer": True,     # Perguntas gerais: responde e volta
        "flow": True,       # Menu: apresenta e volta
    },
)

Exemplo 2: Bot de Leads (Via Código)

Bot que coleta dados mas responde dúvidas rapidamente:

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    global_single_reply=False,
    single_reply_agents={
        # Interview PRECISA de múltiplas interações para coletar dados
        "interview": False,
        
        # Outros agentes podem ser rápidos
        "knowledge": True,    # Tira dúvidas sobre produto
        "answer": True,       # Responde perguntas
        "confirmation": True, # Confirma cadastro
    },
)

Exemplo 3: Ativar para TODOS os agentes

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    global_single_reply=True,  # Todos respondem uma vez
)

Via YAML (single_reply_config.yaml)

Crie o arquivo single_reply_config.yaml na pasta do cliente:

# Global: se true, TODOS os agentes respondem apenas uma vez
global: false

# Configuração por agente (sobrescreve global)
agents:
  # Agentes de consulta: respondem uma vez
  knowledge: true      # FAQ: responde e volta
  answer: true         # Perguntas: responde e volta
  confirmation: true   # Confirma e volta
  usage: true          # Explica uso e volta
  
  # Agentes de coleta: múltiplas interações
  interview: false     # Precisa coletar dados
  onboarding: false    # Precisa guiar usuário
  
  # Opcionais
  flow: true           # Menu: apresenta e volta
  escalation: true     # Registra e volta
  feedback: true       # Coleta feedback e volta

Fluxo Visual

Com single_reply=True:

[Usuário: "Qual o preço?"]
         ↓
    [Triage] → detecta consulta
         ↓
  [Knowledge] → responde: "R$ 99,90"
         ↓
    [Triage] ← retorno AUTOMÁTICO
         ↓
[Usuário: "E a entrega?"]
         ↓
    [Triage] → nova análise (ciclo reinicia)

Com single_reply=False (padrão):

[Usuário: "Qual o preço?"]
         ↓
    [Triage] → detecta consulta
         ↓
  [Knowledge] → responde: "R$ 99,90"
         ↓
[Usuário: "E a entrega?"]
         ↓
  [Knowledge] → continua no mesmo agente
         ↓
[Usuário: "Quero falar com humano"]
         ↓
  [Knowledge] → handoff para Escalation

Configuração Recomendada

Para a maioria dos casos de uso:

global: false

agents:
  knowledge: true      # FAQ
  answer: true         # Perguntas gerais
  confirmation: true   # Confirmações
  
  interview: false     # Coleta de dados
  onboarding: false    # Guia de usuário

---

🔐 Filtros de Acesso (Role/User)

O sistema de Filtros de Acesso permite controlar quais agentes, prompts e tools estão disponíveis para cada usuário ou role (função).

📂 Exemplos completos: docs/examples/access_filters/

Quando Usar

Cenário	Solução
Multi-tenant	Diferentes clientes veem diferentes agentes
Níveis de acesso	Admin vê mais opções que cliente
Segurança	Dados sensíveis só para roles específicas
Personalização	Diferentes instruções por departamento

Níveis de Filtragem

1. Agentes: Habilitar/desabilitar agentes inteiros
2. Prompts: Adicionar seções condicionais aos prompts
3. Tools: Habilitar/desabilitar tools específicas

Exemplo 1: Filtros de Agente (Via Código)

from pathlib import Path
from atendentepro import (
    create_standard_network,
    UserContext,
    AccessFilter,
)

# Usuário com role de vendedor
user = UserContext(user_id="vendedor_123", role="vendedor")

# Filtros de agente
agent_filters = {
    # Feedback só para admin
    "feedback": AccessFilter(allowed_roles=["admin"]),
    # Escalation para todos exceto clientes
    "escalation": AccessFilter(denied_roles=["cliente"]),
}

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    user_context=user,
    agent_filters=agent_filters,
)

Exemplo 2: Prompts Condicionais

Adicione instruções específicas baseadas na role:

from atendentepro import FilteredPromptSection

conditional_prompts = {
    "knowledge": [
        # Seção para vendedores
        FilteredPromptSection(
            content="\\n## Descontos\\nVocê pode oferecer até 15% de desconto.",
            filter=AccessFilter(allowed_roles=["vendedor"]),
        ),
        # Seção para admin
        FilteredPromptSection(
            content="\\n## Admin\\nVocê tem acesso total ao sistema.",
            filter=AccessFilter(allowed_roles=["admin"]),
        ),
    ],
}

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    user_context=user,
    conditional_prompts=conditional_prompts,
)

Exemplo 3: Tools Filtradas

from atendentepro import FilteredTool
from agents import function_tool

@function_tool
def deletar_cliente(cliente_id: str) -> str:
    """Remove um cliente do sistema."""
    return f"Cliente {cliente_id} removido"

filtered_tools = {
    "knowledge": [
        FilteredTool(
            tool=deletar_cliente,
            filter=AccessFilter(allowed_roles=["admin"]),  # Só admin
        ),
    ],
}

network = create_standard_network(
    templates_root=Path("./meu_cliente"),
    client="config",
    user_context=user,
    filtered_tools=filtered_tools,
)

Via YAML (access_config.yaml)

# Filtros de agente
agent_filters:
  feedback:
    allowed_roles: ["admin"]
  escalation:
    denied_roles: ["cliente"]

# Prompts condicionais
conditional_prompts:
  knowledge:
    - content: |
        ## Capacidades de Vendedor
        Você pode oferecer até 15% de desconto.
      filter:
        allowed_roles: ["vendedor"]

# Acesso a tools
tool_access:
  deletar_cliente:
    allowed_roles: ["admin"]

Tipos de Filtro

Tipo	Descrição	Exemplo
allowed_roles	Whitelist de roles	["admin", "gerente"]
denied_roles	Blacklist de roles	["cliente"]
allowed_users	Whitelist de usuários	["user_vip_1"]
denied_users	Blacklist de usuários	["user_bloqueado"]

Prioridade de Avaliação

1. denied_users - Se usuário está negado, bloqueia
2. allowed_users - Se lista existe e usuário está nela, permite
3. denied_roles - Se role está negada, bloqueia
4. allowed_roles - Se lista existe e role não está nela, bloqueia
5. Permite por padrão - Se nenhum filtro matched

Fluxo Visual

┌────────────────────────────────────────────────┐
│         Requisição: role="vendedor"            │
└────────────────────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────┐
│              FILTRO DE AGENTES                 │
│  Knowledge: ✅ (vendedor allowed)              │
│  Escalation: ✅ (vendedor not denied)          │
│  Feedback: ❌ (only admin)                     │
└────────────────────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────┐
│             FILTRO DE PROMPTS                  │
│  Knowledge recebe: "## Descontos..."           │
│  (seção condicional para vendedor)             │
└────────────────────────────────────────────────┘
                        │
                        ▼
┌────────────────────────────────────────────────┐
│              FILTRO DE TOOLS                   │
│  consultar_comissao: ✅                        │
│  deletar_cliente: ❌ (only admin)              │
└────────────────────────────────────────────────┘

---

👤 Carregamento de Usuários (User Loader)

O User Loader carrega dados do usuário que ficam em uma estrutura de banco de dados (ou CSV/API): identidade, perfil, role e dados estatísticos daquele usuário. Não é para memória nem para sessão (conversa) — memória e session_id usam outros mecanismos (session_id_factory, parâmetros, backend de memória).

O carregamento pode ser usado apenas para um agente: chame run_with_user_context(network, network.flow, messages) (ou o agente desejado, ex.: flow) só para esse agente; os demais podem ser executados com Runner.run(agent, messages) sem user_loader.

O user_loader deve retornar um UserContext com user_id preenchido (obrigatório quando o loader retorna contexto). O user_id deve vir de um único lugar (UserContext) — ao usar user_loader, não informe user_id em dois lugares; quando houver user_loader, run_with_memory usará loaded_user_context.user_id e não deve ser passado um user_id diferente por parâmetro.

A função de carregamento (load_user / loader_func) busca os dados e retorna um dicionário. Esse dicionário preenche o UserContext: user_id e role vão para os campos fixos; o resto fica em metadata. Exemplo de acesso após o carregamento: network.loaded_user_context.metadata.get("nome"), metadata.get("plano").

📂 Exemplos completos: docs/examples/user_loader/

Quando Usar

Cenário	Solução
Usuário existente	Identifica automaticamente e pula onboarding
Personalização	Carrega dados do usuário (perfil, plano, etc.) do banco para respostas personalizadas
Contexto enriquecido	Agentes que usam run_with_user_context têm acesso a loaded_user_context (dados em banco/perfil)
Múltiplas fontes	Suporta CSV, banco de dados, APIs REST, etc.

Funcionalidades

1. Extração automática de identificadores (telefone, email, CPF, etc.)
2. Carregamento de dados de múltiplas fontes
3. Criação automática de UserContext
4. Integração transparente com a rede de agentes

Exemplo 1: Carregamento de CSV

from pathlib import Path
from atendentepro import (
    create_standard_network,
    create_user_loader,
    load_user_from_csv,
    extract_email_from_messages,
    run_with_user_context,
)

# Função para carregar do CSV
def load_user(identifier: str):
    return load_user_from_csv(
        csv_path=Path("users.csv"),
        identifier_field="email",
        identifier_value=identifier
    )

# Criar loader
loader = create_user_loader(
    loader_func=load_user,
    identifier_extractor=extract_email_from_messages
)

# Criar network com loader
network = create_standard_network(
    templates_root=Path("./templates"),
    user_loader=loader,
    include_onboarding=True,
)

# Executar com carregamento automático
messages = [{"role": "user", "content": "Meu email é [e-mail]"}]
result = await run_with_user_context(network, network.triage, messages)

# Verificar se usuário foi carregado
if network.loaded_user_context:
    print(f"Usuário: {network.loaded_user_context.metadata.get('nome')}")

Exemplo 2: Carregamento de Banco de Dados

import sqlite3
from atendentepro import create_user_loader, extract_email_from_messages

def load_from_db(identifier: str):
    conn = sqlite3.connect("users.db")
    cursor = conn.cursor()
    cursor.execute("SELECT * FROM users WHERE email = ?", (identifier,))
    row = cursor.fetchone()
    conn.close()
    
    if row:
        return {
            "user_id": row[0],
            "role": row[1],
            "nome": row[2],
            "email": row[3],
        }
    return None

loader = create_user_loader(load_from_db, extract_email_from_messages)

network = create_standard_network(
    templates_root=Path("./templates"),
    user_loader=loader,
)

Exemplo 3: Múltiplos Identificadores

from atendentepro import (
    create_user_loader,
    extract_email_from_messages,
    extract_phone_from_messages,
)

def extract_identifier(messages):
    # Tenta email primeiro
    email = extract_email_from_messages(messages)
    if email:
        return email
    
    # Se não encontrou, tenta telefone
    phone = extract_phone_from_messages(messages)
    if phone:
        return phone
    
    return None

loader = create_user_loader(
    loader_func=load_user,
    identifier_extractor=extract_identifier
)

Funções Disponíveis

Extratores de Identificador

from atendentepro import (
    extract_phone_from_messages,    # Extrai telefone
    extract_email_from_messages,     # Extrai email
    extract_user_id_from_messages,  # Extrai CPF/user_id
)

Criar Loader

from atendentepro import create_user_loader

loader = create_user_loader(
    loader_func=load_user_function,
    identifier_extractor=extract_email_from_messages  # Opcional
)

Executar com Contexto

from atendentepro import run_with_user_context

result = await run_with_user_context(
    network,
    network.triage,
    messages
)

Integração com Onboarding

Quando um user_loader está configurado:

• ✅ Usuário encontrado: Vai direto para o triage, sem passar pelo onboarding
• ✅ Usuário não encontrado: É direcionado para o onboarding normalmente
• ✅ Contexto disponível: Todos os agentes têm acesso a network.loaded_user_context

Benefícios

1. ✅ Experiência personalizada - Respostas baseadas em dados do usuário
2. ✅ Menos fricção - Usuários conhecidos não precisam fazer onboarding
3. ✅ Contexto rico - Todos os agentes têm acesso a informações do usuário
4. ✅ Flexível - Suporta múltiplas fontes de dados
5. ✅ Automático - Funciona transparentemente durante a conversa

---

🔀 Múltiplos Agentes (Multi Interview + Knowledge)

O AtendentePro suporta criar múltiplas instâncias de Interview e Knowledge agents, cada um especializado em um domínio diferente.

📂 Exemplo completo: docs/examples/multi_agents/

Caso de Uso

Empresa que atende diferentes tipos de clientes:

• Pessoa Física (PF): Produtos de consumo
• Pessoa Jurídica (PJ): Soluções empresariais

Arquitetura

                    ┌─────────────────┐
                    │     Triage      │
                    │  (entry point)  │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
              ▼              ▼              ▼
    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
    │  Interview  │  │  Interview  │  │    Flow     │
    │     PF      │  │     PJ      │  │   (comum)   │
    └──────┬──────┘  └──────┬──────┘  └─────────────┘
           │                │
           ▼                ▼
    ┌─────────────┐  ┌─────────────┐
    │  Knowledge  │  │  Knowledge  │
    │     PF      │  │     PJ      │
    └─────────────┘  └─────────────┘

Implementação

from atendentepro import (
    create_custom_network,
    create_triage_agent,
    create_interview_agent,
    create_knowledge_agent,
)

# 1. Criar agentes especializados
interview_pf = create_interview_agent(
    interview_questions="CPF, data de nascimento, renda mensal",
    name="interview_pf",  # Nome único!
)

interview_pj = create_interview_agent(
    interview_questions="CNPJ, razão social, faturamento",
    name="interview_pj",  # Nome único!
)

knowledge_pf = create_knowledge_agent(
    knowledge_about="Produtos para consumidor final",
    name="knowledge_pf",
    single_reply=True,
)

knowledge_pj = create_knowledge_agent(
    knowledge_about="Soluções empresariais B2B",
    name="knowledge_pj",
    single_reply=True,
)

# 2. Criar Triage
triage = create_triage_agent(
    keywords_text="PF: CPF, pessoal, minha conta | PJ: CNPJ, empresa, MEI",
    name="triage_agent",
)

# 3. Configurar handoffs
triage.handoffs = [interview_pf, interview_pj, knowledge_pf, knowledge_pj]
interview_pf.handoffs = [knowledge_pf, triage]
interview_pj.handoffs = [knowledge_pj, triage]
knowledge_pf.handoffs = [triage]
knowledge_pj.handoffs = [triage]

# 4. Criar network customizada
network = create_custom_network(
    triage=triage,
    custom_agents={
        "interview_pf": interview_pf,
        "interview_pj": interview_pj,
        "knowledge_pf": knowledge_pf,
        "knowledge_pj": knowledge_pj,
    },
)

Cenários de Roteamento

Mensagem do Usuário	Rota
"Quero abrir conta para mim"	Triage → Interview PF → Knowledge PF
"Preciso de maquininha para minha loja"	Triage → Interview PJ → Knowledge PJ
"Quanto custa o cartão gold?"	Triage → Knowledge PF (direto)
"Capital de giro para empresa"	Triage → Knowledge PJ (direto)

Padrão: 1 Interview → 2 Knowledge

Outro padrão comum é ter um único Interview que pode direcionar para múltiplos Knowledge:

        ┌───────────────┐
        │   Interview   │
        │ (coleta dados)│
        └───────┬───────┘
                │
        ┌───────┴───────┐
        ▼               ▼
┌───────────────┐ ┌───────────────┐
│   Knowledge   │ │   Knowledge   │
│   Produtos    │ │Troubleshooting│
└───────────────┘ └───────────────┘

# Um interview que direciona para múltiplos knowledge
interview.handoffs = [knowledge_produtos, knowledge_troubleshooting, triage]

📂 Exemplo completo: example_one_interview_two_knowledge.py

Dicas

1. Nomes únicos: Cada agente precisa de um name distinto
2. Handoffs claros: Configure quais agentes cada um pode chamar
3. Keywords no Triage: Inclua palavras-chave para direcionar corretamente
4. single_reply: Use em Knowledge para evitar loops

---

📊 Tracing e Monitoramento

MonkAI Trace (Recomendado)

Integração com MonkAI Trace para monitoramento completo de agentes:

pip install monkai-trace

from atendentepro import (
    activate,
    create_standard_network,
    configure_monkai_trace,
    run_with_monkai_tracking,
)

# 1. Ativar biblioteca
activate("ATP_seu-token")

# 2. Configurar MonkAI Trace
configure_monkai_trace(
    tracer_token="tk_seu_token_monkai",  # ou env MONKAI_TRACER_TOKEN
    namespace="meu-projeto",
)

# 3. Criar rede
network = create_standard_network(...)

# 4. Executar com tracking
result = await run_with_monkai_tracking(
    agent=network.triage,
    user_input="Olá, preciso de ajuda",
    user_id="user123",  # Opcional: para sessões multi-usuário
)

Recursos do MonkAI Trace:

• ✅ Tracking automático de sessões
• ✅ Segmentação de tokens (input, output, process, memory)
• ✅ Rastreamento de handoffs entre agentes
• ✅ Captura de ferramentas internas (web_search, RAG)
• ✅ Suporte multi-usuário (WhatsApp, chat)

Uso Avançado

from atendentepro import (
    get_monkai_hooks,
    set_monkai_user,
    set_monkai_input,
)
from agents import Runner

# Para controle manual
hooks = get_monkai_hooks()
set_monkai_user("5511999999999")  # WhatsApp
set_monkai_input("Como cancelar?")

result = await Runner.run(network.triage, messages, hooks=hooks)

Application Insights (Azure)

Para Azure, use Application Insights:

from atendentepro import configure_application_insights

configure_application_insights(
    connection_string="InstrumentationKey=..."
)

---

🔧 Tuning (Post-Training)

O módulo opcional Tuning usa feedback das conversas (Supabase) e registros do MonkAI Trace para sugerir melhorias nos YAMLs do cliente. As alterações são gravadas numa pasta de sugeridos (client/_suggested/) para revisão; o usuário decide se substitui os originais.

Instalação: pip install atendentepro[tuning]

Variáveis de ambiente: SUPABASE_URL, SUPABASE_SERVICE_KEY (ou SUPABASE_ANON_KEY), MONKAI_TRACER_TOKEN

Fluxo resumido:

1. Rodar o pipeline com apply=True e write_to_suggested_folder=True — os YAMLs alterados são gravados em client/_suggested/ e um relatório _suggestions_report.json é gerado; os originais não são alterados.
2. Revisar os arquivos em client/_suggested/ e o relatório.
3. Se aprovar, chamar replace_originals_with_suggested(client, templates_root) para copiar os sugeridos sobre os originais.

from pathlib import Path
from atendentepro.tuning import run_tuning_pipeline, replace_originals_with_suggested

result = run_tuning_pipeline(
    namespace="customer-support",
    client="meu_cliente",
    templates_root=Path("./client_templates"),
    start_date="2025-01-01",
    apply=True,
    write_to_suggested_folder=True,
)
# Revisar client_templates/meu_cliente/_suggested/
replace_originals_with_suggested(client="meu_cliente", templates_root=Path("./client_templates"))

Documentação completa: atendentepro/tuning/README.md e docs/TUNING.md

---

Memória de contexto longo (GRKMemory)

O módulo opcional Memória integra o GRKMemory para memória de longo prazo: antes de cada execução do agente, busca memórias relevantes e injeta no contexto; após a resposta, persiste o turno. Suporte async e multi-tenant (user_id / session_id).

Instalação: pip install atendentepro[memory]

Variáveis de ambiente: GRKMEMORY_API_KEY, OPENAI_API_KEY (ou Azure conforme documentação do GRKMemory)

from atendentepro import create_standard_network
from atendentepro.memory import run_with_memory, create_grk_backend

network = create_standard_network(templates_root=Path("templates"), client="standard")
network.memory_backend = create_grk_backend()

messages = [{"role": "user", "content": "O que combinamos na última vez?"}]
result = await run_with_memory(network, network.triage, messages)

Ao usar memória ou sessão, user_id é obrigatório (para isolar conversas por usuário). Toda sessão deve ter um user_id associado. Quando houver user_loader, use o mesmo user_id do UserContext — não informe em dois lugares; run_with_memory usará loaded_user_context.user_id automaticamente. session_id é chave de sessão (não vem de UserContext/user_loader): use apenas o parâmetro session_id ou o session_id_factory como fonte única.

Documentação completa: atendentepro/memory/README.md

---

🤝 Suporte

• 📧 Email: [e-mail]
• 🌐 Site: https://www.monkai.com.br

Documentação adicional: docs/CI.md (pipeline de CI), docs/PUBLISHING.md (publicação), docs/WORKFLOW_PYPI_EXPLAINED.md (workflow PyPI), docs/PRODUCTION_SECURITY.md (segurança em produção), docs/SECURITY.md (mitigações de prompt injection), docs/AUDIT_REPORT.md (auditoria R5), docs/AUDIT_REPORT.html (auditoria R5 — versão HTML), docs/QUALITY_CERTIFICATE.md (certificado de qualidade — serial e verificação), docs/QUALITY_CERTIFICATE.html (certificado — versão HTML), docs/TUNING.md (módulo de tuning), docs/fluxogramas/ (diagramas de arquitetura).

---

📝 Changelog

v0.6.26 (Atual)

• Seguranca — SQL injection corrigido: Exemplo multi_knowledge reescrito com queries parametrizadas e whitelist de tabelas/colunas
• Seguranca — Proxy confiavel: X-Forwarded-For so aceito de IPs em PROXY_TRUSTED_IPS; padrao seguro (IP direto)
• Seguranca — Mensagens de erro: str(e) removido de license.py e exemplos; mensagens genericas + logger.warning
• Escalabilidade — TTL no cache de guardrails: _GUARDRAIL_CACHE com TTL configuravel via ATENDENTEPRO_GUARDRAIL_CACHE_TTL (default 300s)
• Escalabilidade — API versioning: Rotas do servidor de validacao sob /v1/ com aliases legacy para compatibilidade
• Escalabilidade — Structured logging: JSONFormatter ativado com ATENDENTEPRO_LOG_FORMAT=json; configure_logging() exportado
• Escalabilidade — docker-compose: server/docker-compose.yml para desenvolvimento local do servidor
• Escalabilidade — Docs multi-instancia: server/README.md com guia Redis/DB para revocation list em clusters
• Usabilidade — Typo corrigido: AtendentProConfig renomeado para AtendenteProConfig (alias mantido para compatibilidade)
• Usabilidade — Tipagem melhorada: Reducao de Any em memory/runner.py (Protocol) e network.py (Union types para handoffs)
• Usabilidade — Cobertura 65%: Meta elevada para 65% com 33 novos testes (193 total, 65.04%)
• Certificado de qualidade: Auditoria R5 (revalidação independente), serial MONKAI-AP-0626-F59FC5E769C0CE46, nota 8.4/10 (Segurança 8.9, Usabilidade 8.4, Escalabilidade 7.9)

v0.6.24–0.6.25

• Rate limiter TTL/LRU: Evicao automatica de usuarios inativos para evitar crescimento ilimitado de memoria (max_users, active_users)
• HTTP retry com backoff: Chamadas HTTP (license validation, webhooks) agora fazem ate 3 tentativas com backoff exponencial (0.5s, 1s, 2s)
• Webhook HMAC-SHA256: Webhook de escalacao agora assina payloads com X-Webhook-Signature via ESCALATION_WEBHOOK_SECRET
• CORS configuravel: Servidor de validacao com CORSMiddleware via CORS_ALLOWED_ORIGINS
• pytest-cov: Cobertura de testes monitorada no CI (62.65%, meta 60%)
• Escalation migrado para httpx: Unificacao de client HTTP (removido requests)

v0.6.23

• Persistencia revocation list: Tokens revogados salvos em JSON, sobrevivem restarts
• mypy zero divida: agents.*, memory.*, setup_copilot verificados sem erros
• Build CI condicional: Job build so roda apos testes passarem
• Testes feedback persistence: 23 novos testes

v0.6.22

• Rate limiting no servidor: /validate (60 req/min) e /revoke (10 req/min) com sliding window por IP
• Persistencia tickets por cliente: Storage isolado em <templates_root>/<client>/tickets.json
• Seguranca producao: Modo producao (ATENDENTEPRO_PRODUCTION=1), exigencia de UserContext, verificacao de guardrails

v0.6.21

• Rate Limiter embutido: RateLimiter (sliding window, thread-safe) exportado na API publica
• Servidor de validacao online: FastAPI com /validate, /revoke, /health
• Testes de integracao: 65 testes cobrindo licenciamento, RBAC, guardrails e servidor

v0.6.20

• Seguranca: Chave HMAC removida do codigo, geracao de tokens removida do pacote, validacao online real, pickle eliminado, CI bloqueante, pre-filtro jailbreak, thread-safety licenca

v0.6.15

• Memoria de contexto longo (GRKMemory): run_with_memory, create_grk_backend; pip install atendentepro[memory]
• Tuning (Post-Training): Modulo opcional para melhorar YAMLs com base em feedback e Trace

v0.6.9

• Correções: Serialização do tool RAG (go_to_rag) para compatibilidade com MonkAI Trace; exportações de load_feedback_config, load_escalation_config, load_answer_config e modelos de config no pacote templates
• 0.6.7–0.6.8: Configurações YAML do Feedback, Escalation e Answer passam a ser carregadas e aplicadas; persistência de tickets em JSON; tipos de ticket e prioridades configuráveis
• 0.6.6: User Loader (carregamento automático de usuários), parâmetros user_loader e auto_load_user em create_standard_network

v0.6.1

• Documentação PyPI atualizada com AgentStyle e changelog completo

v0.6.0

• AgentStyle: Nova classe para personalizar tom e estilo de comunicação
  • tone, language_style, response_length, custom_rules
• style_config.yaml: Configuração de estilos via YAML
• Parâmetros global_style e agent_styles em create_standard_network()
• Todos os agentes aceitam style_instructions

v0.5.9

• Descrição PyPI formal: "Framework de orquestração de agentes IA"
• README profissional com foco em capacidades corporativas

v0.5.8

• Novos keywords: triage, handoff, escalation, feedback, knowledge-base
• Dependência tracing agora usa monkai-trace

v0.5.7

• MonkAI Trace: Integração completa para monitoramento de agentes
• Novas funções: configure_monkai_trace, run_with_monkai_tracking
• Suporte multi-usuário para WhatsApp/chat

v0.5.6

• Agentes configuráveis: include_knowledge=False, include_flow=False, etc.
• Permite criar redes sem agentes específicos

v0.5.5

• Workflow PyPI apenas com tags de versão

v0.5.4

• Documentação completa standalone no PyPI

v0.5.3

• Links de documentação corrigidos para PyPI

v0.5.2

• Contatos atualizados (monkai.com.br)

v0.5.1

• Prompts modulares para Escalation e Feedback
• Remoção de handoff circular Answer→Interview

v0.5.0

• Novo: Feedback Agent (tickets/SAC)
• Ferramentas: criar_ticket, consultar_ticket, listar_meus_tickets

v0.4.0

• Novo: Escalation Agent (transferência humana)
• Verificação de horário, prioridade automática, webhooks

v0.3.0

• Sistema de licenciamento com tokens
• Publicação inicial no PyPI

v0.2.0

• Arquitetura modular completa
• 8 agentes especializados
• Sistema de templates YAML

---

Made with ❤️ by MonkAI