APIs seguras para agentes de IA: escritas rastreáveis

Um agente de IA não torna uma API perigosa por si só. Uma API se torna perigosa quando oferece verbos amplos, resultados ambíguos e erros que obrigam o chamador a adivinhar. Operadores humanos compensam isso com contexto, cautela e uma mensagem rápida no chat. Um agente compensa com novas tentativas e outra chamada de ferramenta. Essa diferença transforma um timeout inofensivo em dois reembolsos, duas implantações ou um registro excluído sem que ninguém pretendesse isso.

APIs seguras para agentes de IA tornam pequena a ação permitida, fazem com que escritas repetidas não causem danos e deixam um rastro que uma pessoa pode acompanhar depois. Isso é trabalho de desenho de API, não de prompt. Um prompt pode dizer ao agente para ter cuidado, mas o endpoint ainda precisa recusar uma ação que esteja fora do contrato.

Já vi equipes colocarem telas de aprovação diante de um endpoint administrativo genérico e chamarem isso de controle. Não basta. Se a chamada aprovada significa «alterar qualquer coisa nesta conta», a aprovação pede que uma pessoa examine, sob pressão, um conjunto de consequências ocultas. Coloque a precisão primeiro na API. Assim, a aprovação terá algo compreensível para aprovar.

Verbos amplos fazem os agentes adivinhar

Um agente deve chamar uma operação cujo nome, entradas e efeitos colaterais caibam em uma frase. Endpoints amplos obrigam o agente a inferir regras de negócio a partir de campos genéricos, exemplos antigos ou um erro que diz apenas «requisição inválida». É aí que começa a improvisação insegura.

Considere um endpoint como POST /admin/execute, com um payload que contém action e JSON arbitrário. Um cliente escrito por uma pessoa pode usar apenas cinco ações hoje, mas o endpoint apresenta todas as ações atuais e futuras a qualquer chamador que receba acesso. O servidor não consegue comunicar um limite de permissão útil, e um aprovador não consegue saber o que o agente fará sem ler o payload como se fosse código-fonte.

Substitua-o por operações que deem nome à transição de estado:

• POST /projects/{project_id}/deployments cria uma implantação a partir de uma revisão especificada.
• POST /invoices/{invoice_id}/refunds cria um reembolso com valor e motivo explícitos.
• POST /users/{user_id}/access-revocations remove o acesso de um usuário identificado.
• POST /exports inicia uma exportação definida, com uma categoria de dados declarada.

Essas operações ainda podem oferecer riscos. A questão é que cada uma dá ao servidor um lugar para impor regras: transições válidas, limites de valor, propriedade do alvo, aprovações obrigatórias e um campo de motivo onde ele realmente faz sentido.

Não confunda uma interface CRUD genérica com uma interface útil para agentes. PATCH /customers/{id} convida o chamador a alterar qualquer campo editável. Se alterar billing_email for uma tarefa comum, mas alterar tax_status iniciar um processo de conformidade, essas mudanças não devem ficar atrás do mesmo patch casual. Crie uma operação específica para a transição relevante e faça o modelo de entrada refletir a decisão.

Uma operação restrita também melhora a recuperação. Quando um agente diz «a requisição de implantação expirou», um operador pode procurar uma única criação de implantação. Quando ele diz «o comando administrativo expirou», o operador primeiro precisa descobrir qual comando foi montado.

Coloque as precondições na requisição

As escritas devem declarar a condição sob a qual fazem sentido. Uma requisição que aprova uma despesa pode incluir o estado de revisão esperado. Uma requisição que atualiza um documento pode incluir a versão lida. Se o estado mudou, o servidor deve recusar a escrita em vez de aplicá-la silenciosamente a uma realidade diferente.

O HTTP já oferece mecanismos úteis. A RFC 9110 define requisições condicionais por meio de cabeçalhos como If-Match; o servidor pode recusar uma etiqueta de entidade desatualizada com 412 Precondition Failed. Você também pode expor um campo expected_version quando isso se encaixar melhor na sua API. A escolha importa menos que a disciplina: o cliente precisa indicar a versão ou o estado que pretende alterar.

Não aceite um campo de cliente como force: true para servir de saída de emergência em todo conflito. Esse campo costuma virar uma forma de os agentes atropelarem exatamente a verificação de segurança que você adicionou. Reserve uma substituição para uma operação separada, outro nível de autorização e um registro de auditoria visível.

