Créer des applications agentiques avec AceDataCloud AI Chat v2

Un point de terminaison de chat peut renvoyer du texte. Un point de terminaison d’agent peut inspecter un fichier, rechercher sur le Web, appeler un outil autorisé, demander des informations manquantes et retransmettre chaque étape vers votre interface.

C’est la différence pratique apportée par AceDataCloud AI Chat v2. Le point de terminaison POST https://api.acedata.cloud/aichat2/conversations conserve le style simple de requête de l’API de conversation d’origine tout en ajoutant des blocs de contenu multimodaux, l’utilisation autonome d’outils sur plusieurs tours, des connexions MCP, des événements de streaming structurés, des conversations reprenables et des actions CRUD sur les conversations.

Architecture AI Chat v2 : entrées multimodales, outils d’agent et événements structurés

Ce guide se concentre sur les décisions d’intégration qui comptent lors du passage d’un chatbot basique à une expérience d’agent de production.

¶ Qu’est-ce qui change dans AI Chat v2 ?

AI Chat v2 est une mise à niveau complète de l’interface /aichat/conversations d’origine. Ses principales capacités sont :

Entrée multimodale : envoyez des blocs text, image_url et file_url ordonnés dans un seul tableau message.
Utilisation autonome d’outils : le modèle peut appeler des outils intégrés et des serveurs MCP autorisés par l’utilisateur sur plusieurs tours.
Streaming typé : affichez le texte, l’activité des outils, les citations, les cartes, les artefacts, les erreurs et les données de fin comme des événements distincts.
Pause et reprise : gérez un événement ask_user_question et poursuivez la même conversation avec un résultat d’outil.
Gestion des conversations : récupérez, récupérez par lot, mettez à jour et supprimez via des actions sur le même point de terminaison.
Requêtes rétrocompatibles : les clients existants utilisant model + question peuvent migrer en modifiant le chemin du point de terminaison.

Le changement architectural important est que votre frontend n’a plus à traiter la réponse comme une seule chaîne opaque. Il peut devenir un espace de travail piloté par les événements.

¶ Commencez par le chemin rétrocompatible

La migration à plus faible risque est volontairement limitée. Conservez le corps de requête existant et modifiez uniquement le point de terminaison :

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
  }'

En mode JSON, la réponse conserve la forme familière :

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

Conservez l’id renvoyé. L’envoyer dans la requête suivante poursuit la conversation gérée sans obliger votre client à renvoyer l’historique complet des messages.

stateful vaut true par défaut. Définissez-le explicitement sur false lorsqu’un tour ne doit pas être stocké.

Cette première étape de migration vous permet de valider l’authentification, la disponibilité du modèle, la latence et le comportement de l’application avant d’introduire des outils ou une nouvelle interface de streaming.

¶ Utilisez `message` lorsque l’ordre et la modalité comptent

L’ancien champ question est pratique pour les invites textuelles uniquement. Pour du texte mélangé à des images ou des fichiers, utilisez un tableau message ordonné :

{
  "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"
      }
    }
  ]
}

Les blocs de contenu pris en charge sont :

Bloc	Valeur requise	Meilleure utilisation
`text`	`text`	Instructions, contexte et questions
`image_url`	`image_url.url`	Captures d’écran, graphiques, images produit
`file_url`	`file_url.url`	PDF, CSV, TXT et autres fichiers

AI Chat v2 reconnaît toujours l’ancien tableau references. Les extensions d’image sont converties en blocs d’image, tandis que les autres URL deviennent des blocs de fichier. Cette compatibilité est utile pendant la migration, mais message est le meilleur contrat à long terme lorsque l’ordre du contenu compte.

¶ Concevez le client autour des événements, pas seulement des jetons

Choisissez le format de réponse avec l’en-tête accept :

Client	En-tête	Format
Interface navigateur	`text/event-stream`	Événements envoyés par le serveur
Node, Python, CLI, worker	`application/x-ndjson`	Un événement JSON par ligne
Requête backend simple	`application/json`	Objet final `{answer, id}`

Un consommateur Python NDJSON minimal peut assembler le texte tout en préservant les autres types d’événements :

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))

Les interfaces de production devraient définir un moteur de rendu ou un gestionnaire pour chaque famille d’événements :

text_delta met à jour la zone de réponse.
tool_use et tool_result pilotent les états d’activité et les vues d’audit.
citation attache des sources à la sortie pertinente.
card affiche des aperçus structurés.
artifact expose un livrable généré distinct.
thinking ne doit être géré que lorsque le modèle choisi l’expose.
error termine ou rétablit le tour actuel.
done ferme le flux et enregistre l’utilisation des jetons ainsi que la raison de terminaison.

Si votre interface a uniquement besoin de la réponse finale, concaténez content de chaque text_delta. Cela équivaut à l’answer renvoyé en mode JSON.

¶ Laissez l’agent utiliser des outils, mais rendez l’activité visible

