Documentation

Documentazione

Guide complete per costruire, configurare e distribuire agenti AI con AgentForge.

Quick Start

Crea il tuo primo agente AI in 5 semplici passaggi.

AgentForge ti permette di costruire agenti AI conversazionali senza scrivere una riga di codice. In meno di 10 minuti puoi avere un agente funzionante, testarlo e incorporarlo nel tuo sito.

1. Crea un account

Vai su /signup e registrati con la tua email. Dopo la registrazione verrai reindirizzato alla pagina di billing per scegliere il piano. Seleziona il piano più adatto alle tue esigenze: Starter (€25/mese) per iniziare, Growth (€79/mese) per agenzie, Scale (€297/mese) per volumi elevati.

2. Crea il tuo primo agente

Dal dashboard clicca su “Nuovo Agente”. Puoi partire da zero (scratch), scegliere uno dei 12 template predefiniti (supporto clienti, prenotazioni, lead qualification, e-commerce...) oppure importare una configurazione da URL. Scegli il template più vicino al tuo caso d'uso per risparmiare tempo.

3. Configura la personalità

Nel Builder, scheda “Personalità”, imposta nome, avatar emoji, lingua e tono dell'agente. Scrivi il system prompt: questo è il cuore dell'agente, definisce come si comporta, cosa sa e come risponde. Aggiungi il messaggio di benvenuto e il messaggio di fallback per i casi in cui non capisce la domanda.

4. Testa l'agente

Usa il pannello di chat live a destra del Builder per testare l'agente in tempo reale. Ogni modifica al system prompt viene applicata immediatamente. Prova domande edge-case, verifica che il tono sia corretto e che le risposte siano accurate. Usa la scheda “Regole” per aggiungere comportamenti specifici (cosa fare e non fare).

5. Pubblica e incorpora

Vai alla scheda “Deploy”, clicca “Pubblica e ottieni link” per generare il link demo condivisibile. Copia il codice di incorporamento widget e incollalo nel tag <body> del tuo sito HTML. L'agente sarà subito attivo e operativo. Puoi anche condividere il link demo direttamente con i clienti per raccogliere feedback.

💡 Suggerimento

Inizia sempre con un template esistente e poi personalizzalo. Risparmierai almeno il 70% del tempo di configurazione.

Guida al Builder

Esplora i 7 tab del Builder e le loro funzionalità.

Il Builder è il cuore di AgentForge. È diviso in 7 schede tematiche che coprono ogni aspetto dell'agente, dal comportamento alla distribuzione. Sul lato destro hai sempre a disposizione la chat di anteprima live.

Personalità

Configura l'identità dell'agente: nome, descrizione, avatar emoji, lingua e tono. Il system prompt è il campo più importante: definisce chi è l'agente, cosa sa e come risponde. Puoi scegliere tra 6 toni predefiniti (professionale, amichevole, formale, informale, empatico, conciso) e supporta tutte le lingue.

Regole

