AI-Frente-Corretora-Assistente/docs/README.md

Assistente Projeto Produto - Documentacao

Esta documentacao cobre o sistema de assistente de IA construido com LangChain/LangGraph para suporte ao Comm.Pix.

Indice

• Visao Geral
• Arquitetura
• Componentes
• Configuracao
• Uso
• Documentacao Adicional

Visao Geral

O Assistente e um agente RAG (Retrieval-Augmented Generation) que fornece suporte tecnico para usuarios da plataforma Comm.Pix. Ele utiliza:

• Claude Sonnet 4 via Amazon Bedrock para capacidades de LLM
• Amazon Knowledge Bases para recuperacao de documentos
• DynamoDB para persistencia de memoria de conversas
• Langfuse para observabilidade e scoring
• LangGraph para orquestracao do agente

Arquitetura

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  Entrada User   │────▶│   agent_call()   │────▶│  Claude Sonnet  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                               │                         │
                               │                         ▼
                        ┌──────┴──────┐          ┌─────────────────┐
                        │             │          │ Knowledge Base  │
                        ▼             ▼          │   Retriever     │
                 ┌──────────┐  ┌──────────┐      └─────────────────┘
                 │ DynamoDB │  │ Langfuse │
                 │  Memoria │  │ Tracking │
                 └──────────┘  └──────────┘

Componentes

agent.py

Modulo principal de orquestracao do agente contendo:

• agent_call(event, context) - Ponto de entrada principal para a funcao Lambda
• out_of_scope_and_dont_know_answer() - Ferramenta para lidar com perguntas desconhecidas

Estrutura do Evento de Entrada:

{
  "username": "usuario123",
  "email": "usuario@exemplo.com",
  "language": "Portuguese",
  "message": [{"role": "user", "content": "Pergunta aqui"}],
  "chat_history": [],
  "origem": "web"
}

Estrutura da Resposta:

{
  "json": "Texto da resposta do assistente",
  "dynamo_response": {...},
  "chat_history": [...]
}

tools/dynamo.py

Operacoes DynamoDB para memoria de conversas:

• write_memory(user, timestamp, role, content) - Armazena mensagens da conversa
• read_memory(userid) - Recupera as ultimas 30 mensagens de um usuario

tools/secrets.py

Integracao com AWS Secrets Manager:

• get_secret() - Recupera chaves de API do Langfuse do AWS Secrets Manager

Configuracao

Recursos AWS Necessarios

1. Tabela DynamoDB: assistente-produtos-servicos-memoria

   • Partition Key: UserId (String)
   • Sort Key: Timestamp (Number)

2. Secret no AWS Secrets Manager: assistente-produtos-servicos

   • Chaves: api-langfuse-public, api-langfuse-secret

3. Amazon Knowledge Base: ID PETAZDUOFZ

Requisitos de Ambiente

• Credenciais AWS configuradas (via IAM role ou variaveis de ambiente)
• Python 3.9+
• Pacotes necessarios no requirements.txt

Uso

Uso Basico

from agent import agent_call

event = {
    "username": "usuario123",
    "email": "usuario@exemplo.com",
    "language": "Portuguese",
    "message": [{"role": "user", "content": "Como funciona o Pix?"}],
    "chat_history": [],
    "origem": "web"
}

response = agent_call(event, None)
print(response["json"])

Como AWS Lambda

A funcao agent_call foi projetada para ser usada como handler de AWS Lambda.

Documentacao Adicional

• Guia de Integracao Langfuse - Como usar Langfuse para scoring e observabilidade
• Guia do Bedrock Knowledge Base - Como adicionar documentos a Knowledge Base
• Referencia da API - Documentacao detalhada da API
• Melhorias de Codigo - Sugestoes de melhorias para o codigo