As APIs Públicas para o AI Agent Studio permitem que você chame, gerencie e execute qualquer agente HighLevel do seu próprio software — sem fazer login no HighLevel. Este artigo explica o que são as APIs, por que elas são importantes e como usá-las de forma segura com o OAuth.
O que é a API Pública do Agent Studio?
Uma API Pública (Interface de Programação de Aplicações) é uma forma segura de aplicações externas se comunicarem com o HighLevel. No Agent Studio, a API Pública permite que seu software liste, recupere e execute agentes de I.A. prontos para produção de forma programática, sem fazer login no painel do HighLevel.
Seu aplicativo envia solicitações HTTP seguras para os servidores do HighLevel, que executam o agente selecionado e retornam uma resposta JSON estruturada. Cada solicitação é vinculada a uma subconta específica (local) e deve incluir a autenticação adequada usando tokens de portador (bearer tokens) OAuth 2.0 ou um Token de Integração Privada (PIT). Apenas os agentes que estão Ativos no estágio de ciclo de vida de Produção podem ser acessados por meio da API Pública.
Principais Benefícios da API Pública do Agent Studio
- Incorpore agentes de I.A. dentro de aplicativos móveis, plataformas SaaS, assistentes de voz ou ferramentas internas.
- Acione fluxos de trabalho complexos de agentes a partir de automações externas (Zapier, Make, Airflow, etc.).
- Centralize a segurança com OAuth 2.0 e tokens de acesso com escopo.
- Aproveite as integrações PIT para executar agentes dentro de seu próprio ambiente, respeitando as regras de privacidade de dados.
- Retorne JSON rico e estruturado para que sistemas downstream possam analisar os resultados sem PNL (Processamento de Linguagem Natural) extra.
Gerenciar Agentes com APIs Públicas
As APIs Públicas do Agent Studio agora suportam o gerenciamento completo de agentes, tornando possível criar, recuperar, atualizar, publicar, executar e excluir agentes de forma programática. Isso dá aos usuários com foco em API uma maneira mais completa de gerenciar agentes sem depender apenas da interface do usuário (UI) do Agent Studio.
O suporte à API Pública agora abrange o ciclo de vida principal do agente, ajudando as equipes a automatizar as operações do agente dentro de suas plataformas e fluxos de trabalho existentes.
Ações de Gerenciamento de Agentes Suportadas
Agora você pode usar APIs públicas para estas ações do Agent Studio:
- Criar Agente
- Listar Agentes
- Obter Agente
- Atualizar Agente
- Atualizar Metadados do Agente
- Excluir Agente
- Promover para Produção e Publicar
- Executar Agente
Dependendo do endpoint, os requisitos podem variar para escopos, contexto de localização e parâmetros de solicitação. Em geral, as ações de leitura usam acesso somente leitura, enquanto as ações de criar, atualizar, publicar, executar e excluir requerem acesso de gravação.
Endpoints Obsoletos e Orientação de Migração
Alguns endpoints públicos herdados do Agent Studio permanecem disponíveis e são marcados como obsoletos (deprecated) para compatibilidade com versões anteriores.
Para novos desenvolvimentos, use os endpoints públicos atuais em vez dos obsoletos. Os endpoints obsoletos podem ser substituídos ou removidos em versões futuras da API, portanto, integrações mais recentes devem ser criadas nas rotas ativas da API do Agent Studio.
Se você depende atualmente de endpoints obsoletos, revise a documentação mais recente da API do Agent Studio e migre para os endpoints atualizados onde estiverem disponíveis.
API Listar Agentes (List Agents API)
Este endpoint retorna todos os agentes ativos para um determinado local.
- Método: GET /agent-studio/public-api/agents
- Parâmetro de consulta (query) obrigatório: locationId
- Paginação opcional: limit, offset
- Uso típico: mostrar um menu suspenso de agentes disponíveis em seu aplicativo.
API Obter Agente (Get Agent API)
Recupere metadados completos sobre um único agente.
- Método: GET /agent-studio/public-api/agents/{agentId}
- Parâmetro de consulta obrigatório: locationId
- Retorna: name, status, tool-nodes, variables, lifecycle stage e muito mais.
- Uso típico: exibir detalhes do agente antes da execução ou inspecionar variáveis.
API Executar Agente (Execute Agent API)
Execute um agente e obtenha a saída completa em um payload JSON.
- Método: POST /agent-studio/public-api/agents/{agentId}/execute
- Corpo (Body): { locationId, input, executionId? }
- A primeira chamada omite o executionId; a resposta retorna o executionId para que você possa continuar o mesmo tópico de conversa em chamadas subsequentes.
- Uso típico: fornecer resultados instantâneos (por exemplo, "Resuma este PDF" ou "Gere texto de anúncio").
Autenticação OAuth
As APIs públicas usam tokens de portador (bearer tokens) OAuth 2.0. Crie uma integração privada no HighLevel ou use o fluxo padrão do OAuth para obter um token de acesso. Os tokens são JWTs que devem ser incluídos no cabeçalho de Autenticação:
Authorization: Bearer {access_token}
Integrações PIT
Os Tokens de Integração Privada (PIT) oferecem uma alternativa simplificada ao OAuth completo quando você precisa de chamadas de servidor para servidor. Gere um PIT nas Configurações do Desenvolvedor do HighLevel, defina o escopo para a subconta necessária e inclua-o no cabeçalho de Autenticação (Authorization) da mesma forma que um token de acesso OAuth.
Como Configurar a API Pública do Agent Studio
Siga estes passos para conectar seu aplicativo externo:
- Habilite AI Agents → Agent Studio em sua subconta (deve ter agentes em "Produção").
- Vá para Configurações → Desenvolvedor e crie uma Integração Privada ou Aplicativo OAuth.
- Copie o Client ID e o Client Secret (OAuth) ou o valor PIT (Integração Privada).
- Para OAuth:
a. Chame POST /oauth/token com grant_type=authorization_code para trocar o código por um token de acesso.
b. Armazene o token de acesso com segurança; atualize-o (refresh) conforme necessário. - Teste a conexão com Listar Agentes:
curl -H "Authorization: Bearer {token}" "https://services.leadconnectorhq.com/agent-studio/public-api/agents?locationId={locationId}"
Analise a resposta e salve o(s) agentId(s) que você pretende executar. - Execute o agente:
curl -X POST
-H "Authorization: Bearer {token}"
-H "Content-Type: application/json"
-d '{ "locationId":"abc123", "input":{ "prompt":"Escreva um anúncio no Facebook para encanadores"} }'
https://services.leadconnectorhq.com/agent-studio/public-api/agents/{agentId}/execute
Armazene o executionId retornado se precisar de conversas de vários turnos.
Perguntas Frequentes
P: Existe um limite de taxa (rate limit)?
Sim. Cada subconta é limitada a 300 solicitações de API por minuto em todos os endpoints do Agent Studio.
P: Posso transmitir (stream) respostas parciais?
Ainda não. O endpoint Execute Agent atualmente retorna um único objeto JSON após a conclusão.
P: Os agentes precisam estar em Produção?
Sim. Apenas agentes com status = "Ativo" no estágio de ciclo de vida de Produção são acessíveis por meio da API pública.
P: O que acontece se eu omitir o locationId?
A API retorna HTTP 400 ("locationId is required").
P: Posso chamar a API a partir do JavaScript do lado do cliente?
Não é recomendado; sempre faça proxy da solicitação a partir de seu back-end para proteger o bearer token.
P: Por quanto tempo um executionId é válido?
Os IDs de execução expiram após 30 minutos de inatividade. Inicie uma nova sessão se necessário.
P: O OAuth suporta tokens de atualização (refresh tokens)?
Sim, siga a concessão padrão refresh_token do OAuth 2.0 para renovar os tokens de acesso sem a interação do usuário.
P: Os tokens PIT são limitados a um único local?
Sim. Os tokens PIT têm o escopo da subconta que você selecionou ao gerar o token.