Die API auf einem selbst gehosteten Server aufrufen

Ein selbst gehosteter Claude Managed Agents-Server hat dieselbe API wie der gehostete Managed Agents-Dienst von Anthropic. Dein Code ruft ihn mit dem offiziellen SDK, cURL oder der ant CLI auf. Zwei Dinge ändern sich: Die „base URL“ (Basis-URL) ist die Adresse deines Servers, und der API-Key ist dein Server-API-Key anstelle eines Claude API-Keys.

Um Agenten zu erstellen und Sitzungen in einem Browser auszuführen, siehe Die Konsole auf deinem Server verwenden.

Voraussetzungen

• Ein laufender Server: Starte einen mit Erste Schritte mit selbst gehostetem Claude Managed Agents oder Auf Kubernetes bereitstellen.
• Zugriff auf den Server: Wenn jemand anderes den Server betreibt, frage nach seiner Adresse und danach, wie du dich authentifizierst. Wenn dort Single Sign-on verwendet wird, siehe Entwicklern die Anmeldung über ein Terminal ermöglichen.
• Die ant CLI: Installiere die neueste Version, wie der CLI-Schnellstart zeigt.

Deinen Client auf deinen Server ausrichten

Das SDK und die ant CLI lesen die Adresse des Servers aus ANTHROPIC_BASE_URL und den API-Key aus ANTHROPIC_API_KEY. Setze beide Variablen in einem Terminal, das du für diesen Server reservierst.

Führe für den Schnellstart-Stack diese Befehle in dem Verzeichnis aus, das deine .env-Datei enthält:

export ANTHROPIC_BASE_URL=http://127.0.0.1:8400
export ANTHROPIC_API_KEY=$(grep '^CMA_SERVER__API_KEY=' .env | cut -d= -f2)

Setze unter Kubernetes die beiden Variablen, wie Eine Sitzung ausführen zeigt, und lass das dortige Port-Forwarding weiterlaufen.

In diesem Terminal erreicht jeder ant-Befehl, wie etwa ant beta:agents list, deinen Server. Führe Claude Code oder docker compose nicht in diesem Terminal aus, da sie dieselben Variablen lesen.

Eine Sitzung starten

Eine Sitzung benötigt die ID eines Agents und die ID einer Umgebung:

• Agent: Erstelle einen, wie Einen Agenten erstellen zeigt, wobei dein Client auf deinen Server ausgerichtet ist. Wenn du direkte HTTP-Anfragen sendest, ersetze https://api.anthropic.com in der URL durch $ANTHROPIC_BASE_URL.
• Umgebung: Der Schnellstart-Stack erstellt eine Umgebung namens compose-sandbox, und die Helm-Charts erstellen eine namens default. ant beta:environments list gibt den Namen und die ID jeder Umgebung aus. Für deine eigenen Worker ist es die ID, die die Admin-CLI in Eigene Worker betreiben ausgegeben hat.

Lege deine beiden IDs anstelle dieser Beispiel-IDs in deiner Shell ab:

export AGENT_ID=agent_011CYm1BLqPXpQRk5khsSXrs
export ENVIRONMENT_ID=env_01595EKxaaTTGwwY3kyXdtbs

Das folgende Beispiel erstellt eine Sitzung und sendet ihre erste Nachricht in derselben Anfrage:

import os

from anthropic import Anthropic

client = Anthropic()

session = client.beta.sessions.create(
    agent=os.environ["AGENT_ID"],
    environment_id=os.environ["ENVIRONMENT_ID"],
    initial_events=[
        {
            "type": "user.message",
            "content": [
                {"type": "text", "text": "List the files in the working directory."}
            ],
        },
    ],
)
print(session.id)

Die Antwort enthält die ID der Sitzung, die mit sesn_ beginnt. Der Agent beginnt sofort mit der Arbeit. Seine integrierten Tools, wie bash, laufen auf einem Worker, der die Umgebung bedient.

Um die Sitzung zu beobachten, öffne die Konsole auf deinem Server in einem Browser, wähle Sessions und dann die Sitzung aus. Eine Sitzung, die du wie auf dieser Seite mit dem Server-API-Key gestartet hast, wird nur Administratoren angezeigt.

