Agenti AI

Un agente AI è un assistente a più passaggi. Legge la conversazione, pianifica, chiama strumenti (i Suoi strumenti AI, gli strumenti MCP e una ricerca nella knowledge base), osserva i risultati e richiama il modello finché non ha una risposta. Il nodo Crea completamento chat AI effettua una sola chiamata al modello e risponde; il nodo Agente AI può continuare a lavorare con più chiamate al modello e agli strumenti, entro i limiti che imposta, prima di rispondere.

Usi un agente quando una richiesta richiede più passaggi, ad esempio "trova l'ordine del cliente, controlla lo stato della consegna e proponi una nuova data". Per una risposta diretta basata su istruzioni e su una knowledge base, il nodo AI è più semplice ed economico.

Gli elementi di base

Elemento	Che cos'è	Dove si imposta
AI Harness	Il motore che esegue il ciclo dell'agente: quello di MonoChat, un SDK per agenti o un servizio di agenti ospitato.	Impostazioni › Automazione › Harness AI
Modelli	I modelli AI con cui l'agente ragiona: un modello principale, un modello di fallback facoltativo e un modello veloce facoltativo. Gli harness ospitati usano invece i modelli del proprio provider.	Il nodo Agente AI
Strumenti	Ambiti AI, funzioni Strumento AI e strumenti MCP.	Il nodo Agente AI
Budget di esecuzione	Limiti su chiamate al modello, chiamate agli strumenti, token, durata e tentativi per ogni esecuzione.	Il nodo Agente AI
Esecuzione	Una singola esecuzione dell'agente. Ogni esecuzione viene registrata in Esecuzioni dell'agente AI.	Creata dal nodo o dall'API

Harness AI

Impostazioni › Automazione › Harness AI elenca gli harness su cui possono girare i Suoi agenti: quelli che MonoChat offre a ogni workspace e quelli che aggiunge Lei con le Sue credenziali.

Harness	Dove viene eseguito	Modelli che usa	Chi lo aggiunge
MonoChat Native	All'interno di MonoChat	I Suoi modelli AI	MonoChat
OpenAI Agents SDK	All'interno di MonoChat	I Suoi modelli AI	MonoChat
Claude Agent SDK	Sull'agent runner di MonoChat	I Suoi modelli AI	MonoChat
pi	Sull'agent runner di MonoChat	I Suoi modelli AI	MonoChat
OpenAI Agents API	Nel cloud di OpenAI	I modelli consentiti dell'harness	Lei, con la Sua chiave API OpenAI (anche MonoChat può offrirne una)
Claude Managed Agents	Nel cloud di Anthropic	I modelli consentiti dell'harness	Lei, con la Sua chiave API Anthropic (anche MonoChat può offrirne una)
Custom Endpoint	Sul Suo server	I Suoi modelli AI (facoltativo)	Lei, con il Suo endpoint e il Suo secret

Gli harness che girano su MonoChat sono offerti da MonoChat; il Suo workspace può aggiungere solo harness che richiedono credenziali proprie. Claude Agent SDK e pi richiedono l'agent runner di MonoChat: dove non è configurato, un'esecuzione su di essi non riesce con "Questo harness non è disponibile su questo server."

Qualunque sia l'harness, MonoChat mantiene il controllo: ogni chiamata al modello di un harness che usa i Suoi modelli AI passa da MonoChat (quindi si applicano fatturazione e budget), ogni chiamata agli strumenti esegue le Sue funzioni, i Suoi strumenti MCP e i Suoi ambiti AI nel Suo workspace, e il budget viene applicato su ogni harness.

Aggiungere un harness