Definisci comportamenti specifici con tre liste: “Cosa fare” (DOS) — istruzioni positive come rispondere sempre in italiano, citare i prezzi, usare un certo formato. “Cosa non fare” (DON'Ts) — restrizioni come non discutere di competitor, non fornire consulenza legale. “Trigger di escalation” — frasi o situazioni che attivano il trasferimento a un operatore umano.

Flusso

Controlla il comportamento della conversazione: numero massimo di turni, ritardo di digitazione simulato (per sembrare più umano), escalation automatica quando si supera il limite di turni, e il messaggio di trasferimento mostrato quando avviene l'handoff a un operatore.

Widget

Personalizza l'aspetto del widget di chat: colore primario, nome bot, URL avatar personalizzato, messaggio di benvenuto e posizione (in basso a destra, sinistra o centro). L'anteprima si aggiorna in tempo reale.

Deploy

Gestisci lo stato dell'agente (Bozza, In test, Attivo, In pausa), configura il sito web cliente, attiva la demo pubblica e genera il codice di incorporamento. Il pulsante “Pubblica” crea il link demo e imposta lo stato su Attivo.

Canali

Collega l'agente a canali di messaggistica esterni: WhatsApp Business API, Telegram bot, Instagram Direct, Messenger. Ogni canale ha la propria configurazione con token e webhook URL da inserire nel pannello del provider.

Knowledge Base

Aggiungi una base di conoscenza all'agente importando siti web (lo scraper estrae automaticamente il testo) o aggiungendo testi manuali (FAQ, listini prezzi, documentazione). Il contenuto viene usato dal modello AI per rispondere con informazioni specifiche del tuo business.

💾 Salvataggio

Ricorda di salvare le modifiche con il pulsante “Salva” in alto a destra. Le modifiche al system prompt si applicano immediatamente nella preview ma vengono persistite solo al salvataggio.

Widget Embed

Incorpora la chat del tuo agente in qualsiasi sito web.

Il widget AgentForge è uno snippet JavaScript leggero che puoi aggiungere a qualsiasi sito HTML, WordPress, Webflow, Shopify o piattaforma che permetta codice personalizzato. Il widget si carica in modo asincrono senza impattare le performance del sito.

Ottieni il codice

Nel Builder → Deploy, clicca “Pubblica e ottieni link”. Il codice viene generato automaticamente con il tuo agentId e le impostazioni del widget.

Incolla nel tuo sito

Copia il tag <script> e incollalo prima della chiusura del tag </body> in tutte le pagine dove vuoi mostrare la chat. Se usi un CMS, usa il campo “Codice personalizzato” nel footer globale.

Snippet di esempio

html

<script
  src="https://app.agentforge.ai/widget/agentforge-widget.js"
  data-agent="YOUR_AGENT_SLUG"
  data-color="#F97316"
  data-title="Supporto AgentForge"
  data-welcome="Ciao! Come posso aiutarti?"
></script>

Attributi disponibili

→data-agent — ID o slug dell'agente (obbligatorio)
→data-color — Colore hex del widget (es. #F97316)
→data-title — Titolo mostrato nella testata del widget
→data-welcome — Messaggio di benvenuto iniziale

🔵 WordPress

In WordPress, vai in Aspetto → Editor del tema → footer.php e incolla lo snippet prima di </body>. In alternativa usa un plugin come “Insert Headers and Footers” per aggiungere il codice senza modificare il tema.

🌐 Webflow

In Webflow, vai in Impostazioni Progetto → Custom Code → Footer Code e incolla lo snippet. Il widget apparirà su tutte le pagine del progetto.

⚡ Performance

Il widget si carica in modo asincrono e non blocca il rendering della pagina. La dimensione totale è inferiore a 15KB gzippato.

Knowledge Base

Insegna al tuo agente informazioni specifiche del tuo business.

La Knowledge Base permette all'agente di rispondere con informazioni accurate e specifiche della tua azienda: prezzi, prodotti, procedure, FAQ. Puoi importare siti web o aggiungere testo manualmente.

Importare un sito web

Step 1

Nel Builder → Knowledge, clicca “Importa Sito Web”.

Step 2

Inserisci l'URL del sito (es. https://tuodominio.com) e un nome opzionale per il documento.

Step 3

Clicca “Importa Sito”. Lo scraper visita la pagina, estrae il testo e lo indicizza.

Step 4

Il documento appare nella lista con lo stato “Pronto”. L'agente userà questo contenuto per rispondere.

⚠️ Nota

Lo scraper funziona su pagine HTML pubbliche. Non supporta contenuti dietro login o generati dinamicamente con JavaScript pesante. Per siti complessi, usa l'aggiunta manuale di testo.

Aggiungere testo manuale

Usa il campo “Carica Testo Manuale” per incollare FAQ, listini prezzi, schede prodotto, procedure interne o qualsiasi testo strutturato. Assegna un nome descrittivo (es. “FAQ Prodotto”, “Listino 2024”) per identificare facilmente i documenti.

Limiti e consigli

✓Ogni documento può contenere fino a 100.000 caratteri.
✓Aggiungi documenti separati per argomenti diversi (prezzi, prodotti, supporto) per migliorare la precisione.
✓Aggiorna i documenti quando le informazioni cambiano per mantenere l'agente accurato.
✓Più la knowledge base è specifica e strutturata, più accurate saranno le risposte.

Canali

Collega il tuo agente a WhatsApp, Telegram, Instagram e Messenger.

AgentForge supporta l'integrazione con i principali canali di messaggistica. Ogni canale richiede una configurazione specifica con credenziali API del provider. La configurazione si trova nel Builder → Canali.

💬 WhatsApp Business

Richiede un account WhatsApp Business API (via Meta for Developers o provider come Twilio, 360dialog). Avrai bisogno di: Phone Number ID, WhatsApp Business Account ID e Access Token permanente. Inserisci il Webhook URL fornito da AgentForge nel dashboard Meta per ricevere i messaggi.

✈️ Telegram

Crea un bot Telegram tramite @BotFather, ottieni il bot token (formato: 123456789:ABCDEFxxxxx). Incollalo nel campo Token Telegram nel Builder. AgentForge configura automaticamente il webhook di Telegram per ricevere i messaggi.

📸 Instagram Direct

Richiede un account Instagram Business collegato a una Pagina Facebook e l'accesso all'API Messenger di Meta. Usa il Meta App Review per ottenere i permessi necessari (instagram_manage_messages). Inserisci il Page Access Token e verifica il webhook con il token di verifica fornito.

💙 Messenger

Collega una Pagina Facebook al tuo agente. Crea un'app su Meta for Developers, aggiungi il prodotto Messenger, seleziona la Pagina e genera un Page Access Token. Configura il webhook con l'URL di AgentForge e iscriviti all'evento “messages”.

📋 Note importanti

•I canali WhatsApp e Instagram richiedono la verifica dell'account business da parte di Meta (processo di 1-7 giorni).
•Telegram non richiede approvazioni: è il canale più semplice da configurare.
•Puoi attivare più canali sullo stesso agente simultaneamente.
•I messaggi ricevuti da tutti i canali appaiono nella sezione Conversazioni del dashboard.

API Keys

Integra AgentForge nelle tue applicazioni tramite API REST.

Le API Keys ti permettono di interagire con i tuoi agenti programmaticamente: inviare messaggi, creare agenti, leggere conversazioni e altro. Le trovi in Dashboard → Impostazioni → API Keys.

Creare una API Key

Step 1

Vai in Impostazioni → API Keys.

Step 2

Clicca “Nuova API Key” e assegna un nome descrittivo (es. “Integrazione CRM”, “App Mobile”).

Step 3

Copia la chiave generata (formato: sk-af-xxxxxxxxxx). Viene mostrata una sola volta.

Step 4

Usa la chiave nell'header Authorization: Bearer sk-af-xxxxxxxxxx di ogni richiesta.

Endpoint principali

POST /api/agents/{id}/chat — Invia un messaggio all'agente e ricevi la risposta
GET /api/agents — Lista tutti i tuoi agenti
GET /api/conversations — Lista le conversazioni
GET /api/analytics — Dati analytics aggregati

Esempio di richiesta

bash

curl -X POST https://app.agentforge.ai/api/agents/{agentId}/chat \
  -H "Authorization: Bearer sk-af-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Ciao, ho bisogno di aiuto",
    "sessionId": "session_abc123"
  }'

🔒 Sicurezza

!Non esporre mai le API Key nel codice client-side (JavaScript del browser).
!Usa variabili d'ambiente per le API Key nei tuoi server.
!Crea API Key separate per ogni applicazione o integrazione.
!Puoi eliminare e ricreare le chiavi in qualsiasi momento dalla pagina Impostazioni.

Webhook

Ricevi notifiche in tempo reale sugli eventi del tuo agente.

I webhook permettono ad AgentForge di inviare notifiche HTTP al tuo server quando avvengono eventi specifici: nuovi messaggi, conversazioni avviate, crediti in esaurimento. Perfetti per integrazioni con Zapier, Make, o applicazioni custom.

Webhook Outbound (AgentForge → il tuo server)

Configura webhook outbound in Dashboard → Integrazioni → Webhook. Inserisci l'URL del tuo endpoint e scegli gli eventi da monitorare.

Eventi disponibili

agent.message_received— Un utente ha inviato un messaggio all'agente
agent.message_sent— L'agente ha risposto
conversation.started— Nuova conversazione avviata
conversation.ended— Conversazione terminata
agent.created— Un nuovo agente è stato creato
credit.low— Crediti in esaurimento (sotto il 10%)

Payload di esempio

json

{
  "event": "agent.message_received",
  "timestamp": "2025-03-11T10:00:00Z",
  "agentId": "clxxx...",
  "data": {
    "conversationId": "clyyy...",
    "message": "Ciao, vorrei prenotare",
    "sessionId": "session_abc123"
  }
}

Verifica firma

Ogni richiesta webhook include l'header X-AgentForge-Signature con un HMAC-SHA256 del payload firmato con il tuo secret. Verifica sempre la firma per assicurarti che la richiesta provenga da AgentForge.

javascript

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return `sha256=${expected}` === signature;
}

