Agentische Apps mit AceDataCloud AI Chat v2 erstellen

Ein Chat-Endpunkt kann Text zurückgeben. Ein Agenten-Endpunkt kann eine Datei prüfen, das Web durchsuchen, ein autorisiertes Tool aufrufen, nach fehlenden Informationen fragen und jeden Schritt an Ihre Schnittstelle zurückstreamen.

Das ist der praktische Unterschied hinter AceDataCloud AI Chat v2. Der Endpunkt unter POST https://api.acedata.cloud/aichat2/conversations bewahrt den einfachen Anfragestil der ursprünglichen Conversation-API und fügt gleichzeitig multimodale Inhaltsblöcke, autonome Tool-Nutzung über mehrere Runden, MCP-Verbindungen, strukturierte Streaming-Ereignisse, fortsetzbare Konversationen und CRUD-Aktionen für Konversationen hinzu.

AI Chat v2-Architektur: multimodale Eingaben, Agenten-Tools und strukturierte Ereignisse

Dieser Leitfaden konzentriert sich auf die Integrationsentscheidungen, die beim Wechsel von einem einfachen Chatbot zu einer produktionsreifen Agentenerfahrung wichtig sind.

Was ändert sich in AI Chat v2?

AI Chat v2 ist ein umfassendes Upgrade der ursprünglichen Schnittstelle /aichat/conversations. Seine Hauptfunktionen sind:

  • Multimodale Eingabe: Senden Sie geordnete text-, image_url- und file_url-Blöcke in einem message-Array.
  • Autonome Tool-Nutzung: Das Modell kann integrierte Tools und vom Benutzer autorisierte MCP-Server über mehrere Runden hinweg aufrufen.
  • Typisiertes Streaming: Stellen Sie Text, Tool-Aktivität, Zitate, Karten, Artefakte, Fehler und Abschlussdaten als separate Ereignisse dar.
  • Anhalten und Fortsetzen: Behandeln Sie ein ask_user_question-Ereignis und setzen Sie dieselbe Konversation mit einem Tool-Ergebnis fort.
  • Konversationsverwaltung: Rufen Sie Konversationen ab, rufen Sie sie stapelweise ab, aktualisieren und löschen Sie sie durch Aktionen am selben Endpunkt.
  • Abwärtskompatible Anfragen: Bestehende Clients mit model + question können durch Ändern des Endpunktpfads migrieren.

Die wichtige architektonische Änderung besteht darin, dass Ihr Frontend die Antwort nicht mehr als eine undurchsichtige Zeichenfolge behandeln muss. Es kann zu einem ereignisgesteuerten Arbeitsbereich werden.

Beginnen Sie mit dem abwärtskompatiblen Pfad

Die risikoärmste Migration ist bewusst klein. Behalten Sie den bestehenden Anfragetext bei und ändern Sie nur den Endpunkt:

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

Im JSON-Modus behält die Antwort die vertraute Form bei:

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

Behalten Sie die zurückgegebene id. Wenn Sie sie in der nächsten Anfrage senden, wird die verwaltete Konversation fortgesetzt, ohne dass Ihr Client den vollständigen Nachrichtenverlauf erneut senden muss.

stateful ist standardmäßig auf true gesetzt. Setzen Sie es explizit auf false, wenn eine Runde nicht gespeichert werden soll.

Dieser erste Migrationsschritt ermöglicht es Ihnen, Authentifizierung, Modellverfügbarkeit, Latenz und Anwendungsverhalten zu validieren, bevor Sie Tools oder eine neue Streaming-Benutzeroberfläche einführen.

Verwenden Sie message, wenn Reihenfolge und Modalität wichtig sind

Das ältere Feld question ist für reine Text-Prompts praktisch. Verwenden Sie für Text gemischt mit Bildern oder Dateien ein geordnetes message-Array:

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

Unterstützte Inhaltsblöcke sind:

Block Erforderlicher Wert Beste Verwendung
text text Anweisungen, Kontext und Fragen
image_url image_url.url Screenshots, Diagramme, Produktbilder
file_url file_url.url PDF-, CSV-, TXT- und andere Dateien

AI Chat v2 erkennt weiterhin das ältere references-Array. Bilderweiterungen werden in Bildblöcke umgewandelt, während andere URLs zu Dateiblöcken werden. Diese Kompatibilität ist während der Migration nützlich, aber message ist der bessere langfristige Vertrag, wenn die Inhaltsreihenfolge wichtig ist.

Gestalten Sie den Client um Ereignisse herum, nicht nur um Tokens

Wählen Sie das Antwortformat mit dem accept-Header:

Client Header Format
Browser-Benutzeroberfläche text/event-stream Server-Sent Events
Node, Python, CLI, Worker application/x-ndjson Ein JSON-Ereignis pro Zeile
Einfache Backend-Anfrage application/json Abschließendes {answer, id}-Objekt

Ein minimaler Python-NDJSON-Consumer kann Text zusammensetzen und dabei andere Ereignistypen bewahren:

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

Produktionsschnittstellen sollten für jede Ereignisfamilie einen Renderer oder Handler definieren:

  • text_delta aktualisiert den Antwortbereich.
  • tool_use und tool_result steuern Aktivitätszustände und Audit-Ansichten.
  • citation fügt relevanten Ausgaben Quellen hinzu.
  • card rendert strukturierte Vorschauen.
  • artifact stellt ein separates generiertes Ergebnis bereit.
  • thinking sollte nur verarbeitet werden, wenn das gewählte Modell es bereitstellt.
  • error beendet oder stellt die aktuelle Runde wieder her.
  • done schließt den Stream und zeichnet die Token-Nutzung sowie den Endgrund auf.

