Confiabilidade no Envelope Instrucional

Este guia define um padrao pratico para construir envelopes instrucionais robustos em cenarios operacionais (agendamento, status, preparo, ticket e afins), com foco em reduzir alucinacao quando integracoes falham.

Ele complementa o uso de simpleEnvelopIO e nao substitui as referencias de contrato da API.

​

Problema que este guia resolve

Regras como “nao inventar” sao necessarias, mas insuficientes quando o contexto da API chega incompleto, nulo ou com erro.

Sem modo de falha seguro explicitamente definido, o LLM tende a continuar tentando cumprir a tarefa e preencher lacunas por inferencia estatistica.

​

Principios mandatórios de confiabilidade

1. Ausencia de dado = indisponivel

   • Se um dado necessario estiver ausente, nulo, vazio, contraditorio ou com erro de integracao, trate como indisponivel.
   • Nunca deduza, estime, complete ou improvise esse dado.

2. Fonte unica de verdade para dados operacionais

   • Dados operacionais so podem vir do contexto estruturado da API.
   • Memoria da conversa e conhecimento geral do modelo nao substituem dados operacionais ausentes.

3. Confirmacao so com evidencia explicita

   • So confirme agendamento, disponibilidade, status, preparo, protocolo ou validacao quando houver evidencia explicita no contexto.

4. Bloqueio deterministico de acoes sensiveis

   • Acoes como agendar, informar slots, validar status e passar preparo devem depender de pre-condicoes objetivas.

​

Politica de falha segura (obrigatoria)

Inclua no envelope uma politica explicita para casos error, timeout, partial, empty e unavailable.

Padrao recomendado:

• Se faltar dado critico para concluir a acao, informe brevemente indisponibilidade de consulta no momento.
• Nao concluir acao sem dados minimos.
• Nao oferecer alternativas inventadas.
• Nao converter falha tecnica em resposta operacional afirmativa.

​

Hierarquia de fonte da verdade

Use a hierarquia abaixo como regra fixa:

1. dados_operacionais da API (fonte primaria)
2. estado_da_integracao e flags deterministicas (controle de permissao)
3. memoria de conversa apenas para contexto de fluxo, nunca para preencher dado tecnico
4. conhecimento geral do modelo apenas para linguagem e formato, nunca para fato operacional

​

Contrato recomendado de payload para orquestracao

Evite contexto textual solto. Envie estado e dados de forma explicita.

Exemplo:

<estadoDaIntegracao>
agenda_api_status: error
ticket_api_status: success
preparo_api_status: unavailable
exame_api_status: success
</estadoDaIntegracao>

<dadosOperacionais>
horarios_disponiveis: null
preparo_exame: null
ticket_aberto: true
tipo_exame: "ressonancia"
</dadosOperacionais>

Regra obrigatoria no envelope:

Valores nulos, vazios, ausentes ou com status error, timeout, partial ou unavailable nao podem ser preenchidos pela IA.

​

Flags deterministicas para bloquear acao sensivel

Sempre que possivel, o orquestrador deve enviar flags booleanas de permissao de acao:

{
  "can_schedule": false,
  "can_inform_slots": false,
  "can_inform_preparation": false,
  "integration_error": true
}

Comportamento minimo:

• Se can_schedule=false, nao agendar.
• Se can_inform_slots=false, nao informar horarios.
• Se can_inform_preparation=false, nao passar preparo.

Esse bloqueio deve acontecer antes da geracao, reduzindo dependencia de inferencia do LLM.

​

Matriz de estados de integracao

​

Conflitos comuns de prompt e como corrigir

​

Conflito 1: proibicao de pergunta vs obrigacao de sugerir

Exemplo de conflito:

• “Nunca pergunte a data desejada”
• “Voce deve sugerir datas disponiveis”

Risco: com agenda_api_status=error, o modelo tenta inventar datas.

Correcao:

• Condicionar obrigacao de sugerir datas a can_inform_slots=true.
• Definir fallback obrigatorio quando essa condicao for falsa.