Webhook Inbound (il tuo sistema → AgentForge)

Puoi anche inviare messaggi al tuo agente da sistemi esterni tramite il webhook inbound. L'URL è nella sezione Integrazioni e ha il formato: /api/webhooks/inbound/{userId}. Utile per ricevere notifiche da Zapier o Make e farle gestire dall'agente.

🔗 Integrazione Zapier / Make

Usa il webhook outbound come trigger in Zapier o Make per automatizzare flussi: quando un agente riceve un messaggio → aggiungi lead in CRM, invia email di notifica, crea task in Notion, ecc.

Sub-Account

Gestisci i tuoi clienti con account separati e isolati.

I Sub-Account (disponibili dal piano Growth) ti permettono di gestire agenti per conto di clienti diversi mantenendo organizzazione e separazione. Ogni sub-account ha il suo nome, email, sito web e logo. Perfetto per agenzie che gestiscono più clienti.

Creare un sub-account

Step 1

Vai in Dashboard → Clienti → Nuovo Cliente.

Step 2

Inserisci nome, email cliente, URL sito web, logo e note interne.

Step 3

Il sub-account viene creato. Ora puoi assegnargli agenti.

Assegnare agenti a un cliente

Step 1

Vai in Agenti, trova l'agente che vuoi assegnare.