Wenn Ihre Schnittstelle nur die endgültige Antwort benötigt, verketten Sie content aus jedem text_delta. Das entspricht dem im JSON-Modus zurückgegebenen answer.

Lassen Sie den Agenten Tools verwenden – aber machen Sie die Aktivität sichtbar

Tool-Aufrufe sind standardmäßig aktiviert. AI Chat v2 kann integrierte Funktionen wie Websuche, Seitenextraktion und Dateilesen verwenden. Es kann auch vom Benutzer autorisierte MCP-Verbindungen wie Google Drive, Notion, Slack oder GitHub einbinden.

Der Stream zeigt die Grenze klar auf:

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

Ordnen Sie tool_use und tool_result anhand von tool_id einander zu. Dies unterstützt Fortschrittsanzeigen, Latenzmessungen, Fehlerbehandlung und einen für Operatoren lesbaren Audit-Trail.

Verwenden Sie max_turns, um zu begrenzen, wie viele autonome Tool-Runden in einer Anfrage stattfinden können. Der akzeptierte Bereich liegt bei 1–500; der dokumentierte Standardwert ist 500. Ein niedrigerer Wert reduziert die offene Ausführung. Das Setzen von max_turns: 1 erzwingt eine einzelne Antwort und verhindert Tool-Aufrufe.

Ein praktisches Einführungsmuster ist:

  1. Beginnen Sie im JSON-Modus ohne Tools in der Produkt-Benutzeroberfläche.
  2. Fügen Sie NDJSON oder SSE hinzu und rendern Sie text_delta plus done.
  3. Stellen Sie Tool-Aktivität als eingeklappte Zeitleiste dar.
  4. Fügen Sie die Darstellung von Zitaten und Artefakten hinzu.
  5. Legen Sie ein bewusstes max_turns basierend auf Aufgabenkomplexität und Kostentoleranz fest.
  6. Aktivieren Sie schreibfähige Verbindungen erst, nachdem Sie ihr Bestätigungsmodell überprüft haben.

Behandeln Sie Fragen als fortsetzbare Zustandsmaschine

Ein Agent benötigt manchmal eine Klärung. In diesem Fall kann der Stream ask_user_question ausgeben, und die Konversation wechselt in den Zustand awaiting_user_input.

Ihr Client sollte:

  1. Die Konversations-id und tool_id speichern.
  2. Die Frage und ihre Optionen darstellen.
  3. Die Antwort des Benutzers erfassen.
  4. Eine weitere Anfrage mit derselben Konversations-id senden.
  5. Die Antwort über tool_results für den ausstehenden Tool-Aufruf zurückgeben. Dies ist robuster, als vorzutäuschen, dass der Agent mit fehlenden Informationen fertig werden kann. Es ermöglicht auch Genehmigungsschranken für sensible Aktionen.

Interaktive und unbeaufsichtigte Ausführung trennen

Für Webhooks, CI/CD-Jobs und Überwachungssysteme gibt async: true eine Aufgabenkennung zurück, während die Arbeit fortgesetzt wird. Das Ergebnis kann später abgerufen oder an eine HTTP(S)-Callback-URL übermittelt werden.

Unbeaufsichtigter Schreibzugriff sollte explizit sein. AI Chat v2 unterstützt allowed_skills, allowed_mcp_servers oder ein gleichwertiges unattended_policy-Objekt. Eine leere Liste autorisiert keine Fähigkeiten. Vorabautorisierung umgeht nicht den eigenen Sicherheitsmechanismus eines Connectors; eine Fähigkeit, die keine unbeaufsichtigte Bestätigung unterstützt, sollte den Schreibvorgang weiterhin als Trockenlauf ausführen oder verweigern.

Dieser Unterschied ist wichtig: Verfügbarkeit einer Verbindung ist nicht dasselbe wie die Berechtigung, ohne eine anwesende Person zu handeln.

Checkliste für die Produktion

Bevor Sie eine agentische Schnittstelle starten, überprüfen Sie:

  • API-Anmeldedaten werden serverseitig gespeichert, niemals im Browser-Code.
  • Modellnamen stammen aus der aktuellen Liste unterstützter Modelle und nicht aus fest codierten Annahmen.
  • Der Stream-Parser toleriert partielle Netzwerk-Chunks und unbekannte Ereignistypen.
  • Tool-Ereignisse werden anhand von tool_id gepaart und Fehler werden aufgezeichnet.
  • max_turns wird bewusst festgelegt.
  • Zitierungs- und Artefakt-URLs werden sicher gerendert.
  • ask_user_question speichert genügend Zustand, um später fortzufahren.
  • Schreibfähige Verbindungen behalten eine Bestätigung oder eine eng begrenzte unbeaufsichtigte Autorisierung bei.
  • done.usage und terminal_reason fließen in die Beobachtbarkeit ein.
  • Richtlinien für das Löschen und Aufbewahren von Konversationen entsprechen Ihren Produktanforderungen.

Der kürzeste Weg vom Chatbot zum Agenten

AI Chat v2 erzwingt keine vollständige Neuschreibung. Beginnen Sie damit, den Endpunkt zu ändern und Ihren aktuellen Request-Body beizubehalten. Wechseln Sie dann zu multimodalen message-Blöcken, übernehmen Sie strukturiertes Streaming, machen Sie Tool-Fortschritt sichtbar und fügen Sie die Behandlung von Pausieren und Fortsetzen hinzu.

Das Ergebnis ist ein Client, der von einfachen Antworten zu einem auditierbaren Agenten-Workflow wachsen kann—ohne ein separates Protokoll für Dateien, Tools, Zitierungen, Artefakte oder Benutzerklärung zu erfinden.

Offizielle Ressourcen