API degli Agenti AI

Un Agente AI è il cervello dietro il tuo bot: le sue istruzioni, la personalità, la lingua, la conoscenza e gli strumenti. Crei un Agente una volta e poi indirizzi il traffico verso di esso. Questa guida copre tutto ciò che puoi fare con un Agente tramite l’API: crearlo, configurarlo, fornirgli conoscenze e strumenti, rivedere le sue bozze e instradare le conversazioni verso di esso.

URL di base — https://api.youraiconnector.com/v1
Autenticazione — la tua chiave API (vedi Autenticazione)
Errori e paginazione — vedi Errori e paginazione

Tutti gli esempi seguenti mostrano il formato di query ?apiKey= in cURL e l’intestazione X-API-Key in JavaScript e Python; entrambi funzionano su ogni endpoint.

Se non hai familiarità con il concetto di Agenti, leggi prima Agenti AI.

Come è composto un Agente

Quattro elementi vengono gestiti separatamente ed è utile sapere cosa sia cosa prima di iniziare:

Elemento	Cos’è	Dove si imposta
Configurazione	Istruzioni, regole, obiettivo, personalità, lingua, livello AI, comportamento di prenotazione e follow-up	`PUT /agents/{agentId}` o il più specifico `PUT /agents/{agentId}/bot-config`
Conoscenza	FAQ e fonti di conoscenza (pagine e documenti che la piattaforma ha letto per te)	API FAQ e `POST /agents/{agentId}/kb-sources`
Strumenti	Funzioni personalizzate e server MCP che l’Agente può chiamare durante la conversazione	`POST /agents/{agentId}/custom-functions` e `POST /agents/{agentId}/mcp-servers`
Instradamento	Quali canali e conversazioni raggiungono effettivamente questo Agente	Punti di ingresso — `PUT /entry-points/channel-defaults` e `POST /agents/{agentId}/entry-points`

Un nuovo Agente non risponde a nessuno finché non lo instradi. Creare un Agente non lo inserisce in un canale. Questo è il passaggio che la maggior parte delle integrazioni dimentica: vedi Instradare le conversazioni verso un Agente alla fine di questa pagina.

L’oggetto Agente

Un documento Agente completo è grande: diverse centinaia di kilobyte, principalmente il suo elenco di FAQ, le sue fonti di conoscenza e qualsiasi contenuto di pagina letto dal tuo sito web. Per questo motivo, l’elenco restituisce una breve riga di riepilogo per Agente quando la richiedi:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Campo	Tipo	Descrizione
`id`	string	L’identificatore univoco dell’Agente.
`name`	string \| null	Nome dell’Agente, come mostrato nella dashboard.
`active`	boolean \| null	Se all’Agente è attualmente consentito rispondere.
`language`	string \| null	Lingua in cui risponde l’Agente.
`goal`	string \| null	Obiettivo dell’Agente, abbreviato ai primi 200 caratteri (un’ellissi finale indica che è stato abbreviato).
`tags`	array \| null	Regole di tagging dell’Agente.
`anthropic_model`	string \| null	Livello di qualità AI: `standard`, `economy`, `max` o `mini`.
`ai_speed`	string \| null	Quanta capacità di ragionamento applica l’Agente prima di rispondere: `fast`, `fast_thinker`, `balanced` o `thorough`.
`enable_bookings`	boolean \| null	Se l’Agente può prenotare appuntamenti.
`enable_follow_ups`	boolean \| null	Se l’Agente invia messaggi di follow-up.
`faq_refs_count`	integer	Quante FAQ sono presenti nella base di conoscenza di questo Agente.
`kb_source_refs_count`	integer	Quante fonti di conoscenza sono collegate ad esso.
`created_at`	integer \| null	Data di creazione, millisecondi dall’epoca.
`last_modified_at`	integer \| null	Ultima modifica, millisecondi dall’epoca.

Il documento completo aggiunge tutto il resto: instructions, rules, personality, availability, follow_up_config, gli elenchi collegati di FAQ e fonti di conoscenza, i blocchi di testo generati e qualsiasi stato di esecuzione (tag_generation, optimize_run).

Alcune risposte contengono anche substrate_campaign_id. È un record interno mantenuto sugli account più vecchi; non è mai necessario intervenire su di esso e sugli account più recenti è null o assente.

Elenco Agenti

GET /agents — ogni Agente sull’account, dal più recente al meno recente.