L’appel d’outils est activé par défaut. AI Chat v2 peut utiliser des capacités intégrées telles que la recherche Web, l’extraction de pages et la lecture de fichiers. Il peut aussi monter des connexions MCP autorisées par l’utilisateur, telles que Google Drive, Notion, Slack ou GitHub.

Le flux expose clairement la frontière :

{"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}

Associez tool_use et tool_result par tool_id. Cela prend en charge les indicateurs de progression, les mesures de latence, la gestion des erreurs et une piste d’audit lisible par l’opérateur.

Utilisez max_turns pour limiter le nombre de tours d’outils autonomes pouvant se produire dans une requête. La plage acceptée est de 1 à 500 ; la valeur par défaut documentée est 500. Une valeur plus basse réduit l’exécution ouverte. Définir max_turns: 1 force une réponse unique et empêche les appels d’outils.

Un modèle de déploiement pratique est :

Commencez en mode JSON sans outils dans l’interface produit.
Ajoutez NDJSON ou SSE et affichez text_delta ainsi que done.
Exposez l’activité des outils sous forme de chronologie repliée.
Ajoutez le rendu des citations et des artefacts.
Définissez un max_turns délibéré en fonction de la complexité de la tâche et de la tolérance aux coûts.
Activez les connexions capables d’écrire uniquement après avoir examiné leur modèle de confirmation.

¶ Gérez les questions comme une machine à états reprenable

Un agent a parfois besoin d’une clarification. Dans ce cas, le flux peut émettre ask_user_question, et la conversation entre dans un état awaiting_user_input.

Votre client devrait :

Enregistrer l’id de conversation et le tool_id.
Afficher la question et ses options.
Recueillir la réponse de l’utilisateur.
Envoyer une autre requête avec le même id de conversation.
Renvoyer la réponse via tool_results pour l’appel d’outil en attente. C’est plus robuste que de prétendre que l’agent peut terminer avec des informations manquantes. Cela rend également possibles des étapes d’approbation pour les actions sensibles.

¶ Séparer l’exécution interactive et sans surveillance

Pour les webhooks, les tâches CI/CD et les systèmes de surveillance, async: true renvoie un identifiant de tâche pendant que le travail se poursuit. Le résultat peut être récupéré plus tard ou livré à une URL de rappel HTTP(S).

L’accès en écriture sans surveillance doit être explicite. AI Chat v2 prend en charge allowed_skills, allowed_mcp_servers, ou un objet unattended_policy équivalent. Une liste vide n’autorise aucune capacité. La préautorisation ne contourne pas le propre mécanisme de sécurité d’un connecteur ; une compétence qui ne prend pas en charge la confirmation sans surveillance doit toujours effectuer une simulation ou refuser l’écriture.

Cette distinction est importante : la disponibilité de la connexion n’est pas la même chose que l’autorisation d’agir sans qu’une personne soit présente.

¶ Liste de contrôle pour la production

Avant de lancer une interface agentique, vérifiez :

¶ Le chemin le plus court du chatbot à l’agent

AI Chat v2 n’impose pas une réécriture complète. Commencez par changer le point de terminaison et conservez le corps de votre requête actuel. Passez ensuite aux blocs message multimodaux, adoptez le streaming structuré, exposez la progression des outils et ajoutez la gestion de pause et de reprise.

Le résultat est un client qui peut évoluer de simples réponses vers un flux de travail agentique auditable, sans inventer un protocole distinct pour les fichiers, les outils, les citations, les artefacts ou la clarification utilisateur.

Créez des applications agentiques avec AceDataCloud AI Chat v2 : entrée multimodale, outils MCP et diffusion d’événements en continu

Créer des applications agentiques avec AceDataCloud AI Chat v2

¶ Qu’est-ce qui change dans AI Chat v2 ?

¶ Commencez par le chemin rétrocompatible

¶ Utilisez `message` lorsque l’ordre et la modalité comptent

¶ Concevez le client autour des événements, pas seulement des jetons

¶ Laissez l’agent utiliser des outils, mais rendez l’activité visible

¶ Gérez les questions comme une machine à états reprenable

¶ Séparer l’exécution interactive et sans surveillance

¶ Liste de contrôle pour la production

¶ Le chemin le plus court du chatbot à l’agent

¶ Ressources officielles

Créer des applications agentiques avec AceDataCloud AI Chat v2

¶ Qu’est-ce qui change dans AI Chat v2 ?

¶ Commencez par le chemin rétrocompatible

¶ Utilisez message lorsque l’ordre et la modalité comptent

¶ Concevez le client autour des événements, pas seulement des jetons

¶ Laissez l’agent utiliser des outils, mais rendez l’activité visible

¶ Gérez les questions comme une machine à états reprenable

¶ Séparer l’exécution interactive et sans surveillance

¶ Liste de contrôle pour la production

¶ Le chemin le plus court du chatbot à l’agent

¶ Ressources officielles

¶ Utilisez `message` lorsque l’ordre et la modalité comptent