89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# Runbook - Captain Tools, Pix e Daniela (blindagem)
|
|
|
|
## Objetivo
|
|
Documentar o estado atual do fluxo de reservas/Pix e das ferramentas do Captain para evitar regressao quando houver novas mudancas.
|
|
|
|
## Escopo
|
|
- Ferramentas do Captain (tools) usadas pela Jasmine/Daniela.
|
|
- Geracao de Pix com expiracao de 1h e reemissao.
|
|
- Exposicao das ferramentas na UI (poderes/capacidades) e fallback por ferramenta.
|
|
|
|
## Principais mudancas feitas
|
|
1) Pix com expiracao e reemissao
|
|
- Pix expira em 1 hora.
|
|
- Se houver Pix pendente e expirado, gera novo Pix.
|
|
- Se ainda valido, reenvia o Pix existente.
|
|
- Arquivos:
|
|
- enterprise/app/models/captain/pix_charge.rb
|
|
- enterprise/app/services/captain/inter/cob_service.rb
|
|
- enterprise/app/services/captain/tools/generate_pix_tool.rb
|
|
- enterprise/lib/captain/tools/scenario_delegator_tool.rb
|
|
|
|
2) Ferramentas do Captain listadas na UI
|
|
- list_reservations adicionada ao catalogo de tools.
|
|
- Ferramentas com configuracao local (nao webhook) aparecem sem bloco de configuracao.
|
|
- faq_lookup continua visivel, mas sem toggle de ligar/desligar.
|
|
- Arquivos:
|
|
- config/agents/tools.yml
|
|
- enterprise/app/services/captain/tools/definitions.rb
|
|
- app/javascript/dashboard/routes/dashboard/captain/assistants/tools/Index.vue
|
|
|
|
3) Fallback personalizado por ferramenta
|
|
- Cada tool pode ter fallback_message opcional.
|
|
- Se tool falhar e houver fallback, resposta usa esse texto.
|
|
- Excecoes sem fallback custom: faq_lookup, react_to_message.
|
|
- Arquivos:
|
|
- db/migrate/20260116000000_add_fallback_message_to_captain_tool_configs.rb
|
|
- enterprise/app/controllers/api/v1/accounts/captain/tools_controller.rb
|
|
- enterprise/app/services/captain/tools/tool_runner.rb
|
|
- enterprise/app/services/captain/llm/assistant_chat_service.rb
|
|
|
|
4) Correcoes de schema das tools (evitar erro type)
|
|
- RubyLLM espera parametros como RubyLLM::Parameter.
|
|
- BaseTool converte schema JSON em parametros.
|
|
- JasmineBrain imprime schema correto no prompt.
|
|
- Arquivos:
|
|
- enterprise/app/services/captain/tools/base_tool.rb
|
|
- enterprise/app/services/captain/tools/check_availability_tool.rb
|
|
- enterprise/app/services/captain/tools/create_reservation_intent_tool.rb
|
|
- enterprise/app/services/captain/llm/jasmine_brain.rb
|
|
|
|
## Sintomas conhecidos quando quebra
|
|
- Jasmine responde "Desculpe, estou com dificuldades tecnicas..." apos um simples "Ola".
|
|
- Erro no log: undefined method 'type' for an instance of String.
|
|
- Causa tipica: tool parameters em formato incorreto (schema JSON cru).
|
|
|
|
## Testes rapidos (smoke)
|
|
1) Saudacao simples
|
|
- Mensagem: "Ola"
|
|
- Esperado: resposta normal da Jasmine (sem erro tecnico).
|
|
|
|
2) Reserva com Pix novo
|
|
- Mensagem: "Quero reservar a suite Stilo dia 20/01 as 14h."
|
|
- Esperado: consulta disponibilidade, cria intencao, pede CPF se nao houver, gera Pix novo.
|
|
|
|
3) Pix expirado
|
|
- Repetir pedido apos >1h.
|
|
- Esperado: "Pix expirado. Gerando um novo agora." e Pix novo.
|
|
|
|
4) Consultar reservas
|
|
- Daniela deve poder chamar listar reservas quando cliente perguntar "em nome de quem".
|
|
|
|
## Comandos de log curtos
|
|
- Erro de tool schema:
|
|
rg -n "undefined method 'type'" log/development.log | tail -n 5
|
|
|
|
- Falha de tools do Captain:
|
|
rg -n "ScenarioDelegatorTool|LLM Error" log/development.log | tail -n 20
|
|
|
|
- Execucao das ferramentas de reserva/Pix:
|
|
rg -n "CreateReservationIntentTool|GeneratePixTool|CheckAvailabilityTool" log/tool_debug.log | tail -n 20
|
|
|
|
## Observacoes importantes
|
|
- Nao alterar formato de tool parameters sem validar com RubyLLM::Parameter.
|
|
- Se adicionar nova tool, usar BaseTool e preferir tool_parameters_schema.
|
|
- Sempre reiniciar Rails apos mudar tools, schema ou defs.
|
|
|
|
## Responsavel por revisao
|
|
- Antes de qualquer mudanca: rodar os testes rapidos e verificar logs curtos.
|