Tin mit der Agent API in Ihr eigenes Produkt einbauen

Tin ist der Agent, der verstreute Gedanken in klare nächste Schritte verwandelt. Die meisten sprechen mit Tin im endue-Chat. Öffnen Sie die API, und derselbe Tin arbeitet in etwas, das Sie selbst gebaut haben: hinter einem Button „Plan daraus machen“ in Ihrer Notiz-App, in einem Skript, das jeden Morgen läuft, oder in einer Automatisierung, die bei jedem eingehenden Formular anspringt.

Tin über die API ist derselbe Agent, mit dem Sie chatten. Er nutzt dieselben Anweisungen, Skills und Konnektoren und dasselbe Gedächtnis, und die Nutzung wird Ihrem Konto zugerechnet. Sie müssen keinen Server hosten und kein Modell anbinden.

So greift es ineinander

1. In Studio erstellen Sie einen API-Schlüssel, der nur für Tin gilt.
2. Ihr Server schickt Tin mit diesem Schlüssel eine Anfrage. Der Body kann ein einziger Satz sein, der sagt, was Sie brauchen.
3. Tin schickt seine Antwort zurück. Der Austausch wird außerdem in Ihrer endue-Unterhaltungsliste gespeichert, sodass Sie ihn später im Web nachlesen können.

Gut für

• Eine Funktion in Ihrer eigenen App. Schicken Sie die Notiz eines Nutzers an Tin und zeigen Sie den Plan, der zurückkommt, auf Ihrem eigenen Bildschirm. Ihre Nutzer müssen nie erfahren, dass es endue gibt.
• Jobs, die nach Zeitplan laufen. Ein Cron-Job schickt die unerledigten Aufgaben von gestern, und Tin dampft sie auf drei Dinge für heute ein. Wohin das Ergebnis geht, entscheidet Ihr Code: ein Intranet-Beitrag, Ihre Datenbank, eine Chatnachricht.
• No-Code-Automatisierungstools. Jedes Tool, das eine HTTP-Anfrage senden kann, etwa Zapier, Make oder n8n, kann Tin ohne Code aufrufen.

Wenn Sie das Ergebnis nur in endue brauchen, ist eine Routine einfacher. Greifen Sie zur API, wenn das Ergebnis in Ihrem eigenen System landen muss.

Was Sie brauchen

• Ein endue-Konto und einen Agenten. Diese Anleitung verwendet Tin.
• Einen Ort, von dem aus Sie Anfragen senden: ein Terminal, den Server Ihres Produkts oder ein Automatisierungstool, das HTTP-Anfragen stellen kann.
• Einen sicheren Ort für den Schlüssel, etwa eine Umgebungsvariable oder einen Secrets-Manager auf Ihrem Server.

Schritt 1. Die API in Studio öffnen

Öffnen Sie Tin und wechseln Sie oben zu Studio, um die Konfiguration des Agenten zu sehen. In der Spalte „01 Requests come in“ gibt es eine Karte API. Klicken Sie darauf, und rechts öffnet sich das API-Panel.

Die POST-Adresse oben im Panel ist Tins Endpunkt. Das curl-Beispiel darunter lässt sich mit einem Klick kopieren und enthält bereits Tins Agent-ID.

Schritt 2. Einen Schlüssel für Tin ausstellen

Klicken Sie auf Issue key und legen Sie zwei Dinge fest.

• Key name (Schlüsselname). Geben Sie an, wo der Schlüssel verwendet wird, zum Beispiel „Planner app server“. Der Name erscheint neben Unterhaltungen, die über diesen Schlüssel hereinkamen, und wenn Sie mehrere Schlüssel haben, sehen Sie auf einen Blick, welchen Sie widerrufen müssen.
• Expiration (Ablauf). Wählen Sie kein Ablaufdatum, 30, 90 oder 365 Tage. Ein kurzes Zeitfenster ist die sicherere Wahl, solange Sie testen.

