> ## 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 utilizadores atuarem por eles

> A Didit permite que as pessoas aprovem agentes de IA para atuarem por elas, numa sessão limitada que expira sozinha e pode ser revogada.

O acesso de agentes do Didit Authentication permite que as pessoas que usam a sua aplicação aprovem os seus próprios agentes de IA para agirem em seu nome.
A pessoa vê o que o agente pede, aprova-o, e o agente recebe uma sessão própria, com âmbito limitado, que termina automaticamente e que a pessoa ou a sua equipa pode revogar a qualquer momento.
O seu backend distingue o pedido de um agente do pedido da pessoa através da reivindicaçã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 atuar em nome de uma pessoa na sua aplicação, indicando os âmbitos de que precisa.
2. A pessoa inicia sessão no ecrã de aprovação alojado pela sua aplicação ou no seu próprio ecrã de consentimento, e vê o nome do agente, se está verificado e os âmbitos que pede.
3. A pessoa pode restringir o pedido (menos âmbitos, uma sessão mais curta, apenas algumas das suas [organizações](https://docs.didit.me/pt/authentication/organizations.md)) e depois aprová-lo, com uma nova chave de acesso quando as suas definições o exigirem.
4. O agente recebe um código de utilização única e troca-o pelos seus próprios tokens. Os tokens de acesso duram no máximo 5 minutos, tal como os de uma pessoa.
5. Cada pedido que o agente faz ao seu back-end inclui um token cuja declaração `act` identifica o agente e os âmbitos que a pessoa aprovou.

A sessão do agente termina quando expira o seu tempo de vida, após o tempo limite de inatividade definido por si, ou quando a pessoa ou a sua equipa a revogam.

## Ativar e escolher as regras

O acesso de agentes está desativado numa aplicação nova.
Ative-o em **Authentication > Agent access** e, depois, escolha **Edit settings**:

| Definição | Opções | Predefinição |
| - | - | - |
| O que os agentes podem fazer | **Read only** (`read`): ver as informações da conta da pessoa. **Acts for them** (`act`): alterar as definições e preferências da conta da pessoa. | Nenhuma até escolher |
| Que agentes podem pedir | Atualmente, qualquer agente pode pedir, e o ecrã de aprovação mostra se está verificado. Permitir apenas agentes verificados ainda não está disponível. | Qualquer agente |
| Duração de uma sessão | 1, 7 ou 30 dias. | 7 dias |
| Termina após inatividade de | 30 minutos, 2 horas ou 24 horas. | 2 horas |
| Como as pessoas aprovam | **A passkey**, ou **Their usual sign-in**. | A passkey |
| Só as pessoas aprovam pedidos de agentes | Cada aprovação exige uma nova asserção da passkey da própria pessoa que aprova. | Desativado |

As pessoas podem desativar qualquer âmbito que disponibilize no ecrã de aprovação, mas nunca o ativar.
As alterações aplicam-se a novas aprovações: as sessões de agente ativas mantêm o que a pessoa aprovou.

**Only people approve agent requests** (`agent_humans_only`) só pode ser alterada por um Owner ou Admin da sua organização Didit, que precisa primeiro de uma passkey na sua própria conta da consola.
Comprova que a pessoa que aprova usou o seu próprio autenticador com verificação do utilizador, nos últimos cinco minutos e associado a esse pedido; não deteta automação em geral.
Para o seu próprio ecrã de consentimento, as chamadas estão em [aprovação de agente com passkey](https://docs.didit.me/pt/authentication/sign-in-methods.md#aprovação-de-agentes-com-passkey).

## Integrar na sua aplicação

Os agentes que o suportam encaminham as pessoas para o seu ecrã de aprovação por iniciativa própria.
A sua aplicação faz duas coisas:

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

**Verifique a declaração `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 só `act` os distingue:

| `act` | Quem chama | O que permitir |
| - | - | - |
| `null` | A pessoa. | O que a pessoa pode fazer. |
| `{"sub", "agent", "scopes"}` | Um agente de IA a atuar em nome da pessoa. | Apenas o que `act.scopes` concede, nas rotas que abrir a agentes. Rejeite-o em todas as outras. |

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

## Acompanhar e revogar na consola

**Authentication > Agent access** mostra:

* **At a glance:** sessões de agente ativas, sessões aprovadas por pessoas nos últimos 7 dias, pessoas com um agente e revogações deste mês, por pessoas e pela sua equipa.
* **Active agent sessions:** cada pessoa, o agente com a respetiva descrição e se está verificado, o que pode fazer, a última atividade e quando termina, com um botão **Revoke**.

![A página Agent access na Didit Business Console, com as definições do agente, as métricas principais e as sessões de agente ativas com um botão Revoke](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 termina de imediato a sessão do agente, e pode enviar um e-mail à pessoa a informar que a sessão terminou.
A sua equipa também pode terminar todas as sessões de agente de uma pessoa: bloquear uma pessoa, repor o respetivo MFA ou revogar as suas sessões em **Users** também revoga o respetivo acesso ao agente.

## E-mails e eventos

Quando a sua equipa revoga o acesso de um agente a partir da consola, pode optar por enviar um e-mail à pessoa para a informar de que o acesso foi terminado. O e-mail usa a sua marca, tal como acontece com todos os [e-mails de início de sessão](https://docs.didit.me/pt/authentication/branding-and-custom-domain.md#emails-de-início-de-sessão).

As aprovações e as revogações são registadas como eventos `security.agent_access_approved` e `security.agent_access_revoked` na cronologia da pessoa. O Didit regista uma aprovação quando a pessoa dá o seu consentimento, mesmo que o agente nunca troque o seu código. Consulte o [registo de auditoria de aprovação do agente](https://docs.didit.me/pt/authentication/events-and-webhooks.md#auditoria-de-aprovação-de-agentes).


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