Adds documentation and fixes
This commit is contained in:
273
docs/api-reference.md
Normal file
273
docs/api-reference.md
Normal file
@@ -0,0 +1,273 @@
|
||||
# Referencia da API
|
||||
|
||||
Documentacao detalhada de todas as funcoes e modulos do assistente.
|
||||
|
||||
## Indice
|
||||
|
||||
- [agent.py](#agentpy)
|
||||
- [tools/dynamo.py](#toolsdynamopy)
|
||||
- [tools/secrets.py](#toolssecretspy)
|
||||
|
||||
---
|
||||
|
||||
## agent.py
|
||||
|
||||
Modulo principal que contem a logica do agente de IA.
|
||||
|
||||
### agent_call(event, context)
|
||||
|
||||
Funcao principal que processa perguntas do usuario e retorna respostas do assistente.
|
||||
|
||||
**Parametros:**
|
||||
|
||||
| Parametro | Tipo | Obrigatorio | Descricao |
|
||||
|-----------|------|-------------|-----------|
|
||||
| `event` | dict | Sim | Evento contendo dados da requisicao |
|
||||
| `context` | object | Nao | Contexto do Lambda (pode ser None) |
|
||||
|
||||
**Estrutura do `event`:**
|
||||
|
||||
```python
|
||||
{
|
||||
"username": str, # Identificador do usuario
|
||||
"email": str, # Email do usuario
|
||||
"language": str, # Idioma desejado (ex: "Portuguese", "English")
|
||||
"message": list, # Lista de mensagens no formato LangChain
|
||||
"chat_history": list, # Historico de chat ([] para nova conversa)
|
||||
"origem": str # (Opcional) Canal de origem da pergunta
|
||||
}
|
||||
```
|
||||
|
||||
**Formato das mensagens:**
|
||||
|
||||
```python
|
||||
# Mensagem do usuario
|
||||
{"role": "user", "content": "Texto da pergunta"}
|
||||
|
||||
# Mensagem do assistente
|
||||
{"role": "assistant", "content": "Texto da resposta"}
|
||||
```
|
||||
|
||||
**Retorno:**
|
||||
|
||||
```python
|
||||
{
|
||||
"json": str, # Resposta do assistente
|
||||
"dynamo_response": dict, # Resposta da operacao DynamoDB
|
||||
"chat_history": list # Historico atualizado
|
||||
}
|
||||
```
|
||||
|
||||
**Exemplo de Uso:**
|
||||
|
||||
```python
|
||||
from agent import agent_call
|
||||
|
||||
# Nova conversa
|
||||
event = {
|
||||
"username": "joao.silva",
|
||||
"email": "joao@empresa.com",
|
||||
"language": "Portuguese",
|
||||
"message": [{"role": "user", "content": "O que e o Comm.Pix?"}],
|
||||
"chat_history": [],
|
||||
"origem": "web"
|
||||
}
|
||||
|
||||
response = agent_call(event, None)
|
||||
print(response["json"]) # Resposta do assistente
|
||||
```
|
||||
|
||||
**Codigos de Erro:**
|
||||
|
||||
| Erro | Causa | Solucao |
|
||||
|------|-------|---------|
|
||||
| KeyError | Campo obrigatorio ausente no event | Verificar estrutura do event |
|
||||
| BedrockException | Erro na API do Bedrock | Verificar credenciais AWS |
|
||||
| DynamoDBException | Erro ao acessar DynamoDB | Verificar permissoes IAM |
|
||||
|
||||
---
|
||||
|
||||
### out_of_scope_and_dont_know_answer()
|
||||
|
||||
Tool do LangChain para respostas padrao quando o agente nao encontra a resposta.
|
||||
|
||||
**Parametros:** Nenhum
|
||||
|
||||
**Retorno:** `str` - Mensagem padrao orientando o usuario a abrir ticket de suporte
|
||||
|
||||
**Comportamento:**
|
||||
- Registra um score "Miss" no Langfuse
|
||||
- Retorna mensagem com link para portal de suporte
|
||||
|
||||
**Quando e Chamada:**
|
||||
- Perguntas fora do escopo do Comm.Pix
|
||||
- Perguntas dentro do escopo mas sem resposta nos documentos
|
||||
|
||||
---
|
||||
|
||||
## tools/dynamo.py
|
||||
|
||||
Modulo para operacoes de memoria no DynamoDB.
|
||||
|
||||
### write_memory(user, timestamp, role, content)
|
||||
|
||||
Armazena uma mensagem da conversa no DynamoDB.
|
||||
|
||||
**Parametros:**
|
||||
|
||||
| Parametro | Tipo | Obrigatorio | Descricao |
|
||||
|-----------|------|-------------|-----------|
|
||||
| `user` | str | Sim | Identificador do usuario (UserId) |
|
||||
| `timestamp` | int | Sim | Timestamp Unix da mensagem |
|
||||
| `role` | str | Sim | Papel da mensagem ("user" ou "assistant") |
|
||||
| `content` | str | Sim | Conteudo da mensagem |
|
||||
|
||||
**Retorno:** `None`
|
||||
|
||||
**Exemplo:**
|
||||
|
||||
```python
|
||||
from tools import dynamo
|
||||
import time
|
||||
|
||||
dynamo.write_memory(
|
||||
user="joao.silva",
|
||||
timestamp=int(time.time()),
|
||||
role="user",
|
||||
content="Como funciona o Finance Batch?"
|
||||
)
|
||||
```
|
||||
|
||||
**Estrutura no DynamoDB:**
|
||||
|
||||
```json
|
||||
{
|
||||
"UserId": "joao.silva",
|
||||
"Timestamp": 1704067200,
|
||||
"role": "user",
|
||||
"content": "Como funciona o Finance Batch?"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### read_memory(userid)
|
||||
|
||||
Recupera as ultimas 30 mensagens de um usuario.
|
||||
|
||||
**Parametros:**
|
||||
|
||||
| Parametro | Tipo | Obrigatorio | Descricao |
|
||||
|-----------|------|-------------|-----------|
|
||||
| `userid` | str | Sim | Identificador do usuario |
|
||||
|
||||
**Retorno:** `list` - Lista de mensagens ordenadas por timestamp (mais recentes primeiro)
|
||||
|
||||
**Exemplo:**
|
||||
|
||||
```python
|
||||
from tools import dynamo
|
||||
|
||||
history = dynamo.read_memory("joao.silva")
|
||||
for msg in history:
|
||||
print(f"{msg['role']}: {msg['content']}")
|
||||
```
|
||||
|
||||
**Retorno Exemplo:**
|
||||
|
||||
```python
|
||||
[
|
||||
{"UserId": "joao.silva", "Timestamp": 1704067300, "role": "assistant", "content": "..."},
|
||||
{"UserId": "joao.silva", "Timestamp": 1704067200, "role": "user", "content": "..."},
|
||||
# ... ate 30 mensagens
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## tools/secrets.py
|
||||
|
||||
Modulo para recuperacao de segredos do AWS Secrets Manager.
|
||||
|
||||
### get_secret()
|
||||
|
||||
Recupera as credenciais armazenadas no Secrets Manager.
|
||||
|
||||
**Parametros:** Nenhum
|
||||
|
||||
**Retorno:** `str` - String JSON contendo os segredos
|
||||
|
||||
**Exemplo:**
|
||||
|
||||
```python
|
||||
from tools import secrets
|
||||
import json
|
||||
|
||||
secret_string = secrets.get_secret()
|
||||
secrets_data = json.loads(secret_string)
|
||||
|
||||
langfuse_public = secrets_data['api-langfuse-public']
|
||||
langfuse_secret = secrets_data['api-langfuse-secret']
|
||||
```
|
||||
|
||||
**Estrutura do Segredo:**
|
||||
|
||||
```json
|
||||
{
|
||||
"api-langfuse-public": "pk-lf-xxxxxxxx",
|
||||
"api-langfuse-secret": "sk-lf-xxxxxxxx"
|
||||
}
|
||||
```
|
||||
|
||||
**Erros Possiveis:**
|
||||
|
||||
| Erro | Causa | Solucao |
|
||||
|------|-------|---------|
|
||||
| `ResourceNotFoundException` | Segredo nao encontrado | Verificar nome do segredo |
|
||||
| `AccessDeniedException` | Sem permissao | Verificar politica IAM |
|
||||
| `DecryptionFailure` | Erro de descriptografia | Verificar chave KMS |
|
||||
|
||||
---
|
||||
|
||||
## Fluxo Completo de Execucao
|
||||
|
||||
```
|
||||
1. agent_call() recebe o evento
|
||||
│
|
||||
2. Inicializa Langfuse handler
|
||||
│
|
||||
3. Configura ChatBedrock (Claude Sonnet 4)
|
||||
│
|
||||
4. Configura Knowledge Base Retriever
|
||||
│
|
||||
5. Carrega historico
|
||||
│ ├── Se chat_history vazio: dynamo.read_memory('frente')
|
||||
│ └── Se nao: usa chat_history do evento
|
||||
│
|
||||
6. Cria agente ReAct com tools:
|
||||
│ ├── retriever.as_tool() - Busca documentos
|
||||
│ └── out_of_scope_and_dont_know_answer - Resposta padrao
|
||||
│
|
||||
7. Executa agente com streaming
|
||||
│ ├── Registra scores no Langfuse (Origem, Email)
|
||||
│ └── Processa cada step do agente
|
||||
│
|
||||
8. Salva mensagem no DynamoDB
|
||||
│
|
||||
9. Retorna resposta
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variaveis de Configuracao
|
||||
|
||||
| Variavel | Local | Valor Padrao | Descricao |
|
||||
|----------|-------|--------------|-----------|
|
||||
| `model_id` | agent.py | `us.anthropic.claude-sonnet-4-20250514-v1:0` | Modelo Claude |
|
||||
| `region_name` | agent.py | `us-east-1` | Regiao AWS |
|
||||
| `knowledge_base_id` | agent.py | `PETAZDUOFZ` | ID da Knowledge Base |
|
||||
| `temperature` | agent.py | `0.1` | Temperatura do modelo |
|
||||
| `max_tokens` | agent.py | `2000` | Maximo de tokens |
|
||||
| `numberOfResults` | agent.py | `4` | Documentos retornados |
|
||||
| `table_name` | dynamo.py | `assistente-produtos-servicos-memoria` | Tabela DynamoDB |
|
||||
| `secret_name` | secrets.py | `assistente-produtos-servicos` | Nome do segredo |
|
||||
Reference in New Issue
Block a user