Um die Sitzung stattdessen in deinem Terminal zu verfolgen, übergib ihre ID an ant beta:sessions connect:

ant beta:sessions connect sesn_011CZkZAtmR3yMPDzynEDxu7

Was eine Sitzung sonst noch kann, etwa eine Agent-Version festlegen, findest du unter Eine Session starten.

Eine Nachricht senden und die Antwort lesen

Lege die ID deiner Sitzung anstelle dieser Beispiel-ID in deiner Shell ab:

export SESSION_ID=sesn_011CZkZAtmR3yMPDzynEDxu7

Warte, bis die Sitzung im Leerlauf ist, bevor du das nächste Beispiel ausführst. Das Beispiel hört auf zu lesen, wenn ein Turn endet. Wenn ein früherer Turn noch läuft, kann sein Ende das Beispiel stoppen, bevor die Antwort auf deine Nachricht eintrifft. Die Konsole und ant beta:sessions connect zeigen beide den Status der Sitzung an.

Das folgende Beispiel sendet eine Nachricht und gibt die Antwort des Agenten aus. Es öffnet zuerst den Event-Stream der Sitzung, weil ein Stream nur die Events liefert, die nach seinem Öffnen eintreffen:

import os

from anthropic import Anthropic

client = Anthropic()
session_id = os.environ["SESSION_ID"]

with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {"type": "text", "text": "Summarize what you did in one sentence."}
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    if block.type == "text":
                        print(block.text, end="")
            case "session.error":
                error_message = event.error.message if event.error else "unknown"
                print(f"\n[Error: {error_message}]")
            case "session.status_idle":
                if event.stop_reason.type != "requires_action":
                    break
            case "session.status_terminated":
                break

Neben der Ausgabe von agent.message-Text verarbeitet die Schleife drei Events:

• session.status_idle: Die Schleife endet, es sei denn, der stop_reason.type des Events ist requires_action.
• session.status_terminated: Die Schleife endet.
• session.error: Die Schleife gibt die Meldung des Fehlers aus und liest weiter, weil der Server einen fehlgeschlagenen Modellaufruf wiederholen und den Turn abschließen kann.

requires_action bedeutet, dass die Sitzung für einen Tool-Aufruf pausiert hat. Was die Pause beendet, hängt vom Aufruf ab:

• Ein Aufruf eines benutzerdefinierten Tools oder eine Anfrage zur Bestätigung eines Tool-Aufrufs: Nur dein Code kann darauf antworten. Wenn dein Agent eines davon verwendet, siehe Tool-Aufrufe beantworten, die die Session pausieren.
• Ein Aufruf eines Tools, das ein Worker ausführt, etwa bash: Dieser Aufruf pausiert die Sitzung normalerweise nicht. Wenn etwa 3 Minuten lang kein Worker den Aufruf übernimmt, pausiert die Sitzung, bis ein Worker das Ergebnis zurückgibt. Dein Code muss dann nichts beantworten. Halte den Stream offen, und der Turn wird fortgesetzt, wenn ein Worker den Aufruf ausführt.

Um die anderen Events zu sehen, die eine Sitzung sendet, und zu erfahren, wie du dich erneut verbindest, ohne eines zu verpassen, siehe Session-Event-Stream.

Daten in eine Sitzung hinein- und aus ihr herausbringen

Daten gelangen über das Arbeitsverzeichnis des Workers in eine Sitzung und aus ihr heraus.

Auf dem Schnellstart-Stack startet der Container jeder Sitzung mit einem leeren /workspace-Verzeichnis, abgesehen von den Klonen der Repositories der Sitzung. Standardmäßig wird der Container etwa eine Minute nach dem Ende eines Turns beendet, und Docker löscht ihn zusammen mit diesem Verzeichnis. Alles, was eine Sitzung behalten muss, muss vorher über einen Tool-Aufruf, etwa einen Upload oder einen git push, nach außen gelangen.

Ein Container wird außerdem etwa eine Stunde nach seinem Start beendet, selbst mitten in einem Turn. Keine Einstellung ändert das. Der Turn wird in einem neuen Container fortgesetzt, normalerweise nach ein oder zwei Minuten, und dein Client erhält kein Event für den Wechsel. Der Wechsel hat zwei Kosten:

