Para validar os limites de acesso de uma integração Anthropic, separe o ambiente de teste, use uma credencial restrita e transforme cada restrição em um caso verificável: chamada permitida, recurso inacessível, chave inválida, excesso de tráfego e parada por orçamento. A aprovação depende de observar a reação da aplicação, não apenas de receber uma resposta do Claude.
Este roteiro trata da API direta do Claude. Conectores dos aplicativos têm controles próprios; consulte o catálogo de integrações Anthropic Claude para identificar o produto usado. Os passos abaixo são recomendações de engenharia; códigos, escopos e cabeçalhos citados vêm da documentação oficial indicada nas fontes.
Resumo rápido
- Use workspace e segredos próprios para homologação, com dados fictícios.
- Compare limites do workspace com os da organização antes de gerar tráfego.
- Teste permissão, autenticação, taxa e orçamento separadamente.
- Simule falhas caras no cliente; não esgote a cota da organização para provar um bloqueio.
- Guarde resultado esperado, resultado observado e evidência sem credenciais.
1. Defina o que a integração pode acessar
Comece pelo contrato de acesso. Escreva qual serviço fará as chamadas, qual workspace utilizará e quais recursos precisa consultar. Distinga a autorização no fornecedor da autorização no seu sistema. Uma chave aceita pela API não prova que o usuário pode ler qualquer documento do seu banco ou acionar qualquer ferramenta do agente.
Para um classificador de documentos, por exemplo, o contrato pode permitir enviar texto fictício ao modelo e gravar a classificação em uma tabela de teste. Consultar arquivos de produção ou alterar cadastros reais fica fora do escopo. Esse inventário impede uma homologação enganosa: o modelo responde corretamente enquanto o aplicativo usa uma conexão administrativa ampla demais.
Monte uma ficha com responsável técnico, ambiente, identificador da credencial, workspace esperado, recurso permitido e recurso proibido. Anote também onde o segredo está guardado e quem pode substituí-lo. Use identificadores internos, nunca o valor da chave. O guia de permissões para agentes de IA ajuda a separar leitura e escrita nos sistemas conectados.
Defina o sinal de aprovação antes da execução. “Acesso negado” precisa significar que a chamada foi recusada e nenhum efeito ocorreu. Uma tela mostrando erro, enquanto uma tarefa assíncrona continua escrevendo no banco, reprova o teste. Confira tanto a resposta quanto os efeitos persistidos.
2. Prepare workspace, identidade e orçamento
A documentação de workspaces permite separar projetos e ambientes dentro de uma organização. Para homologação, configure um workspace específico e limites inferiores aos da organização. Os limites organizacionais continuam valendo. A página de limites informa que o Default Workspace não permite configurar limites próprios; escolha outro para esse roteiro.
Crie uma credencial exclusiva do teste. A documentação de autenticação distingue chaves pessoais, de contas de serviço e chaves legadas de workspace. Para uma carga compartilhada ou sem operador, ela orienta usar conta de serviço. Restrinja a chave ao workspace necessário, guarde-a em um gerenciador de segredos e defina expiração compatível com o período do ensaio.
Não copie o arquivo de configuração de produção inteiro. Prepare uma lista explícita das variáveis permitidas e revise os destinos de banco, fila, armazenamento e alertas. Uma integração pode chamar o workspace correto e ainda enviar o resultado para um CRM real. A separação deve abranger todo o trajeto da informação.
Estabeleça um teto local de chamadas, tempo e concorrência, além do orçamento no Console. O limite do fornecedor é uma proteção adicional; seu teste deve conseguir parar sozinho. Registre quem interrompe a execução e qual evento dispara a parada. Confirme essas condições com uma execução curta antes de aumentar a carga.
3. Transforme barreiras em uma matriz de testes
Altere uma variável de cada vez. Primeiro confirme uma chamada mínima válida. Depois execute os casos negativos mantendo o restante da configuração igual. Caso contrário, uma requisição malformada pode ser recusada antes da verificação que você pretendia testar, dando falsa impressão de proteção.
| Caso | Preparação recomendada | Critério de aprovação |
|---|---|---|
| Chamada permitida | Mensagem curta e credencial de teste válida | Resposta recebida e ambiente identificado |
| Credencial inválida | Valor fictício no cliente isolado | Falha clara, sem fallback para segredo de produção |
| Recurso de outro workspace | Recurso fictício criado em segundo workspace de teste | Conteúdo não retornado nem copiado para logs |
| Taxa excedida | Limite baixo e concorrência controlada | Fila desacelera e novas tentativas têm teto |
| Orçamento bloqueado | Resposta simulada no adaptador HTTP | Processamento para e responsável recebe alerta |
| Credencial substituída | Troca do segredo no ambiente isolado | Nova chave funciona e a antiga deixa de ser utilizada |
O teste entre workspaces deve usar somente recursos artificiais criados para isso. Não descubra identificadores reais de outro cliente para “ver se passa”. Se a integração não trabalha com recursos persistentes da API, adapte o caso para a fronteira que existe no seu aplicativo, como a separação de documentos por empresa.
Para cada linha, registre preparação, requisição sanitizada, resposta e estado final. Uma evidência suficiente pode ser a combinação de um identificador de execução, código de resposta e consulta ao registro fictício. Evite guardar prompts completos quando bastam metadados.
4. Diferencie erros e valide a recuperação
A referência de erros descreve 401 para autenticação, 403 para permissão, 404 para recurso não encontrado e 429 para limitação de taxa. Isso não permite concluir que toda recusa de acesso terá 403. A documentação de autenticação informa que a seleção de um workspace inexistente ou inacessível, com chave que não é restrita a um workspace, pode retornar 404.
Por isso, teste o contrato do endpoint utilizado e leia o corpo do erro. Não transforme um 404 automaticamente em autorização para criar um recurso substituto. Também não mude para outra chave quando ocorrer 401. Uma recuperação que usa credencial mais poderosa pode esconder exatamente o defeito que a homologação precisava encontrar.
Para o 429 temporário, a página de limites documenta retry-after, em segundos, quando fornecido. Nem todo 429 traz esse cabeçalho. Inspecione a causa antes de agendar novas tentativas; um bloqueio por gasto não se resolve repetindo a chamada. Configure fila, espera crescente e quantidade máxima de tentativas como decisões do seu aplicativo.
Verifique a configuração do SDK e do seu próprio adaptador para não multiplicar tentativas. Se ambas as camadas repetirem automaticamente, uma tarefa pode durar muito mais que o prazo esperado. Simule uma sequência de falhas, conte as chamadas efetivas e confira se o cancelamento chega aos trabalhadores em execução.
Faça o teste de retomada: depois da espera ou da correção da credencial, o trabalho deve continuar sem duplicar registros. Separe uma tentativa de geração de texto de uma ação de negócio. Repetir uma geração pode ser aceitável; reenviar uma notificação exige controle próprio de duplicidade.
5. Leia os limites sem provocar uma falha cara
Registre os valores atuais de requisições e tokens disponíveis no Console. A Rate Limits API também oferece consulta programática aos limites da organização e dos workspaces. Essa leitura é útil para guardar um retrato da configuração antes do ensaio, em vez de depender de uma captura antiga compartilhada em uma conversa.
Compare três situações: carga curta, carga sustentada e pequena rajada. Use mensagens fictícias equivalentes e mantenha um teto total. O objetivo é verificar a disciplina da fila sob condições diferentes. Não faça um teste de exaustão indiscriminado para descobrir a capacidade máxima da conta.
Em respostas autenticadas que resolvem um workspace, o cabeçalho anthropic-workspace-id ajuda a confirmar onde a chamada ocorreu. Ele pode estar ausente quando a autenticação falha e em requisições administrativas que não resolvem um workspace. Trate essa ausência conforme o contexto, sem classificá-la automaticamente como erro da sua instrumentação.
Use simulação para cenários que exigiriam gastos desnecessários. O simulador verifica como o cliente trata a resposta; ele não demonstra que a configuração remota está correta. Complete a evidência com a leitura do Console ou da API administrativa. Essa distinção deixa claro o que foi observado de verdade e o que foi exercitado artificialmente.
Exemplo: classificador fiscal em Belo Horizonte
Considere um escritório de contabilidade em Belo Horizonte preparando um classificador de documentos. O exemplo é ilustrativo. A equipe cria um workspace de homologação e uma conta de serviço, utiliza documentos inteiramente inventados e aponta o resultado para um banco separado.
O primeiro caso envia um documento fictício e confirma a resposta. O segundo substitui a chave por um valor inválido: o aplicativo deve parar sem procurar outro segredo. No terceiro, uma fixture HTTP devolve um erro de orçamento e a fila deve suspender novos trabalhos. A ficha registra expressamente que esse último caso foi simulado.
Para a taxa, a equipe configura um limite reduzido e executa um conjunto curto de mensagens. Observa o tempo entre tentativas e confere se o cancelamento encerra o lote. Depois repete uma tarefa interrompida e verifica que a tabela não contém classificações duplicadas. O sucesso depende desses comportamentos observáveis, sem inventar um ganho de produtividade.
O relatório final separa aprovação do cliente, revisão da configuração remota e pendências. Um responsável libera a passagem para produção apenas quando as três partes têm evidências. O roteiro geral de testes de agentes antes da produção complementa os ensaios de acesso com avaliação da qualidade das respostas.
Erros comuns
- Confundir resposta correta com autorização correta. Confira também identidade, recurso e efeitos produzidos.
- Usar a chave de produção para acelerar. Um segredo exclusivo torna o encerramento do teste controlável.
- Forçar gasto para testar bloqueio. Combine simulação do cliente com inspeção da configuração remota.
- Repetir todo erro. Classifique a causa e imponha limite de tempo e tentativas.
- Registrar segredos no relatório. Guarde identificadores e evidências sanitizadas.
- Declarar sucesso sem testar retomada. Verifique cancelamento, troca da chave e duplicidade.
Perguntas frequentes
Workspace é um sandbox gratuito?
Workspace é uma divisão de uso e recursos da organização. Não presuma gratuidade para chamadas de teste; confirme as condições da conta no Console e controle o consumo. Separar o ambiente organiza a validação, mas não elimina a necessidade de orçamento.
Preciso testar todos os modelos disponíveis?
Teste os modelos e endpoints que a integração realmente utiliza. Registre a configuração escolhida e repita o conjunto relevante quando ela mudar. Uma homologação genérica não comprova o comportamento de caminhos que nunca foram exercitados.
Um 404 comprova que o identificador não existe?
Não necessariamente. A documentação de autenticação prevê 404 também para determinados casos de workspace inacessível. A aplicação deve preservar a recusa, sem tentar contorná-la ou revelar detalhes adicionais ao usuário.
Quando repetir a homologação?
Repita os casos afetados após alterar credencial, identidade, workspace, limites, SDK ou lógica de recuperação. Mantenha o relatório anterior para comparar comportamento e documente qualquer caso que passou a exigir nova evidência.