Klicken Sie auf Issue, und ein Schlüssel, der mit sk_ beginnt, erscheint genau einmal. Nach dem Schließen des Fensters können Sie ihn nicht mehr sehen, kopieren Sie ihn also direkt an einen sicheren Ort. Wenn Sie ihn verlieren, widerrufen Sie ihn und stellen Sie einen neuen aus. Die Beispielanfrage oben im Panel enthält jetzt auch den neuen Schlüssel, Sie können sie also kopieren und sofort testen.

Ein hier erstellter Schlüssel ist ausschließlich für Tin bestimmt. Ihre anderen Agenten kann er nicht aufrufen. Kontoweite Schlüssel, die jeden Agenten aufrufen können, werden separat unter Settings › Account › API Keys ausgestellt. Wenn Sie aber nur einen Agenten brauchen, ist der dedizierte Schlüssel die sicherere Wahl.

Schritt 3. Die erste Anfrage senden

Sie können es direkt im Terminal ausprobieren. Legen Sie den Schlüssel in einer Umgebungsvariable ab, statt ihn in den Befehl zu tippen. Ersetzen Sie AGENT_ID durch die Adresse, die Sie aus Studio kopiert haben.

export ENDUE_API_KEY="sk_..."   # der Schlüssel aus Schritt 2

curl -X POST https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke \
  -H "Authorization: Bearer $ENDUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": "Turn this into a plan for this week: I want to start a small newsletter for our cafe. I have about 5 hours this week."}'

Wenn Tin fertig ist, erhalten Sie eine Antwort wie diese.

{
  "success": true,
  "data": {
    "run_id": "...",
    "session_id": "cnv_...",
    "conversation_id": "cnv_...",
    "agent_id": "...",
    "status": "completed",
    "finish_reason": "final",
    "output_text": "Here's a week that gets the first issue out without eating your weekend. ...",
    "usage": { "input_tokens": 1830, "output_tokens": 264, "total_tokens": 2094 }
  }
}

Drei Felder sind am wichtigsten.

• output_text: Tins Antwort, also der Teil, den Sie auf Ihrem Bildschirm zeigen.
• session_id: die ID der Unterhaltung. Schicken Sie sie mit Ihrer nächsten Anfrage zurück, um weiterzusprechen. conversation_id enthält denselben Wert und ist der Name, den der Hinweis in Studio verwendet.
• status: completed bedeutet, dass Tin vollständig geantwortet hat. incomplete bedeutet, dass ihm die Schritte ausgegangen sind oder dass er an einer Stelle angehalten hat, die die Entscheidung eines Menschen brauchte. Versuchen Sie es mit einer genaueren Anfrage noch einmal.

Schritt 4. Die Unterhaltung fortsetzen

Angenommen, Ihr Nutzer antwortet „Mittwoch kann ich nicht.“ Schicken Sie das zusammen mit der session_id aus der vorherigen Antwort, und Tin überarbeitet den Plan, den er bereits gemacht hat.

{
  "input": "I can't do Wednesday. Move that part to Thursday and redo the plan.",
  "session_id": "cnv_..."
}

Lassen Sie session_id weg, beginnt eine neue Unterhaltung. Um eine Unterhaltung pro Nutzer oder pro Notiz zu führen, speichern Sie die session_id in Ihrer Datenbank gleich daneben.

Schritt 5. In Ihr Produkt einbauen

Stellen Sie sich einen Button „Plan daraus machen“ in einer Notiz-App vor. Eine Regel zählt mehr als alle anderen: Der Code, der Tin aufruft, liegt auf Ihrem Server. Einen Schlüssel in einem Browser oder einer mobilen App kann jeder auslesen, der hinschaut. Ihre Oberfläche spricht mit Ihrem Server, und Ihr Server spricht mit Tin.

Auf einem Node.js-Server sieht das so aus.

// Servercode. Der Schlüssel kommt aus einer Umgebungsvariable.
const TIN_URL = 'https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke';