• Befehle: Alles, was im alten Container läuft, stoppt. Der neue Container führt den unterbrochenen Tool-Aufruf erneut von Anfang an aus, aber nichts startet einen Befehl neu, den der Agent im Hintergrund laufen gelassen hat.
• Dateien: Das /workspace des neuen Containers ist wieder leer, abgesehen von frischen Klonen der Repositories der Sitzung.

Lass den Agenten in einem langen Turn seine Arbeit fortlaufend hochladen oder pushen, und vermeide Befehle, die Schaden anrichten, wenn sie zweimal ausgeführt werden.

Unter Kubernetes behält eine Sitzung einen Pod höchstens etwa eine Stunde lang, und der Turn wird auf dieselbe Weise fortgesetzt. Zwei Dinge unterscheiden sich: Der neue Pod findet die Dateien der Sitzung in /workspace, und er startet etwa 6 Minuten, nachdem der alte Pod stoppt.

Lege bei Workern, die du selbst startest, Eingabedateien im Arbeitsverzeichnis ab, bevor du die Nachricht sendest, die sie benötigt. Lies Ausgabedateien anschließend von dort.

Wenn du selbst für jede Sitzung einen Container startest, binde ein Verzeichnis, das die Eingabedateien der Sitzung enthält, als Arbeitsverzeichnis des Containers ein. Hole die Ausgabedateien von dort ab, nachdem der Container beendet wurde. Siehe Dateien für eine Sitzung bereitstellen.

Weitere Beispiele in den Leitfäden des gehosteten Dienstes finden

Die Leitfäden des gehosteten Dienstes erklären die Kernkonzepte der API und enthalten Beispiele für jede Funktion. Ihre SDK- und CLI-Beispiele rufen deinen Server auf, wenn du sie in dem Terminal ausführst, in dem ANTHROPIC_BASE_URL und ANTHROPIC_API_KEY gesetzt sind. Ihre cURL-Beispiele nennen https://api.anthropic.com, ersetze diese Adresse also durch $ANTHROPIC_BASE_URL, bevor du eines ausführst.

Für manche Funktionen benötigt dein Server zuerst eine Einstellung, oder ein Beispiel benötigt eine Änderung:

Unterschiede zum gehosteten Dienst enthält die vollständige Liste. Prüfe sie, bevor du eine bestehende Anwendung umziehst.

Eigene Worker betreiben

Der Schnellstart-Stack erstellt eine Umgebung und betreibt die Worker dieser Umgebung. Das tun auch die Helm-Charts in Auf Kubernetes bereitstellen. Wenn diese Worker alles sind, was du brauchst, überspringe diesen Abschnitt.

Du betreibst Worker wie bei selbst gehosteten Sandboxes: mit denselben ant beta:worker-Befehlen und SDK-Workern, auf die Weisen, die Selbst gehostete Worker bereitstellen zeigt. Die Ausnahme sind durch Webhooks ausgelöste Worker, da dein Server keine sendet.

Eine Umgebung und ihren Schlüssel erstellen

Erstelle mit der Admin-CLI, nicht in der Claude Console, eine Umgebung und einen „environment key“ (Umgebungsschlüssel). Die CLI, cma-server-admin, liegt in der obersten Ebene des Release-Archivs, führe den Befehl also von dort aus. Übergib für -base-url die Adresse, unter der deine Worker den Server erreichen:

• Worker auf dem Rechner, auf dem der Schnellstart-Stack läuft: http://127.0.0.1:8400
• Worker auf einem anderen Rechner: die https-Adresse des TLS-Proxys, den du vor den Server schaltest

Die Admin-CLI ruft den Server unter derselben Adresse auf, führe sie also auf einem Rechner aus, der diese Adresse erreichen kann.

echo "$ANTHROPIC_API_KEY" | ./cma-server-admin bootstrap \
  -base-url http://127.0.0.1:8400 -name my-env -key-file -

Der Befehl gibt die Einstellungen des Workers, den Befehl zum Starten eines Workers sowie die ID und das Ablaufdatum des Schlüssels aus:

