Crea app agentiche con AceDataCloud AI Chat v2

Un endpoint chat può restituire testo. Un endpoint agente può ispezionare un file, cercare nel web, chiamare uno strumento autorizzato, chiedere informazioni mancanti e trasmettere ogni passaggio in streaming alla tua interfaccia.

Questa è la differenza pratica alla base di AceDataCloud AI Chat v2. L'endpoint su POST https://api.acedata.cloud/aichat2/conversations preserva il semplice stile di richiesta dell'API di conversazione originale aggiungendo blocchi di contenuto multimodale, utilizzo autonomo di strumenti su più round, connessioni MCP, eventi di streaming strutturati, conversazioni ripristinabili e azioni CRUD sulle conversazioni.

Architettura di AI Chat v2: input multimodali, strumenti dell'agente ed eventi strutturati

Questa guida si concentra sulle decisioni di integrazione che contano quando si passa da un chatbot di base a un'esperienza agente di produzione.

Cosa cambia in AI Chat v2?

AI Chat v2 è un aggiornamento completo dell'interfaccia originale /aichat/conversations. Le sue capacità principali sono:

  • Input multimodale: invia blocchi ordinati text, image_url e file_url in un unico array message.
  • Utilizzo autonomo degli strumenti: il modello può chiamare strumenti integrati e server MCP autorizzati dall'utente su più round.
  • Streaming tipizzato: visualizza testo, attività degli strumenti, citazioni, schede, artefatti, errori e dati di completamento come eventi separati.
  • Pausa e ripresa: gestisci un evento ask_user_question e continua la stessa conversazione con un risultato dello strumento.
  • Gestione delle conversazioni: recupera, recupera in batch, aggiorna ed elimina tramite azioni sullo stesso endpoint.
  • Richieste retrocompatibili: i client esistenti con model + question possono migrare cambiando il percorso dell'endpoint.

Il cambiamento architetturale importante è che il tuo frontend non deve più trattare la risposta come un'unica stringa opaca. Può diventare uno spazio di lavoro guidato dagli eventi.

Inizia con il percorso retrocompatibile

La migrazione a minor rischio è intenzionalmente ridotta. Mantieni il corpo della richiesta esistente e cambia solo l'endpoint:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "Summarize the three most important points in this request.",
    "stateful": true
  }'

In modalità JSON, la risposta mantiene la forma familiare:

{
  "answer": "...",
  "id": "conversation-uuid"
}

Conserva l'id restituito. Inviarlo nella richiesta successiva continua la conversazione gestita senza richiedere al tuo client di reinviare l'intera cronologia dei messaggi.

stateful è impostato su true per impostazione predefinita. Impostalo esplicitamente su false quando un round non deve essere archiviato.

Questo primo passaggio di migrazione ti consente di convalidare l'autenticazione, la disponibilità del modello, la latenza e il comportamento dell'applicazione prima di introdurre strumenti o una nuova UI di streaming.

Usa message quando l'ordine e la modalità sono importanti

Il precedente campo question è pratico per prompt di solo testo. Per testo combinato con immagini o file, utilizza un array message ordinato:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

I blocchi di contenuto supportati sono:

Blocco Valore richiesto Miglior utilizzo
text text Istruzioni, contesto e domande
image_url image_url.url Screenshot, grafici, immagini di prodotti
file_url file_url.url PDF, CSV, TXT e altri file

AI Chat v2 riconosce ancora il precedente array references. Le estensioni delle immagini vengono convertite in blocchi immagine, mentre gli altri URL diventano blocchi file. Questa compatibilità è utile durante la migrazione, ma message è il contratto migliore a lungo termine quando l'ordine dei contenuti è importante.

Progetta il client attorno agli eventi, non solo ai token

Scegli il formato di risposta con l'header accept:

Client Header Formato
UI del browser text/event-stream Server-Sent Events
Node, Python, CLI, worker application/x-ndjson Un evento JSON per riga
Semplice richiesta backend application/json Oggetto finale {answer, id}

Un consumer Python NDJSON minimo può assemblare il testo preservando al contempo altri tipi di evento:

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "Research the topic, cite sources, and return a concise brief.",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers, stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []

    for raw_line in response.iter_lines():
        if not raw_line:
            continue

        event = json.loads(raw_line)
        event_type = event.get("type")

        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

Le interfacce di produzione dovrebbero definire un renderer o un gestore per ciascuna famiglia di eventi:

  • text_delta aggiorna l'area della risposta.
  • tool_use e tool_result guidano gli stati di attività e le viste di audit.
  • citation collega le fonti all'output pertinente.
  • card visualizza anteprime strutturate.
  • artifact espone un deliverable generato separato.
  • thinking dovrebbe essere gestito solo quando il modello scelto lo espone.
  • error termina o ripristina il round corrente.
  • done chiude lo stream e registra l'utilizzo dei token più il motivo terminale.

