Descrizione dell'articolo: AI Chat v2 mantiene il semplice modo di chiamata dell'interfaccia di conversazione originale, aggiungendo al contempo input multimodali, flussi di eventi strutturati, chiamata automatica degli strumenti, pausa e ripresa, esecuzione asincrona e gestione delle sessioni. Questo articolo parte da una migrazione che quasi non richiede di riscrivere il codice, per spiegare chiaramente come questi cambiamenti influenzano lo sviluppo di prodotti reali.

Molte interfacce di chat sono molto facili da usare nella fase di dimostrazione: si passa una domanda, si attende che il modello restituisca un testo e poi lo si visualizza sulla pagina.

Quando il prodotto continua ad avanzare, non si tratta più solo di “fare una domanda, ricevere una risposta”. Gli utenti caricheranno PDF e screenshot, il modello dovrà cercare pagine web, leggere file e persino chiamare strumenti già autorizzati come GitHub, Notion e altri. Un'attività può durare diversi turni e potrebbe fermarsi a metà perché mancano informazioni, per fare ulteriori domande. A questo punto, se l'interfaccia restituisce ancora soltanto una stringa di testo in continua crescita, per il frontend è difficile sapere cosa stia facendo il modello e anche per il backend è difficile determinare se l'attività sia effettivamente terminata.

Ace Data Cloud AI Chat v2 API risolve proprio questo problema. Non ribalta il modo originale di conversare, ma, sulla base della compatibilità con le chiamate semplici, scompone una risposta in eventi che il programma può riconoscere ed elaborare: il testo è testo, la chiamata di strumenti è chiamata di strumenti, e citazioni, file, errori e stato finale hanno ciascuno una posizione chiara.

Ace Data Cloud AI Chat v2: input multimodali, strumenti Agent e flusso di eventi strutturato

Figura: AI Chat v2 non comprime più l'intera attività in un singolo testo, ma mantiene strutturati gli eventi di input, strumenti e output.

La migrazione può iniziare modificando un solo indirizzo

Se il progetto sta usando la vecchia versione /aichat/conversations, non è necessario riscrivere prima la struttura dei messaggi, né creare prima un'interfaccia Agent. V2 continua ad accettare campi originali quali model, question, stateful, id, references e preset. La migrazione minima richiede solo di modificare l'indirizzo della richiesta in:

https://api.acedata.cloud/aichat2/conversations

Anche una richiesta di base rimane molto breve:

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": "Riassumi i tre problemi più importanti in questi requisiti.",
    "stateful": true
  }'

Nella normale modalità JSON, l'interfaccia restituisce ancora un risultato familiare:

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

Salvare l'id restituito e includere lo stesso id nella richiesta successiva permette di continuare la conversazione. Il valore predefinito di stateful è true e viene usato per controllare se caricare e continuare il contesto della conversazione salvata.

Questo passaggio è molto adatto ai progetti reali: prima si verifica se autenticazione, modello, latenza e logica aziendale esistente funzionano normalmente, quindi si integrano gradualmente le nuove funzionalità. Non è necessario vincolare la migrazione e la ricostruzione dell'interfaccia alla stessa release.

Quando file e immagini entrano nella conversazione, anche l'ordine diventa informazione

