Agent API

Im Bereich API erstellst du Schlüssel, mit denen etwas außerhalb von endue diesen Agenten aufrufen kann. Neben einer Unterhaltung und einem Kanal ist das der dritte Weg zum Agenten, und zwar der für Programme.

Wann du sie nutzt

Wenn Code den Agenten aufruft: ein Skript, das täglich eine Zusammenfassung ablegt, ein Backend, das einen Agenten etwas klassifizieren lässt, ein Job, der in der CI läuft. Ruft eine Person den Agenten auf, passt ein Kanal besser, denn dort bekommt sie einen Thread, Fragen und Freigaben.

Schlüssel erstellen

1. Öffne den Bereich API im Agent Builder und erstelle einen Schlüssel.

2. Kopiere ihn sofort. Der Schlüssel wird nur einmal angezeigt. Wenn du ihn verlierst, widerrufe ihn und erstelle einen neuen.

3. Bewahre ihn dort auf, wo ein Programm ihn lesen kann, eine Person aber nicht: in einer Umgebungsvariable oder einem Secret Store, niemals in einem Repository.

Ein hier erstellter Schlüssel gilt nur für diesen Agenten: Deine anderen Agenten lassen sich damit nicht aufrufen. Kontoweite Schlüssel, die das können, erstellst du stattdessen unter Einstellungen → Konto. Nimm lieber den eng begrenzten.

In voller Größe öffnen

Den Agenten aufrufen

Sende den Schlüssel als Authorization: Bearer sk_… (oder X-API-Key) und schick per POST, was der Agent tun soll:

POST /api/public/v1/agents/{agent_id}/invoke
Authorization: Bearer sk_...
Content-Type: application/json

{ "input": "Summarize yesterday's support tickets" }

Zurück kommt die Antwort des Agenten zusammen mit einer Sitzungs-ID. Schickst du diese ID beim nächsten Aufruf mit, macht der Agent im selben Kontext weiter, also in derselben Unterhaltung mit ihrem Verlauf, statt neu anzufangen:

{ "input": "Now group them by product area", "session_id": "..." }

Mit "stream": true bekommst du die Antwort, während sie entsteht, statt auf die ganze Ausführung zu warten.

Eine Sitzung ist eine Unterhaltung

Sitzungen musst du nicht gesondert verwalten. Jede ist eine Unterhaltung, die du in endue öffnen kannst, in der Seitenleiste unter der API-Gruppe des Agenten. Dort liest du nach, was der Agent gefragt wurde und was er geantwortet hat.

Was ein API-Aufruf nicht bekommt

Wer per API aufruft, sitzt nicht vor der Unterhaltung. Deshalb gilt der Aufruf als unbeaufsichtigte Ausführung:

• Aktionen, die etwas nach außen senden oder löschen, werden abgelehnt und nicht zur Freigabe zurückgestellt.
• Für Fragen, die der Agent geklärt haben muss, ist niemand da, der sie beantwortet.

Formuliere die Anfrage so genau, dass der Agent nichts entscheiden muss, und rechne eher mit Entwürfen als mit versendeten Nachrichten.

Einschränkungen

• Pro Sitzung läuft immer nur eine Ausführung. Ein weiterer Aufruf, während in dieser Sitzung eine Ausführung läuft, wird abgelehnt und nicht eingereiht.
• Schlüssel werden nur einmal angezeigt und lassen sich nicht wiederherstellen. Widerrufe sie und erstelle neue.
• Ein Schlüssel für einen bestimmten Agenten funktioniert nur für diesen Agenten. Für andere antwortet der Endpunkt mit „nicht gefunden“.
• Ein widerrufener Schlüssel ist sofort ungültig.

Siehe auch

KanäleDer Weg für Menschen statt für Programme.

FreigabenWarum ein API-Aufruf nicht von sich aus E-Mails senden kann.

Sicherheit und BerechtigungenWorauf ein Schlüssel zugreifen kann und wie du ihn widerrufst.