export async function askTin(input, sessionId) {
  const res = await fetch(TIN_URL, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.ENDUE_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(sessionId ? { input, session_id: sessionId } : { input }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.error?.message ?? `HTTP ${res.status}`);
  return { plan: body.data.output_text, sessionId: body.data.session_id };
}

Ein Python-Skript für den Lauf am Morgen ist noch kürzer.

import os
import requests

res = requests.post(
    "https://platform.endue.ai/api/public/v1/agents/AGENT_ID/invoke",
    headers={"Authorization": f"Bearer {os.environ['ENDUE_API_KEY']}"},
    json={"input": "Left over from yesterday: reply to the quote, order coffee beans, blog draft. Give me three things to do today."},
    timeout=120,
)
res.raise_for_status()
print(res.json()["data"]["output_text"])

Standardmäßig wartet der Aufruf, bis Tin fertig ist, und liefert alles auf einmal zurück. Eine Anfrage, die echtes Nachdenken braucht, kann einige Dutzend Sekunden dauern, setzen Sie das Timeout also großzügig an. Wenn der Text wie in einem Chat erscheinen soll, während er geschrieben wird, ergänzen Sie die Anfrage um "stream": true. Sie erhalten dann denselben SSE-Stream, den der Web-Chat nutzt: run_created, dann delta-Events mit Textstücken, dann done.

Jeder Aufruf ist in endue festgehalten

Unterhaltungen, die über die API hereinkommen, sammeln sich in Tins Seitenleiste unter der Gruppe API. Die Nachricht des Aufrufers trägt das Label „API caller“, und neben dem Titel steht der Schlüssel, über den sie kam. Wenn eine Antwort seltsam wirkte, sehen Sie hier genau, was Tin gefragt wurde und was er gesagt hat.

Diese Unterhaltungen sind in endue schreibgeschützt. Fortsetzen lässt sich eine nur mit einem weiteren API-Aufruf mit derselben session_id.

Auch die Konfigurationsansicht in Studio ändert sich. Der neue Schlüssel erscheint auf der API-Karte als Active, mit einer Linie, die zu Tin führt.

Bevor Sie sich darauf verlassen

Vor einem API-Aufruf sitzt niemand, deshalb behandelt endue ihn als unbeaufsichtigte Ausführung.

• Aktionen, die etwas verschicken oder löschen, etwa das Senden einer E-Mail, werden abgelehnt, statt auf eine Freigabe zu warten. Reine Leseaktionen, etwa eine Abfrage, funktionieren wie gewohnt.
• Wenn Tin eine Rückfrage stellen muss, ist niemand da, der antwortet. Geben Sie von Anfang an mit, was er braucht: Fristen, verfügbare Zeit, das Format, das Sie zurückhaben möchten.

Am besten funktioniert es, wenn Tin Entwürfe und Pläne zurückgibt und Ihr eigener Code das Senden und Speichern übernimmt.

Schlüssel sicher aufbewahren

• Schlüssel bleiben auf dem Server. Nie in Browser-Code, einer mobilen App oder einem Git-Repository.
• Ein Schlüssel pro Einsatzort. Mit getrennten Schlüsseln wie „Planner app server“ und „Morning summary script“ bedeutet ein Leck, dass Sie einen Schlüssel widerrufen, nicht alle.
• Schnell widerrufen. Klicken Sie im API-Panel auf Revoke, und Anfragen mit diesem Schlüssel werden innerhalb einer Minute blockiert.
• Ein Ablaufdatum setzen. Schlüssel, die bald ablaufen oder schon abgelaufen sind, werden im Panel und in Studio markiert.

Was die Statuscodes bedeuten

• 401: Der Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen.
• 403: Sie haben Tin mit einem Schlüssel aufgerufen, der für einen anderen Agenten bestimmt ist.
• 404: Die Agent-ID ist falsch, oder die session_id gehört zu einem anderen Agenten.
• 409: Eine frühere Anfrage in derselben Session läuft noch. Senden Sie erneut, sobald sie fertig ist.
• 402: Sie haben das Nutzungslimit Ihres Tarifs erreicht. Prüfen Sie auf der Seite Usage, was noch übrig ist.

Anfragefelder und Limits sind ausführlich in der Dokumentation zur Agent API beschrieben.