export ANTHROPIC_BASE_URL='http://127.0.0.1:8400'
export ANTHROPIC_ENVIRONMENT_ID='env_...'
export ANTHROPIC_ENVIRONMENT_KEY='sk-ant-oat01-...'
# then: histchars= HISTFILE=/dev/null ant beta:worker poll --workdir /workspace
# key id: 'etok_...'  expires: '...'

Der Befehl zeigt den Schlüssel nur einmal an, speichere also den Schlüssel, seine ID und sein Ablaufdatum in deinem Secret-Manager. Der Schlüssel funktioniert nach 365 Tagen nicht mehr. Befolge vorher Einen Umgebungsschlüssel für deine eigenen Worker ersetzen.

Halte den Server-API-Key von den Rechnern fern, auf denen Worker laufen. Führe Worker in einem Container oder einer VM aus, die nichts enthalten, was du schützen musst. Deine weiteren Sicherheitspflichten findest du unter Deine Verantwortlichkeiten für die Sicherheit.

Ein lokales Experiment ausführen

Führe die drei export-Zeilen in der Shell aus, in der du den Worker startest. Starte den Worker dann mit diesen Befehlen, nicht mit dem ausgegebenen. Der erste Befehl erstellt das Arbeitsverzeichnis des Workers, da der Worker es nicht erstellt:

mkdir -p "$HOME/cma-workspace" "$HOME/.config/cma"
cat > "$HOME/.config/cma/worker.inputrc" <<'EOF'
$include /etc/inputrc
set disable-completion on
EOF
histchars= HISTFILE=/dev/null INPUTRC="$HOME/.config/cma/worker.inputrc" \
  ant beta:worker poll --workdir "$HOME/cma-workspace"

histchars, INPUTRC und HISTFILE richten die Shell hinter dem bash-Tool des Workers so ein, dass sie jeden Befehl so ausführt, wie der Agent ihn geschrieben hat:

• histchars=: Die Shell behandelt ! nicht als Verweis auf ihren Befehlsverlauf.
• INPUTRC: Die Datei schaltet die Vervollständigung aus, die sonst jedes Tabulatorzeichen in einem Befehl verbrauchen würde. Halte die Datei aus dem Arbeitsverzeichnis heraus, wo die Datei-Tools des Agenten sie überschreiben könnten.
• HISTFILE=/dev/null: Die Shell liest und schreibt keine Verlaufsdatei.

Verwende diesen Worker für nichts anderes. Er hält den Umgebungsschlüssel und führt die Tools jeder Sitzung in einem einzigen Prozess aus. Er klont auch nicht die Repositories einer Sitzung. Die Sitzung läuft ohne sie, und dein Client erhält keinen Fehler.

Worker in der Produktion betreiben

Für alles außer einem lokalen Experiment starte für jede Sitzung einen Container und führe darin ant beta:worker run aus, wie Eine Sandbox pro Sitzung ausführen zeigt. Gib seinem Image, was Ein eigenes Sandbox-Image erstellen auflistet, und ändere drei Dinge in diesem Setup:

• Umgebungsschlüssel: Übergib ANTHROPIC_ENVIRONMENT_KEY nicht an den Container einer Sitzung. Der Server akzeptiert diesen Schlüssel für jede Sitzung in der Umgebung, und der Container benötigt nur Zugriff auf eine Sitzung.
• Secret des Work-Items: Übergib dieses Secret anstelle des Schlüssels, weil der Server es nur für diese eine Sitzung akzeptiert. Das Secret des Arbeitselements weiterleiten zeigt, wo dein Code es empfängt. Wo jener Abschnitt ANTHROPIC_WORK_SECRET setzt, lege das Secret in einer Datei ab, die nur der Benutzer des Containers lesen kann. Leite das Secret zum Beispiel per Pipe an die Standardeingabe des Containers weiter und lass den Container die Datei schreiben, bevor er den Worker startet. Setze dann ANTHROPIC_WORK_SECRET_FILE auf den Pfad der Datei.
• Serveradresse: Setze ANTHROPIC_BASE_URL auf eine Adresse, die der Container erreichen kann. http://127.0.0.1:8400 ist keine solche Adresse.

Für einen SDK-Worker gelten zwei weitere Punkte:

