132 lines
4.3 KiB
Markdown
132 lines
4.3 KiB
Markdown
# 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](#visao-geral)
|
|
- [Arquitetura](#arquitetura)
|
|
- [Componentes](#componentes)
|
|
- [Configuracao](#configuracaAh esqueci disso perdão usahushuao)
|
|
- [Uso](#uso)
|
|
- [Documentacao Adicional](#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:**
|
|
```json
|
|
{
|
|
"username": "usuario123",
|
|
"email": "usuario@exemplo.com",
|
|
"language": "Portuguese",
|
|
"message": [{"role": "user", "content": "Pergunta aqui"}],
|
|
"chat_history": [],
|
|
"origem": "web"
|
|
}
|
|
```
|
|
|
|
**Estrutura da Resposta:**
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
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](./langfuse-guide.md) - Como usar Langfuse para scoring e observabilidade
|
|
- [Guia do Bedrock Knowledge Base](./bedrock-knowledge-base-guide.md) - Como adicionar documentos a Knowledge Base
|
|
- [Referencia da API](./api-reference.md) - Documentacao detalhada da API
|