Come usare le API pubbliche in Agent Studio

Le API pubbliche di Agent Studio ti permettono di richiamare, gestire ed eseguire qualsiasi agente di GoHighLevel / Squadd direttamente dal tuo software, senza accedere alla dashboard di GoHighLevel / Squadd. Questo articolo spiega cosa sono le API, perché sono utili e come usarle in modo sicuro con OAuth.

Cos'è la API pubblica di Agent Studio?
Vantaggi chiave della API pubblica di Agent Studio
API List Agents
API Get Agent
API Execute Agent
Autenticazione OAuth
Integrazioni PIT
Come configurare la API pubblica di Agent Studio
Domande frequenti
Articoli correlati

Cos'è la API pubblica di Agent Studio?

Una API pubblica (Application Programming Interface) è un modo sicuro per far comunicare applicazioni esterne con GoHighLevel / Squadd. In Agent Studio, la API pubblica consente al tuo software di elencare, recuperare ed eseguire agenti AI pronti per la produzione in modo programmatico, senza accedere alla dashboard di Squadd.

La tua applicazione invia richieste HTTP sicure ai server di GoHighLevel / Squadd, che eseguono l'agente selezionato e restituiscono una risposta JSON strutturata. Ogni richiesta è associata a una specifica Location e deve includere un'autenticazione corretta tramite token bearer OAuth 2.0 o un Private Integration Token (PIT). Solo gli agenti con stato Attivo nella fase del ciclo di vita Production sono accessibili tramite la API pubblica.

Vantaggi chiave della API pubblica di Agent Studio

Incorpora agenti AI all'interno di app mobile, piattaforme SaaS, assistenti vocali o strumenti interni.

Avvia workflow complessi degli agenti da automazioni esterne (Zapier, Make, Airflow, ecc.).

Centralizza la sicurezza con OAuth 2.0 e token di accesso con scope limitato.

Usa le integrazioni PIT per eseguire agenti nel tuo ambiente rispettando le regole sulla privacy dei dati.

Ricevi risposte JSON strutturate e complete, così i sistemi a valle possono elaborare i risultati senza ulteriore NLP.

Gestione degli agenti con le API pubbliche

Le API pubbliche di Agent Studio supportano ora la gestione completa degli agenti, consentendo di creare, recuperare, aggiornare, pubblicare, eseguire ed eliminare agenti in modo programmatico. Questo offre agli utenti API-first un modo più completo di gestire gli agenti senza dover ricorrere soltanto all'interfaccia di Agent Studio.

Il supporto alle API pubbliche copre ora l'intero ciclo di vita degli agenti, aiutando i team ad automatizzare le operazioni sugli agenti all'interno delle loro piattaforme e workflow esistenti.

Azioni di gestione degli agenti supportate

Puoi ora utilizzare le API pubbliche per queste azioni di Agent Studio:

Create Agent (Crea agente)
List Agents (Elenca agenti)
Get Agent (Recupera agente)
Update Agent (Aggiorna agente)
Update Agent Metadata (Aggiorna metadati agente)
Delete Agent (Elimina agente)
Promote to Production and Publish (Promuovi in produzione e pubblica)
Execute Agent (Esegui agente)

A seconda dell'endpoint, i requisiti possono variare in termini di scope, contesto della Location e parametri della richiesta. In generale, le azioni di lettura richiedono accesso in sola lettura, mentre le azioni di creazione, aggiornamento, pubblicazione, esecuzione ed eliminazione richiedono accesso in scrittura.

Endpoint deprecati e guida alla migrazione

Alcuni endpoint pubblici legacy di Agent Studio sono ancora disponibili e contrassegnati come deprecati per compatibilità con versioni precedenti.

Per nuovi sviluppi, utilizza gli endpoint pubblici attuali invece di quelli deprecati. Gli endpoint deprecati potrebbero essere sostituiti o rimossi nelle versioni future dell'API, pertanto le nuove integrazioni dovrebbero essere costruite sulle route API di Agent Studio attive.

Se attualmente utilizzi endpoint deprecati, consulta la documentazione API più recente di Agent Studio ed esegui la migrazione agli endpoint aggiornati dove disponibili.

API List Agents

Questo endpoint restituisce tutti gli agenti attivi per una determinata Location.

