Definiere deinen Agenten

Ein Agent ist eine wiederverwendbare, versionierte Konfiguration, die Persona und Fähigkeiten definiert. Er bündelt das Modell, den 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 leichter verwalten.

Felder der Agentenkonfiguration

Du kannst außerdem model, system, tools, mcp_servers und skills für eine einzelne Session überschreiben, ohne den Agenten zu ändern. Eine Überschreibung von model ersetzt das model-Objekt des Agenten vollständig, sodass der eigene effort-Wert 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 das neueste Claude Opus-Modell verwendet und Zugriff auf das vorgefertigte Agenten-Toolset hat. Das Toolset ermöglicht es dem Agenten, Code zu schreiben, Dateien zu lesen, im Web zu suchen und mehr. Die vollständige Liste der unterstützten Tools findest du in der Referenz zu Agenten-Tools.

Die Beispiele verwenden curl, die ant CLI oder eines der SDKs. Falls du noch keines davon 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 zurück und ergänzt die Felder id, type, version, created_at, updated_at und archived_at. Außerdem füllt sie model-Felder, die du weglässt, wie etwa effort, mit ihren Standardwerten aus. 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": "medium" },
    "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 des Toolsets zeigt dessen standardmäßige Berechtigungsrichtlinie, always_allow, die gilt, sofern du keine konfigurierst.

Die Inference-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-Inference-Geo des Workspace zum Zeitpunkt ihrer Verarbeitung. Die Geo-Steuerungen auf Workspace-Ebene und die Preise findest du unter Datenresidenz.

Das folgende Beispiel legt einen Agenten auf US-Inferenz fest und gibt den inference_geo-Wert 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 daraus erstellt wird und bei jedem Turn, den die Session verarbeitet. Wenn die Allowlist des Workspace so eingeschränkt wird, 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 nie ausgenommen, da Workspaces sich für Compliance und Datenresidenz auf sie verlassen.

Das Setzen von inference_geo bei einem Modell, das keine geografische Festlegung der Inferenz unterstützt, gibt einen 400-Fehler zurück; die Modelle, die dies unterstützen, findest du unter Modellverfügbarkeit. In einer multiagent-Konfiguration müssen die Festlegung des Agenten und die Festlegung jedes Agenten, der in der predefined_agents-Liste von subagents oder workflows aufgeführt ist, alle auf denselben Wert gesetzt oder alle nicht gesetzt sein; siehe Multiagenten-Orchestrierung. Um die Festlegung später zu ändern oder zu entfernen, aktualisiere das model-Objekt des Agenten; wenn du model ohne inference_geo übergibst, wird sie entfernt, 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äufigkeitskontrolle 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.

Bearbeite mit der CLI die Datei des Agenten und führe 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 vorherige Beispiel übergibt version aus der Erstellungsantwort, 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:

unconditional_agent = client.beta.agents.update(
    agent.id,
    description="Writes and reviews code.",
)

print(f"New version: {unconditional_agent.version}")

Aktualisierungssemantik

• version ist optional und muss, wenn angegeben, mindestens 1 sein. Wenn angegeben, gibt die Anfrage einen 409 zurück, falls der Wert nicht mit der aktuellen Version des Agenten übereinstimmt, selbst wenn die gesendeten Felder bereits den gespeicherten Werten entsprechen; 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 dass einer der Aufrufer einen Fehler erhält. Die Angabe von version ist der empfohlene Standard für interaktive Aufrufer, während das Weglassen zu deklarativen Apply-Schleifen passt, etwa einem CI-Job, der eingecheckte Agentendefinitionen synchronisiert, bei dem 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 None geleert werden. model und name sind Pflichtfelder und können nicht geleert werden. Innerhalb eines von dir übergebenen model-Objekts ist effort die einzige Ausnahme: Wenn die Modell-id unverändert ist, bleibt die gespeicherte Effort-Stufe beim Weglassen von effort unverändert. Wenn du die Modell-id änderst, wird ein weggelassenes effort auf den Standardwert des neuen Modells zurückgesetzt. Andere model-Felder werden zusammen mit dem Objekt ersetzt: Wenn du model ohne inference_geo übergibst, wird die Inference-Geo-Festlegung des Agenten entfernt.

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

• multiagent wird Ebene für Ebene mit dem gespeicherten Block zusammengeführt, wenn die Aktualisierung den Typ multiagent_20261001 beibehält. Eine Einstellung, die du weglässt, behält ihren gespeicherten Wert, und eine predefined_agents-Liste, die du sendest, ersetzt die gespeicherte Liste. Jede andere Aktualisierung, die multiagent sendet, ersetzt den gespeicherten Block als Ganzes, und die darin weggelassenen Einstellungen erhalten ihre Standardwerte. Übergib multiagent=None, um den gesamten Block zu leeren. Innerhalb des Blocks setzt null eine Einstellung auf ihren Standardwert zurück, sodass das Setzen von workflows auf null dynamische Workflows aktiviert. Siehe Dynamische Workflows aktivieren.

• Metadaten werden 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.

• Erkennung von No-ops. Wenn die Aktualisierung im Vergleich zur aktuellen Version keine Änderung bewirkt, wird keine neue Version erstellt und die bestehende Version zurückgegeben.

• Die predefined_agents-Listen anderer Agenten werden nicht aktualisiert. Agenten, die diesen Agenten in der predefined_agents-Liste von subagents oder workflows aufführen, behalten die Version, die bei ihrer Erstellung oder bei der letzten Aktualisierung, die diese Liste gesendet hat, festgelegt wurde, selbst wenn die Referenz version weglässt. Um an die neue Version zu delegieren, aktualisiere den Agenten, der ihn aufführt, sodass die Liste auf die neue Version verweist.

Die folgende Aktualisierung leert die Beschreibung, löscht den Schlüssel team aus metadata und setzt workflows auf null, wodurch dynamische Workflows aktiviert werden:

ant apply code-reviewer.md

---
name: Code Reviewer
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
metadata:
  owner: docs
multiagent:
  type: multiagent_20261001
  workflows: null
---

You are a helpful coding agent.

Lebenszyklus eines Agenten

Versionen auflisten

Rufe den vollständigen Versionsverlauf ab, um nachzuverfolgen, wie sich ein Agent im Laufe der Zeit verä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 Zeitstempel der Archivierung.

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

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

Nächste Schritte