AgentChat
🇺🇸English 🇨🇳简体中文 🇭🇰繁體中文 🇯🇵日本語 🇰🇷한국어 🇫🇷Français 🇩🇪Deutsch 🇪🇸Español 🇮🇹Italiano
Accedi
← Tutti gli articoli
Architettura·10 min di lettura

Come aggiungere un agente IA al tuo SaaS utilizzando le API che già possiedi

Un’architettura pratica per trasformare le API di prodotto esistenti in funzionalità sicure per gli agenti, senza creare uno strumento personalizzato per ogni azione.

Questa guida implementa un’integrazione completa di AgentChat per un SaaS fittizio chiamato SupportFlow. SupportFlow dispone già di API per trovare le fatture scadute, inviare promemoria e aggiungere note agli account. Doteremo AgentChat di queste API, creeremo una chat associata all’utente, avvieremo un’esecuzione asincrona dell’agente e visualizzeremo il risultato dai messaggi persistenti e dal database proprietario di SupportFlow.

Il confine architetturale importante è concreto: AgentChat gestisce il ragionamento del modello, la selezione degli strumenti, la cronologia della chat e il controllo delle esecuzioni. SupportFlow continua a gestire clienti, fatture, autorizzazione, convalida e registrazioni aziendali finali. La documentazione dell’API collega i due sistemi.

Non aggiungere tutte le funzionalità del SaaS all’ambiente di esecuzione dell’agente. Esponi un piccolo insieme di operazioni aziendali fondamentali come API HTTP e rendi disponibili i relativi contratti in ogni chat.

Il flusso delle richieste completato

  1. SupportFlow crea un'unica chiave API di AgentChat dal pannello di controllo e la memorizza esclusivamente nel proprio backend.
  2. Il suo backend registra le operazioni di SupportFlow tramite POST /api/api-documents.
  3. Quando un utente apre l'assistente, SupportFlow crea una sessione con l'UUID del documento, un UUID della configurazione LLM e credenziali utente di sola scrittura per il proprio host API.
  4. SupportFlow invia il messaggio dell'utente a POST /api/agent/sessions/{id}/chat.
  5. AgentChat legge il contratto allegato e utilizza il proprio strumento integrato http_request per chiamare SupportFlow.
  6. SupportFlow interroga periodicamente i messaggi di AgentChat, mentre la sua normale interfaccia utente legge fatture e note dal database di SupportFlow.

Passaggio 1: esporre operazioni aziendali mirate

All'agente non servono né l'accesso al database né un'unica API interna enorme. Per questo flusso di lavoro, SupportFlow espone esattamente tre endpoint consapevoli del tenant:

GET /v1/invoices?status=overdue&limit=3
→ { "items": [{ "invoice_id": "inv_72", "account_id": "acct_9", "amount": 480, "currency": "USD", "due_at": "2026-08-01" }] }

POST /v1/reminders
{ "invoice_id": "inv_72", "tone": "friendly" }
→ { "reminder_id": "rem_31", "status": "queued" }

POST /v1/accounts/acct_9/notes
{ "body": "Friendly reminder queued for overdue invoice inv_72." }
→ { "note_id": "note_55", "created_at": "2026-08-23T09:30:00Z" }

Ogni endpoint autentica il chiamante, ricava il tenant dalla credenziale e filtra ogni operazione sul database. Gli ID restituiti da una chiamata diventano input sicuri per quella successiva. Il modello non riceve mai una password del database né un'interfaccia per query senza restrizioni.

Passaggio 2: creare una sola volta la configurazione del modello

Ogni sessione AgentChat richiede una configurazione LLM di proprietà dell'utente. SupportFlow può crearne una tramite la dashboard o l'API e conservare l'UUID restituito.

POST $AGENTCHAT_SITE_URL/api/llm-config
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "name": "Support production model",
  "api_url": "https://llm-provider.example.com/v1/chat/completions",
  "api_key": "provider_secret",
  "model": "provider-model-name",
  "max_context_length": 128000,
  "max_output_tokens": 8192,
  "temperature": 0.2,
  "disable_reasoning": false
}

La risposta è racchiusa in success e data. Salva data.id come llm_config_id da usare quando si creano le chat. AgentChat maschera la chiave del provider quando le configurazioni vengono recuperate.

Passaggio 3: predisporre il documento API di SupportFlow

Questo è il meccanismo dei plugin. Il documento contiene istruzioni operative, input esatti, output esatti e regole di sequenziamento, non testo di marketing né un link che costringa l'agente a indovinare.

POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "SupportFlow Invoice Actions",
  "description": "Find overdue invoices, queue reminders, and record account notes.",
  "content": "# SupportFlow Invoice Actions\nBase URL: https://support.example.com/v1\n\nGET /invoices?status=overdue&limit=3 returns items with invoice_id, account_id, amount, currency, and due_at. Use only when the user requests invoice lookup.\n\nPOST /reminders body: invoice_id required; tone is friendly or firm. Response: reminder_id and status. Never send more reminders than the user requested.\n\nPOST /accounts/{account_id}/notes body: body required. Call only after the reminder request succeeds. Include the invoice ID and reminder status in the note.\n\nIf any write returns 401 or 403, stop writing and explain that the session credential needs access. Do not retry a permission denial."
}

AgentChat restituisce il nuovo documento in data, incluso il relativo UUID. Conserva tale UUID nella configurazione dell’integrazione di SupportFlow. L’aggiornamento successivo di questo documento modifica le istruzioni utilizzate nei turni di chat successivi, perché le sessioni allegano il documento invece di copiarlo.

