Definiere deinen Agenten

Ein Agent ist eine wiederverwendbare, versionierte Konfiguration, die Persona und Fähigkeiten definiert. Er bündelt das Modell, den „system prompt“ (System-Prompt), Tools, MCP-Server und Skills, die bestimmen, wie sich Claude während einer Session verhält.

Erstelle den Agenten einmal als wiederverwendbare Ressource und referenziere ihn jedes Mal per ID, wenn du eine Session startest. Agenten sind versioniert und lassen sich über viele Sessions hinweg einfacher verwalten.

Felder der Agentenkonfiguration

Du kannst model, system, tools, mcp_servers und skills auch für eine einzelne Session überschreiben, ohne den Agenten zu ändern. Eine model-Überschreibung ersetzt das model-Objekt des Agenten vollständig, sodass das eigene effort des Agenten nicht übernommen wird. Um die Session mit einer bestimmten Effort-Stufe auszuführen, setze effort innerhalb des model-Objekts der Überschreibung. Siehe Agentenkonfiguration für eine Session überschreiben.

Einen Agenten erstellen

Das folgende Beispiel definiert einen Coding-Agenten, der Claude Opus 5 mit Zugriff auf das vorgefertigte Agenten-Toolset verwendet. Das Toolset ermöglicht es dem Agenten, Code zu schreiben, Dateien zu lesen, im Web zu suchen und mehr. Siehe die Referenz der Agenten-Tools für die vollständige Liste der unterstützten Tools.

Die Beispiele verwenden curl, die ant-CLI oder eines der SDKs. Falls du noch keines eingerichtet hast, behandelt der Schnellstart die Installation und die Client-Einrichtung.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent.

Die Antwort gibt deine Konfiguration wieder und fügt die Felder id, type, version, created_at, updated_at und archived_at hinzu und füllt model-Felder, die du weglässt, wie etwa effort, mit ihren Standardwerten auf. Die version beginnt bei 1 und wird jedes Mal erhöht, wenn eine Aktualisierung den Agenten ändert.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-5-5",
    "effort": { "type": "high" },
    "speed": "standard"
  },
  "system": "You are a helpful coding agent.",
  "description": null,
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": {
        "permission_policy": { "type": "always_allow" }
      }
    }
  ],
  "skills": [],
  "mcp_servers": [],
  "multiagent": null,
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Die default_config am Toolset zeigt dessen standardmäßige Berechtigungsrichtlinie, always_allow, die gilt, sofern du keine konfigurierst.

Die Inferenz-Geo festlegen

Wie speed und effort wird inference_geo über die Objektform von model gesetzt: Übergib model als Objekt und setze inference_geo neben id. Das Feld akzeptiert "us" oder "global". Wenn es nicht gesetzt ist, folgt jede Modellanfrage der Standard-Inferenz-Geo des Workspace zum Zeitpunkt ihrer Bearbeitung. Siehe Datenresidenz für die Geo-Steuerungen auf Workspace-Ebene und die Preise.

Das folgende Beispiel legt einen Agenten auf US-Inferenz fest und gibt den Wert inference_geo aus dem model-Objekt des Agenten aus:

ant apply geo-pinned-assistant.md

---
name: Geo-pinned assistant
model:
  id: claude-opus-5-5
  inference_geo: us
---

You are a helpful assistant.

Eine inference_geo-Festlegung wird gegen die allowed_inference_geos des Workspace validiert, wenn der Agent gespeichert wird, wenn eine Session aus ihm erstellt wird und bei jedem Turn, den die Session bearbeitet. Wenn sich die Allowlist des Workspace so verengt, dass eine Festlegung nicht mehr erlaubt ist, können keine neuen Sessions aus dem Agenten erstellt werden und laufende Sessions verweigern weitere Turns; Festlegungen werden niemals ausgenommen, da Workspaces sich für Compliance und Datenresidenz auf sie verlassen.

Das Setzen von inference_geo bei einem Modell, das keine geografische Inferenz-Festlegung unterstützt, gibt einen 400-Fehler zurück; siehe Modellverfügbarkeit für die Modelle, die dies unterstützen. In einer multiagent-Konfiguration müssen die Festlegung des Koordinators und die jedes Roster-Mitglieds alle auf denselben Wert gesetzt oder alle nicht gesetzt sein; siehe Multiagenten-Orchestrierung. Um die Festlegung später zu ändern oder zu löschen, aktualisiere das model-Objekt des Agenten; die Angabe von model ohne inference_geo löscht sie, wie unter Aktualisierungssemantik beschrieben.

Einen Agenten aktualisieren

