AI-Frente-Corretora-Assistente/docs/api-reference.md

Referencia da API

Documentacao detalhada de todas as funcoes e modulos do assistente.

Indice

• agent.py
• tools/dynamo.py
• tools/secrets.py

---

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:

{
    "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:

# Mensagem do usuario
{"role": "user", "content": "Texto da pergunta"}

# Mensagem do assistente
{"role": "assistant", "content": "Texto da resposta"}

Retorno:

{
    "json": str,              # Resposta do assistente
    "dynamo_response": dict,  # Resposta da operacao DynamoDB
    "chat_history": list      # Historico atualizado
}

Exemplo de Uso:

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:

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:

{
    "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:

from tools import dynamo

history = dynamo.read_memory("joao.silva")
for msg in history:
    print(f"{msg['role']}: {msg['content']}")

Retorno Exemplo:

[
    {"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:

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:

{
    "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