Vada in Impostazioni › Automazione › Harness AI e faccia clic su + (Crea).
Inserisca un Nome e, facoltativamente, una Descrizione.
Scelga l'Harness. Ogni opzione indica dove viene eseguito.
In Credenziali, inserisca ciò che serve all'harness:
- OpenAI Agents API, Claude Managed Agents: Chiave API.
- Custom Endpoint: Endpoint e Chiave API.
Per un harness ospitato, compili Modelli consentiti: inserisca i nomi dei modelli del provider (ad esempio l'ID del modello OpenAI o Anthropic). Usi Aggiungi modello per un massimo di 10 modelli. Gli agenti su questo harness possono scegliere solo da questo elenco.
Faccia clic su Salva.

Quando modifica un harness, il tipo di Harness non può essere cambiato e il campo della chiave riporta Chiave API (lasci vuoto per mantenere la chiave salvata).

Claude Managed Agents

La prima volta che viene usato un harness di questo tipo, MonoChat crea un agente e un ambiente in quell'account Anthropic e poi li riutilizza.

Custom Endpoint

Un harness Custom Endpoint invia le esecuzioni al Suo servizio, ad esempio un agente self-hosted. Per ogni esecuzione MonoChat invia una POST a <Endpoint>/runs con Authorization: Bearer <API Key>. Il corpo contiene l'ID dell'esecuzione, le istruzioni, l'input, i messaggi della conversazione, il budget, gli alias dei modelli (agent-main, agent-fallback, agent-fast) e tre URL con un token per questa esecuzione:

un gateway dei modelli (URL di base compatibili con OpenAI …/v1 e con Anthropic) che chiama i modelli AI del nodo e applica il budget,
un server MCP che espone gli strumenti dell'esecuzione,
un URL degli eventi in cui il Suo servizio comunica il risultato (completed con result, oppure failed con error).

Il token dell'esecuzione smette di funzionare quando l'esecuzione termina.

Il nodo Agente AI

Aggiunga un agente a un flusso con il nodo Agente AI, tra i nodi ibridi del designer dei flussi. Per sapere come aggiungere e collegare i nodi, consulti Flussi.

Campi

Sezione	Campo	Descrizione
	Nome	Il nome del nodo mostrato sul canvas.
	AI Harness	Obbligatorio. L'harness che esegue l'agente.
	Istruzioni	Le istruzioni di sistema dell'agente: il suo ruolo, il tono, le regole e ciò che può o non può fare.
	Attività (aggiunta alle istruzioni dell'agente; è possibile usare i tag)	Ciò che questo nodo chiede di fare all'agente. Viene aggiunta dopo le istruzioni e può usare gli stessi tag del prompt del nodo AI, ad esempio per includere i dati del cliente.
Modelli	Modello principale	Il modello usato dall'agente. Obbligatorio per ogni harness tranne Custom Endpoint.
	Modello di fallback (dopo il limite soft)	Il modello a cui l'agente passa una volta raggiunto il limite soft di chiamate al modello, in genere un modello più economico o più veloce.
	Modello veloce (attività leggere in background)	Un modello che un harness può usare per le sue chiamate leggere in background.
	Modello (uno dei modelli consentiti dell'harness)	Mostrato al posto dei tre campi precedenti per un harness ospitato.
Conversazione dell'agente	Conversazione	Continua la sessione dell'agente esistente (predefinito) oppure Avvia una nuova sessione dell'agente. Vedere Sessioni dell'agente.
	Chiave attività (conversazioni dell'agente separate per attività)	Facoltativa. Mantiene una sessione dell'agente separata per ogni chiave nella stessa conversazione, ad esempio `booking` e `support`.
	Limite della cronologia messaggi	Quanti messaggi della conversazione riceve l'agente.
	Modelli AI di riconoscimento vocale	Un modello con Trascrizione. I messaggi vocali della conversazione arrivano all'agente come testo.
Impostazioni dello strumento	Ambiti AI	Knowledge base in cui l'agente può cercare. Vengono offerte all'agente come strumento di ricerca nella knowledge base.
	Strumento AI	Funzioni di tipo Strumento AI che l'agente può chiamare.
	Imposta gli strumenti contenuti client MCP AI	Apre il pannello in cui aggiunge gli strumenti MCP. Vedere Client MCP.
Messaggi	Inoltra i messaggi intermedi al cliente	Disattivato per impostazione predefinita. Quando è attivo, ciò che l'agente scrive mentre sta ancora lavorando (ad esempio "Controllo subito il Suo ordine") viene inviato al cliente; quando è disattivato viene aggiunto alla sessione come messaggio riservato visibile solo al Suo team.
	Invia risposta	Attivo per impostazione predefinita. Invia al cliente la risposta finale dell'agente. Lo disattivi per usare la risposta solo all'interno del flusso.
Budget di esecuzione	Numero massimo di chiamate al modello	Predefinito 4.
	Limite soft: chiamate al modello	Facoltativo. Dopo questo numero di chiamate al modello l'agente passa al modello di fallback. Deve essere inferiore a Numero massimo di chiamate al modello e richiede un modello di fallback.
	Numero massimo di chiamate agli strumenti	Predefinito 6. Con `0`, l'esecuzione termina come Budget superato non appena l'agente tenta di chiamare uno strumento.
	Numero massimo di token totali	Predefinito 20000. Token di input e di output di tutte le chiamate al modello dell'esecuzione.
	Durata massima (secondi)	Predefinito 30.
	Numero massimo di tentativi	Predefinito 2. Quante volte viene ritentata una chiamata al modello non riuscita.

suggerimento

Scriva le regole stabili in Istruzioni e il compito specifico di questo passaggio in Attività. In questo modo più nodi Agente AI di un flusso possono condividere le stesse istruzioni e differire solo per l'attività.

avvertenza

Gli harness ospitati non supportano un limite soft, perché non possono passare a un modello di fallback. Lasci vuoto Limite soft: chiamate al modello per questi harness.

Cosa succede quando il flusso raggiunge il nodo

MonoChat controlla il Suo saldo e le impostazioni del nodo, e avvia un'esecuzione. L'esecuzione è In coda, poi In esecuzione. L'istanza del flusso resta in attesa sul nodo.
L'agente riceve le istruzioni e l'attività e, quando il flusso appartiene a una conversazione, i messaggi della conversazione fino al Limite della cronologia messaggi, con i messaggi vocali trascritti.
L'agente chiama modelli e strumenti finché non ha una risposta o non raggiunge un limite. Il testo che scrive tra una chiamata e l'altra agli strumenti viene gestito come messaggio intermedio.
Quando l'esecuzione termina:
- se è Completato e Invia risposta è attivo, la risposta viene inviata al cliente. Le risposte lunghe vengono suddivise in più messaggi quando superano il limite del canale (4096 caratteri su WhatsApp);
- se è terminata in un altro modo, al team viene aggiunto alla sessione un messaggio riservato "Esecuzione dell'agente AI terminata: stato. errore".
Il flusso prosegue sull'uscita che corrisponde a come si è conclusa l'esecuzione.

Le esecuzioni della stessa sessione dell'agente vengono elaborate una alla volta, in ordine.

Uscite

Uscita	Quando
Completato	L'agente ha concluso con una risposta.
Budget superato	L'esecuzione ha esaurito Numero massimo di chiamate al modello, Numero massimo di chiamate agli strumenti o Numero massimo di token totali.
Tempo scaduto	L'esecuzione ha raggiunto Durata massima (secondi).
Odio, Jailbreak, Autolesionismo, Contenuti sessuali, Violenza	Il filtro dei contenuti del provider del modello ha interrotto l'esecuzione per questa categoria. Sono le stesse uscite del nodo AI.
In caso di errore	L'esecuzione non è riuscita per qualsiasi altro motivo, oppure è stata annullata. Anche l'interruzione da parte del filtro dei contenuti arriva qui nei nodi salvati prima che queste uscite esistessero; apra e salvi un nodo di questo tipo per ottenerle.

Colleghi almeno Completato e In caso di errore. Uno schema comune consiste nell'inviare Budget superato, Tempo scaduto e In caso di errore a un nodo Assegna conversazione, in modo che un collega subentri.

Sessioni dell'agente

Una sessione dell'agente è la memoria dell'agente tra le esecuzioni. MonoChat mantiene una sessione dell'agente attiva per conversazione, harness e chiave attività.

Continua la sessione dell'agente esistente la riutilizza, così l'agente riprende da dove si era fermato. Sugli harness ospitati prosegue anche la sessione del provider.
Avvia una nuova sessione dell'agente chiude quella attiva e riparte da zero, ad esempio all'inizio di un nuovo argomento.
Una Chiave attività mantiene sessioni indipendenti affiancate nella stessa conversazione.

Fatturazione

Le chiamate ai modelli AI forniti da MonoChat vengono addebitate sul Suo saldo come di consueto. Le chiamate ai Suoi modelli sono fatturate dal Suo provider.
Un harness fornito da MonoChat può aggiungere costi propri per esecuzione, per minuto e per chiamata agli strumenti e, per un harness ospitato, i token comunicati dal suo provider. Compaiono in Transazioni come Esecuzione dell'agente AI, Durata dell'agente AI, AI Agent Tool Call e categorie di token AI.
Un harness che aggiunge con le Sue credenziali non ha costi MonoChat; la fattura il suo provider.
Un'esecuzione non parte se il Suo saldo è insufficiente.

Evento Esecuzione dell'agente AI terminata

Esecuzione dell'agente AI terminata è un nodo evento. Si attiva quando termina un'esecuzione collegata a un cliente, sia che l'esecuzione sia stata avviata da un flusso sia tramite l'API con una conversazione. Come gli altri nodi evento ha le impostazioni facoltative Condizione e Tempo scaduto. Lo usi per avviare un flusso separato dopo le esecuzioni dell'agente, ad esempio per registrare i risultati o avvisare un team.

Avviare un agente dal codice

Le funzioni personalizzate e i client API possono eseguire agenti con questi metodi (permesso Avviare / Leggere / Annullare esecuzioni di agenti AI nell'automazione):

Metodo	Cosa fa
`business.tenants.automation.ai.aiAgentRuns.create`	Avvia un'esecuzione. Restituisce `aiAgentRunId` e `aiAgentSessionId`.
`business.tenants.automation.ai.aiAgentRuns.show`	Restituisce un'esecuzione (`_id`) con stato, utilizzo, passaggi e risultato.
`business.tenants.automation.ai.aiAgentRuns.cancel`	Annulla un'esecuzione in coda o in corso (`_id`).

create accetta aiHarnessClientId, input (l'attività), facoltativamente sessionId (per lavorare in una conversazione), aiAgentSessionId, taskKey e isNewSession, e options con le stesse impostazioni del nodo: instructions, aiModelClientId, fallbackAiModelClientId, fastAiModelClientId, harnessModel, toolCustomFunctionIds, aiScopeIds, aiMcpClientDatas, messageHistoryLimit, speechToTextAiModelClientId, forwardIntermediateMessages, willSendAnswer e un budget obbligatorio. Tramite l'API, forwardIntermediateMessages e willSendAnswer sono false per impostazione predefinita.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

L'esecuzione è asincrona: la legga in seguito con show, oppure reagisca ad essa con l'evento Esecuzione dell'agente AI terminata. Senza un sessionId, ogni chiamata avvia una nuova sessione dell'agente, a meno che non passi l'aiAgentSessionId restituito da una chiamata precedente; l'agente vede allora come cronologia le esecuzioni completate in precedenza di quella sessione dell'agente. Per chiamare i metodi da una funzione, consulti Method.

Permessi

Permesso	Consente
Leggere / Creare / Aggiornare / Eliminare harness AI nell'automazione	Gestire gli Harness AI
Leggere esecuzioni di agenti AI nell'automazione	Vedere le Esecuzioni dell'agente AI
Avviare esecuzioni di agenti AI nell'automazione	Chiamare `aiAgentRuns.create`
Annullare esecuzioni di agenti AI nell'automazione	Chiamare `aiAgentRuns.cancel`

Vedere Ruoli.

Esecuzioni dell'agente AI: vedere cosa ha fatto ogni esecuzione
Modelli AI
Client MCP
Ambiti AI
Flussi

Gli elementi di base​

Harness AI​

Aggiungere un harness​

Custom Endpoint​

Il nodo Agente AI​

Campi​

Cosa succede quando il flusso raggiunge il nodo​

Uscite​

Sessioni dell'agente​

Fatturazione​

Evento Esecuzione dell'agente AI terminata​

Avviare un agente dal codice​

Permessi​

Correlati​