• Version: Baue den Worker auf der neuesten Version des SDK auf, wie SDKs, CLI und Bibliotheken beschreibt. Der Worker dieser Version wartet auf eine Bestätigung, bevor er einen Tool-Aufruf ausführt, der sie benötigt, und führt nie einen Aufruf aus, den eine Richtlinie ablehnt. Ein Worker, der auf einer früheren Version aufbaut, führt jeden Tool-Aufruf aus, sobald er eintrifft.
• Beispiele: Die Beispiele in Den SDK-Worker innerhalb der Sandbox ausführen lesen den Umgebungsschlüssel, daher funktionieren sie hier nicht unverändert.

Ein eigenes Sandbox-Image erstellen

Ein eigenes Image benötigt diese Pakete und Einstellungen:

• Pakete: Git 2.38 oder höher, curl, jq und ripgrep, mit dem das grep-Tool des Workers sucht.

• Shell-Einstellungen: histchars, HISTFILE und INPUTRC, wie im lokalen Experiment, sowie TERMINFO. Füge diese Zeilen in das Dockerfile ein, vor jeder USER-Zeile:

  ENV histchars=
  RUN printf '\nset disable-completion on\n' >> /etc/inputrc
  ENV INPUTRC=/etc/inputrc TERMINFO=/etc/terminfo HISTFILE=/dev/null
  RUN test -r /etc/terminfo/d/dumb

  

  TERMINFO muss das Verzeichnis angeben, das d/dumb enthält, die Terminalbeschreibung, die das bash des Workers liest. Unter Alpine mit installiertem bash ist das /etc/terminfo, wie gezeigt. Auf einer anderen Basis, etwa Debian oder Ubuntu, ist es /lib/terminfo oder /usr/share/terminfo, je nachdem, welches d/dumb enthält. Trage dieses Verzeichnis in der TERMINFO-Einstellung und in der RUN test-Zeile ein, die den Build stoppt, wenn die Datei fehlt.

Das Image benötigt außerdem zwei Skripte aus dem Archiv, die ausgeführt werden, bevor der Worker startet:

1. Kopiere image-build/with-repositories.sh nach /usr/local/bin/cma-with-repositories. Es klont die Repositories einer Sitzung.
2. Kopiere image-build/with-egress.sh nach /usr/local/bin/cma-with-egress. Es richtet die Tools der Sitzung auf das Egress-Gateway aus, falls dein Server eines betreibt.
3. Mache beide Dateien ausführbar.
4. Stelle beide dem Befehl des Workers voran, wie in cma-with-egress cma-with-repositories ant beta:worker run .... Überspringe diesen Schritt, wenn dein Image das kubernetes/sandbox/worker.sh des Archivs ausführt, weil dieses Skript den Worker auf diese Weise startet.

Ein Worker, der ohne cma-with-repositories startet, führt die Sitzung ohne Repository aus. Dein Client erhält keinen Fehler.

Worker vom gehosteten Dienst umziehen

Wenn du bereits Worker für den gehosteten Dienst von Anthropic betreibst, können dieselben Worker stattdessen deinen Server bedienen. Tu drei Dinge:

• Übergib dem Prozess, der nach Arbeit pollt, die drei export-Werte, die die Admin-CLI ausgegeben hat.
• Starte diesen Prozess mit gesetzten histchars, HISTFILE und INPUTRC, wie im lokalen Experiment.
• Nimm die Änderungen vor, die Worker in der Produktion betreiben beschreibt, und prüfe das Image jeder Sitzung anhand von Ein eigenes Sandbox-Image erstellen.

Nächste Schritte

• Entwicklern die Anmeldung über ein Terminal ermöglichen: Richte Single Sign-on ein, damit Entwickler die ant CLI unter ihrer eigenen Identität verwenden, in einem Terminal ohne ANTHROPIC_API_KEY.
• Agent-Identität und Anmeldeinformationen: Lass externe Systeme deinen Agents vertrauen, und bewahre Vault-Anmeldedaten in deinem Secret-Manager auf.
• Inferenzanbieter: Sende Modellaufrufe an einen Cloud-Anbieter oder dein eigenes Modell-Gateway.