Uma escrita precisa de uma identidade separada da tentativa HTTP

Toda escrita visível externamente deve ter um identificador de idempotência fornecido pelo cliente. O servidor o usa para reconhecer que várias tentativas de entrega expressam a mesma ação pretendida.

Um ID de requisição e um identificador de idempotência resolvem falhas diferentes. Um gateway ou servidor geralmente cria um ID de requisição para cada tentativa HTTP. Se a rede cair depois que o servidor confirmar a escrita, mas antes de a resposta chegar ao chamador, a nova tentativa receberá outro ID de requisição. O identificador de idempotência precisa continuar igual, porque a escrita pretendida não mudou.

A sequência habitual de falha é esta:

1. O agente envia uma requisição para criar um pagamento.
2. Seu servidor armazena o pagamento e chama um provedor externo.
3. A conexão falha antes que o agente receba a resposta de sucesso.
4. O agente vê um resultado desconhecido e tenta novamente.
5. Seu servidor cria outro pagamento porque recebeu uma nova requisição HTTP.

A política de novas tentativas não causou o defeito. A API causou o defeito ao tratar a entrega como intenção.

Use um cabeçalho ou campo de requisição criado pelo cliente antes da primeira tentativa e preservado até que ele receba uma resposta definitiva. Nomes de cabeçalhos HTTP costumam usar Idempotency-Key, embora o identificador não precise ser secreto. Um UUID aleatório funciona bem. Não o derive apenas de um timestamp e não use um identificador que possa colidir entre escritas sem relação.

Armazene a impressão digital da requisição e o resultado

O servidor precisa associar o identificador de idempotência a mais do que uma indicação de status. Armazene a identidade do chamador, a rota de destino, uma impressão digital canônica do corpo da requisição semanticamente relevante e o resultado completo necessário para reprodução. Quando o mesmo chamador tentar novamente com o mesmo identificador e a mesma impressão digital, retorne a resposta original. Quando o corpo for diferente, recuse a requisição com um conflito.

O rascunho da IETF «The Idempotency-Key HTTP Header Field» descreve esse cabeçalho como uma forma de tornar métodos HTTP não idempotentes tolerantes a falhas. O alerta sobre exclusividade é importante: o cliente não deve reutilizar um valor para uma requisição diferente. Eu iria um passo além na implementação. Faça o servidor impor essa regra, porque agentes tentam novamente, reiniciam e às vezes reutilizam um estado que um cliente humano teria descartado.

Um contrato compacto pode ser assim:

POST /v1/projects/prj_48/deployments
Idempotency-Key: 8c8d77c1-4ef9-4fae-b0ba-5480f686ce4c
Content-Type: application/json

{
  "revision": "a1b2c3d4",
  "environment": "staging",
  "expected_project_version": 17
}

Na primeira chamada aceita, retorne um recurso e os dois identificadores:

{
  "request_id": "req_01J8X7QK3JZ6",
  "deployment": {
    "id": "dep_01J8X7R5G2",
    "state": "queued",
    "revision": "a1b2c3d4",
    "environment": "staging"
  }
}

Se o agente repetir a requisição idêntica depois de um timeout, retorne o mesmo dep_01J8X7R5G2, não uma segunda implantação. Se ele mudar environment para production mantendo o identificador, retorne um conflito que deixe a correção clara:

{
  "error": {
    "code": "idempotency_payload_mismatch",
    "message": "This idempotency identifier belongs to a deployment request with different parameters.",
    "request_id": "req_01J8X84S9P2V"
  }
}

Mantenha os registros de idempotência pelo menos durante o período em que novas tentativas realistas do cliente e a recuperação de tarefas podem ocorrer. Um período de retenção muito curto cria uma duplicação tardia que parece intermitente em produção. Se a pressão por armazenamento exigir expiração, documente o intervalo com clareza e faça os consumidores escolherem um comportamento de tentativa compatível com ele.

Tentar novamente só faz sentido quando o resultado é conhecido o suficiente

Um agente deve repetir falhas de transporte e algumas respostas temporárias selecionadas, mas nunca deve inventar uma ação nova para escapar da incerteza. As classes de resposta precisam tornar essa escolha possível.