Il vecchio question è adatto al testo puro. Per attività come “prima leggi il report, poi confrontalo con lo screenshot e infine fornisci una conclusione”, un semplice elenco di allegati non è più sufficientemente preciso. V2 aggiunge un array message strutturato, in cui è possibile inserire in ordine testo, immagini e file:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Leggi il report e confronta le tendenze in esso contenute con lo screenshot della dashboard successivo."
    },
    {
      "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 disponibili includono text, image_url e file_url. Ciò che è importante non è soltanto il “supporto degli allegati”, ma il fatto che la relazione tra i contenuti non venga persa durante la trasmissione. Il client può indicare chiaramente al modello: quale parte è la descrizione dell'attività, quale file è il materiale originale e cosa deve essere confrontato successivamente.

Per consentire una migrazione fluida dei vecchi client, V2 continua a riconoscere references. Gli URL con estensioni di immagini vengono elaborati come immagini, mentre gli altri URL vengono elaborati come file. Se si sta solo aggiornando l'interfaccia, è possibile mantenere temporaneamente il vecchio formato; se l'ordine degli input influisce sulla comprensione, si consiglia di usare message.

La risposta in streaming non è più solo “sta digitando”

L'output in streaming tradizionale di solito contiene solo incrementi di testo. Dopo che il modello inizia a cercare, leggere file o chiamare strumenti esterni, la pagina sembra bloccata: l'utente non sa se l'attività prosegue e lo sviluppatore non può ottenere uno stato chiaro.

AI Chat v2 offre tre modalità di risposta tramite l'header della richiesta accept:

Scenario d'uso accept Modalità di restituzione
Semplice richiesta lato server application/json Restituisce {answer, id} al completamento
Node, Python, CLI o Worker application/x-ndjson Un evento JSON per riga
Frontend Web text/event-stream Flusso di eventi SSE

Nelle modalità NDJSON e SSE, non vengono restituiti solo token, ma un insieme di eventi tipizzati. text_delta viene usato per gli incrementi del testo, tool_use indica che il modello sta per chiamare uno strumento, tool_result restituisce il risultato dello strumento, citation fornisce la fonte della citazione, card e artifact trasportano schede o artefatti visualizzabili separatamente, error indica il fallimento di questo turno e done fornisce l'utilizzo e il motivo della terminazione.

Il seguente consumer Python accumula il testo da un lato e conserva gli stati chiave dall'altro:

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": "检索资料,给出带来源的简要结论。",
    "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("开始调用:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("工具是否失败:", event.get("is_error"))
        elif event_type == "error":
            raise RuntimeError(event.get("message", "未知错误"))
        elif event_type == "done":
            print("用量:", event.get("usage"))
            print("终止原因:", event.get("terminal_reason"))

print("".join(answer))

Se il prodotto si interessa solo del testo finale, basta concatenare tutti i text_delta.content; se invece si desidera creare un'interfaccia Agent osservabile, è possibile renderizzare separatamente le chiamate agli strumenti, le citazioni, gli artefatti e gli stati. Le due esigenze utilizzano la stessa interfaccia, senza dover mantenere due protocolli per la “chat semplice” e i “compiti complessi”.

Le chiamate agli strumenti sono disponibili per impostazione predefinita, ma il prodotto deve comunque tracciare confini chiari

V2 può consentire al modello di chiamare capacità integrate come la ricerca web, l'estrazione di pagine e la lettura di file in base alle necessità del compito; dopo che l'utente ha collegato e autorizzato i servizi corrispondenti, può anche utilizzare strumenti MCP per elaborare dati esterni come GitHub e Notion.

Nel flusso compariranno rispettivamente tool_use e tool_result, abbinati tramite tool_id. Il frontend può così mostrare l'avanzamento reale, e il backend può anche registrare la durata di ogni strumento e il punto del fallimento.

Il fatto che gli strumenti possano essere chiamati automaticamente non significa che l'ambito di esecuzione debba essere aperto senza limiti. max_turns viene usato per vincolare il numero di iterazioni dell'Agent in una singola richiesta; l'intervallo fornito dalla documentazione è 1—500; quando viene impostato a 1, in questo turno verrà eseguita una sola chiamata al modello, senza proseguire con le chiamate agli strumenti. In ambiente di produzione, dovrebbe essere impostato attivamente in base alla complessità del compito, al tempo di risposta e al budget dei costi, anziché dipendere a lungo da un limite predefinito elevato.

Per Webhook, CI/CD o attività di monitoraggio, V2 supporta async: true: il compito può essere eseguito in background e i risultati possono essere ottenuti tramite query o callback_url. Tuttavia, le azioni che implicano invio, pubblicazione o scrittura richiedono una preautorizzazione esplicita tramite allowed_skills, allowed_mcp_servers o unattended_policy.

La connessione risolve il “se sia possibile accedere”, mentre la politica di autorizzazione risolve il “se in questa occasione sia possibile agire al posto dell'utente”. Queste due cose non possono essere confuse.

Quando l'Agent non dispone di informazioni, non deve fingere che il compito sia già completato

I compiti complessi spesso si bloccano su questioni specifiche: su quale canale pubblicare, quale formato adottare, se sovrascrivere file esistenti. V2 fornisce a questo scopo l'evento ask_user_question. Dopo la comparsa dell'evento, la sessione entra nello stato di attesa dell'input dell'utente.

Il client salva l'id della sessione corrente e il tool_id corrispondente, mostra la domanda e raccoglie la risposta, quindi usa lo stesso id della sessione per restituire la risposta tramite tool_results, e il compito può continuare dal punto di sospensione. Questo meccanismo è adatto anche per creare nodi di approvazione. Piuttosto che lasciare che il modello faccia supposizioni autonome quando le informazioni sono insufficienti, è meglio restituire all'utente le scelte mancanti.

Anche le sessioni stesse possono essere gestite

V2 aggiunge una leggera CRUD delle sessioni nello stesso endpoint, distinguendo retrieve, retrieve_batch, update e delete tramite action.

retrieve_batch restituisce riepiloghi senza includere i messages completi, ed è adatto per una barra laterale delle sessioni; quando l'utente apre effettivamente una sessione, viene quindi chiamato retrieve per leggere il contenuto. Per le sessioni lunghe, anche la riorganizzazione del contesto sul server non sostituirà i messaggi originali salvati con dei riepiloghi. Quando è necessario continuare a modificare un articolo, verificare dati numerici o preparare una pubblicazione, si dovrebbe comunque leggere il testo originale, anziché usare un riepilogo al posto del contenuto.

Prima della messa in produzione, non verificare soltanto “se viene restituito del testo”

Dopo l'integrazione di un'interfaccia Agent, ricevere una parte del testo non significa che questo turno sia stato completato in modo affidabile; anche la fine del flusso non rappresenta necessariamente il successo del compito. Il client dovrebbe gestire error e, dopo aver ricevuto done, registrare usage e terminal_reason. In SSE, [DONE] indica soltanto la fine della trasmissione e non può sovrascrivere gli eventi di errore già comparsi in precedenza.

L'API Token dovrebbe essere conservato solo sul server; il parser del flusso deve poter gestire segmentazioni di rete e nuovi eventi temporaneamente sconosciuti; le chiamate agli strumenti devono essere abbinate in base a tool_id; i link delle citazioni e gli artefatti devono essere renderizzati in modo sicuro; le connessioni con possibilità di scrittura devono continuare a mantenere la conferma umana o un'autorizzazione unattended sufficientemente limitata. Il nome del modello, la fatturazione e le capacità disponibili possono essere aggiornati; durante l'integrazione formale, si dovrebbe fare riferimento alla documentazione corrente, alla pagina del servizio e alla console, senza fissare a lungo le configurazioni di esempio nel codice.

L'aspetto più degno di attenzione di AI Chat v2 non è aggiungere qualche pulsante in più alla finestra di chat. Consente finalmente all'applicazione di vedere cosa accade all'interno di un'attività AI: quando il modello produce testo, quando chiama strumenti, dove attende l'utente e con quale stato termina.

Se il progetto esistente è ancora soltanto una normale casella di domande e risposte, è possibile iniziare modificando l'indirizzo dell'interfaccia e continuare a usare il corpo della richiesta originale. Dopo che questo passaggio sarà stabile, si potranno integrare message, NDJSON o SSE, la timeline degli strumenti e la sospensione e ripresa. L'aggiornamento può essere piccolo, ma lascia spazio sufficiente per le forme di prodotto successive.