Metodo: GET /agent-studio/public-api/agents

Parametro query obbligatorio: locationId

Paginazione opzionale: limit, offset

Uso tipico: mostrare un menu a tendina degli agenti disponibili nella tua app.

API Get Agent

Recupera i metadati completi di un singolo agente.

Metodo: GET /agent-studio/public-api/agents/{agentId}

Parametro query obbligatorio: locationId

Restituisce: nome, stato, nodi strumento, variabili, fase del ciclo di vita e altro ancora.

Uso tipico: visualizzare i dettagli dell'agente prima dell'esecuzione o ispezionare le variabili.

API Execute Agent

Esegui un agente e ottieni l'output completo in un unico payload JSON.

Metodo: POST /agent-studio/public-api/agents/{agentId}/execute

Body: { locationId, input, executionId? }

La prima chiamata omette executionId; la risposta restituisce un executionId che puoi usare per proseguire lo stesso thread di conversazione nelle chiamate successive.

Uso tipico: fornire risultati immediati (es. "Riepiloga questo PDF" o "Genera testo per un annuncio").

Autenticazione OAuth

Le API pubbliche utilizzano token bearer OAuth 2.0. Crea un'integrazione privata in GoHighLevel / Squadd oppure usa il flusso OAuth standard per ottenere un token di accesso. I token sono JWT e devono essere inclusi nell'header Authorization:

Authorization: Bearer {access_token}

Integrazioni PIT

I Private Integration Token (PIT) offrono un'alternativa semplificata al flusso OAuth completo quando sono necessarie chiamate server-to-server. Genera un PIT nelle Impostazioni (Settings) per sviluppatori di GoHighLevel / Squadd, assegnalo alla Location richiesta e includilo nell'header Authorization esattamente come un token di accesso OAuth.

Come configurare la API pubblica di Agent Studio

Segui questi passaggi per connettere la tua applicazione esterna:

Abilita AI Agents → Agent Studio nella tua Location (è necessario avere agenti in stato "Production").

Vai su Impostazioni (Settings) → Developer e crea un'integrazione privata o un'app OAuth.

Copia il Client ID e il Client Secret (OAuth) oppure il valore PIT (integrazione privata).

Per OAuth:

Chiama POST /oauth/token con grant_type=authorization_code per scambiare il codice con un token di accesso.

b. Salva il token di accesso in modo sicuro e rinnovalo quando necessario.

Testa la connessione con List Agents:

curl -H "Authorization: Bearer {token}" "https://services.leadconnectorhq.com/agent-studio/public-api/agents?locationId={locationId}"

Analizza la risposta e salva gli agentId che intendi eseguire.

Esegui l'agente:

curl -X POST \

-H "Authorization: Bearer {token}" \

-H "Content-Type: application/json" \

-d '{ "locationId":"abc123", "input":{ "prompt":"Write a Facebook ad for plumbers"} }' \

https://services.leadconnectorhq.com/agent-studio/public-api/agents/{agentId}/execute

Salva l'executionId restituito se hai bisogno di conversazioni multi-turno.

Domande frequenti

D: Esiste un limite di velocità (rate limit)?

Sì. Ogni Location è limitata a 300 richieste API al minuto su tutti gli endpoint di Agent Studio.

D: Posso ricevere risposte in streaming parziale?

Non ancora. L'endpoint Execute Agent restituisce attualmente un singolo oggetto JSON al completamento dell'esecuzione.

D: Gli agenti devono essere in Production?

Sì. Solo gli agenti con stato = "Active" nella fase del ciclo di vita Production sono accessibili tramite la API pubblica.

D: Cosa succede se ometto il locationId?

L'API restituisce HTTP 400 ("locationId is required").

D: Posso chiamare l'API da JavaScript lato client?

Non è consigliato; effettua sempre il proxy della richiesta dal tuo backend per proteggere il token bearer.

D: Per quanto tempo è valido un executionId?

Gli execution ID scadono dopo 30 minuti di inattività. Avvia una nuova sessione se necessario.

D: OAuth supporta i refresh token?

Sì. Segui il grant standard OAuth 2.0 refresh_token per rinnovare i token di accesso senza interazione dell'utente.

D: I token PIT sono limitati a una singola Location? Sì. I token PIT sono associati alla Location selezionata al momento della generazione del token.