Contrato `FALHA_CONSULTA`¶

Mecanismo central de comunicação de erro entre as tools e o agente. Sem ele, o LLM tenta adivinhar / inventar horários.

Definição¶

Quando a tool falha por qualquer motivo "controlado" (timeout, dado inconsistente, convênio não aceito, agenda vazia), retorna uma string que começa com FALHA_CONSULTA:.

return f"FALHA_CONSULTA: convenio nao encontrado: {nome_convenio}"

Todos os prefixos conhecidos:

FALHA_CONSULTA: medico 'X' nao possui agendamento automatico
FALHA_CONSULTA: medico 'X' nao encontrado
FALHA_CONSULTA: convenio nao encontrado: Y
FALHA_CONSULTA: procedimento 'Z' nao encontrado
FALHA_CONSULTA: agenda sem horarios disponiveis
FALHA_CONSULTA: nenhum medico tem horarios disponiveis
FALHA_CONSULTA: erro ao consultar horarios apos 2 tentativas
FALHA_CONSULTA: agenda retornada nao bate com o medico esperado
FALHA_CONSULTA: slot indisponivel (pode ter sido ocupado)
FALHA_CONSULTA: cadastro de paciente falhou
FALHA_CONSULTA: erro interno: <detalhe>
FALHA_CONSULTA: resposta vazia

Regras para o agente (no system prompt)¶

SE uma ferramenta retornar string iniciando com "FALHA_CONSULTA":
  1. NAO tente chamar a ferramenta novamente no mesmo turno.
  2. NAO invente horarios, datas, ou confirmacoes.
  3. Responda ao paciente que houve uma dificuldade e transfira.
  4. Chame transferir_atendimento(motivo="FALHA_CONSULTA + detalhe").

Tratamento típico pelo agente¶

Paciente: "Pode marcar amanha as 14h com a Dra Joana?"

Tool consultar_horarios(...) -> "FALHA_CONSULTA: agenda sem horarios disponiveis"

Agente (mensagem final):
"Não encontrei horários disponíveis na agenda da Dra. Joana no momento.
Vou te encaminhar para um atendente que consegue verificar alternativas."

Tool transferir_atendimento(motivo="FALHA_CONSULTA: agenda sem horarios") -> OK

Por que não exceção¶

Se a tool lança exceção, o agente aborta (LangGraph transforma em erro). O workflow captura e devolve fallback genérico — mas o agente não tem chance de escolher uma mensagem boa para o paciente.

FALHA_CONSULTA dá ao LLM uma oportunidade de parafrasear o erro em linguagem natural apropriada ao contexto.

Logs¶

Toda FALHA_CONSULTA deve deixar rastro:

logger.error("FALHA: %s", mensagem)
log_error(error_type="falha_consulta", error_message=mensagem, ...)

Dashboard/alertas podem agrupar por motivo e alertar se volume sobe.

E os erros "não-controlados"?¶

Exceções não previstas (ex: json.JSONDecodeError pois OTIMUS devolveu HTML) sobem. O run_agent captura, loga em dashboard_errors, e retorna uma mensagem genérica:

Desculpe, tive um problema tecnico. Um atendente ja foi acionado.

E transfere a sessão.

Não use FALHA_CONSULTA para sucesso-parcial¶

Se a tool tem resposta mas incompleta (ex: 1 slot em vez de 4), retorne o que tem. Deixe o agente decidir o que fazer.

FALHA_CONSULTA é não-actionable: o agente deve transferir, não tentar continuar.

Contrato FALHA_CONSULTA¶