A RFC 9110 define 429 Too Many Requests e permite Retry-After; respeite esse mecanismo quando o enviar. O chamador pode esperar o período indicado, preservar o identificador de idempotência e enviar a mesma requisição. Para uma falha temporária do servidor, retorne uma resposta 5xx com um ID de requisição e indique se o servidor aceitou a operação. Não use um 500 genérico para uma falha de validação ou uma recusa de autorização. Isso ensina aos clientes o comportamento errado de novas tentativas.

Para escritas assíncronas, aceitação e conclusão são fatos diferentes. Uma resposta 202 Accepted deve retornar um recurso de operação que identifique o trabalho e seu estado. Depois de um timeout, o agente pode consultar esse recurso em vez de reenviar um efeito colateral.

{
  "request_id": "req_01J8X9FW7GH2",
  "operation": {
    "id": "op_01J8X9FTVX",
    "state": "running",
    "status_url": "/v1/operations/op_01J8X9FTVX"
  }
}

O recurso de status precisa de mais que running e failed. Inclua um estado terminal, uma referência ao resultado quando houver sucesso e um código público de falha quando o worker não puder concluir o trabalho. Uma implantação que falhou nas verificações de integridade, por exemplo, não deve parecer uma falha de transporte da API. O agente precisa informar ou corrigir a falha da implantação; deve repetir apenas uma falha de conexão quando o servidor nunca aceitou a requisição.

Evite novas tentativas automáticas para ações que enviam e-mails, cobram dinheiro, alternam credenciais ou chamam sistemas externos, a menos que seu servidor controle a deduplicação até o efeito final. A idempotência no banco de dados não impede dois e-mails se um worker cair depois de o provedor de e-mail aceitar a mensagem, mas antes de o worker registrar a conclusão. Use um registro outbox com uma referência estável de deduplicação no provedor quando ele oferecer esse recurso. Se o sistema externo não puder deduplicar, torne a operação observável e exija uma decisão humana depois de um resultado desconhecido.

Os erros precisam dizer ao chamador como corrigir a requisição

Mensagens de erro úteis descrevem o contrato que falhou, não o constrangimento do servidor. Um agente consegue trabalhar com um erro preciso. Ele não consegue trabalhar com segurança com uma página de erro HTML, um rastreamento de pilha ou «entrada inválida» depois de uma requisição com dez campos.

Retorne um envelope JSON consistente para toda falha esperada. Inclua um code estável para programas, uma message concisa para registros e pessoas, um ID de requisição e detalhes por campo quando for seguro expô-los. A RFC 9457, «Problem Details for HTTP APIs», oferece uma estrutura padrão com campos como type, title, status, detail e instance. Você não precisa adotar todos os campos para aprender sua lição central: erros fazem parte do contrato da API, não são texto incidental.

Esta resposta informa exatamente ao agente o que mudar:

{
  "error": {
    "code": "invalid_state_transition",
    "message": "A refund can be created only for a paid invoice.",
    "request_id": "req_01J8XAS2D8M4",
    "details": {
      "invoice_id": "inv_204",
      "current_state": "draft",
      "allowed_states": ["paid", "partially_paid"]
    }
  }
}

Esta resposta provoca adivinhações:

{
  "error": "Request failed"
}

A segunda envia o agente de volta à documentação, ao código-fonte ou a chamadas exploratórias. Chamadas exploratórias contra uma API de escrita são como um pequeno defeito vira um incidente barulhento.

Não coloque segredos nos erros. Não repita cabeçalhos de autorização, tokens de acesso, URLs assinadas, consultas brutas ao banco de dados ou uma resposta de serviço externo que possa conter dados de outro cliente. Um padrão ruim é capturar toda exceção e devolver sua mensagem ao chamador. Isso facilita a depuração por um dia e cria um canal de exposição por anos.

Separe entrada inválida de autoridade insuficiente. 422 Unprocessable Content pode descrever um payload bem formado que viola uma regra de negócio. 403 Forbidden deve dizer que a operação solicitada exige uma permissão ou aprovação, sem revelar recursos que o chamador não pode consultar. 404 Not Found pode fazer sentido quando você pretende ocultar a existência do recurso. Escolha a semântica, documente-a e aplique-a de modo consistente.

Um bom erro também diz quando não adianta tentar novamente. invalid_state_transition, idempotency_payload_mismatch e approval_required devem interromper novas tentativas cegas. rate_limited, com um atraso para nova tentativa, e upstream_temporarily_unavailable podem permitir uma tentativa controlada. Essa distinção evita mais danos do que um prompt engenhoso para o agente.

