> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Acesso de agentes de IA: deixe os agentes dos seus usuários agirem por eles

> Com a Didit, usuários aprovam agentes de IA para agir por eles numa sessão com escopo limitado, que expira sozinha e pode ser revogada.

A autenticação da Didit com acesso de agentes permite que as pessoas que usam o seu aplicativo aprovem os próprios agentes de IA para agir em nome delas. A pessoa vê o que o agente está pedindo, aprova, e o agente recebe uma sessão própria, com escopo limitado, que se encerra automaticamente e que a pessoa ou a sua equipe pode revogar a qualquer momento. O seu backend diferencia a requisição de um agente da requisição da pessoa pela declaração `act` no token.

O acesso de agentes está incluído em todos os planos, sem preço separado.

## Como funciona

1. Um agente de IA pede para agir em nome de uma pessoa na sua aplicação, informando os escopos de que precisa.
2. A pessoa faz login na tela de aprovação hospedada da sua aplicação ou na sua própria tela de consentimento, e vê o nome do agente, se ele é verificado e quais escopos ele solicita.
3. A pessoa pode restringir a solicitação (menos escopos, uma sessão mais curta, apenas algumas das suas [organizações](https://docs.didit.me/pt-br/authentication/organizations.md)) e, em seguida, aprová-la, com uma nova chave de acesso quando as suas configurações exigirem.
4. O agente recebe um código de uso único e o troca pelos seus próprios tokens. Os tokens de acesso dele valem no máximo 5 minutos, assim como os de uma pessoa.
5. Toda requisição que o agente faz ao seu backend carrega um token cujo claim `act` identifica o agente e os escopos que a pessoa aprovou.

A sessão do agente termina quando o seu tempo de vida expira, após o tempo limite de inatividade configurado por você, ou quando a pessoa ou a sua equipe a revoga.

## Ative e escolha as regras

O acesso de agentes vem desativado em uma aplicação nova.
Ative-o em **Authentication > Agent access** e, em seguida, clique em **Edit settings**:

| Configuração | Opções | Padrão |
| - | - | - |
| O que os agentes podem fazer | **Somente leitura** (`read`): ver as informações da conta da pessoa. **Agir em nome dela** (`act`): alterar as configurações e preferências da conta da pessoa. | Nenhuma até você escolher |
| Quais agentes podem pedir acesso | Qualquer agente pode pedir hoje, e a tela de aprovação mostra se ele é verificado. Permitir somente agentes verificados ainda não está disponível. | Qualquer agente |
| Duração da sessão | 1, 7 ou 30 dias. | 7 dias |
| Encerra após ficar ocioso por | 30 minutos, 2 horas ou 24 horas. | 2 horas |
| Como as pessoas aprovam | **Uma passkey** ou **O login habitual delas**. | Uma passkey |
| Somente pessoas aprovam pedidos de agentes | Cada aprovação exige uma nova asserção da passkey própria da pessoa que aprova. | Desativado |

As pessoas podem desativar, na tela de aprovação, qualquer escopo que você oferecer, mas nunca podem ativar um escopo.
As alterações valem para as novas aprovações: as sessões de agentes ativas mantêm o que a pessoa aprovou.

**Somente pessoas aprovam pedidos de agentes** (`agent_humans_only`) só pode ser alterada por um Owner ou Admin da sua organização na Didit, que precisa antes ter uma passkey na própria conta do console.
Ela comprova que a pessoa que aprova usou o próprio autenticador com verificação do usuário, dentro de cinco minutos e vinculado àquele pedido; ela não detecta automação de modo geral.
Para a sua própria tela de consentimento, as chamadas estão em [aprovação de agente com passkey](https://docs.didit.me/pt-br/authentication/sign-in-methods.md#aprovação-de-agente-com-passkey).

## Adicione ao seu app

Agentes que oferecem suporte a isso encaminham as pessoas para a sua tela de aprovação por conta própria.
Seu app faz duas coisas:

**Permita que as pessoas vejam e revoguem os seus agentes.**
No React, renderize `<ConnectedAgents />` na página de configurações da conta: ela lista os agentes que a pessoa aprovou, cada um com um botão **Revogar**.
Veja o [guia rápido do React](https://docs.didit.me/pt-br/authentication/quickstarts/react.md).

**Verifique o claim `act` no seu backend.**
O token de acesso de um agente é assinado com a mesma chave e tem os mesmos `typ`, `iss` e `aud` que o de uma pessoa, por isso somente o `act` os diferencia:

| `act` | Quem está chamando | O que permitir |
| - | - | - |
| `null` | A pessoa. | O que a pessoa pode fazer. |
| `{"sub", "agent", "scopes"}` | Um agente de IA agindo em nome da pessoa. | Somente o que `act.scopes` concede, nas rotas que você abre para agentes. Rejeite-o em todas as outras rotas. |

O `sid` no token de um agente é o ID do acesso que a pessoa concedeu, e `GET /session/` sempre rejeita o token de um agente.
Veja [verificar um token no seu servidor](https://docs.didit.me/pt-br/authentication/tokens-and-jwks.md#verificar-um-token-no-seu-servidor) para as verificações em código.

## Acompanhe e revogue no console

**Authentication > Agent access** mostra:

* **Visão geral:** sessões de agentes ativas, sessões que as pessoas aprovaram nos últimos 7 dias, pessoas com um agente e revogações neste mês, por pessoas e pela sua equipe.
* **Sessões de agentes ativas:** cada pessoa, o agente com sua descrição e se ele é verificado, o que ele pode fazer, sua última atividade e quando termina, com um botão **Revogar**.

![A página Agent access no Business Console da Didit, com as configurações do agente, as métricas principais e as sessões de agentes ativas com um botão Revogar](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-agent-access.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=7cc518e37e2ccafa5515eb22e6ef9b8d)

Authentication > Agent access.

Revogar encerra a sessão do agente imediatamente, e você pode enviar um e-mail à pessoa informando que a sessão foi encerrada.
Sua equipe também pode encerrar todas as sessões de agentes de uma pessoa: bloquear uma pessoa, redefinir o MFA dela ou revogar as sessões dela em **Users** também revoga o acesso dela ao agente.

## E-mails e eventos

Quando sua equipe revoga o acesso de um agente pelo console, você pode optar por enviar um e-mail à pessoa informando que o acesso foi encerrado.
O e-mail usa a sua marca, como todo [e-mail de login](https://docs.didit.me/pt-br/authentication/branding-and-custom-domain.md#e-mails-de-login).

As aprovações e revogações são registradas como os eventos `security.agent_access_approved` e `security.agent_access_revoked` na linha do tempo da pessoa.
A Didit registra uma aprovação quando a pessoa dá consentimento, mesmo que o agente nunca troque o código.
Consulte a [auditoria de aprovação do agente](https://docs.didit.me/pt-br/authentication/events-and-webhooks.md#auditoria-de-aprovação-de-agente).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.