Pular para o conteúdo principal

Guia rápido

Em poucos minutos você vai registrar uma ferramenta, registrar um agente (a IA faz a correspondência), aprovar o acesso e conversar com o agente. Há dois caminhos: a interface e a API.

Pela interface​

1. Registre uma ferramenta​

Vá em Ferramentas (Tools) → Nova Tool e informe:

  • Nome — ex.: consultar_fatura;
  • Descrição — o que a ferramenta faz. Capriche aqui: é o texto que a IA usa para decidir quais agentes precisam dela;
  • URL do endpoint e método HTTP;
  • Tipo de autenticação (Nenhuma, API Key, Bearer, OAuth2 ou identidade de workload) e seus parâmetros;
  • Input schema (JSON) — os parâmetros de entrada da ferramenta.

Veja Ferramentas para detalhes e importação em massa.

2. Registre um agente​

Vá em Agentes (Agents) → Novo Agente e informe nome, descrição/contexto (o propósito do agente), responsável (e-mail) e o prazo de revisão (em dias). Ao salvar, a IA cria automaticamente as solicitações de acesso para as ferramentas relevantes.

3. Aprove o acesso​

Vá em Solicitações de acesso (Access Requests), revise a justificativa gerada pela IA e clique em Aprovar. Na primeira aprovação do agente, o client_secret é exibido uma única vez — copie e guarde com segurança.

4. Converse​

Vá em Playground (chat), selecione o agente e converse. O agente responde usando apenas as ferramentas aprovadas.

Pela API​

O exemplo abaixo faz o mesmo fluxo via API. Substitua https://SEU-AGENTHUB pela URL da sua organização.

BASE=https://SEU-AGENTHUB

# 1. Login (obtém o token de acesso da plataforma)
TOKEN=$(curl -s -X POST $BASE/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@empresa.com","password":"sua-senha"}' \
  | jq -r .access_token)

# 2. Registre uma ferramenta
curl -s -X POST $BASE/api/v1/tools \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "consultar_fatura",
    "description": "Consulta os detalhes de uma fatura pelo ID. Retorna valor, status e vencimento.",
    "endpoint_url": "https://api.financeiro.exemplo.com/faturas/{id}",
    "http_method": "GET",
    "auth_type": "api_key",
    "auth_config": {"header": "X-API-Key", "value": "sua-chave"},
    "input_schema": {"type":"object","properties":{"id":{"type":"string"}},"required":["id"]}
  }'

# 3. Registre um agente (a IA associa "consultar_fatura" automaticamente)
AGENT=$(curl -s -X POST $BASE/api/v1/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistente de Faturas",
    "description": "Assistente que responde dúvidas de clientes sobre status de faturas e histórico de pagamentos.",
    "owner_email": "operacoes@empresa.com",
    "review_period_days": 30
  }')
AGENT_ID=$(echo $AGENT | jq -r .agent.id)
REQUEST_ID=$(echo $AGENT | jq -r '.access_requests[0].id')

# 4. Aprove a solicitação de acesso (o client_secret vem UMA vez)
RESULT=$(curl -s -X POST $BASE/api/v1/access-requests/$REQUEST_ID/approve \
  -H "Authorization: Bearer $TOKEN")
CLIENT_SECRET=$(echo $RESULT | jq -r .client_secret)

# 5. Converse com o agente (use o client_secret, não o token de admin)
curl -s -X POST $BASE/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?"}'
O client_secret aparece só uma vez

Ele é retornado apenas na primeira aprovação do agente e não pode ser recuperado depois. Se perder, será preciso reativar o agente para gerar um novo. Guarde-o num cofre de segredos.

Próximos passos​