Chat-API: Session- und Chat-Endpunkte

Starte eine Session und sende Chat-Nachrichten an deinen Agenten, pro Anwendung, über eine gestreamte Verbindung.

Der Chat jeder Anwendung baut auf zwei Endpunkten auf, die auf die ID dieser Anwendung beschränkt sind, und die dir im Tab Application Endpoints der Anwendung angezeigt werden. Beide sind POST-Anfragen und beide benötigen einen der unten beschriebenen Authentifizierungs-Header; nur der Chat-Endpunkt streamt seine Antwort, der Session-Endpunkt antwortet mit einem einzelnen JSON-Objekt. Ein dritter Endpunkt, nicht in diesem Tab angezeigt, lässt dich eine Session vorzeitig beenden.

https://mcp-host.tuix.ch/stream/<ApplicationId>/session
https://mcp-host.tuix.ch/stream/<ApplicationId>/chat

Tab Application Endpoints mit den Session- und Chat-URLs

Authentifizierung

Beide Endpunkte benötigen einen der folgenden Header:

Header	Erforderlich	Beschreibung
`Authorization`	Eines von `Authorization` oder `X-Api-Key`	Der Wert, den deine eigene API erwartet, üblicherweise das Bearer-Token des Endnutzers. Tuix AI Agents leitet ihn als `Authorization: Bearer <value>` an jeden mit dieser Anwendung verbundenen MCP-Server weiter, und von dort an deine API, sodass der Agent mit dieser Identität handelt.
`X-Api-Key`	Eines von `Authorization` oder `X-Api-Key`	Ein API-Schlüssel aus API-Schlüssel, verwendet, um den Aufruf gegenüber Tuix AI Agents zu authentifizieren, wenn kein Authorization-Header angegeben ist

Egal welcher Header den Aufruf authentifiziert, Authorization oder X-Api-Key, Tuix AI Agents leitet die zugrunde liegende Anmeldeinformation stromabwärts als einzelnen Authorization: Bearer <Anmeldeinformation>- Header weiter, nicht als den Header, in dem du sie ursprünglich gesendet hast:

Du sendest	Deine API erhält
`Authorization: Bearer abc123`	`Authorization: Bearer abc123`
`X-Api-Key: abc123`	`Authorization: Bearer abc123`

Es gibt auf dieser Ebene keine separate X-Api-Key-Weiterleitung, sodass deine eigene API die Anmeldeinformation über ihren Authorization-Header akzeptieren muss, damit der Chat-Ablauf sie erreicht. (Ein direkt aufgerufener generierter MCP-Server, ohne über Tuix AI Agents zu gehen, unterstützt einen separaten X-Api-Key-Header, siehe Autorisierung.)

Ein X-Api-Key darf niemals dem Browser ausgesetzt oder in clientseitigem Code verschickt werden: Wer ihn liest, kann jede Anwendung in deinem Konto aufrufen. Setze für einen öffentlich zugänglichen Chat ein Backend zwischen dein Frontend und Tuix AI Agents und bewahre den Schlüssel dort auf.

Session-Endpunkt

Rufe diesen einmal auf, um eine Unterhaltung zu starten.

POST https://mcp-host.tuix.ch/stream/<ApplicationId>/session

Body

{
    "userId": "<identifier>"
}

userId kann eine zufällige Kennung oder eine echte Nutzer-ID aus deinem eigenen System sein. Sie wird nur als zusätzliche Kennung für deine Session verwendet; Tuix AI Agents schlägt sie nirgends nach.

Antwort

{
    "sessionId": "session-192838110457-7be04c1e",
    "userId": "<identifier>",
    "sessionSecret": "p9QzT2mX_kLr8wYVdN3s...",
    "createdAt": "2026-09-16T09:14:02.331904512Z",
    "initialMessage": "Hello! How can I assist you today?"
}

Speichere sessionId und sessionSecret. Beide werden für den Rest der Unterhaltung benötigt und können danach nicht mehr abgerufen werden.

initialMessage ist die konfigurierte Initial Message der Anwendung, hier zurückgegeben, damit du sie sofort anzeigen kannst, ohne auf eine Antwort des Agenten zu warten.

Beispiel

Diese Beispiele authentifizieren mit X-Api-Key, gelesen zusammen mit der Basis-URL und der Application ID aus der Umgebung. Tausche ihn gegen einen Authorization-Header, wenn du im Namen eines eingeloggten Nutzers handelst, siehe Authentifizierung.

const startSession = async (userId: string) => {
    const response = await fetch(
        `${process.env.MCP_HOST_BASE_URL}/stream/${process.env.APPLICATION_ID}/session`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-Api-Key': process.env.TUIX_AI_AGENTS_API_KEY!,
            },
            body: JSON.stringify({ userId }),
        },
    )
 
    if (!response.ok) {
        throw new Error(`Failed to start session: ${response.status}`)
    }
 
    return response.json()
    // { sessionId, userId, sessionSecret, createdAt, initialMessage }
}

Chat-Endpunkt

Rufe diesen auf, um eine Nachricht zu senden und die gestreamte Antwort des Agenten zu erhalten.

POST https://mcp-host.tuix.ch/stream/<ApplicationId>/chat

Body

{
    "sessionId": "session-192838110457-7be04c1e",
    "message": "<your message>"
}

Header

Header	Erforderlich	Beschreibung
`x-session-secret`	Ja	Das von der Session-Endpunkt zurückgegebene `sessionSecret`.
`Authorization` / `X-Api-Key`	Ja, einer von beiden	Wie beim Session-Endpunkt, siehe Authentifizierung oben.

