Task Interface

Ein Endpunkt. Einfache Sprache. Der Agent erledigt alles andere.

---

Der Wandel

Herkömmliche Integrationen zwingen dich, Endpunkte zu lernen, Felder zuzuordnen, Schemata zu versionieren und jeden Sonderfall abzudecken. Das Chat-Agent-Gateway ersetzt all das durch agentische Kommunikation. Beschreibe, was du brauchst. Der eigene Agent von SOIS interpretiert deine Absicht, klärt die Details, führt sie über deinen Workspace aus und antwortet mit dem Ergebnis. Das ist der Einstieg für Aufrufer, die keine eigene KI mitbringen. Wenn du bereits einen Agenten hast, verbinde ihn stattdessen direkt über den MCP-Server.

Keine Konnektoren. Keine Middleware. Keine Drittanbieter-Automatisierungsschicht.

---

Authentifizierung

Jede Nachricht erfordert zwei Zugangsdaten:

Warum zwei? Dein Token weist deine Identität nach. Dein Key steuert die Ausgaben. Wenn nur eines davon durchsickert, ist es ohne das andere nutzlos. Ein Benutzer kann mehrere Keys mit unterschiedlichen Budgets für unterschiedliche Integrationen haben.

Beides erhältst du unter Settings in deinem Sois AI Workspace.

---

Eine Nachricht senden

POST /api/agent

Headers

Authorization: Bearer <your_token>
X-Api-Key: sois_...
Content-Type: application/json

Body

Beispiel

curl -X POST "https://your-workspace.sois.ai/api/agent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Api-Key: sois_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a contact for John Smith at Acme Corp, [email protected], +44 7700 900000",
    "context": { "entity_type": "contact", "action": "create" }
  }'

Antwort 202 Accepted

{
    "conversation_uuid": "6cafd8ba-dd51-4411-808e-671d1dd59561",
    "status": "accepted",
    "message": "Your request has been queued."
}

Deine Nachricht ist im Gateway. Der Agent übernimmt von hier.

---

Die Antwort empfangen

Du hast zwei Möglichkeiten: auf den Webhook warten oder die Unterhaltung abfragen.

Option 1: Webhook (empfohlen)

Wenn dein Key eine response_url hat, liefert der Agent das Ergebnis direkt an dich, sobald er fertig ist: signiert, verifiziert, ohne Polling.

POST https://your-app.com/webhook
Content-Type: application/json
X-Signature: <hmac_sha256>
X-Conversation-UUID: 6cafd8ba-...

Resolved:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "response": "Contact created: John Smith, Acme Corp, [email protected], +44 7700 900000."
}

Failed:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "failed",
    "error": "An error occurred while processing your request."
}

Option 2: Die Unterhaltung abfragen

GET /api/agent/{conversation_uuid}

Authorization: Bearer <your_token>
X-Api-Key: sois_...

Antwort 200 OK:

{
    "conversation_uuid": "6cafd8ba-...",
    "status": "resolved",
    "turns": [
        {
            "role": "user",
            "payload": { "message": "Find all contacts from London" },
            "timestamp": "2026-02-12T01:07:03+00:00"
        },
        {
            "role": "agent",
            "payload": {
                "content": "I found 12 contacts based in London..."
            },
            "timestamp": "2026-02-12T01:07:13+00:00"
        }
    ],
    "webhook": {
        "status": "delivered",
        "delivered_at": "2026-02-12T01:07:14+00:00"
    },
    "resolved_at": "2026-02-12T01:07:13+00:00",
    "expires_at": "2026-02-13T01:07:03+00:00",
    "created_at": "2026-02-12T01:07:03+00:00"
}

Status der Unterhaltung

---

Webhook-Signaturen verifizieren

Jeder Webhook wird mit HMAC-SHA256 unter Verwendung des Signing Secret deines Keys signiert. Verifiziere ihn immer vor der Verarbeitung.

Python:

import hmac, hashlib

expected = hmac.new(
    key=your_signing_secret.encode(),
    msg=raw_request_body.encode(),
    digestmod=hashlib.sha256
).hexdigest()

assert expected == request.headers['X-Signature']

Node.js:

const crypto = require('crypto');
const expected = crypto
    .createHmac('sha256', signingSecret)
    .update(rawBody)
    .digest('hex');

if (expected !== req.headers['x-signature']) {
    throw new Error('Invalid signature');
}

PHP:

$expected = hash_hmac('sha256', $rawBody, $signingSecret);
if (!hash_equals($expected, $request->header('X-Signature'))) {
    abort(403, 'Invalid signature');
}

---

Beispielunterhaltungen

Der Agent hat vollen Zugriff auf deinen Sois AI Workspace. Hier sind einige Dinge, um die du ihn bitten kannst:

Suchen:

{ "message": "Find all contacts from London" }

Erstellen:

{
    "message": "Create a contact: Jane Doe, CEO of Acme Corp, [email protected]",
    "context": { "entity_type": "contact", "action": "create" }
}

E-Mail:

{
    "message": "Send an email to [email protected] introducing our new product line",
    "context": { "entity_type": "inbox", "action": "compose" }
}

Aufgaben:

{
    "message": "Create a task: Research competitor pricing for Q1 2026",
    "context": { "entity_type": "task", "action": "create" }
}

Zusammenfassen:

{
    "message": "Give me a full summary of this contact",
    "context": { "entity_type": "contact", "entity_id": "abc-123", "action": "summarize" }
}

Mehrstufig:

{ "message": "Find the Q1 report, summarise it, and email the summary to the sales team" }

Der Agent klärt Mehrdeutigkeiten. Wenn er erst suchen muss, bevor er handeln kann, sucht er. Wenn mehrere Datensätze passen, wählt er den besten und erklärt dir warum. Keine starren Schemata, nur Absicht.

---

Key-Verwaltung

Verwalte deine Keys unter Settings > API Keys in deinem Sois AI Workspace oder programmatisch.

Einen Key erstellen

POST /api/api-keys

{
    "label": "My CRM Integration",
    "response_url": "https://your-app.com/webhook",
    "budget_usd_cents": 5000,
    "budget_period": "monthly"
}

Die Antwort enthält deinen Key (wird einmal angezeigt, kopiere ihn sofort) und dein Signing Secret zur Webhook-Verifizierung.

Keys verwalten

---

Budgetsteuerung

Herkömmliche Integrationen drosseln dich mit willkürlichen Rate Limits: 100 Anfragen pro Minute, 10.000 pro Tag. Das Chat-Agent-Gateway rechnet in Dollar.

Lege ein Budget pro Key fest. Der Agent berechnet Credits pro Aktion. Du bestimmst, was jede Integration wert ist.

Wird ein Budget überschritten, geben Nachrichten 429 mit einer klaren Erklärung zurück, nicht einen kryptischen Fehlercode.

---

Fehler

Jeder Fehler folgt demselben Format:

{
    "error": {
        "code": "ERROR_CODE",
        "message": "A clear, human-readable explanation."
    }
}

---

Limits