Ferramentas (Tools)
Uma ferramenta é uma API externa registrada no AgentHub. Depois de registrada, ela pode ser aprovada para um ou mais agentes — que então a utilizam em suas conversas, sempre dentro do fluxo de governança.
Registrar uma ferramenta
Em Ferramentas (Tools) → Nova Tool, preencha:
| Campo | Descrição |
|---|---|
| Nome | Identificador único da ferramenta (ex.: consultar_fatura). |
| Descrição | O que a ferramenta faz. É o texto que a IA usa na correspondência — descreva com clareza o resultado e quando usá-la. |
| URL do endpoint | O endereço da API. Pode conter parâmetros de caminho (ex.: .../faturas/{id}). |
| Método HTTP | GET, POST, PUT, DELETE… |
| Tipo de autenticação | Como o AgentHub se autentica nessa API (veja abaixo). |
| Input schema (JSON) | Os parâmetros de entrada, em JSON Schema. Define o que o agente pode enviar. |
A correspondência por IA depende quase inteiramente da descrição. Uma boa descrição ("Consulta o status de uma fatura pelo ID; use para responder dúvidas de cobrança") leva a associações precisas. Uma descrição vaga ("API de faturas") leva a associações ruins.
Tipos de autenticação
O AgentHub guarda a configuração de autenticação de forma protegida e a aplica ao chamar a API. Os tipos disponíveis:
| Tipo | Quando usar |
|---|---|
| Nenhuma | APIs públicas, sem autenticação. |
| API Key | Envia uma chave em um cabeçalho configurável (ex.: X-API-Key). |
| Bearer Token | Envia Authorization: Bearer <token>. |
| OAuth2 (client credentials) | A plataforma obtém um token via client credentials (token URL, client ID/secret, escopo). |
| Identidade de workload (SPIFFE/SPIRE) | Para APIs que exigem identidade de carga de trabalho, sem segredos estáticos. |
A configuração de autenticação nunca é exposta de volta em texto puro depois de salva.
Input schema
O input schema descreve os parâmetros que a ferramenta aceita, em JSON Schema:
{
"type": "object",
"properties": {
"id": { "type": "string", "description": "ID da fatura" }
},
"required": ["id"]
}
A IA usa o schema para preencher corretamente os parâmetros ao chamar a ferramenta durante uma conversa.
Importar de Postman ou OpenAPI
Para registrar muitas ferramentas de uma vez, use Importar Postman ou Importar OpenAPI na tela de Ferramentas:
- Postman — uma Collection v2.1 (JSON);
- OpenAPI — uma spec 3.x (JSON ou YAML).
Opções de importação:
- Preview (sem salvar) — mostra o que seria importado, ignorado ou recusado, sem gravar nada;
- Sobrescrever existentes — atualiza ferramentas com o mesmo nome.
O resultado lista o que foi importado, ignorado (ex.: já existe) e os erros (ex.: faltou descrição).
Editar e desativar
- Editar — atualizações parciais são suportadas; altere descrição, endpoint, autenticação ou schema a qualquer momento.
- Desativar — uma ferramenta desativada fica indisponível para todos os agentes: concessões existentes são preservadas, mas a execução é bloqueada. É uma desativação reversível (soft delete), não uma exclusão definitiva.
Se uma ferramenta passou a se comportar de forma indevida, desativá-la corta o acesso de todos os agentes imediatamente, sem precisar mexer em cada concessão.
Veja também
- Agentes — como os agentes recebem e usam ferramentas.
- Solicitações e aprovações — como o acesso a uma ferramenta é concedido.
- Referência da API — Ferramentas.