IDs de requisição transformam uma ação contestada em uma investigação

Dê a cada requisição recebida um ID de requisição, devolva-o no corpo ou cabeçalho da resposta e carregue-o por toda chamada interna, mensagem de fila, tarefa de worker e chamada a um provedor externo. Quando um agente diz que não recebeu resposta, você precisa responder a duas perguntas diferentes: sua API aceitou a ação e o que cada componente fez depois?

Gere o ID de requisição no limite de confiança quando o chamador não fornecer um. Você pode aceitar um ID de correlação do chamador para o controle interno dele, mas não permita que um chamador não confiável substitua o identificador emitido pelo servidor. Mantenha os dois quando isso for útil. O identificador do servidor ancora seus registros; o identificador do chamador conecta uma sequência de decisões do agente.

Registre eventos estruturados em vez de montar linhas de texto que os operadores terão de analisar depois com expressões regulares. No mínimo, registre o ID da requisição, a identidade autenticada, o nome da operação, o recurso-alvo, o identificador de idempotência quando houver, a decisão de autorização, o status do resultado e referências aos recursos criados. Redija campos da requisição por esquema, não por um filtro textual aplicado às pressas. Um campo chamado token é fácil de ocultar. Uma credencial embutida em texto arbitrário não é.

O rastreamento deve preservar a ordem sem fingir que prova mais do que realmente prova. Um ID de requisição pode mostrar que sua API aceitou uma tarefa e que um worker enviou uma chamada ao provedor. Ele não prova que uma pessoa pretendia a ação, a menos que seu sistema registre essa decisão separadamente. Mantenha a distinção clara:

• Um registro de correlação conecta eventos pertencentes a uma requisição.
• Um registro de auditoria informa quem ou o que autorizou uma ação e o que o sistema fez.
• Um registro de idempotência impede uma escrita lógica duplicada.

As equipes costumam reunir tudo em uma única linha do banco de dados. Então a linha precisa atender a novas tentativas, depuração, análise de conformidade e histórico para o usuário, e não faz nenhuma dessas coisas com clareza. Você pode armazenar referências relacionadas juntas, mas preserve os significados separados no modelo de dados.

Para ações de maior risco, registre a requisição normalizada, o contexto de autorização, o resultado da política ou aprovação e um resumo do resultado em um fluxo de auditoria somente de acréscimo. Proteja esse fluxo da conta normal da aplicação. Caso contrário, um serviço comprometido poderá reescrever o histórico que o denunciaria.

O Sallyport adota uma abordagem útil para ações de agentes: registra sessões de agentes e chamadas individuais em um único registro de auditoria criptografado, encadeado por hash e sem acesso de escrita, e sp audit verify verifica a cadeia offline sem uma chave do cofre. Sua API ainda precisa dos próprios registros, porque um gateway pode mostrar que despachou uma chamada, enquanto somente seu serviço pode mostrar a transição de estado que confirmou.

O escopo da autenticação não corrige uma operação insegura

Credenciais de curta duração e escopos restritos reduzem o impacto de um incidente, mas não tornam seguro um endpoint amplo. Um token limitado a um projeto ainda pode destruir todas as implantações, exportar todos os dados permitidos ou disparar todas as ações administrativas disponíveis nesse projeto.

Vincule a autorização à operação e ao alvo. Um chamador autorizado a criar uma implantação não deve ser automaticamente autorizado a promovê-la para produção. Um chamador autorizado a revogar o acesso de um usuário não deve receber permissão para alterar o perfil de cobrança desse usuário apenas porque ambos ficam sob /users/{id}.

Mantenha o material de credenciais longe do agente sempre que puder. Um agente que recebe um token bearer pode copiá-lo para uma transcrição, um arquivo de depuração, o histórico do shell ou uma chamada a um serviço externo. Em vez disso, coloque o uso de credenciais atrás de um gateway de ações local ou de um broker no servidor que selecione a credencial para uma operação aprovada. O agente envia a intenção e os parâmetros; o componente confiável injeta o segredo apenas ao fazer a chamada externa.

Esse desenho não elimina a necessidade de validar parâmetros. Se um agente puder dizer url: https://anything.example, um helper HTTP que injeta credenciais pode virar uma ferramenta de exfiltração de segredos. Vincule credenciais a upstreams e métodos nomeados. Valide os hosts depois dos redirecionamentos e também antes deles. Para SSH, associe uma credencial a hosts conhecidos e, quando possível, a uma interface de comandos restrita, em vez de oferecer acesso arbitrário a um shell remoto.