Passaggio 4: crea una chat per l’utente SupportFlow corrente

POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "Invoice assistant for user_42",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["supportflow_document_uuid"],
  "system_prompt": "Act only on the user’s explicit request. Summarize every write with the affected invoice and account IDs.",
  "compact_threshold_percent": 80,
  "max_turns": 12,
  "tool_timeout_seconds": 120,
  "tool_result_max_chars": 10000,
  "host_headers": [
    { "host": "support.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_user_42_token" },
    { "host": "support.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_7" }
  ]
}

I valori delle intestazioni sono di sola scrittura. AgentChat li memorizza per questa sessione, li inserisce solo quando http_request è indirizzato all’host corrispondente e non ne espone i valori al modello né nelle risposte dell’API. Un secondo utente di SupportFlow ottiene una sessione diversa con lo stesso UUID del documento, ma con intestazioni diverse.

Passaggio 5: avviare l’esecuzione asincrona

POST $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{ "message": "Find my three most overdue invoices, send each a friendly reminder, and add a note to each account." }

→ { "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

AgentChat restituisce immediatamente il controllo e continua l’esecuzione in background. L’agente riceve il documento SupportFlow allegato insieme a esattamente quattro strumenti integrati: get_api_document, http_request, sleep e view_image. Le funzionalità di SupportFlow non sono compilate in questi strumenti; vengono apprese dal contratto API fornito ed eseguite tramite http_request.

Cosa fa l’agente durante questa richiesta

  1. Chiamare tramite http_request l’endpoint documentato delle fatture scadute.
  2. Leggere gli elementi strutturati e selezionare al massimo le tre fatture richieste dall’utente.
  3. Accodare i promemoria. Le chiamate indipendenti prodotte da una risposta del modello possono essere eseguite contemporaneamente.
  4. Dopo che sono disponibili risultati positivi dei promemoria, chiamare l’endpoint delle note sul conto con ogni fattura e ID del conto restituiti.
  5. Produrre un messaggio finale dell’assistente che elenchi le operazioni completate e qualsiasi errore relativo a ciascuna fattura.

Ecco perché la progettazione delle risposte è importante. Un risultato vago come «successo» non lascia all’agente nulla di affidabile a cui collegare l’azione successiva. ID e stati strutturati consentono al ciclo di ragionamento di combinare diverse API ordinarie in un unico risultato per l’utente.

Passaggio 6: eseguire il polling dei messaggi persistenti, non di uno stream LLM

GET $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENTCHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "message_uuid", "role": "assistant", "content": "...", "stream_status": "streaming", "revision": 4 }],
    "last_id": "message_uuid",
    "last_revision": 4,
    "is_processing": true,
    "total_tokens": 2840
  }
}

SupportFlow esegue il polling una volta al secondo dal proprio backend o da un client proxy, unisce le righe in base all’ID del messaggio e sostituisce il contenuto solo quando la revisione aumenta. Il database di AgentChat è la fonte autorevole per l’output della conversazione. Il database di SupportFlow rimane la fonte autorevole per fatture, promemoria e note.

Quando is_processing diventa false, SupportFlow può aggiornare le proprie query per fatture e account. La normale interfaccia del prodotto mostra quindi i promemoria e le note creati tramite le proprie API; non deve analizzare la prosa dell’assistente per ricostruire lo stato aziendale.

Controllo dell’esecuzione e recupero dagli errori

GET  /api/agent/sessions/session_uuid/state
POST /api/agent/sessions/session_uuid/stop
POST /api/agent/sessions/session_uuid/continue

L’endpoint di stato indica se l’elaborazione è attiva e se l’azione successiva è «continue». Le richieste di arresto annullano un’esecuzione attiva. Se un errore recuperabile o il limite massimo di turni mette in pausa il lavoro, «continue» avvia un’altra esecuzione con un nuovo budget di turni e lo stesso contesto di conversazione persistente.

Cosa predisporre e cosa non predisporre

  • Predisponete API che rappresentino funzionalità aziendali stabili: cercare, creare, aggiornare, convalidare, pubblicare o controllare lo stato dei job.
  • Documentate i campi obbligatori, i vincoli, gli oggetti di risposta, il significato degli errori, gli effetti collaterali e i requisiti di ordinamento.
  • Allegate solo i documenti necessari per l’esperienza di chat, invece di includere ogni endpoint interno.
  • Conservate le credenziali negli header di sessione specifici dell’host, mai nei prompt o nel contenuto della documentazione delle API.
  • Non esponete SQL non elaborato, accesso illimitato ai file o un proxy interno generico solo per rendere flessibile l’agente.
  • Fate eseguire la vostra autorizzazione e validazione a ogni richiesta dello strumento esattamente come per gli altri client.

Perché l'insieme delle capacità può crescere senza ampliare il set di strumenti principali

Un prodotto RAG può predisporre endpoint per la ricerca e le citazioni. Un prodotto per la creazione di storie può predisporre endpoint per capitoli, generazione di immagini e pubblicazione. Un prodotto di programmazione può predisporre endpoint per i file dell'area di lavoro, i controlli e i deployment. AgentChat continua a utilizzare gli stessi quattro strumenti principali. Le operazioni specifiche dell'applicazione arrivano come documenti API, quindi aggiungere una capacità è una modifica di provisioning anziché una nuova release del runtime dell'agente.

Questo è il modello centrale di AgentChat: creare documenti API, creare una sessione di chat con ambito definito, lasciare che l'agente componga le tue operazioni HTTP, consumare messaggi persistenti e visualizzare i record risultanti dal database della tua applicazione.