Step 2

Clicca ⋯ → “Assegna a cliente” e seleziona il sub-account.

Step 3

L'agente appare ora associato al cliente nella lista agenti.

🔗 Portale condiviso

Ogni sub-account ha un portale condiviso con link univoco. Puoi attivarlo per dare al cliente accesso in sola lettura ai propri agenti e conversazioni, senza accesso all'intero dashboard AgentForge.

🏷️ White-label

Combinato con le impostazioni White-Label (Impostazioni → Organizzazione), puoi presentare la piattaforma con il tuo brand: logo, colori e dominio personalizzato. I tuoi clienti vedranno il tuo marchio, non AgentForge.

Piani e Crediti

Comprendi come funziona il sistema di crediti e cosa include ogni piano.

AgentForge usa un sistema a crediti: ogni messaggio inviato a un agente consuma 1 credito. I crediti si rinnovano mensilmente con il piano. Non esiste un piano gratuito: i nuovi account iniziano con 50 crediti di prova (piano PROVA).

Piani disponibili

PROVA

50 crediti inclusi alla registrazione. Modello Claude Haiku. Nessun pagamento richiesto per iniziare. Accesso limitato alle funzionalità avanzate.

STARTER — €25/mese

500 crediti mensili. Modello Claude Haiku. Fino a 3 agenti. Supporto email. Ideale per freelancer e piccole attività.

GROWTH — €79/mese

3.000 crediti mensili. Modelli Claude Haiku e Sonnet. Agenti illimitati. Sub-account clienti. Analytics avanzate. Webhook. Supporto prioritario.

SCALE — €297/mese

10.000 crediti mensili. Tutti i modelli AI (Haiku, Sonnet, Opus). White-label completo. Dominio personalizzato. SSO/SAML. Account manager dedicato.

💳 Come funzionano i crediti

→1 credito = 1 messaggio utente inviato all'agente.
→Le demo pubbliche (link /demo/...) sono gratuite: non consumano crediti.
→I crediti si azzerano e si rinnovano ogni mese dalla data di inizio abbonamento.
→Puoi monitorare i crediti rimanenti nella barra in alto del dashboard.
→Quando i crediti scendono sotto il 10%, ricevi una notifica email e un webhook credit.low.

Come aggiornare il piano

Vai in Dashboard → Billing e clicca “Scegli piano” sul piano desiderato. Verrai reindirizzato a Stripe per il pagamento sicuro. Il piano si attiva immediatamente dopo il pagamento e i crediti vengono aggiunti all'account.

Vai a Billing

FAQ

Domande frequenti su AgentForge.

Non hai trovato la risposta?

Il nostro team di supporto è disponibile per aiutarti.

Apri un ticket hello@agentforge.ai