​

Conflito 2: coleta de turno sem disponibilidade consultavel

Exemplo de conflito:

• “Pergunte turno desejado quando o usuario pedir horarios”
• Integracao de agenda fora do ar

Correcao:

• Nao abrir subfluxo de coleta de turno quando can_inform_slots=false.

​

Conflito 3: preparo somente apos agendamento, mas preparo ausente

Risco: apos concluir agendamento, o modelo gerar preparo generico.

Correcao:

• Exigir can_inform_preparation=true + preparo_exame explicito para responder preparo.

​

Frases de fallback aprovadas

Forneca fallback pronto para remover improviso:

• “No momento nao consegui acessar as informacoes necessarias para seguir com o agendamento.”
• “Ainda nao tenho dados disponiveis para informar os horarios desse exame.”
• “Nao consigo confirmar essa informacao com seguranca agora.”
• “Assim que as informacoes estiverem disponiveis, consigo seguir com voce.”

Regras de uso:

• Respostas curtas e objetivas.
• Nao complementar com suposicoes, exemplos ilustrativos ou orientacoes inventadas.
• Nao confundir “sem horario disponivel” com “falha ao consultar horario”.

​

Bloco pronto para colar no envelope

Use como base em scopeAndLimits, uncertaintyAndVerification e fallbacksAndEscalation:

<politicaDeConfiabilidade>
- A fonte unica de verdade para dados operacionais e o contexto recebido da API.
- Nunca utilize conhecimento geral, memoria de conversa ou inferencia para preencher lacunas operacionais.
- Se qualquer dado necessario estiver ausente, nulo, vazio, contraditorio ou com falha de integracao, trate como indisponivel.
- Nesses casos, nao invente datas, horarios, preparos, status, confirmacoes, precos, servicos, protocolos ou proximos passos.
- Se nao houver dados suficientes para concluir a acao, informe apenas que nao foi possivel consultar as informacoes necessarias no momento.
- Nunca confunda "sem horarios disponiveis" com "falha ao consultar horarios". So informe indisponibilidade real quando vier explicitamente no contexto.
- Nunca confirme agendamento, reagendamento, ticket, preparo ou disponibilidade sem evidencia explicita no contexto.
</politicaDeConfiabilidade>

<respostasSegurasEmFalha>
- Quando faltar informacao critica, use respostas curtas e objetivas.
- Exemplos permitidos:
  - "No momento nao consegui acessar as informacoes necessarias para seguir com o agendamento."
  - "Ainda nao tenho dados disponiveis para informar os horarios desse exame."
  - "Nao consigo confirmar essa informacao com seguranca agora."
- Nao complemente essas respostas com suposicoes, exemplos ilustrativos ou alternativas inventadas.
</respostasSegurasEmFalha>

​

Checklist de validacao antes de publicar

• O envelope define explicitamente que ausencia de dado nao autoriza inferencia.
• O payload diferencia claramente empty de error para cada dominio critico.
• Existem flags deterministicas para bloquear acoes sensiveis.
• Ha fallback aprovado para indisponibilidade de consulta.
• Regras de prompt nao entram em conflito em cenarios de falha.

​

Cenários minimos de teste (obrigatorios)

1. Usuario pede horarios e agenda_api_status=error.
2. Usuario pede preparo e preparo_api_status=error.
3. Usuario pede status e ticket_api_status=timeout.
4. Contexto parcial (partial) com apenas parte dos campos criticos.
5. Exame valido, mas horarios_disponiveis ausente.
6. Exame valido com horarios_disponiveis=[] (vazio real).

Resultado esperado em todos os testes: nenhuma inferencia operacional sem evidencia.

​

Onde este guia se conecta

• Contrato de campos e exemplos de request/response: Simple Envelop IO
• Estrutura do pilar de envelope instrucional: Pilar 3 - Envelope Instrucional
• Visao geral do treinamento: Treinamento do Avatar