Das Aktualisieren eines Agenten erzeugt eine neue Version, wenn sich die Konfiguration ändert. Das Feld version ist optional: Gib es für optimistische Nebenläufigkeit an (eine Abweichung gibt einen 409 zurück) oder lass es weg, um die Aktualisierung bedingungslos anzuwenden (der letzte Schreibvorgang gewinnt). Aktualisierungen archivierter Agenten werden abgelehnt.

Mit der CLI bearbeitest du die Datei des Agenten und führst ant apply erneut aus; apply übergibt version für dich.

ant apply coding-assistant.md

---
name: Coding Assistant
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
---

You are a helpful coding agent. Always write tests.

Das vorangehende Beispiel gibt version aus der Erstellungsantwort an, sodass die Aktualisierung nur angewendet wird, wenn nichts anderes den Agenten geändert hat, seit du ihn gelesen hast. Um eine Aktualisierung bedingungslos anzuwenden, lass version in der Anfrage weg:

updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "description": "Writes and reviews code."
  }')

echo "New version: $(jq -r '.version' <<< "$updated_agent")"

Aktualisierungssemantik

• version ist optional und muss, wenn angegeben, mindestens 1 sein. Wenn angegeben, gibt die Anfrage einen 409 zurück, falls sie nicht mit der aktuellen Version des Agenten übereinstimmt, selbst wenn die von dir gesendeten Felder bereits mit den gespeicherten Werten übereinstimmen; lies den Agenten erneut und versuche es noch einmal. Wenn weggelassen, wird die Aktualisierung bedingungslos angewendet und die jüngste Aktualisierung ersetzt stillschweigend jede gleichzeitige, ohne Fehler für einen der beiden Aufrufer. Die Angabe von version ist der empfohlene Standard für interaktive Aufrufer, und das Weglassen passt zu deklarativen Apply-Schleifen, etwa einem CI-Job, der eingecheckte Agentendefinitionen synchronisiert, bei denen die Schleife den Agenten besitzt.

• Weggelassene Felder bleiben erhalten. Du musst nur die Felder angeben, die du ändern möchtest.

• Skalare Felder (model, system, name, description) werden durch den neuen Wert ersetzt. system und description können durch Übergabe von null gelöscht werden. model und name sind obligatorisch und können nicht gelöscht werden. Innerhalb eines von dir angegebenen model-Objekts ist effort die einzige Ausnahme: Wenn die Modell-id unverändert ist, lässt das Weglassen von effort die gespeicherte Effort-Stufe unverändert. Wenn du die Modell-id änderst, wird ein weggelassenes effort auf den Standard des neuen Modells zurückgesetzt. Andere model-Felder werden zusammen mit dem Objekt ersetzt: Die Angabe von model ohne inference_geo löscht die Inferenz-Geo-Festlegung des Agenten.

• Array-Felder (tools, mcp_servers, skills) werden vollständig durch das neue Array ersetzt. Um ein Array-Feld vollständig zu leeren, übergib null oder ein leeres Array.

• multiagent wird als Ganzes ersetzt, einschließlich seines agents-Rosters. Übergib null, um es zu löschen.

• Metadata wird auf Schlüsselebene zusammengeführt. Von dir angegebene Schlüssel werden hinzugefügt oder aktualisiert. Weggelassene Schlüssel bleiben erhalten. Um einen bestimmten Schlüssel zu löschen, setze seinen Wert auf null.

• No-op-Erkennung. Wenn die Aktualisierung keine Änderung gegenüber der aktuellen Version bewirkt, wird keine neue Version erstellt und die bestehende Version zurückgegeben.

• Koordinator-Roster werden nicht aktualisiert. Koordinatoren, die diesen Agenten in ihrem multiagent.agents-Roster referenzieren, behalten die Version, die beim Erstellen oder letzten Aktualisieren des Koordinators festgelegt wurde, selbst wenn die Referenz version weglässt. Um an die neue Version zu delegieren, aktualisiere den Koordinator, sodass sein Roster sie referenziert.

Agenten-Lebenszyklus

Versionen auflisten

Rufe den vollständigen Versionsverlauf ab, um nachzuverfolgen, wie sich ein Agent im Zeitverlauf geändert hat. Die Ergebnisse sind paginiert, und die SDK-Beispiele rufen automatisch jede Seite ab.

for version in client.beta.agents.versions.list(agent.id):
    print(f"Version {version.version}: {version.updated_at.isoformat()}")

Einen Agenten archivieren

Das Archivieren macht den Agenten schreibgeschützt und kann nicht rückgängig gemacht werden. Bestehende Sessions laufen weiter, aber neue Sessions können den Agenten nicht referenzieren. Die Antwort setzt archived_at auf den Archivierungszeitstempel.

archived = client.beta.agents.archive(agent.id)

print(f"Archived at: {archived.archived_at.isoformat()}")

Nächste Schritte