As citações da API do Claude ligam partes da resposta a passagens dos documentos enviados pela aplicação. Para usar o recurso, envie o conteúdo em blocos de documento, habilite citations e preserve as referências devolvidas junto de cada bloco de texto. A interface deve permitir abrir a fonte correspondente, com a mesma versão que o modelo recebeu.
Isso ajuda quem precisa conferir uma política comercial, um manual ou um procedimento antes de agir. A existência de uma referência não garante que a conclusão esteja correta: o trecho pode ser verdadeiro e insuficiente para sustentar uma interpretação ampla. O produto precisa mostrar a evidência e facilitar a revisão, especialmente quando documentos divergem.
Resumo rápido
- Habilite citações nos documentos e preserve a estrutura da resposta.
- Congele a versão consultada antes de gerar a resposta.
- Mostre a passagem ao lado da afirmação que ela deveria sustentar.
- Separe verificação da localização e avaliação do significado.
- Teste perguntas sem resposta e documentos contraditórios antes de liberar o assistente.
O que uma citação permite conferir
Em uma resposta comum, pedir “cite a cláusula” deixa a apresentação da referência por conta do modelo. Na API, o recurso de citações acrescenta dados de localização que a aplicação pode interpretar. A documentação de citações da Anthropic descreve referências por caracteres no texto, páginas no PDF e blocos no conteúdo personalizado. Os índices do documento identificam a fonte enviada.
Use essa estrutura para construir uma experiência verificável: a pessoa lê uma afirmação, abre a passagem e decide se há apoio suficiente. O botão “ver fonte” deve chegar ao documento certo. Abrir a pasta de arquivos e obrigar o usuário a procurar o trecho sozinho elimina boa parte da utilidade.
Há duas perguntas diferentes na revisão. A primeira é se o endereço da evidência é válido. A segunda é se a passagem sustenta a conclusão. Uma cláusula sobre entrega em dias úteis não permite concluir, sozinha, que um pedido específico chegará na sexta-feira. Faltam data do pedido, feriados e eventuais exceções. O sistema deve reconhecer essa lacuna.
Considere também a confiança na própria fonte. Um arquivo desatualizado pode produzir uma resposta perfeitamente referenciada e operacionalmente errada. Defina quem aprova documentos, como uma versão substitui outra e quando um arquivo deixa de ser elegível para consulta. Esses critérios pertencem ao negócio e devem anteceder o desenho da tela.
Como preparar documentos e habilitar o recurso
O seguinte fragmento ilustra o bloco enviado dentro de uma mensagem à API. Ele não contém credenciais nem escolhe uma versão de modelo. Configure esses valores no servidor e confira a referência de Messages para montar a chamada completa.
{
"type": "document",
"source": {
"type": "text",
"media_type": "text/plain",
"data": "Trocas por defeito devem ser encaminhadas à assistência."
},
"title": "Procedimento de atendimento aprovado",
"citations": {"enabled": true}
}A documentação determina habilitar citações em todos os documentos da solicitação ou em nenhum. Também distingue o conteúdo citável em source dos campos auxiliares title e context. Por isso, coloque uma regra que precise servir de evidência no corpo da fonte, em vez de escondê-la somente nos metadados.
Antes do envio, gere um identificador interno para a versão. Guarde o conteúdo exato consultado, a autorização de acesso e a associação entre a posição do documento na requisição e seu identificador. Se houver três manuais com nomes parecidos, o título exibido ao usuário deve ajudar a distinguir área, edição e situação de aprovação.
Evite mandar toda a biblioteca “por garantia”. Selecione fontes autorizadas e relevantes, registrando a seleção. O recurso de citação resolve a apresentação da evidência que chegou ao modelo; a seleção e o controle de acesso continuam responsabilidade da aplicação. O panorama da integração com Anthropic Claude ajuda a situar essa chamada dentro de uma implantação maior.
Escolher o formato e preservar a localização
O formato deve combinar com a forma como o usuário revisa o material. Texto simples facilita comparação e controle de versões; PDFs preservam uma organização familiar para equipes que trabalham com manuais paginados. Conteúdo personalizado pode refletir unidades de negócio bem definidas, como uma instrução completa por bloco.
| Formato | Referência retornada | Cuidado na interface |
|---|---|---|
| Texto simples | Intervalo de caracteres | Destacar sobre o texto exato enviado |
| PDF com texto | Intervalo de páginas | Abrir a edição consultada na página indicada |
| Conteúdo personalizado | Intervalo de blocos | Manter a ordem e a identidade dos blocos |
Os intervalos usam limite final exclusivo; páginas começam em um, enquanto posições de caracteres e blocos começam em zero. Trate essa convenção em uma única função testada. Não espalhe ajustes de índice por componentes da tela. A referência de citações traz os campos correspondentes a cada formato.
Para PDFs, consulte também o guia oficial de suporte a PDF. Ler a aparência de uma página e oferecer uma citação textual são capacidades distintas. Uma digitalização sem texto extraível exige preparação própria antes de servir como evidência textual. Confira o reconhecimento de caracteres com uma amostra, incluindo acentos, tabelas e rodapés.
Não normalize espaços, remova cabeçalhos ou traduza a fonte depois de receber a resposta e antes de destacar posições. Essas transformações podem deslocar a referência. Se uma visualização acessível precisar de outra representação, mantenha um mapeamento explícito entre as versões. Sem esse mapeamento, prefira apresentar a passagem citada com a identificação da fonte.
Montar uma resposta que continue auditável
Leia todos os blocos devolvidos, na ordem, e associe suas citações ao texto correspondente. Converter tudo em uma string e anexar uma lista de arquivos no fim dificulta saber qual fonte apoia cada frase. Uma resposta pode conter afirmações com graus diferentes de sustentação.
Na interface, apresente a passagem, o título, a versão e um caminho de abertura autorizado. Antes de servir o arquivo, cheque novamente a permissão do usuário. O fato de uma pessoa ter enviado a pergunta não implica acesso permanente a qualquer documento mencionado. Se a autorização mudou, informe que a fonte deixou de estar acessível sem revelar trechos protegidos.
Guarde um registro de auditoria enxuto: pergunta, identificadores das fontes, versão do fluxo, resposta estruturada e resultado da revisão. Estabeleça prazo para esse registro, porque perguntas e passagens também podem conter dados pessoais. Veja os cuidados complementares no guia de segurança e LGPD na implantação de IA.
Para uma experiência com texto aparecendo progressivamente, a documentação de streaming descreve eventos específicos para citações. Só marque uma referência como pronta quando sua estrutura tiver sido recebida. Se a conexão cair, sinalize resposta incompleta e não preserve um selo visual de verificação sobre uma geração parcial.
Se outro componente precisar de JSON estrito, planeje a arquitetura antes. A documentação atual registra incompatibilidade entre citações e structured outputs na mesma chamada. O guia de function calling e structured outputs explica a função desses esquemas. Uma opção de projeto é conservar a resposta citada como evidência e construir uma representação interna validada pela aplicação, sem inventar referências durante a conversão.
Exemplo: assistência técnica em Campinas
Imagine uma assistência de equipamentos comerciais em Campinas. Os atendentes consultam procedimentos de fabricantes e regras internas para orientar a abertura de uma ordem de serviço. O exemplo é ilustrativo e não pressupõe ganho de produtividade medido.
A pergunta é: “Posso prometer troca imediata para este equipamento?” A aplicação seleciona o procedimento vigente para aquele produto e a política comercial autorizada. Se o procedimento exige avaliação técnica e a política tem uma exceção para um lote específico, a resposta precisa mostrar as duas fontes e explicar quais dados ainda faltam.
O atendente abre a evidência e percebe que a exceção vale apenas para determinado número de série. Como esse número não foi informado, o assistente deve solicitar a identificação do equipamento. Uma resposta curta com essa pendência é mais útil do que uma conclusão categórica acompanhada de uma referência apenas parcialmente relevante.
Na aprovação do piloto, a responsável pela assistência escolhe perguntas reais anonimizadas. Para cada uma, registra a passagem esperada, a informação ausente e a conduta aceitável. A equipe inclui documentos antigos deliberadamente, verificando se o mecanismo de seleção consegue excluí-los. O teste avalia a implantação inteira, desde o catálogo até o clique na referência.
Quando o procedimento muda, a empresa cria uma versão nova e mantém a anterior apenas conforme sua política de guarda. Respostas históricas continuam associadas à versão antiga; respostas novas usam a edição aprovada. Assim, uma auditoria consegue reconstruir o que o atendente tinha disponível naquele momento.
Erros comuns
- Tratar citação como aprovação automática. Confira se a passagem sustenta a afirmação inteira, incluindo condições e exceções.
- Reordenar fontes sem atualizar o mapeamento. Uma posição válida pode passar a abrir outro arquivo quando o produto perde a associação original.
- Esconder ausência de evidência. Reserve uma apresentação clara para perguntas que o material enviado não resolve.
- Conservar só o nome do arquivo. Dois documentos podem compartilhar nome e conteúdo diferente. Registre a versão consultada.
- Publicar trechos sem autorização. A visualização da passagem deve respeitar os mesmos controles do documento completo.
- Medir apenas quantidade de citações. Uma resposta com muitas referências pode repetir a mesma evidência e continuar deixando a pergunta central sem resposta.
Um conjunto de testes útil inclui afirmação negada no documento, tabela com exceção, conflito de versões, pergunta sem resposta e arquivo ilegível. Registre separadamente localização correta, suporte semântico, respeito às permissões e clareza para o atendente. Essas categorias mostram onde corrigir o produto sem reduzir tudo a uma nota única.
Perguntas frequentes
Preciso montar uma busca vetorial para usar citações?
Não. Você pode enviar documentos selecionados pela própria aplicação. Uma busca pode ajudar a escolher fontes em uma biblioteca maior, mas não é requisito para testar uma resposta vinculada a um procedimento específico. Comece com um conjunto pequeno e controlado.
Uma fonte citada prova que a resposta está certa?
Não. Ela permite inspecionar a evidência. A revisão ainda precisa considerar escopo, contexto, exceções e atualização do documento. Decisões sensíveis devem ter critérios claros para encaminhamento a uma pessoa responsável.
Posso mudar o documento depois da geração?
Você pode publicar outra versão, mas deve manter a associação da resposta com a versão consultada enquanto essa resposta precisar ser auditada. Redirecionar silenciosamente uma referência histórica para uma edição nova compromete a conferência.
Como lidar com uma pergunta sem evidência suficiente?
Instrua o assistente a apontar a lacuna e peça os dados necessários. Na interface, diferencie informação sustentada, interpretação e pendência. Nos testes, rejeite respostas que preencham essa ausência com uma regra plausível inventada.
O que verificar antes de colocar em produção?
Teste o clique na fonte, os limites dos índices, documentos sem texto e bloqueio de acesso entre usuários. Faça a equipe do negócio revisar o significado das passagens. Confirme as compatibilidades na documentação oficial, porque a API evolui.
