Le API Pubbliche per AI Agent Studio ti permettono di chiamare, gestire ed eseguire qualsiasi agente HITLEAD dal tuo software, senza effettuare il login a HITLEAD. Questo articolo spiega cosa sono le API, perché sono utili e come usarle in modo sicuro con OAuth.

INDICE

Cos'è l'API Pubblica di Agent Studio?

Un'API Pubblica (Application Programming Interface) è un modo sicuro per consentire ad applicazioni esterne di comunicare con HITLEAD. In Agent Studio, l'API Pubblica permette al tuo software di elencare, recuperare ed eseguire agenti AI pronti per la produzione in modo programmatico, senza accedere alla Dashboard di HITLEAD.

La tua applicazione invia richieste HTTP sicure ai server di HITLEAD, che eseguono l'agente selezionato e restituiscono una risposta JSON strutturata. Ogni richiesta è associata a un sub-account specifico (location) e deve includere un'autenticazione corretta tramite bearer token OAuth 2.0 o un Private Integration Token (PIT). Solo gli agenti con stato "Active" nella fase del ciclo di vita Production sono accessibili tramite l'API Pubblica.

Principali vantaggi dell'API Pubblica di Agent Studio

  • Incorpora agenti AI in app mobile, piattaforme SaaS, assistenti vocali o strumenti interni.
  • Attiva Workflow complessi di agenti da automazioni esterne (Zapier, Make, Airflow, ecc.).
  • Centralizza la sicurezza con OAuth 2.0 e token di accesso con scope definiti.
  • Sfrutta le integrazioni PIT per eseguire agenti nel tuo ambiente rispettando le regole sulla privacy dei dati.
  • Restituisce JSON strutturato e ricco, così i sistemi downstream possono analizzare i risultati senza elaborazione NLP aggiuntiva.

Gestisci gli agenti con le API Pubbliche

Le API Pubbliche di Agent Studio supportano ora la gestione completa degli agenti, rendendo possibile creare, recuperare, aggiornare, pubblicare, eseguire ed eliminare agenti in modo programmatico. Questo offre agli utenti API-first un modo più completo per gestire gli agenti senza dipendere solo dall'interfaccia di Agent Studio.

Il supporto API Pubblica copre ora il ciclo di vita principale degli agenti, aiutando i team ad automatizzare le operazioni sugli agenti all'interno delle loro piattaforme e Workflow esistenti.

Azioni di gestione agenti supportate

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

  • Create Agent
  • List Agents
  • Get Agent
  • Update Agent
  • Update Agent Metadata
  • Delete Agent
  • Promote to Production and Publish
  • Execute Agent

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

Schermata 1 — Come Usare le API Pubbliche in Agent Studio

Schermata 2 — Come Usare le API Pubbliche in Agent Studio

Schermata 3 — Come Usare le API Pubbliche in Agent Studio

Schermata 4 — Come Usare le API Pubbliche in Agent Studio

Schermata 5 — Come Usare le API Pubbliche in Agent Studio

Endpoint deprecati e guida alla migrazione

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

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

Se attualmente usi endpoint deprecati, consulta la documentazione API più recente di Agent Studio e migra agli endpoint aggiornati dove disponibili.

Schermata 6 — Come Usare le API Pubbliche in Agent Studio

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, tool-node, variabili, fase del ciclo di vita e altro.
  • 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 executionId in modo da poter continuare lo stesso thread di conversazione nelle chiamate successive.
  • Uso tipico: fornire risultati immediati (es. "Riassumi questo PDF" o "Genera copy per un annuncio").

Autenticazione OAuth

Le API Pubbliche usano bearer token OAuth 2.0. Crea un'integrazione privata in HITLEAD o usa il flusso OAuth standard per ottenere un token di accesso. I token sono JWT che devono essere inclusi nell'header Authorization:

Authorization: Bearer {access_token}

Integrazioni PIT

I Private Integration Token (PIT) offrono un'alternativa semplificata all'OAuth completo quando hai bisogno di chiamate server-to-server. Genera un PIT in Developer Settings di HITLEAD, assegnalo al sub-account richiesto e includilo nell'header Authorization esattamente come un token di accesso OAuth.

Come configurare l'API Pubblica di Agent Studio

Segui questi passaggi per connettere la tua app esterna:

  1. Abilita AI Agents → Agent Studio nel tuo sub-account (devi avere agenti in "Production").

  2. Vai su Settings → Developer e crea una Private Integration o un OAuth App.

  3. Copia il Client ID e il Client Secret (OAuth) o il valore PIT (Private Integration).

Per OAuth:

a. 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; aggiornalo secondo necessità.

  1. Testa la connessione con List Agents:
curl -H "Authorization: Bearer {token}" "https://services.leadconnectorhq.com/agent-studio/public-api/agents?locationId={locationId}"
  1. 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
  1. Salva l'executionId restituito se hai bisogno di conversazioni multi-turno.

Domande frequenti

D: Esiste un rate limit?

Sì. Ogni sub-account è limitato 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 termine 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 l'API pubblica.

D: Cosa succede se ometto locationId?

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

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

Non è consigliato; fai sempre passare la richiesta dal tuo backend per proteggere il bearer token.

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 al sub-account selezionato durante la generazione del token.

Articoli correlati

  • Come Usare AI Agent Studio in HITLEAD
  • Integrazione Ask AI + Agent Studio
  • Integrazioni Private: tutto quello che devi sapere
  • Panoramica di Agent Studio