Agentes (Agents)
Um agente é uma entidade de IA com identidade própria que só chama ferramentas explicitamente aprovadas para ele. Esta página cobre o ciclo de vida do agente do ponto de vista de quem o cria e o opera.
Registrar um agente
Em Agentes (Agents) → Novo Agente, informe:
| Campo | Descrição |
|---|---|
| Nome | Como o agente aparece na plataforma. |
| Descrição / contexto | O propósito do agente. A IA usa esse texto para decidir quais ferramentas ele precisa — descreva o que ele faz e para quem. |
| Responsável (owner) | E-mail de quem responde pelo agente. Recebe notificações de expiração e re-aprovação. |
| Prazo de revisão (em dias) | Por quanto tempo cada acesso aprovado vale antes de exigir re-aprovação. |
Ao salvar, a IA cria automaticamente as solicitações de acesso para as ferramentas relevantes (veja Como funciona).
Identidade e credenciais
Cada agente tem:
client_id— um identificador (UUID) gerado no registro;client_secret— a credencial usada para conversar com o agente. É gerada e exibida uma única vez, na primeira aprovação de acesso, e não pode ser recuperada depois.
client_secret com segurançaArmazene-o em um cofre de segredos — nunca em código-fonte ou variáveis de ambiente expostas. Se for perdido, reative o agente para gerar um novo.
Estados do agente
| Estado | Significado | Pode conversar? |
|---|---|---|
| Pendente de aprovação | Registrado, sem ferramentas aprovadas ainda. | Não |
| Ativo | Tem ao menos uma ferramenta aprovada e vigente. | Sim |
| Suspenso | Todas as ferramentas expiraram. | Não, até re-aprovar |
Um agente suspenso volta a ativo assim que uma re-aprovação concede novamente
acesso a alguma ferramenta — mantendo o mesmo client_secret.
Conversar com o agente
- No painel — use o Playground (chat), selecione o agente e converse.
- Via API — chame o endpoint de conversa do agente autenticando com o
client_secret(e não com o token de usuário da plataforma):
curl -s -X POST https://SEU-AGENTHUB/api/v1/agents/$AGENT_ID/chat \
-H "Authorization: Bearer $CLIENT_SECRET" \
-H "Content-Type: application/json" \
-d '{"message": "Qual o status da fatura INV-2024-001?"}'
A resposta inclui o texto gerado, as ferramentas efetivamente usadas e o identificador de sessão (para continuar a conversa e correlacionar na auditoria). O agente só consegue usar ferramentas aprovadas e vigentes — qualquer tentativa de chamar outra é bloqueada e registrada.
Expor um agente como ferramenta (multiagente)
Qualquer agente ativo pode ser exposto como ferramenta para que outros agentes o utilizem — permitindo pipelines multiagente sem compartilhar credenciais nem burlar o fluxo de aprovação.
Ao ativar expor como ferramenta no agente:
- a plataforma gera um segredo dedicado (
expose_secret), separado doclient_secret, retornado uma única vez; - uma ferramenta correspondente é criada automaticamente, apontando para o endpoint de conversa do agente;
- outros agentes podem então solicitar acesso a essa ferramenta pelo fluxo normal de aprovação.
Ao desativar, a ferramenta vinculada é desativada e o segredo é descartado.
O
expose_secretpassa pelo mesmo fluxo de solicitação → aprovação antes que o Agente A possa usar o Agente B como ferramenta. Nada escapa da governança.
Excluir um agente
Excluir um agente remove-o e os dados relacionados de forma definitiva. Para apenas cortar o acesso temporariamente, prefira deixar as concessões expirarem (o agente é suspenso) ou desative as ferramentas correspondentes.