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

# Revisões de agentes independentes

> Solicite revisão humana, colete decisões distintas e aplique o resultado final na sua aplicação.

As aprovações de agente registram decisões humanas sobre uma ação de agente proposta em um ambiente de espaço de trabalho. Elas são separadas das aprovações do mecanismo de fluxo de trabalho, concessões de permissão, recibos de ação criptográfica e execução Temporal.

## Antes de começar

* Use um agente ativo do mesmo espaço de trabalho e ambiente que sua credencial.
* Crie solicitações usando uma chave de API de espaço de trabalho ou um usuário de espaço de trabalho conectado.
* Os revisores devem ser membros humanos ativos do espaço de trabalho com a permissão `tenant:governance:approve` em nível de espaço de trabalho. Uma função apenas de organização é insuficiente.
* O solicitante não pode aprovar ou rejeitar sua própria solicitação. Cada revisor pode decidir uma vez. Chaves de API não podem votar humanamente.

No Console, abra **Agentes de IA → Aprovações de Agente**. Os formulários de solicitação, revisão e cancelamento têm cada um uma página dedicada. Salve o link da solicitação para retornar a ela depois que ela sair da fila de pendentes.

## Criar uma solicitação

Este exemplo solicita duas aprovações independentes em uma janela de uma hora. Substitua o identificador do agente por um agente de sandbox existente; um agente de produção não pode ser usado com uma credencial de sandbox.

```bash theme={null}
curl --fail-with-body https://sandbox-api.truthlocks.com/v1/approvals \
  -H "X-API-Key: $TRUTHLOCKS_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{
    "agent_id": "YOUR_SANDBOX_AGENT_ID",
    "action": "publish reviewed report",
    "resource": "reports/quarterly-review",
    "scope": "reports:publish",
    "risk_level": "high",
    "justification": "The report has completed technical review. Confirm the approved version before publication.",
    "required_approvals": 2,
    "ttl_minutes": 60
  }'
```

A resposta `201` contém `id`, `requested_by`, `status: "pending"`, `current_approvals: 0` e `expires_at`. Salve `id`; a criação não publica o relatório nem cria um fluxo de trabalho em segundo plano.

## Revisar com uma sessão humana

Use o Console para decisões interativas. Se sua integração usa a API, forneça a sessão de portador de espaço de trabalho de curta duração do revisor. Não substitua uma chave de API ou incorpore um token de sessão no código-fonte.

```bash theme={null}
curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID/approve" \
  -H "Authorization: Bearer $TRUTHLOCKS_REVIEWER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"reason":"Reviewed the exact report version and its supporting evidence."}'
```

A primeira aprovação neste exemplo retorna `status: "pending"` e `current_approvals: 1`. Um revisor autorizado diferente deve fornecer o segundo voto. Reutilizar o mesmo revisor retorna um conflito. Uma rejeição muda imediatamente a solicitação para `rejected`, independentemente de aprovações anteriores.

O serviço verifica as permissões de associação atuais, a propriedade da solicitação, a expiração e os votos existentes dentro da transação de decisão. Os votos e o evento de auditoria são confirmados juntos. As decisões não podem ser editadas ou excluídas por meio dessas APIs.

## Verificar e aplicar o resultado

```bash theme={null}
curl --fail-with-body "https://sandbox-api.truthlocks.com/v1/approvals/$APPROVAL_ID" \
  -H "X-API-Key: $TRUTHLOCKS_API_KEY"
```

A resposta detalhada inclui o histórico do revisor. Prossiga apenas quando `status` for `approved` e a solicitação ainda corresponder ao agente, ação, recurso e escopo exatos que sua aplicação pretende usar. Sua aplicação também deve impor as permissões de acesso atuais, o status do agente e seus próprios controles de uso único ou repetição. Esses registros de aprovação não fornecem um mecanismo automático de execução ou consumo.

| Status | Significado |
| - | - |
| `pending` | Mais aprovações independentes são necessárias. |
| `approved` | O quórum configurado foi atingido dentro da janela de revisão. |
| `rejected` | Um revisor independente rejeitou a solicitação. |
| `expired` | Uma solicitação pendente ultrapassou seu prazo de revisão. |
| `cancelled` | Seu solicitante original o cancelou. |

O prazo de revisão limita quando as decisões podem ser enviadas. Não transforma uma solicitação já aprovada em um token de acesso expirado. Defina qualquer prazo de execução em seu próprio aplicativo.

## Fila, cancelamento e erros

`GET /v1/approvals` retorna um array de no máximo 100 solicitações pendentes mais antigas e não expiradas. Não possui paginação ou filtro de status histórico. A fila omite o histórico de decisões individuais; busque uma solicitação por ID para esse histórico.

O solicitante original pode enviar `POST /v1/approvals/{approvalID}/cancel` com um `reason` não em branco. Uma solicitação não pode ser reaberta após cancelamento, rejeição, aprovação ou expiração. Crie uma nova solicitação se a ação proposta for alterada.

| Status HTTP | O que verificar |
| - | - |
| `400` | Limites de campo, um ID de pedido UUID e uma razão de decisão não vazia. |
| `403` | Permissão atual de revisor do espaço de trabalho, auto-revisão do solicitante, votação por chave de API ou propriedade de cancelamento. |
| `404` | A requisição ou agente ativo pertence ao ambiente de espaço de trabalho selecionado. |
| `409` | A requisição é final, expirou ou esta pessoa já votou. |

Esses registros apoiam seu processo de revisão; eles não estabelecem conformidade com SOC 2, certificação ISO, verificação de documentos de identidade ou a correção das evidências enviadas.


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