Se la tua interfaccia necessita solo della risposta finale, concatena content da ogni text_delta. È equivalente all'answer restituito in modalità JSON.

Lascia che l'agente utilizzi strumenti, ma rendi visibile l'attività

La chiamata degli strumenti è abilitata per impostazione predefinita. AI Chat v2 può utilizzare capacità integrate come la ricerca web, l'estrazione di pagine e la lettura di file. Può inoltre montare connessioni MCP autorizzate dall'utente come Google Drive, Notion, Slack o GitHub.

Lo stream espone chiaramente il confine:

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

Associa tool_use e tool_result tramite tool_id. Ciò supporta indicatori di avanzamento, misurazioni della latenza, gestione degli errori e una traccia di audit leggibile dall'operatore.

Utilizza max_turns per limitare quanti round autonomi di strumenti possono avvenire in una richiesta. L'intervallo accettato è 1–500; il valore predefinito documentato è 500. Un valore inferiore riduce l'esecuzione senza limiti. Impostare max_turns: 1 forza una singola risposta e impedisce le chiamate agli strumenti.

Un modello pratico di rollout è:

  1. Inizia in modalità JSON senza strumenti nella UI del prodotto.
  2. Aggiungi NDJSON o SSE e visualizza text_delta più done.
  3. Mostra l'attività degli strumenti come una timeline compressa.
  4. Aggiungi la visualizzazione di citazioni e artefatti.
  5. Imposta un max_turns deliberato in base alla complessità del compito e alla tolleranza dei costi.
  6. Abilita connessioni con capacità di scrittura solo dopo aver esaminato il loro modello di conferma.

Gestisci le domande come una macchina a stati ripristinabile

Un agente a volte necessita di chiarimenti. In tal caso, lo stream può emettere ask_user_question e la conversazione entra in uno stato awaiting_user_input.

Il tuo client dovrebbe:

  1. Salvare l'id della conversazione e il tool_id.
  2. Visualizzare la domanda e le relative opzioni.
  3. Raccogliere la risposta dell'utente.
  4. Inviare un'altra richiesta con lo stesso id della conversazione.
  5. Restituire la risposta tramite tool_results per la chiamata dello strumento in sospeso. Questo è più robusto che fingere che l'agente possa terminare con informazioni mancanti. Rende inoltre possibili porte di approvazione per azioni sensibili.

Separare l'esecuzione interattiva e non presidiata

Per webhook, job CI/CD e sistemi di monitoraggio, async: true restituisce un identificatore dell'attività mentre il lavoro continua. Il risultato può essere recuperato in seguito o consegnato a un URL di callback HTTP(S).

L'accesso in scrittura non presidiato dovrebbe essere esplicito. AI Chat v2 supporta allowed_skills, allowed_mcp_servers o un oggetto unattended_policy equivalente. Un elenco vuoto non autorizza alcuna capacità. La pre-autorizzazione non aggira il meccanismo di sicurezza di un connettore; una skill che non supporta la conferma non presidiata dovrebbe comunque eseguire un dry-run o rifiutare la scrittura.

Questa distinzione è importante: la disponibilità della connessione non è la stessa cosa dell'autorizzazione ad agire senza una persona presente.

Checklist di produzione

Prima di lanciare un'interfaccia agentica, verificare:

  • Le credenziali API sono archiviate lato server, mai nel codice del browser.
  • I nomi dei modelli provengono dall'elenco attuale dei modelli supportati anziché da supposizioni codificate.
  • Il parser dello stream tollera chunk di rete parziali e tipi di evento sconosciuti.
  • Gli eventi degli strumenti sono associati tramite tool_id e gli errori vengono registrati.
  • max_turns è impostato intenzionalmente.
  • Gli URL di citazioni e artefatti vengono renderizzati in modo sicuro.
  • ask_user_question conserva uno stato sufficiente per riprendere in seguito.
  • Le connessioni abilitate alla scrittura mantengono la conferma o un'autorizzazione non presidiata con ambito ristretto.
  • done.usage e terminal_reason alimentano l'osservabilità.
  • Le politiche di eliminazione e conservazione delle conversazioni corrispondono ai requisiti del prodotto.

Il percorso più breve dal chatbot all'agente

AI Chat v2 non impone una riscrittura completa. Iniziate cambiando l'endpoint e mantenendo il corpo della richiesta attuale. Poi passate ai blocchi message multimodali, adottate lo streaming strutturato, esponete l'avanzamento degli strumenti e aggiungete la gestione di pausa e ripresa.

Il risultato è un client che può crescere da semplici risposte a un flusso di lavoro dell'agente verificabile, senza inventare un protocollo separato per file, strumenti, citazioni, artefatti o chiarimenti dell'utente.

Risorse ufficiali