UI do Agente
Telas onde um agente de IA lê, propõe ou altera algo real têm um trabalho: permitir que uma pessoa veja o que o agente fez,
decida o que ele pode fazer a seguir e confie em ambos. Estas são as regras e as verificações para isso, em qualquer framework e com qualquer
sistema de design. Se o projeto usar Candor UI, o skill candor-ui nomeia o componente para cada trabalho; este skill diz
o que a tela deve fazer, independentemente de quem a desenha.
Como trabalhar
Antes de uma tela, responda a três perguntas e mantenha as respostas à vista enquanto constrói:
- O que o agente pode fazer aqui: apenas ler, propor para uma pessoa aplicar ou agir por conta própria? Cada controle decorre disso.
- O que a pessoa decide e com base em quais evidências? Uma decisão precisa da coisa em si (o diff, os alvos, o
valor), não de uma descrição dela. Leia
references/approvals.mdse algo for aprovado aqui. - O que não pode ser desfeito? Essas ações informam isso, confirmam com mais rigor e nunca ficam sob um padrão ou uma única tecla.
Enquanto constrói, mantenha as nove regras abaixo, use as palavras de status em references/status-and-states.md e mostre
progresso da maneira que references/progress.md indica. Texto de modelo é dado: mostre-o, nunca o execute ou renderize.
Após cada tela, execute references/review-checklist.md contra a tela em execução, uma linha por verificação, e corrija
o que falhar antes de prosseguir. Marque apenas o que você verificou, não o que pretendia.
As nove regras
Cada uma é expandida com exemplos em references/honesty-rules.md.
- Saída do modelo é texto, nunca marcação. Mostre o que o modelo escreveu como texto (no máximo um subconjunto seguro de markdown).
Uma URL que ele escreveu é texto, não um link. Nada do que ele escreve chega a
innerHTML. - Desconhecido permanece desconhecido. Uma duração, custo ou contagem que não foi medido é deixado vazio ou diz "não medido". Uma estimativa diz "estimativa" e no que se baseia. O silêncio de uma execução não é "em execução".
- Um controle que não pode ser usado diz por quê. Bloqueie-o com um motivo que um usuário de teclado e leitor de tela possa alcançar; não
disablee deixe as pessoas adivinhando. - Nada é pré-selecionado em uma decisão. Aprovar e negar, manter e descartar começam sem nenhum escolhido. Enter nunca aprova. A recomendação do agente é marcada, não selecionada.
- Aprovar a alteração exata. A decisão está vinculada à alteração que a pessoa viu (um hash ou versão). Se a alteração mudar, pergunte novamente. A auto-aprovação é recusada onde a política disser; produção pode precisar de uma segunda pessoa.
- Raciocínio é acreditado, não verificado. O relato do modelo sobre o porquê é uma alegação. Rotule-o como tal e mantenha-o separado das evidências (fontes, resultados de teste, o diff).
- O aplicativo nomeia o agente. Toda mensagem do agente carrega um nome dos próprios dados do aplicativo. Linhas de sistema são strings do aplicativo. Nada que o modelo escreve se torna um nome ou uma mensagem de sistema.
- Diga o que pode e não pode ser desfeito. Antes de uma ação destrutiva: o que ela remove, se volta, como e por quanto tempo. Após um desfazer ou restaurar: o que não foi desfeito.
- Movimento segue o resultado. Uma animação relata uma mudança que aconteceu; nunca prevê ou decora uma. Uma
marca de sucesso é desenhada após o resultado se estabilizar, o progresso preenche apenas até o que foi medido, um estado que já era
final quando a tela foi desenhada não anima, e a configuração de movimento reduzido do sistema operacional vence. Dê a cada animação um tipo
de mudança (Candor nomeia quatorze famílias de movimento, listadas em
references/honesty-rules.md) e deixe um tema mudar como ela parece, nunca quando ela toca.
O que ler para quê
| Quando a tela tem… | Leia |
|---|---|
| Algo que uma pessoa aprova, permite ou nega | references/approvals.md |
| Execuções, chamadas de ferramentas, etapas, status, pontos | references/status-and-states.md |
| Um agente trabalhando por mais de um momento, ou terminando enquanto a pessoa está ausente | references/progress.md |
| Uma IA que fala com pessoas, ou conteúdo que uma IA fez | references/disclosure-and-accessibility.md |
| Qualquer coisa, antes de prosseguir | references/review-checklist.md |
Palavras
Simples e medidas. Diga o que aconteceu, para quem e o que fazer a seguir. Caixa de frase, sem pontos de exclamação, sem superlativos, sem afirmações que os dados não carregam. Status é uma palavra com uma cor ao lado, nunca cor sozinha. Números apenas quando medidos; caso contrário, as palavras "estimativa" ou "não medido".