Questo endpoint non è paginato. Per impostazione predefinita, ogni Agente viene restituito con la sua configurazione completa, che è pesante: un singolo Agente può raggiungere i 580 KB e un account con 64 Agenti oltre 3 MB. Passa view=summary per ottenere invece una riga breve per Agente, quindi leggi quella desiderata con Ottieni un Agente.

Parametri di query

Parametro	Descrizione
`view`	Imposta su `summary` per righe brevi. Qualsiasi altro valore restituisce `400`. Ometti per documenti completi.
`fields`	Si applica solo insieme a `view=summary`. Chiavi di riepilogo separate da virgola da mantenere, ad esempio `id,name,active`. `id` è sempre incluso; i nomi sconosciuti vengono ignorati.

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Risposta (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Crea un Agente

POST /agents — solo name è realmente necessario; invia qualsiasi configurazione tu conosca già insieme ad esso. Un nuovo Agente è attivo per impostazione predefinita.

Campi della richiesta (tutti facoltativi eccetto name)

Campo	Tipo	Descrizione
`name`	string	Nome dell’Agente.
`active`	boolean	Se può rispondere immediatamente. Il valore predefinito è `true`.
`language`	string	Lingua in cui risponde l’Agente.
`instructions`	string	Istruzioni principali che guidano il modo in cui parla ai contatti.
`rules`	string	Regole rigide che deve sempre seguire.
`goal`	string	Il risultato verso cui dovrebbe lavorare.
`personality`	string	Tono di voce e personalità.
`availability`	object	Ore di attività per giorno della settimana — vedi Imposta ore di attività.
`ai_speed`	string	`fast`, `fast_thinker`, `balanced` o `thorough`.
`anthropic_model`	string	`standard`, `economy`, `max` o `mini`.
`scrape_urls`	string[]	Pagine da leggere per creare le istruzioni dell’Agente.

Creazione di un Agente dal tuo sito web. Includi scrape_urls e la piattaforma leggerà quelle pagine scrivendo le istruzioni per te. La risposta ti comunica se tale generazione è iniziata, così saprai se interrogare l’Agente per verificarne l’avanzamento.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Risposta (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued è true quando la piattaforma ha iniziato a scrivere le istruzioni dalle pagine fornite.

Un 400 significa che il corpo non era un oggetto JSON, un campo è stato rifiutato o l’Agente supera la dimensione di configurazione consentita dal tuo piano. Un 403 significa che l’account non è autorizzato a utilizzare una delle impostazioni inviate, ad esempio un livello di IA che il fornitore dell’account non ha concesso.

Ottieni un Agente

GET /agents/{agentId}

Passa fields con un elenco separato da virgole per ottenere solo ciò di cui hai bisogno, ad esempio fields=name,active,goal. L’elemento id è sempre incluso e i nomi che non esistono nell’Agente vengono ignorati anziché rifiutati. Omettilo per ottenere l’intero documento.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Un Agente che non esiste nel tuo account restituisce 404.

Aggiorna un Agente

PUT /agents/{agentId} — invia solo i campi che desideri modificare; tutto il resto rimane invariato.

Le impostazioni nidificate possono essere gestite foglia per foglia con una chiave puntata, quindi "availability.monday" modifica solo il lunedì e lascia invariato il resto della settimana.

Note

Per modificare il tipo di evento prenotabile in cui l’Agente effettua la prenotazione, invia event_id (l’id dell’evento, o null per cancellarlo). Invia event_ids con un array per collegarne diversi contemporaneamente: il primo diventa quello principale e [] scollega tutto. event_id e event_ids si escludono a vicenda e il campo event stesso non può essere scritto direttamente.
enable_bookings deve essere un valore booleano reale e booking_provider deve essere uno tra default, zenchef, formitable.
I campi relativi a proprietà e identità vengono ignorati, così come lo stato di esecuzione interno (avanzamento della generazione e dell’ottimizzazione).
Il routing non viene impostato qui. Usa PUT /entry-points/channel-defaults per rendere l’Agente il risponditore per un canale, POST /agents/{agentId}/entry-points per le regole su parole chiave e commenti, e PATCH /agents/{agentId}/active per metterlo in pausa o riprenderlo.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Un corpo vuoto restituisce 400 con "No fields to update".

Aggiorna le impostazioni del bot

PUT /agents/{agentId}/bot-config — il modo specifico per modificare solo le impostazioni di conversazione.

Un Agente non ha una sezione bot separata: le sue impostazioni si trovano direttamente sull’Agente, quindi i nomi dei campi qui sono gli stessi che invieresti a PUT /agents/{agentId}. Questo endpoint esiste come modo sicuro e mirato per modificarne alcuni. È richiesto almeno un campo.

Campo	Descrizione
`instructions`	Istruzioni principali che guidano il modo in cui l’Agente parla con i contatti.
`rules`	Regole rigide che deve sempre seguire.
`goal`	Il risultato verso cui dovrebbe tendere in ogni conversazione.
`personality`	Descrizione del tono di voce e della personalità.
`language`	Lingua in cui risponde l’Agente.
`ai_speed`	`fast`, `fast_thinker`, `balanced` o `thorough`.
`anthropic_model`	`standard`, `economy`, `max` o `mini`.
`max_messages`	Numero massimo di messaggi dell’Agente per conversazione.
`alert_human_when`	Quando l’Agente dovrebbe avvisare un membro del team umano.
`ai_transparency`	Se l’Agente dichiara di essere un’IA.

I nomi dei campi qui devono essere nomi semplici — lettere, numeri, trattini bassi e trattini. I percorsi puntati non sono accettati su questo endpoint (a differenza di PUT /agents/{agentId}), quindi bot.goal viene rifiutato con un 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

Il testo lungo incide sulla dimensione della configurazione consentita dal tuo piano, quindi un set di istruzioni molto ampio può essere rifiutato con un 400.

Imposta gli orari di attività

PUT /agents/{agentId}/active-hours — gli orari durante i quali l’Agente risponde automaticamente. Al di fuori di queste finestre rimane inattivo.

Invia un oggetto availability con chiave basata sul giorno della settimana (da monday a sunday). Ogni giorno accetta una singola finestra temporale o un elenco di finestre, nel formato HH:MM a 24 ore. I giorni che ometti mantengono le impostazioni precedenti e qualsiasi chiave che non sia un giorno della settimana viene rifiutata: in questo modo un errore di battitura non può passare inosservato.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Una chiave del giorno della settimana errata restituisce 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Metti in pausa o riprendi un Agente

PATCH /agents/{agentId}/active — attiva o disattiva l’Agente. Un Agente in pausa mantiene tutta la sua configurazione ma smette immediatamente di rispondere; la ripresa ha effetto immediato.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active deve essere un valore booleano reale — qualsiasi altro valore restituisce 400 con "active (boolean) is required".

Duplica un Agente

POST /agents/{agentId}/duplicate — crea una copia con la configurazione preservata. La copia non invia nulla finché non vi si punta un canale o un Punto di Ingresso.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Risposta (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Un duplicato viene conteggiato nel limite di Agenti del tuo piano esattamente come se ne creassi uno da zero, pertanto viene rifiutato con 403 quando l’account ha raggiunto il limite.

Elimina un Agente

DELETE /agents/{agentId}

L’eliminazione viene rifiutata se l’Agente è ancora collegato a qualcosa che smetterebbe di funzionare senza di esso — una trasmissione, un Punto di Ingresso o (su account meno recenti) una campagna. La risposta elenca ciò che lo sta bloccando, in modo che tu possa prima scollegare tali elementi e riprovare.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Bloccato (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Bozze: rivedi le modifiche prima che diventino effettive

Le modifiche apportate nell’editor e qualsiasi riscrittura prodotta da Ottimizza con AI vengono conservate come bozza non pubblicata finché non le pubblichi. Fino ad allora, l’Agente attivo continuerà a rispondere con la sua configurazione corrente.

Pubblica la bozza

POST /agents/{agentId}/publish-draft — sposta la bozza nella configurazione attiva e cancella la bozza nello stesso passaggio.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys elenca le impostazioni che sono state trasferite dalla bozza all’Agente attivo, così puoi mostrare cosa è cambiato.

Verifica che esista una bozza prima di effettuare questa chiamata. Pubblicare un Agente che non ha bozze non è una chiamata supportata e attualmente restituisce un 500 con un messaggio generico, non specifico. Per eliminare invece una bozza, usa lo scarto qui sotto.

Scarta la bozza

POST /agents/{agentId}/discard-draft — elimina la bozza e lascia la configurazione attiva esattamente com’è. È sicuro chiamarlo quando non c’è alcuna bozza; non succede nulla.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Ottimizza un Agente con l’IA

POST /agents/{agentId}/optimize — riscrive la configurazione dell’Agente in base al tuo feedback (“continua a offrire sconti”, “le risposte sono troppo lunghe”) e salva la riscrittura come bozza invece di renderla attiva.

Invia user_feedback (un’istruzione semplice) oppure, quando reagisci a una risposta specifica errata, thumbs_down_feedback insieme al thumbs_down_message incriminato. Almeno uno dei due deve contenere del testo.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Risposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Il lavoro viene eseguito in background e la chiamata restituisce immediatamente un risultato. Leggi l’Agente con GET /agents/{agentId} e osserva optimize_run.status; una volta tornato a Draft, la riscrittura sarà in attesa come bozza dell’Agente. Revisionala, quindi pubblicala o scartala.

Solo un’esecuzione alla volta per Agente: una seconda chiamata mentre una è in corso restituisce 409. Questo utilizza crediti IA.

Regole di tagging

Una regola di tagging è un tag più una descrizione di quando si applica. Durante una conversazione, l’Agente legge tale descrizione e applica il tag al contatto quando appropriato; è così che vengono attivate le automazioni basate sui tag.

L’oggetto regola

Campo	Obbligatorio	Descrizione
`name`	Sì	Il tag da applicare, ad esempio `hot-lead`.
`description`	No	Quando l’Agente dovrebbe applicarlo, scritto come un’istruzione che deve seguire.
`webhook`	No	URL chiamato quando l’Agente applica questo tag.
`ai_can_remove`	No	Se l’Agente può anche rimuovere il tag. Il valore predefinito è `false`.
`tag_id`	No	ID di un tag esistente nel tuo account a cui collegare la regola. Senza di esso, la regola si collega al tag con lo stesso nome, creandolo se non esiste; in questo modo ogni regola può essere indirizzata tramite l’ID del tag in seguito.

Aggiungi una regola di tagging

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Sostituisci una regola di tagging

PUT /agents/{agentId}/tags/{tagId} — la regola viene trovata tramite l’id del tag nel percorso e sostituita integralmente, non unita, quindi invia la regola completa invece della sola parte che stai modificando. Il tag a cui punta viene preservato anche se ometti tag_id, pertanto una modifica non può scollegare la regola dal suo tag.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Rimuovere una regola di tagging

DELETE /agents/{agentId}/tags/{tagId} — l’Agente smette di applicare quel tag. Il tag stesso, e tutti i contatti che lo possiedono già, rimangono invariati.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Entrambi gli endpoint restituiscono 404 quando l’Agente non esiste o quando non ha alcuna regola per quel tag.

Generare un set di tag con l’IA

POST /agents/{agentId}/tags/generate — progetta un intero set di regole (i nomi dei tag e la formulazione “applica quando…” dietro ciascuno di essi) leggendo le istruzioni e l’obiettivo dell’Agente stesso.

Campo	Descrizione
`mode`	`merge` (l’impostazione predefinita) mantiene le regole già presenti sull’Agente e le integra. `replace` progetta il set da zero.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Risposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

Il lavoro viene eseguito in background. Leggi l’Agente e monitora tag_generation.status; le regole stesse vengono inserite nel campo tags dell’Agente. È consentita solo una esecuzione alla volta per Agente (409 in caso contrario), e vengono utilizzati crediti IA.

Fonti di conoscenza

Le fonti di conoscenza sono le pagine e i documenti che la piattaforma ha letto per te. Collegarne una a un Agente gli consente di rispondere basandosi su quel contenuto.

Da dove provengono gli id delle fonti. Aggiungi contenuti con gli endpoint della knowledge-base — POST /kb-sources/url per una pagina, POST /kb-sources/file per un documento, POST /kb-sources/bulk-import per un intero sito. Questi restituiscono un source_id che devi interrogare con GET /kb-sources/{sourceId} finché non è pronto. POST /kb-sources/url accetta anche autoLinkToAgentId, che collega la fonte a un Agente non appena l’importazione termina, così puoi saltare la chiamata di collegamento sottostante.

Collegare fonti di conoscenza

POST /agents/{agentId}/kb-sources — invia kb_source_ids con un elenco per collegare un intero set in una sola chiamata (ciò che desideri dopo aver scansionato un sito), oppure kb_source_id per una singola fonte. Invia l’uno o l’altro. Collegare qualcosa che è già collegato non modifica nulla.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Risposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Scollegare fonti di conoscenza

DELETE /agents/{agentId}/kb-sources/{kbSourceId} per uno, o POST /agents/{agentId}/kb-sources/bulk-remove con kb_source_ids per diversi. La rimozione in blocco è una POST perché l’elenco degli ID viaggia nel corpo della richiesta.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

Le fonti stesse non vengono eliminate e rimangono disponibili per gli altri tuoi Agenti. Scollegare qualcosa che non è collegato non cambia nulla.

Domande frequenti (FAQ)

Le FAQ sono gestite sui propri endpoint e collegate a un Agente da lì: POST /faqs/{faqId}/link con { "agent_id": "ag7HkQ2ZpLxR3mNb" }, e POST /faqs/{faqId}/unlink per rimuoverle. Una FAQ può essere condivisa da un numero qualsiasi di Agenti. Consulta le API delle FAQ.

Una FAQ viene utilizzata solo dagli Agenti a cui è collegata: crearne una non è sufficiente di per sé.

Strumenti

Funzioni personalizzate

POST /agents/{agentId}/custom-functions consente all’Agente di richiamare una delle tue funzioni personalizzate durante le conversazioni. È possibile collegare solo le funzioni appartenenti allo stesso account e collegarne una già collegata non cambia nulla.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} la scollega. La funzione stessa non viene eliminata e rimane disponibile per gli altri tuoi Agenti.

Gestisci le funzioni stesse su /custom-functions — vedi Funzioni personalizzate per sapere cosa sono.

Server MCP

Un server MCP è un pacchetto pronto all’uso di strumenti che il tuo Agente può scoprire e richiamare autonomamente — vedi Connetti i server MCP al tuo bot. I server vengono registrati una volta sull’account, quindi collegati a qualsiasi Agente debba utilizzarli.

I server MCP richiedono la funzionalità funzioni personalizzate nel tuo piano. Senza di essa, gli endpoint /mcp-servers a livello di account restituiscono 403. Il collegamento di un server già registrato a un Agente non è limitato.

Registra un server

POST /mcp-servers

Campo	Obbligatorio	Descrizione
`name`	Sì	Un’etichetta per il server.
`url`	Sì	L’indirizzo del server. Deve essere raggiungibile tramite la rete internet pubblica.
`auth_type`	No	`header` (il valore predefinito) per un’intestazione di autenticazione statica, o `oauth2`.
`auth_header_name`	No	Intestazione in cui inviare la credenziale. Il valore predefinito è `Authorization`.
`auth_header_value`	No	La credenziale stessa. Non viene mai restituita in alcuna risposta.
`enabled`	No	Indica se il server è disponibile per gli Agenti. Il valore predefinito è `true`.
`enabled_tools`	No	Lista consentita di nomi di strumenti. `null` significa che ogni strumento offerto dal server è attivo.
`tool_policies`	No	Limiti per singolo strumento, indicizzati per nome dello strumento: frequenza di esecuzione, memorizzazione nella cache dei risultati e override di sola lettura. Passa `null` per cancellarli tutti.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Risposta (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Al salvataggio, la piattaforma si connette al server e memorizza nella cache l’elenco degli strumenti offerti. Un server non raggiungibile viene comunque salvato, con la motivazione in last_error e un elenco di strumenti vuoto: in questo modo è possibile effettuare la registrazione prima e risolvere i problemi di connettività in seguito.

Un auth_type di oauth2 salva la registrazione con oauth_connected: false e nessun strumento: non c’è ancora alcun token. L’autorizzazione di un server OAuth richiede un accesso tramite browser e viene effettuata dalla dashboard, non tramite API.

Elenca, aggiorna ed elimina server

GET /mcp-servers — ogni server registrato, dal più recente, sotto servers.
PUT /mcp-servers/{serverId} — invia solo ciò che desideri modificare. La modifica dell’URL o dei campi di autenticazione riesegue il test della connessione e aggiorna l’elenco degli strumenti memorizzato nella cache.
DELETE /mcp-servers/{serverId} — rimuove la registrazione e scollega il server da ogni Agente e campagna che lo aveva abilitato.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

I segreti non vengono mai restituiti. Le risposte contengono auth_header_value_set (un flag true/false che indica che un valore è memorizzato) invece della credenziale, mentre i token OAuth e i segreti del client rimangono lato server. Tutto il resto viene restituito: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Testare una connessione

POST /mcp-servers/test-connection — si connette a un server ed elenca i suoi strumenti. Due modi per richiamarlo:

con server_id — testa la configurazione salvata e aggiorna il suo elenco di strumenti memorizzato nella cache;
con un url in linea (più auth_header_name / auth_header_value) — un test pre-salvataggio che non memorizza nulla.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Risposta (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Un errore di connessione non è un errore HTTP: si ottiene un 200 con success: false e un error che descrive cosa è andato storto, in modo da poterlo mostrare accanto al campo che l’operatore sta modificando.

Collegare un server a un Agente

La registrazione di un server non fornisce ad alcun Agente l’accesso ad esso. Collegalo:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Risposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} lo scollega nuovamente. Il server stesso non viene eliminato e rimane disponibile per gli altri Agenti. Collegare o scollegare qualcosa che si trova già in quello stato non cambia nulla.

Libreria multimediale

La libreria multimediale contiene i file che un Agente può inviare durante una conversazione: un menu, un listino prezzi, la foto di un prodotto. Un Agente può contenere al massimo 50 elementi.

Elenca i file multimediali

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Risposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Gli elementi archiviati sull’Agente appaiono per primi, seguiti da eventuali elementi più vecchi ancora memorizzati nella campagna da cui è stato creato l’Agente; media_home (agent o campaign) indica quale sia l’uno e quale l’altro. All’interno di ciascun gruppo, i più recenti appaiono per primi.

media_url scade dopo 7 giorni. È il link di download creato al momento del caricamento del file: considera quello vecchio come non aggiornato piuttosto che non funzionante, e rileggi l’elenco per ottenere un link nuovo.

Carica file multimediali

POST /agents/{agentId}/media-library — il file viene caricato inline come base64, fino a 10 MB. La chiamata termina una volta che il file è stato archiviato, quindi concedi un po’ più di tempo rispetto a una richiesta normale. Nota che questo corpo utilizza nomi di campo in camelCase.

Campo	Obbligatorio	Descrizione
`base64Data`	Sì	Contenuto del file, codificato in base64, senza prefisso data-URL.
`mimeType`	Sì	Tipo MIME del file.
`fileName`	Sì	Nome file originale, utilizzato per denominare il file archiviato.
`title`	No	Breve etichetta mostrata nella libreria.
`description`	No	L’istruzione “quando dovrebbe inviarlo l’Agente”.
`sendMessage`	No	Formulazione preferita che l’Agente utilizza quando invia l’elemento. Tagliata a 500 caratteri.
`maxSendsPerConversation`	No	Quante volte può essere inviato allo stesso contatto in una conversazione. Il valore predefinito è `1`.
`sendAsVoiceNote`	No	Solo caricamenti audio: archivia il file come nota vocale di WhatsApp. Ignorato per altri tipi di file.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Due operazioni avvengono automaticamente: una GIF animata viene convertita in video in modo che venga riprodotta su ogni canale, e la piattaforma scrive un breve riepilogo del contenuto effettivo del file in modo che l’Agente sappia quando è appropriato utilizzarlo.

Un 400 copre campi mancanti, un tipo di file non supportato, un file vuoto o troppo grande e il raggiungimento del limite di 50 elementi. Un 403 indica che la libreria multimediale è disattivata per l’account.

Aggiorna un elemento multimediale

PATCH /agents/{agentId}/media-library/{itemId} — solo metadati. Il file stesso non può essere sostituito; carica un nuovo elemento ed elimina quello vecchio. Questo corpo utilizza snake_case: title, description, send_message, max_sends_per_conversation (un numero intero non negativo, o null per cancellare il limite).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Risposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Elimina un elemento multimediale

DELETE /agents/{agentId}/media-library/{itemId} — rimuove l’elemento e il relativo file archiviato. L’eliminazione di un elemento già rimosso ha successo e riporta deleted: false, quindi la chiamata è sicura da riprovare.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Genera messaggi di follow-up

POST /agents/{agentId}/template-generation — scrive per te i messaggi di follow-up dell’Agente (i solleciti che invia quando una conversazione si interrompe), in base allo scopo dell’Agente.

Campo	Descrizione
`type`	`all` (impostazione predefinita) scrive l’intero set. `cold_only` scrive solo i messaggi per i contatti che non hanno mai risposto.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Ci sono due modi in cui questo viene restituito, e il campo target ti indica quale:

target: "agent" con un 200 — i messaggi sono stati scritti durante la chiamata e il risultato è in data. Leggili dal follow_up_config dell’Agente. Questo è il caso abituale.
target: "campaign" con un 202 — il lavoro è stato messo in coda per la campagna indicata in campaign_id. Monitora il template_generation_status di quella campagna finché non termina.

cold_only richiede una campagna in uscita e viene rifiutato con 409 (reason: "cold_only_requires_campaign") su un Agente che non ne ha nessuna. Un 403 significa che i follow-up automatici non sono attivi per l’account. Questa funzione utilizza crediti AI, e un 400 con "Insufficient credits." significa che l’account li ha esauriti.

Instradamento delle conversazioni verso un Agente

Un Agente risponde solo alle conversazioni inviate da un Punto di ingresso. Finché un canale non ne ha uno, il primo messaggio di qualcuno con cui non hai mai parlato viene comunque archiviato, ma nessuno lo prende in carico e nessun assistente risponde.

Cosa vuoi fare	Chiamata
Rendere un Agente il risponditore per un intero canale	`PUT /entry-points/channel-defaults` con `{ "channel": "instagram", "agent_id": "AGENT_ID" }`
Aggiungere una regola più specifica (parole chiave, commenti, nuovi follower)	`POST /agents/{agentId}/entry-points`
Vedere le regole che puntano a un Agente	`GET /agents/{agentId}/entry-points`
Lasciare un canale senza nessuno che risponda	`DELETE /entry-points/channel-defaults?channel=instagram`

Elencare i Punti di ingresso di un Agente

GET /agents/{agentId}/entry-points — le regole di instradamento che inviano le conversazioni a questo Agente, dalla più recente alla meno recente. Vengono restituite sia le regole attuali che quelle ritirate; una regola ritirata presenta enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Per le impostazioni predefinite dei canali dell’intero account, incluso un canale impostato deliberatamente su nessuno, leggi invece GET /entry-points/channel-defaults.

Creare un Punto di ingresso

POST /agents/{agentId}/entry-points — l’Agente nel percorso ha sempre la priorità, quindi non è mai possibile creare una regola per un Agente diverso da quello presente nell’URL.

`type`	Cosa fa
`channel_default`	L’Agente risponde a ogni nuovo contatto sui canali elencati. Preferisci `PUT /entry-points/channel-defaults` per questo: ritira automaticamente il risponditore precedente, cosa che la creazione di un secondo valore predefinito qui non fa.
`keyword`	L’Agente prende il controllo quando il primo messaggio contiene una delle `match_config.keywords`. È richiesta almeno una parola chiave.
`instagram_comment` / `facebook_comment`	L’Agente risponde ai commenti sui tuoi post. Il canale corrispondente deve essere elencato in `channels`.
`instagram_follower`	L’Agente saluta i nuovi follower.

channels è obbligatorio e indica quali canali copre la regola — ad esempio whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget o custom_channel. Le nuove regole sono abilitate a meno che tu non specifichi diversamente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Risposta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Quale regola vince quando più di una potrebbe applicarsi: una conversazione in corso o un’assegnazione manuale mantiene l’Agente che ha già; altrimenti, le regole basate su parole chiave prevalgono su quelle per i commenti, che a loro volta prevalgono su quelle per i follower, e un valore predefinito del canale è l’ultima risorsa. Se queste regole abbiano già deciso qualcosa su un account viene riportato da GET /entry-points/routing-status.

Questa è la versione breve. La guida all’Entry Points API copre l’intera gerarchia, le regole per commenti e follower, un Agente per numero WhatsApp e la modifica o l’eliminazione di una regola. Consulta Entry Points per il concetto e la Channels API per collegare il canale stesso.

Errori dell’API degli Agenti IA

Gli endpoint degli Agenti restituiscono il formato di errore standard:

{
  "success": false,
  "error": "Agent not found"
}

Stato	Quando si verifica su un endpoint Agente
`400`	Un campo obbligatorio è mancante o non valido: un corpo di aggiornamento vuoto, un valore al di fuori di un elenco consentito (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), una chiave non relativa a un giorno feriale in `availability`, un nome di campo con punti in `bot-config` o un ID malformato nel percorso.
`403`	L’account non è autorizzato a utilizzare un’impostazione inviata, hai raggiunto il limite di Agenti del tuo piano o una funzionalità necessaria a questo endpoint (libreria multimediale, follow-up, funzioni personalizzate per server MCP) è disattivata. Una modifica che supera la dimensione di configurazione consentita dal tuo piano viene rifiutata con `400`.
`404`	L’Agente, la regola di tag, l’elemento multimediale o il server MCP non sono stati trovati: o non esistono o appartengono a un altro account.
`409`	Qualcosa è già in corso o di intralcio: un’ottimizzazione o una generazione di tag è in esecuzione, l’Agente è ancora collegato a una trasmissione, a un Punto di ingresso o a una campagna, oppure è stato richiesto `cold_only` senza una campagna in uscita.

I codici condivisi che ogni endpoint può restituire — 401, 403 (il tuo piano non include l’accesso all’API), 429 (limite di frequenza) e 500 — sono elencati con indicazioni sui tentativi in Errori e Paginazione.

Una nota sull’explorer. Gli endpoint /agents sono presenti nella specifica OpenAPI pubblicata, quindi puoi consultare i loro campi esatti ed eseguire richieste live nel Riferimento API. Anche gli endpoint /mcp-servers a livello di account sono presenti nella specifica, quindi puoi esplorarli anche lì.

Correlati

Agenti IA — cos’è un Agente, in parole semplici.
Punti di ingresso — come le conversazioni vengono indirizzate a un Agente.
API delle FAQ — crea e collega la conoscenza a cui il tuo Agente risponde.
API dei canali — connetti i canali su cui risponde un Agente.
Connetti server MCP al tuo Bot · Funzioni personalizzate
Riferimento API — l’esploratore interattivo completo degli endpoint.

API degli Agenti AI #

Come è composto un Agente #

L’oggetto Agente #

Elenco Agenti #

Crea un Agente #

Ottieni un Agente #

Aggiorna un Agente #

Aggiorna le impostazioni del bot #

Imposta gli orari di attività #

Metti in pausa o riprendi un Agente #

Duplica un Agente #

Elimina un Agente #

Bozze: rivedi le modifiche prima che diventino effettive #

Pubblica la bozza #

Scarta la bozza #

Ottimizza un Agente con l’IA #

Regole di tagging #

Aggiungi una regola di tagging #

Sostituisci una regola di tagging #

Rimuovere una regola di tagging #

Generare un set di tag con l’IA #

Fonti di conoscenza #

Collegare fonti di conoscenza #

Scollegare fonti di conoscenza #

Domande frequenti (FAQ) #

Strumenti #

Funzioni personalizzate #

Server MCP #

Registra un server #

Elenca, aggiorna ed elimina server #

Testare una connessione #

Collegare un server a un Agente #

Libreria multimediale #

Elenca i file multimediali #

Carica file multimediali #

Aggiorna un elemento multimediale #

Elimina un elemento multimediale #

Genera messaggi di follow-up #

Instradamento delle conversazioni verso un Agente #

Elencare i Punti di ingresso di un Agente #

Creare un Punto di ingresso #

Errori dell’API degli Agenti IA #

Correlati #

API degli Agenti AI

Come è composto un Agente

L’oggetto Agente

Elenco Agenti

Crea un Agente

Ottieni un Agente

Aggiorna un Agente

Aggiorna le impostazioni del bot

Imposta gli orari di attività

Metti in pausa o riprendi un Agente

Duplica un Agente

Elimina un Agente

Bozze: rivedi le modifiche prima che diventino effettive

Pubblica la bozza

Scarta la bozza

Ottimizza un Agente con l’IA

Regole di tagging

Aggiungi una regola di tagging

Sostituisci una regola di tagging

Rimuovere una regola di tagging

Generare un set di tag con l’IA

Fonti di conoscenza

Collegare fonti di conoscenza

Scollegare fonti di conoscenza

Domande frequenti (FAQ)

Strumenti

Funzioni personalizzate

Server MCP

Registra un server

Elenca, aggiorna ed elimina server

Testare una connessione

Collegare un server a un Agente

Libreria multimediale

Elenca i file multimediali

Carica file multimediali

Aggiorna un elemento multimediale

Elimina un elemento multimediale

Genera messaggi di follow-up

Instradamento delle conversazioni verso un Agente

Elencare i Punti di ingresso di un Agente

Creare un Punto di ingresso

Errori dell’API degli Agenti IA

Correlati