A aprovação humana tem seu lugar, mas deve abranger uma ação pequena, com alvo e consequência visíveis. A aprovação por sessão responde «este processo de agente pode agir?». A aprovação por chamada responde «ele pode executar esta ação sensível específica agora?». Nenhuma das duas salva um endpoint cujo payload possa significar qualquer coisa.

A concorrência precisa de um perdedor explícito

A idempotência impede a entrega duplicada de uma intenção. Ela não resolve duas intenções diferentes que competem entre si. Se dois agentes lerem uma fatura no estado paid e ambos enviarem um reembolso total com identificadores de idempotência diferentes, seu servidor precisa decidir qual requisição vence.

Use uma transição de estado transacional quando o sistema de armazenamento permitir. A atualização deve incluir o estado esperado, e o servidor deve informar o conflito quando outro escritor o alterar primeiro. Um campo de versão, uma etiqueta de entidade ou uma atualização condicional dá à API uma forma de recusar uma intenção desatualizada, em vez de aplicá-la depois que os fatos mudaram.

Por exemplo, modele um reembolso como uma operação sobre o saldo ainda reembolsável, não como um comando cego que confia em um valor fornecido pelo cliente. Em uma transação, verifique o valor pago atual, subtraia os reembolsos anteriores, valide o valor solicitado, reserve o novo reembolso e crie o registro do reembolso. Um worker assíncrono separado pode chamar o provedor de pagamentos depois que essa reserva existir. Se o worker tentar novamente, ele retoma o mesmo registro de reembolso em vez de criar outro.

Não diga aos agentes para «verificar primeiro, agir depois» como seu único controle de concorrência. Um GET preliminar ajuda o agente a montar uma requisição útil, mas outro chamador pode mudar o estado entre a leitura e a escrita. O endpoint de escrita é responsável pela correção porque vê o estado real no momento da confirmação.

Projete o cancelamento com o mesmo cuidado. DELETE /operations/{id} não deve prometer que uma ação externa nunca ocorreu. Ele deve retornar o estado real do cancelamento: cancelamento solicitado, cancelado antes do despacho, concluído antes do cancelamento ou impossível de cancelar depois do despacho. Agentes e pessoas precisam de uma linguagem que reflita o limite entre seu sistema e o provedor externo.

Teste resultados desconhecidos antes que os agentes os encontrem em produção

Uma suíte de testes que verifica apenas uma resposta 200 ensina todos a ignorar a parte mais difícil das APIs de ação. Coloque os casos de falha em testes de contrato e execute-os contra um limite de serviço real, não apenas contra um handler simulado.

Para toda operação de escrita, teste uma sequência em que o servidor confirma o efeito e o cliente perde a resposta. Envie novamente o mesmo identificador de idempotência e verifique se o servidor retorna o recurso original. Depois envie esse identificador com um corpo alterado e verifique se o servidor retorna um conflito sem criar outro recurso.

Teste requisições concorrentes com identificadores de idempotência diferentes contra a mesma transição de estado. Verifique se uma é bem-sucedida e a outra recebe um erro específico de estado desatualizado ou regra de negócio. Se ambas forem bem-sucedidas em um banco de testes porque cada teste é executado sozinho, você não testou a propriedade que importa.

Teste o contrato de erro como dados. Verifique códigos de status, códigos de erro estáveis, nomes de campos e a presença de um ID de requisição. Não faça snapshot apenas da mensagem em português. Você melhorará o texto com o tempo; os clientes devem decidir com base em code, não na prosa.

Por fim, faça um exercício com os operadores. Escolha uma ação concluída, uma ação recusada, um timeout com confirmação bem-sucedida no servidor e uma falha assíncrona. Dê a um engenheiro apenas os IDs de requisição e peça que reconstrua o ocorrido. Se ele precisar pesquisar vários registros não relacionados, consultar uma transcrição do agente e adivinhar qual tentativa criou qual registro, corrija a instrumentação antes de permitir escritas sem supervisão.

A primeira ação que normalmente precisa de correção é o endpoint de escrita mais amplo. Divida-o em transições nomeadas, exija um identificador de idempotência e faça a resposta identificar o recurso resultante. Com esse contrato, os agentes podem agir rapidamente sem tratar cada instabilidade de rede como permissão para tentar algo diferente.