# Agent API

> Ruf einen Agenten per HTTP mit einem Schlüssel auf, der nur für ihn gilt – als einzelne Anfrage oder als Sitzung, die ihren Kontext zwischen den Aufrufen behält.

Im Bereich **API** erstellst du Schlüssel, mit denen etwas außerhalb von endue diesen Agenten aufrufen kann. Neben einer [Unterhaltung](/de/docs/work/conversations/) und einem [Kanal](/de/docs/automate/channels/) 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

<Steps>

1. **Öffne den Bereich API** im [Agent Builder](/de/docs/build/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.

</Steps>

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.

<Screenshot
  name="studio-api"
  alt="Der Bereich API: ein ausgestellter Schlüssel mit Präfix und letzter Nutzung, darunter eine Beispielanfrage zum Kopieren."
/>

## Den Agenten aufrufen

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

```http
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:

```json
{ "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.

<Aside type="note" title="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.
</Aside>

## Was ein API-Aufruf nicht bekommt

Wer per API aufruft, sitzt nicht vor der Unterhaltung. Deshalb gilt der Aufruf als [unbeaufsichtigte Ausführung](/de/docs/automate/routines/#niemand-ist-da-um-freizugeben):

- Aktionen, die etwas nach außen senden oder löschen, werden **abgelehnt** und nicht zur Freigabe zurückgestellt.
- Für [Fragen](/de/docs/work/questions/), 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

<CardGrid>
  <LinkCard
    title="Kanäle"
    href="/de/docs/automate/channels/"
    description="Der Weg für Menschen statt für Programme."
  />
  <LinkCard
    title="Freigaben"
    href="/de/docs/work/approvals/"
    description="Warum ein API-Aufruf nicht von sich aus E-Mails senden kann."
  />
  <LinkCard
    title="Sicherheit und Berechtigungen"
    href="/de/docs/account/security/"
    description="Worauf ein Schlüssel zugreifen kann und wie du ihn widerrufst."
  />
</CardGrid>