Ihren Agenten definieren

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 das Verhalten von Claude während einer Sitzung bestimmen.

Erstellen Sie den Agenten einmalig als wiederverwendbare Ressource und referenzieren Sie ihn per ID, wenn Sie eine Sitzung starten. Agenten sind versioniert und lassen sich über viele Sitzungen hinweg einfacher verwalten.

Alle Managed Agents API-Anfragen erfordern den managed-agents-2026-04-01 Beta-Header. Das SDK setzt den Beta-Header automatisch.

Konfigurationsfelder des Agenten

Feld	Beschreibung
`name`	Erforderlich. Ein menschenlesbarer Name für den Agenten.
`model`	Erforderlich. Das Claude-Modell, das den Agenten antreibt. Alle Claude 4.5 und spätere Modelle werden unterstützt.
`system`	Ein System-Prompt, der das Verhalten und die Persona des Agenten definiert. Der System-Prompt unterscheidet sich von Benutzernachrichten, die die zu erledigende Arbeit beschreiben sollten.
`tools`	Die dem Agenten zur Verfügung stehenden Tools. Kombiniert vorgefertigte Agenten-Tools, MCP-Tools und benutzerdefinierte Tools.
`mcp_servers`	MCP-Server, die standardisierte Drittanbieter-Funktionen bereitstellen.
`skills`	Skills, die domänenspezifischen Kontext mit progressiver Offenlegung liefern.
`callable_agents`	Andere Agenten, die dieser Agent für die Multi-Agenten-Orchestrierung aufrufen kann. Dies ist eine Research-Preview-Funktion; fordern Sie Zugang an, um sie auszuprobieren.
`description`	Eine Beschreibung dessen, was der Agent tut.
`metadata`	Beliebige Schlüssel-Wert-Paare für Ihr eigenes Tracking.

Einen Agenten erstellen

Das folgende Beispiel definiert einen Coding-Agenten, der Claude Sonnet 4.6 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 Agenten-Tools-Referenz für die vollständige Liste der unterstützten Tools.

Um Claude Opus 4.6 mit dem Fast-Modus zu verwenden, übergeben Sie model als Objekt: {"id": "claude-opus-4-6", "speed": "fast"}.

Die Antwort gibt Ihre Konfiguration zurück und fügt die Felder id, version, created_at, updated_at und archived_at hinzu. Die version beginnt bei 1 und wird bei jeder Aktualisierung des Agenten erhöht.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-sonnet-4-6",
    "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": [],
  "metadata": {},
  "version": 1,
  "created_at": "2026-04-03T18:24:10.412Z",
  "updated_at": "2026-04-03T18:24:10.412Z",
  "archived_at": null
}

Einen Agenten aktualisieren

Das Aktualisieren eines Agenten erzeugt eine neue Version. Übergeben Sie die aktuelle version, um sicherzustellen, dass Sie von einem bekannten Zustand aus aktualisieren.

Aktualisierungssemantik

Ausgelassene Felder werden beibehalten. Sie müssen nur die Felder angeben, die Sie ändern möchten.
Skalare Felder (model, system, name usw.) werden durch den neuen Wert ersetzt. system und description können durch Übergabe von null geleert werden. model und name sind obligatorisch und können nicht geleert werden.
Array-Felder (tools, mcp_servers, skills, callable_agents) werden vollständig durch das neue Array ersetzt. Um ein Array-Feld vollständig zu leeren, übergeben Sie null oder ein leeres Array.

Agenten-Lebenszyklus

Operation	Verhalten
Aktualisieren	Erzeugt eine neue Agenten-Version.
Versionen auflisten	Ruft den vollständigen Versionsverlauf ab, um Änderungen im Laufe der Zeit zu verfolgen.
Archivieren	Der Agent wird schreibgeschützt. Neue Sitzungen können ihn nicht mehr referenzieren, aber bestehende Sitzungen laufen weiter.

Versionen auflisten

Rufen Sie den vollständigen Versionsverlauf ab, um zu verfolgen, wie sich ein Agent im Laufe der Zeit verändert hat.

Einen Agenten archivieren

Das Archivieren macht den Agenten schreibgeschützt. Bestehende Sitzungen laufen weiter, aber neue Sitzungen können den Agenten nicht mehr referenzieren. Die Antwort setzt archived_at auf den Archivierungszeitstempel.

Nächste Schritte

Tools konfigurieren, um anzupassen, welche Fähigkeiten der Agent nutzen kann.
Skills anhängen für domänenspezifisches Fachwissen.
Eine Sitzung starten, die Ihren Agenten referenziert.

agent=$(curl -fsSL https://api.anthropic.com/v1/agents \
  -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 '{
    "name": "Coding Assistant",
    "model": "claude-sonnet-4-6",
    "system": "You are a helpful coding agent.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }')

AGENT_ID=$(jq -r '.id' <<< "$agent")
AGENT_VERSION=$(jq -r '.version' <<< "$agent")

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 @- <<EOF
{
  "version": $AGENT_VERSION,
  "system": "You are a helpful coding agent. Always write tests."
}
EOF
)

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

curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01")

echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"