Seu agente precisa ler a agenda de um cliente, enviar uma mensagem da conta dele ou abrir um chamado em nome dele. A versão rápida é manter uma conta de serviço com amplo acesso e agir através dela. Cada ação aparece como "a integração", ninguém consegue saber qual usuário acionou o quê, e uma credencial comprometida expõe todas as contas que você toca.
A versão correta é a autorização delegada: o usuário concede ao seu agente um token com escopo definido e revogável, o agente atua como esse usuário, e o registro de auditoria os nomeia. Foi para isso que o OAuth 2.0 foi construído. O que o torna incômodo para os agentes é que o OAuth pressupõe um navegador e uma pessoa presente para clicar em "Permitir", e os agentes rodam em segundo plano às 3 da manhã.
Este guia aborda qual fluxo OAuth se encaixa em um agente, como definir o escopo e armazenar tokens, o que fazer sobre atualização e revogação, e como testar todo o caminho sem uma conta real. Se você ainda está escolhendo entre autenticação baseada em chave e autenticação delegada, nossa comparação entre chaves de API e OAuth é o lugar para começar.
Apidog ajuda com a parte que as equipes subestimam: exercitar todos os ramos do fluxo, incluindo expiração e revogação, antes que um agente os encontre em produção.
Conta de serviço ou acesso delegado
Escolha deliberadamente, porque os dois modelos falham de maneiras diferentes.
Uma conta de serviço é a própria identidade do seu agente, com suas próprias permissões. Ela se adequa ao trabalho que o agente faz em seu nome: ler seu próprio banco de dados, chamar seus próprios serviços internos, executar trabalhos agendados em sua infraestrutura. Defina seu escopo de forma restrita, como em nossa postagem sobre chaves de API de privilégio mínimo para agentes de IA, e rotacione-a.
O acesso delegado é o agente agindo como um usuário específico, com as permissões desse usuário e nada mais. É necessário sempre que os dados pertencem a outra pessoa. Três propriedades fazem com que valha a pena o trabalho extra: o usuário pode ver o que foi concedido, o usuário pode revogá-lo, e cada ação leva sua identidade no registro.
O modo de falha a ser evitado é uma conta de serviço com acesso a toda a organização usada para agir "como" usuários. Funciona, e significa que uma única credencial vazada expõe a todos, sem revogação por usuário e sem um registro de auditoria honesto.
Qual fluxo se encaixa em um agente
O OAuth 2.0 define vários tipos de concessão, e apenas alguns fazem sentido aqui. A especificação OAuth 2.0 tem o conjunto completo; estes são os que você usará.
Código de autorização com PKCE. O fluxo padrão para agir como um usuário. O usuário é redirecionado para o provedor, aprova os escopos, e seu serviço troca o código por tokens. O PKCE protege a troca e agora é a recomendação padrão para todos os tipos de cliente, de acordo com a Melhor Prática de Segurança OAuth 2.0. Nosso passo a passo da concessão de código de autorização cobre a mecânica passo a passo.
O ponto específico do agente: este fluxo é executado uma vez, com o humano presente, no momento da conexão. O agente nunca o executa. Ele usa o token de atualização que o fluxo produziu. Separe esses dois momentos em seu design e a maioria das inconveniências desaparecerá.
Credenciais de cliente. Máquina a máquina, sem envolvimento do usuário. Correto para contas de serviço e errado para agir como um usuário, porque não há usuário para consentir.
Concessão de autorização de dispositivo. Para agentes em máquinas sem navegador. O usuário recebe um código e aprova em seu telefone. Útil para agentes de CLI e ambientes headless.
Troca de token. A RFC 8693 permite que um serviço troque um token por um mais restrito. É assim que você dá a um sub-agente um token limitado a um escopo para uma tarefa, derivado da concessão mais ampla do usuário, sem entregar o original. Se você executa sistemas multiagente, este é o mecanismo que torna as credenciais por agente práticas, e ele se encaixa nas regras de fronteira de nossa postagem sobre transferência de contexto multiagente.
Escopo restritamente, e por agente
Os escopos são onde o acesso delegado se justifica, e onde a maioria das implementações fica preguiçosa ao solicitar tudo o que o aplicativo possa precisar.
Solicite apenas o que este agente faz. Um agente de agendamento precisa de escrita no calendário e nada mais. Nem e-mail, nem contatos, nem arquivos. Os usuários leem a tela de consentimento, e uma longa lista é tanto um problema de confiança quanto um problema de raio de explosão. Nosso explicativo sobre escopos OAuth 2 aborda como os provedores os modelam.
Pergunte incrementalmente. Solicite o mínimo no momento da conexão, depois solicite mais quando o usuário pedir um recurso que precise. O consentimento ligado a uma solicitação concreta é mais fácil de conceder e mais fácil de justificar.
Dê a cada agente seu próprio token. Se um agente de pesquisa e um agente de faturamento agirem para o mesmo usuário, derive dois tokens com escopos diferentes em vez de compartilhar um. Assim, um agente de pesquisa comprometido não pode emitir reembolsos, e o log informa qual agente agiu.
Prefira escopos de leitura por padrão e exija uma escalada explícita para escritas. Combine isso com um portão de aprovação em chamadas destrutivas, como em nossa postagem sobre guardrails para agentes de IA, para que um token que pode escrever não seja a única coisa entre o agente e um erro.
Armazenar, atualizar e revogar
Tokens são credenciais, então trate-os como credenciais.
Armazenamento. Criptografe tokens de atualização em repouso, com chave por usuário. Nunca os escreva em logs, nunca os coloque em prompts e nunca deixe um modelo vê-los. Um token em contexto é um token em seu armazenamento de rastreamento, nos logs de seu provedor e, possivelmente, em um resumo. Nossa postagem sobre rastreamento de chamadas de ferramentas de agente aborda a redação na fronteira, em vez de no momento da leitura.
Atualização. Tokens de acesso são de curta duração por design. O agente nunca deve gerenciar isso sozinho; um gerenciador de tokens na frente do cliente HTTP atualiza quando a expiração está próxima e tenta a chamada novamente uma vez em um `401`.
class TokenManager:
def __init__(self, store, provider):
self.store, self.provider = store, provider
def access_token(self, user_id, agent_scope):
rec = self.store.get(user_id, agent_scope)
if rec.expires_in() > 60:
return rec.access_token
fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
self.store.save(user_id, agent_scope, fresh) # rotation: store the new refresh token
return fresh.access_token
Dois detalhes importam. Os provedores estão cada vez mais rotacionando tokens de atualização, emitindo um novo a cada atualização e invalidando o antigo, então persista o novo imediatamente ou você bloqueará o usuário. E serialize as atualizações por usuário, já que duas atualizações concorrentes com um provedor rotativo irão competir e uma perderá.
Revogação. Usuários revogam acesso, tokens expiram, administradores removem contas. O agente deve tratar `401` e `403` como terminais, não como passíveis de nova tentativa. Tentar novamente uma falha de autenticação nunca ajuda e pode acionar proteções contra abuso. Retorne uma mensagem clara nomeando o usuário e o escopo para que um humano possa agir, seguindo os padrões de erro em nossa postagem sobre design de mensagens de erro de API para agentes de IA.
O problema do consentimento
A parte incômoda dos agentes mais OAuth: o consentimento exige um humano, e os agentes funcionam sem supervisão.
Separe o tempo de conexão do tempo de execução e isso se torna gerenciável. No tempo de conexão, uma pessoa autoriza uma vez, com um navegador, e você armazena um token de atualização. No tempo de execução, o agente usa essa concessão sem envolvimento humano. Isso funciona para agentes agendados e em segundo plano, que é a maioria deles.
Dois limites a planejar. As concessões expiram, às vezes após meses de não uso, às vezes por política. Detecte uma concessão expirada, interrompa a execução e notifique o usuário, em vez de falhar silenciosamente todas as noites. E o consentimento tem um limite de escopo: um agente que precisa de um escopo que o usuário nunca concedeu deve pedir, em vez de escalar por conta própria.
Para qualquer coisa de alto risco, adicione um segundo portão no momento da ação. O token prova que o agente pode agir; um portão de aprovação decide se ele deve. Essas são perguntas diferentes e ambas merecem uma resposta.
Teste o fluxo antes que um agente o encontre
Os caminhos de código de autenticação são a parte menos testada da maioria das integrações, porque exercitá-los manualmente significa clicar nas telas de um provedor.
Construa estes cinco casos:
- Caminho feliz. Um token de acesso válido, uma chamada bem-sucedida. A base.
- Token de acesso expirado. O provedor retorna `401`, o gerenciador atualiza, a chamada tenta novamente uma vez e é bem-sucedida. Este é o caminho real mais comum e frequentemente o menos testado.
- Token de atualização revogado. A atualização retorna `invalid_grant`. O agente deve parar e relatar, não entrar em loop.
- Escopo insuficiente. Um `403` com um erro de escopo. O agente não deve tentar novamente e deve dizer qual escopo está faltando.
- Atualização concorrente. Duas chamadas para o mesmo usuário ao mesmo tempo. Exatamente uma atualização deve ocorrer.
Execute-os contra mocks. No Apidog, você pode definir o endpoint de token e os endpoints protegidos, então simular cada resposta, incluindo os corpos de erro, para que toda a matriz seja executada sem tocar em um provedor real. Nossa postagem sobre execução de agentes contra mocks em vez de produção aborda o hábito mais amplo, e nosso guia de teste de API OAuth 2 aborda o detalhe em nível de requisição.
Três integrações e o que elas precisam
Um assistente de calendário. Lê a disponibilidade e agenda reuniões para um usuário. Acesso delegado, dois escopos, consentimento no momento da conexão em um navegador, execuções em segundo plano depois. A falha interessante é a revogação: o usuário desconecta a integração e a execução noturna deve perceber e parar em vez de tentar novamente uma concessão morta por uma semana.
Um agente de suporte dentro de uma caixa de entrada compartilhada. Age em chamados pertencentes a uma equipe. Aqui a questão da identidade se torna mais nítida. Agir como a conta compartilhada da equipe é defensável, já que o recurso genuinamente pertence à equipe, mas toda resposta então parece idêntica no log de auditoria. Melhor é uma identidade de bot com seus próprios escopos mais um registro de qual humano acionou a execução, o que mantém a atribuição intacta sem fingir que o agente é uma pessoa.
Um agente de operações interno. Reinicia serviços e lê dashboards em sua própria infraestrutura. Sem dados de usuário, sem delegação. Uma conta de serviço com escopos restritos é a resposta correta, e o trabalho se concentra na rotação e no raio de explosão, em vez de no consentimento.
A linha divisória é a propriedade. Se os dados pertencem a alguém que poderia razoavelmente querer revogar seu acesso, use autenticação delegada. Se pertencer a você, use uma conta de serviço e gaste o esforço em definir o escopo.
Mantenha o humano na atribuição
A autenticação delegada responde "em nome de quem". Não responde "a pedido de quem", e para o trabalho do agente, você quer ambos. Um token prova que o agente pode agir como um usuário; não registra qual pessoa solicitou a execução.
Mantenha essa segunda identidade próxima ao trabalho. Onde os agentes executam tarefas atribuídas, a camada de gerenciamento de trabalho é o local natural: uma Tarefa Sharkly registra a pessoa responsável pelo trabalho juntamente com o Agente ou Equipe atribuída para executá-lo, o que mantém a responsabilidade humana e a execução do agente como dois fatos separados e visíveis. A documentação da Sharkly descreve essa divisão em detalhes. De qualquer forma que você o armazene, a pergunta de auditoria após um incidente geralmente é "quem pediu por isso", e um token sozinho não pode respondê-la.
Não deixe o modelo reter a credencial
Uma regra arquitetural previne a maioria dos incidentes de autenticação em sistemas de agentes: o modelo nunca vê um token.
Os tokens são injetados pelo executor na camada HTTP, depois que o modelo escolheu uma ferramenta e produziu argumentos. O esquema da ferramenta não possui um parâmetro `token`, o prompt não contém credenciais, e a resposta que o modelo lê tem o cabeçalho `Authorization` removido.
Isso é mais importante para agentes do que para clientes comuns por causa de onde a entrada do modelo viaja. Qualquer coisa em contexto pode ser resumida em uma transferência, gravada em um rastreamento, repetida em uma mensagem de erro ou retornada a um usuário que pediu ao agente para se explicar. Nenhum desses caminhos é hostil; são todos recursos normais que se tornam vazamentos no momento em que uma credencial está no escopo.
A mesma regra se aplica à identidade do usuário. O executor sabe para qual usuário esta execução age, e seleciona o token a partir disso. Permitir que o modelo nomeie o usuário é uma decisão de autorização tomada pelo componente menos previsível do sistema.
Uma lista de verificação
- Acesso delegado sempre que os dados pertencerem a um usuário, contas de serviço apenas para seus próprios recursos.
- Código de autorização com PKCE no momento da conexão, concessão de dispositivo para máquinas sem interface gráfica.
- Escopos solicitados por agente, mínimos, escalonados incrementalmente.
- Sub-agentes recebem tokens trocados, não cópias da concessão do usuário.
- Tokens de atualização criptografados em repouso e nunca em prompts, logs ou rastreamentos.
- Atualização gerenciada por um gerenciador de tokens, serializada por usuário, rotação persistida.
- `401` e `403` tratados como terminais, com uma mensagem nomeando o usuário e o escopo.
- Concessões expiradas detectadas e exibidas para o usuário, não tentadas novamente todas as noites.
- Ações de alto risco protegidas por aprovação, além do token.
- Todos os cinco cenários de autenticação testados contra mocks no CI.
A autenticação delegada dá mais trabalho do que uma chave compartilhada, e ela lhe oferece as duas coisas de que você precisa quando um agente age por outras pessoas: o usuário pode retirá-la, e o registro diz quem fez o quê. Baixe o Apidog para construir o fluxo de token e seus casos de falha antes que um agente o execute sem supervisão.
Perguntas frequentes
O agente pode completar o fluxo de consentimento OAuth sozinho? Não, e não deveria tentar. O consentimento exige que uma pessoa decida o que conceder. Peça a um humano para autorizar uma vez através de um fluxo de navegador normal, então deixe o agente usar a concessão resultante.
Cada agente deve ter seu próprio cliente OAuth? Clientes separados por integração de produto e tokens separados por agente dentro dela, geralmente via troca de tokens. Clientes distintos ajudam quando os provedores aplicam limites de taxa por cliente ou quando você deseja revogação independente.
O que acontece se o token de atualização girar e eu perder o novo? O usuário fica bloqueado e precisa se reconectar. Persista o novo token de atualização na mesma transação que consome o antigo e serialize as atualizações por usuário para que dois trabalhadores não entrem em conflito.
É seguro deixar o modelo ver um token de acesso? Não. Tokens pertencem à camada HTTP, injetados pelo seu executor. Qualquer coisa que um modelo vê pode acabar em um rastreamento, um resumo ou uma resposta, conforme abordado em nossa postagem sobre chaves de API de privilégio mínimo para agentes de IA.
Como audito qual agente fez o quê? Registre o ID do usuário, o nome do agente, o escopo usado e o identificador do token em cada chamada, nunca o próprio token. Nossa postagem sobre rastreamento de chamadas de ferramentas de agente aborda a forma do registro.
E se o provedor não oferecer suporte à troca de tokens? Armazene concessões separadas por agente onde o provedor permite múltiplas, ou imponha o estreitamento do escopo em seu próprio gateway para que as chamadas de cada agente sejam filtradas para suas operações permitidas antes que saiam de sua rede.