Der Antwort-Stream

Der Chat-Endpunkt antwortet mit einem Stream typisierter Ereignisse statt einem einzelnen JSON-Payload, sodass deine Oberfläche Fortschritt anzeigen kann, während der Agent arbeitet, statt eines leeren Bildschirms. Jedes Ereignis hat einen type und ein data-Payload.

Typ	Wann es passiert
`thinking`	Der Agent hat begonnen, die Nachricht zu verarbeiten.
`tool-call`	Der Agent ruft eines seiner verbundenen Tools auf (eine MCP-Server-Aktion).
`tool-result`	Ein Tool-Aufruf ist abgeschlossen und hat Daten zurückgegeben.
`chunk`	Ein Stück der Textantwort des Agenten, während es generiert wird.
`complete`	Die vollständige Antwort ist fertig, zusammen mit Nutzungs-/Kontextinformationen.
`error`	Etwas ist fehlgeschlagen, z. B. ein Fehler einer nachgelagerten API oder ein ausgelasteter Modellanbieter.
`done`	Der Stream ist beendet. Immer das letzte Ereignis, egal ob der Turn erfolgreich war oder nicht.

Ein typischer Turn mit einem Tool-Aufruf, hier einer, der eine Bestellung erstellt, sieht so aus:

type: thinking
data: {"message":"Processing your request...","timestamp":"2026-09-16T09:15:40Z"}

type: tool-call
data: {"timestamp":"2026-09-16T09:15:41Z","toolCall":{"assistantMessage":{"content":"[{\"input\":{\"productId\":\"prod_2f81\",\"quantity\":2},\"toolCallId\":\"fc_5e21c9b4-7a3d-4f10-9c6e-2d8b1a4f6e5c\",\"toolName\":\"create_order\",\"type\":\"tool-call\"}]","role":"assistant"}}}

type: tool-result
data: {"timestamp":"2026-09-16T09:15:42Z","toolResult":{"content":"{\"content\":[{\"text\":\"{\\\"orderId\\\":\\\"ord_9c14a7\\\",\\\"status\\\":\\\"confirmed\\\",\\\"productId\\\":\\\"prod_2f81\\\",\\\"quantity\\\":2,\\\"total\\\":59.98}\",\"type\":\"text\"}]}","name":"create_order","role":"tool","tool_call_id":"fc_5e21c9b4-7a3d-4f10-9c6e-2d8b1a4f6e5c"}}

type: thinking
data: {"message":"Processing your request...","timestamp":"2026-09-16T09:15:42Z"}

type: chunk
data: {"chunk":"###","timestamp":"2026-09-16T09:15:42Z"}

... weitere chunk-Ereignisse, eines pro Textstück ...

type: complete
data: {"message":"order 2 units of prod_2f81","response":{"content":"### Order confirmed\n\n| Field | Value |\n| --- | --- |\n| Order ID | ord_9c14a7 |\n| Product | prod_2f81 |\n| Quantity | 2 |\n| Total | 59.98 |","contextPercentage":1.42,"maxTokens":100000,"tokensUsed":1420},"timestamp":"2026-09-16T09:15:42Z"}

type: done
data: {"timestamp":"2026-09-16T09:15:42Z"}

chunk-Ereignisse liefern die Antwort während sie geschrieben wird, sodass du sie fortlaufend rendern kannst. complete liefert dieselbe Antwort vollständig, plus tokensUsed/maxTokens/contextPercentage, nützlich um zu zeigen, wie viel vom Kontextbudget der Unterhaltung verbraucht ist. Warte immer auf done, bevor du den Turn als beendet betrachtest, und behandle einen Stream, der ohne done-Ereignis endet, als Fehlschlag, nicht als stillen Erfolg.

Beispiel

const sendMessage = async (sessionId: string, sessionSecret: string, message: string) => {
    const response = await fetch(
        `${process.env.MCP_HOST_BASE_URL}/stream/${process.env.APPLICATION_ID}/chat`,
        {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'x-session-secret': sessionSecret,
                'X-Api-Key': process.env.TUIX_AI_AGENTS_API_KEY!,
            },
            body: JSON.stringify({ sessionId, message }),
        },
    )
 
    if (!response.ok || !response.body) {
        throw new Error(`Chat request failed: ${response.status}`)
    }
 
    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    let buffer = ''
 
    while (true) {
        const { done, value } = await reader.read()
        if (done) break
 
        buffer += decoder.decode(value, { stream: true })
        const lines = buffer.split('\n')
        buffer = lines.pop() ?? ''
 
        for (const line of lines) {
            if (line) console.log(line) // "type: ..." or "data: {...}"
        }
    }
}

Session vorzeitig beenden

Sessions laufen auch von selbst nach 1 Stunde ab, du kannst aber eine früher löschen:

DELETE https://mcp-host.tuix.ch/stream/<ApplicationId>/session/<sessionId>

Erfordert denselben Authorization-/X-Api-Key-Header wie die anderen beiden Endpunkte, keinen Body. Ein erfolgreiches Löschen antwortet mit 204 No Content. Siehe Anfrage-Referenz für die vollständigen Statuscodes.

Session-Dauer

Eine Session dauert 1 Stunde. Danach laufen ihr Chat-Verlauf und die Session selbst ab, und das Senden einer Nachricht mit einer abgelaufenen sessionId schlägt fehl. Rufe den Session-Endpunkt erneut auf, um eine neue zu starten; der Kontext der vorherigen Unterhaltung wird nicht übernommen.

Anwendungs-Endpunkte