---
title: Definiere deinen Agenten
url: https://platform.claude.com/docs/de/managed-agents/agent-setup
description: Erstelle eine wiederverwendbare, versionierte Agentenkonfiguration.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
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](https://platform.claude.com/docs/de/managed-agents/sessions). Agenten sind versioniert und lassen sich über viele Sessions hinweg leichter verwalten.
## Felder der Agentenkonfiguration
| Feld | Beschreibung |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` (csharp, go: `Name`) | Erforderlich. Ein für Menschen lesbarer Name für den Agenten. |
| `model` (csharp, go: `Model`) | Erforderlich. Das Claude-[Modell](https://platform.claude.com/docs/de/models/overview), das den Agenten antreibt. Akzeptiert einen Modell-ID-String oder ein Objekt, zum Beispiel `{"id": "claude-opus-5-5"}`. Claude 4.5 und neuere Modelle werden unterstützt. Die Objektform akzeptiert außerdem die Felder `speed`, `effort` und `inference_geo`; siehe die Tipps unter [Einen Agenten erstellen](https://platform.claude.com/docs/de/managed-agents/agent-setup#create-an-agent), [Effort-Stufen](https://platform.claude.com/docs/de/build-with-claude/effort#effort-levels) und [Die Inference-Geo festlegen](https://platform.claude.com/docs/de/managed-agents/agent-setup#pin-the-inference-geo). |
| `system` (csharp, go: `System`; ruby: `system_`) | Ein [System-Prompt](https://platform.claude.com/docs/de/build-with-claude/prompt-engineering/claude-prompting-best-practices#give-claude-a-role), der das Verhalten und die Persona des Agenten definiert. Der System-Prompt unterscheidet sich von [Benutzernachrichten](https://platform.claude.com/docs/de/managed-agents/reference#event-types), die die zu erledigende Arbeit beschreiben sollten. |
| `tools` (csharp, go: `Tools`) | Die Tools, die dem Agenten zur Verfügung stehen. Kombiniert [vorgefertigte Agenten-Tools](https://platform.claude.com/docs/de/managed-agents/tools), [MCP-Tools](https://platform.claude.com/docs/de/managed-agents/mcp-connector) und [benutzerdefinierte Tools](https://platform.claude.com/docs/de/managed-agents/tools#custom-tools). |
| `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) | [MCP-Server](https://platform.claude.com/docs/de/managed-agents/mcp-connector), die standardisierte Fähigkeiten von Drittanbietern bereitstellen. |
| `skills` (csharp, go: `Skills`) | [Skills](https://platform.claude.com/docs/de/managed-agents/skills), die domänenspezifischen Kontext mit schrittweiser Offenlegung liefern. |
| `multiagent` (csharp, go: `Multiagent`) | Ermöglicht es dem Agenten, Arbeit an andere Agenten zu übergeben, als Subagenten oder in [dynamischen Workflows](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#dynamic-workflows), und optional ein [Advisor](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#give-the-session-an-advisor)-Modell zu konsultieren. Mit dem Typ `multiagent_20261001` sind dynamische Workflows aktiviert, sofern du sie nicht deaktivierst. Siehe [Multiagenten-Orchestrierung](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration). |
| `description` (csharp, go: `Description`) | Eine Beschreibung dessen, was der Agent tut. |
| `metadata` (csharp, go: `Metadata`) | Beliebige Schlüssel-Wert-Paare für dein eigenes Tracking. |
Du kannst außerdem `model` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) und `skills` (csharp, go: `Skills`) für eine einzelne Session überschreiben, ohne den Agenten zu ändern. Eine Überschreibung von `model` (csharp, go: `Model`) ersetzt das `model` (csharp, go: `Model`)-Objekt des Agenten vollständig, sodass der eigene `effort` (csharp, go: `Effort`)-Wert des Agenten nicht übernommen wird. Um die Session mit einer bestimmten Effort-Stufe auszuführen, setze `effort` (csharp, go: `Effort`) innerhalb des `model` (csharp, go: `Model`)-Objekts der Überschreibung. Siehe [Agentenkonfiguration für eine Session überschreiben](https://platform.claude.com/docs/de/managed-agents/sessions#override-agent-configuration-for-a-session).
## 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](https://platform.claude.com/docs/de/managed-agents/tools).
Die Beispiele verwenden curl, die `ant` CLI oder eines der SDKs. Falls du noch keines davon eingerichtet hast, behandelt der [Schnellstart](https://platform.claude.com/docs/de/managed-agents/quickstart#install-the-cli) die Installation und die Client-Einrichtung.
```bash cURL
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-opus-5-5",
"system": "You are a helpful coding agent.",
"tools": [{"type": "agent_toolset_20260401"}]
}'
```
```bash CLI
ant apply coding-assistant.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful coding agent.
```
[`ant apply`](https://platform.claude.com/docs/de/cli-sdks-libraries/cli/apply) erstellt den Agenten aus `coding-assistant.md`, gibt seine ID aus und speichert sie in `claude-lock.json`. Committe `claude-lock.json`, damit das nächste `ant apply` diesen Agenten aktualisiert, anstatt einen zweiten zu erstellen.
```python Python
agent = client.beta.agents.create(
name="Coding Assistant",
model="claude-opus-5-5",
system="You are a helpful coding agent.",
tools=[
{"type": "agent_toolset_20260401"},
],
)
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Coding Assistant",
model: "claude-opus-5-5",
system: "You are a helpful coding agent.",
tools: [{ type: "agent_toolset_20260401" }],
});
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Coding Assistant",
Model = BetaManagedAgentsModel.ClaudeOpus5_5,
System = "You are a helpful coding agent.",
Tools =
[
new BetaManagedAgentsAgentToolset20260401Params
{
Type = "agent_toolset_20260401",
},
],
});
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Coding Assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
},
System: anthropic.String("You are a helpful coding agent."),
Tools: []anthropic.BetaAgentNewParamsToolUnion{{
OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{
Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401,
},
}},
})
if err != nil {
panic(err)
}
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Coding Assistant")
.model(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.system("You are a helpful coding agent.")
.addTool(
BetaManagedAgentsAgentToolset20260401Params.builder()
.type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401)
.build()
)
.build()
);
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Coding Assistant',
model: 'claude-opus-5-5',
system: 'You are a helpful coding agent.',
tools: [
BetaManagedAgentsAgentToolset20260401Params::with(
type: 'agent_toolset_20260401',
),
],
);
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Coding Assistant",
model: "claude-opus-5-5",
system_: "You are a helpful coding agent.",
tools: [{type: "agent_toolset_20260401"}]
)
```
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.
```json
{
"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](https://platform.claude.com/docs/de/managed-agents/permission-policies), `always_allow`, die gilt, sofern du keine konfigurierst.
Um Claude Opus 5.5, Claude Opus 5 oder Claude Opus 4.8 mit dem [Fast Mode](https://platform.claude.com/docs/de/build-with-claude/fast-mode) zu verwenden, übergib `model` als Objekt, zum Beispiel: `{"id": "claude-opus-5-5", "speed": "fast"}`. Siehe die [unterstützten Modelle](https://platform.claude.com/docs/de/build-with-claude/fast-mode#supported-models) auf der Seite zum Fast Mode.
Um die Effort-Stufe des Modells festzulegen, übergib `model` als Objekt, zum Beispiel: `{"id": "claude-opus-5-5", "effort": "high"}`. Das Feld `effort` akzeptiert einen Stufen-String (`low`, `medium`, `high`, `xhigh` oder `max`) oder ein Objekt wie `{"type": "high"}`. Unter [Effort-Stufen](https://platform.claude.com/docs/de/build-with-claude/effort#effort-levels) erfährst du, was jede Stufe bewirkt.
### Die Inference-Geo festlegen
Wie `speed` (csharp, go: `Speed`) und `effort` (csharp, go: `Effort`) wird `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) über die Objektform von `model` (csharp, go: `Model`) gesetzt: Übergib `model` (csharp, go: `Model`) als Objekt und setze `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) neben `id` (csharp, go: `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](https://platform.claude.com/docs/de/manage-claude/data-residency).
Das folgende Beispiel legt einen Agenten auf US-Inferenz fest und gibt den `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)-Wert aus dem `model` (csharp, go: `Model`)-Objekt des Agenten aus:
```bash cURL
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": "Geo-pinned assistant",
"model": {"id": "claude-opus-5-5", "inference_geo": "us"},
"system": "You are a helpful assistant."
}'
```
```bash CLI
ant apply geo-pinned-assistant.md
```
```markdown
---
name: Geo-pinned assistant
model:
id: claude-opus-5-5
inference_geo: us
---
You are a helpful assistant.
```
```python Python
agent = client.beta.agents.create(
name="Geo-pinned assistant",
model={
"id": "claude-opus-5-5",
"inference_geo": "us",
},
system="You are a helpful assistant.",
)
print(f"Inference geo: {agent.model.inference_geo}")
```
```typescript TypeScript
const agent = await client.beta.agents.create({
name: "Geo-pinned assistant",
model: { id: "claude-opus-5-5", inference_geo: "us" },
system: "You are a helpful assistant.",
});
console.log(`Inference geo: ${agent.model.inference_geo}`);
```
```csharp C#
var agent = await client.Beta.Agents.Create(new()
{
Name = "Geo-pinned assistant",
Model = new BetaManagedAgentsModelConfigParams
{
ID = BetaManagedAgentsModel.ClaudeOpus5_5,
InferenceGeo = "us",
},
System = "You are a helpful assistant.",
});
Console.WriteLine($"Inference geo: {agent.Model.InferenceGeo}");
```
```go Go
agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{
Name: "Geo-pinned assistant",
Model: anthropic.BetaManagedAgentsModelConfigParams{
ID: anthropic.BetaManagedAgentsModelClaudeOpus5_5,
InferenceGeo: anthropic.String("us"),
},
System: anthropic.String("You are a helpful assistant."),
})
if err != nil {
panic(err)
}
fmt.Printf("Inference geo: %s\n", agent.Model.InferenceGeo)
```
```java Java
var agent = client.beta().agents().create(
AgentCreateParams.builder()
.name("Geo-pinned assistant")
.model(
BetaManagedAgentsModelConfigParams.builder()
.id(BetaManagedAgentsModel.CLAUDE_OPUS_5_5)
.inferenceGeo("us")
.build()
)
.system("You are a helpful assistant.")
.build()
);
IO.println("Inference geo: " + agent.model().inferenceGeo().orElseThrow());
```
```php PHP
$agent = $client->beta->agents->create(
name: 'Geo-pinned assistant',
model: BetaManagedAgentsModelConfigParams::with(
id: 'claude-opus-5-5',
inferenceGeo: 'us',
),
system: 'You are a helpful assistant.',
);
echo "Inference geo: {$agent->model->inferenceGeo}\n";
```
```ruby Ruby
agent = client.beta.agents.create(
name: "Geo-pinned assistant",
model: {id: "claude-opus-5-5", inference_geo: "us"},
system_: "You are a helpful assistant."
)
puts "Inference geo: #{agent.model.inference_geo}"
```
Eine `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`)-Festlegung wird gegen die [`allowed_inference_geos`](https://platform.claude.com/docs/de/manage-claude/data-residency#workspace-level-restrictions) 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` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) 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](https://platform.claude.com/docs/de/manage-claude/data-residency#model-availability). In einer `multiagent` (csharp, go: `Multiagent`)-Konfiguration müssen die Festlegung des Agenten und die Festlegung jedes Agenten, der in der `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Liste von `subagents` (csharp, go: `Subagents`) oder `workflows` (csharp, go: `Workflows`) aufgeführt ist, alle auf denselben Wert gesetzt oder alle nicht gesetzt sein; siehe [Multiagenten-Orchestrierung](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration). Um die Festlegung später zu ändern oder zu entfernen, aktualisiere das `model` (csharp, go: `Model`)-Objekt des Agenten; wenn du `model` (csharp, go: `Model`) ohne `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) übergibst, wird sie entfernt, wie unter [Aktualisierungssemantik](https://platform.claude.com/docs/de/managed-agents/agent-setup#update-semantics) beschrieben.
## Einen Agenten aktualisieren
Das Aktualisieren eines Agenten erzeugt eine neue Version, wenn sich die Konfiguration ändert. Das Feld `version` (csharp, go: `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.
```bash cURL
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 '{
"version": '"$AGENT_VERSION"',
"system": "You are a helpful coding agent. Always write tests."
}'
```
```bash CLI
ant apply coding-assistant.md
```
```markdown
---
name: Coding Assistant
model: claude-opus-5-5
tools:
- type: agent_toolset_20260401
---
You are a helpful coding agent. Always write tests.
```
```python Python
updated_agent = client.beta.agents.update(
agent.id,
version=agent.version,
system="You are a helpful coding agent. Always write tests.",
)
print(f"New version: {updated_agent.version}")
```
```typescript TypeScript
const updatedAgent = await client.beta.agents.update(agent.id, {
version: agent.version,
system: "You are a helpful coding agent. Always write tests.",
});
console.log(`New version: ${updatedAgent.version}`);
```
```csharp C#
var updatedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Version = agent.Version,
System = "You are a helpful coding agent. Always write tests.",
});
Console.WriteLine($"New version: {updatedAgent.Version}");
```
```go Go
updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Version: anthropic.Int(agent.Version),
System: anthropic.String("You are a helpful coding agent. Always write tests."),
})
if err != nil {
panic(err)
}
fmt.Printf("New version: %d\n", updatedAgent.Version)
```
```java Java
var updatedAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.version(agent.version())
.system("You are a helpful coding agent. Always write tests.")
.build()
);
IO.println("New version: " + updatedAgent.version());
```
```php PHP
$updatedAgent = $client->beta->agents->update(
$agent->id,
version: $agent->version,
system: 'You are a helpful coding agent. Always write tests.',
);
echo "New version: {$updatedAgent->version}\n";
```
```ruby Ruby
updated_agent = client.beta.agents.update(
agent.id,
version: agent.version,
system_: "You are a helpful coding agent. Always write tests."
)
puts "New version: #{updated_agent.version}"
```
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:
```bash cURL
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."
}'
```
```bash CLI
ant beta:agents update \
--agent-id "$AGENT_ID" \
--description "Writes and reviews code."
```
```python Python
unconditional_agent = client.beta.agents.update(
agent.id,
description="Writes and reviews code.",
)
print(f"New version: {unconditional_agent.version}")
```
```typescript TypeScript
const unconditionalAgent = await client.beta.agents.update(agent.id, {
description: "Writes and reviews code.",
});
console.log(`New version: ${unconditionalAgent.version}`);
```
```csharp C#
var unconditionalAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Description = "Writes and reviews code.",
});
Console.WriteLine($"New version: {unconditionalAgent.Version}");
```
```go Go
unconditionalAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Description: anthropic.String("Writes and reviews code."),
})
if err != nil {
panic(err)
}
fmt.Printf("New version: %d\n", unconditionalAgent.Version)
```
```java Java
var unconditionalAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.description("Writes and reviews code.")
.build()
);
IO.println("New version: " + unconditionalAgent.version());
```
```php PHP
$unconditionalAgent = $client->beta->agents->update(
$agent->id,
description: 'Writes and reviews code.',
);
echo "New version: {$unconditionalAgent->version}\n";
```
```ruby Ruby
unconditional_agent = client.beta.agents.update(
agent.id,
description: "Writes and reviews code."
)
puts "New version: #{unconditional_agent.version}"
```
### Aktualisierungssemantik
* **`version` (csharp, go: `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` (csharp, go: `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` (csharp, go: `Model`), `system` (csharp, go: `System`; ruby: `system_`), `name` (csharp, go: `Name`), `description` (csharp, go: `Description`)) werden durch den neuen Wert ersetzt. `system` (csharp, go: `System`; ruby: `system_`) und `description` (csharp, go: `Description`) können durch Übergabe von `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.Null[string]()`; php: `requestOptions: ['extraBodyParams' => ['system' => null, 'description' => null]]`) geleert werden. `model` (csharp, go: `Model`) und `name` (csharp, go: `Name`) sind Pflichtfelder und können nicht geleert werden. Innerhalb eines von dir übergebenen `model` (csharp, go: `Model`)-Objekts ist `effort` (csharp, go: `Effort`) die einzige Ausnahme: Wenn die Modell-`id` (csharp, go: `ID`) unverändert ist, bleibt die gespeicherte Effort-Stufe beim Weglassen von `effort` (csharp, go: `Effort`) unverändert. Wenn du die Modell-`id` (csharp, go: `ID`) änderst, wird ein weggelassenes `effort` (csharp, go: `Effort`) auf den Standardwert des neuen Modells zurückgesetzt. Andere `model` (csharp, go: `Model`)-Felder werden zusammen mit dem Objekt ersetzt: Wenn du `model` (csharp, go: `Model`) ohne `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) übergibst, wird die Inference-Geo-Festlegung des Agenten entfernt.
* **Array-Felder** (`tools` (csharp, go: `Tools`), `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`), `skills` (csharp, go: `Skills`)) werden vollständig durch das neue Array ersetzt. Um ein Array-Feld vollständig zu leeren, übergib `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `param.NullSlice[[]anthropic.BetaAgentUpdateParamsToolUnion]()`; php: `requestOptions: ['extraBodyParams' => ['mcp_servers' => null]]`) oder ein leeres Array.
* **`multiagent` (csharp, go: `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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Liste, die du sendest, ersetzt die gespeicherte Liste. Jede andere Aktualisierung, die `multiagent` (csharp, go: `Multiagent`) sendet, ersetzt den gespeicherten Block als Ganzes, und die darin weggelassenen Einstellungen erhalten ihre Standardwerte. Übergib `"multiagent": null` (python: `multiagent=None`; typescript: `multiagent: null`; ruby: `multiagent: nil`; go: `Multiagent: param.NullStruct[anthropic.BetaManagedAgentsMultiagentParamsUnion]()`; java: `.multiagent(Optional.empty())`; csharp: `Multiagent = null`; php: `requestOptions: ['extraBodyParams' => ['multiagent' => null]]`), um den gesamten Block zu leeren. Innerhalb des Blocks setzt `null` eine Einstellung auf ihren Standardwert zurück, sodass das Setzen von `workflows` (csharp, go: `Workflows`) auf `null` dynamische Workflows aktiviert. Siehe [Dynamische Workflows aktivieren](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows).
* **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` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Listen anderer Agenten werden nicht aktualisiert.** Agenten, die diesen Agenten in der `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Liste von `subagents` (csharp, go: `Subagents`) oder `workflows` (csharp, go: `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` (csharp, go: `Version`) weglässt. Um an die neue Version zu delegieren, [aktualisiere den Agenten, der ihn aufführt](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#list-the-subagents), sodass die Liste auf die neue Version verweist.
Die folgende Aktualisierung leert die Beschreibung, löscht den Schlüssel `team` aus `metadata` (csharp, go: `Metadata`) und setzt `workflows` (csharp, go: `Workflows`) auf `null`, wodurch dynamische Workflows aktiviert werden:
```bash cURL
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": null,
"metadata": {"team": null},
"multiagent": {"type": "multiagent_20261001", "workflows": null}
}'
```
```bash CLI
ant apply code-reviewer.md
```
```markdown
---
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.
```
Die Datei enthält weder `description` noch den Schlüssel `team`, daher sendet `ant apply` für diese `null`. Das Löschen einer Einstellung innerhalb von `multiagent` behält ihren gespeicherten Wert bei, daher setzt die Datei `workflows` auf `null`.
```python Python
cleared_agent = client.beta.agents.update(
agent.id,
description=None,
metadata={"team": None},
multiagent={"type": "multiagent_20261001", "workflows": None},
)
print(f"Description: {cleared_agent.description}")
```
```typescript TypeScript
const clearedAgent = await client.beta.agents.update(agent.id, {
description: null,
metadata: { team: null },
multiagent: { type: "multiagent_20261001", workflows: null },
});
console.log(`Description: ${clearedAgent.description}`);
```
```csharp C#
var clearedAgent = await client.Beta.Agents.Update(agent.ID, new()
{
Description = null,
Metadata = new Dictionary { ["team"] = null },
Multiagent = new BetaManagedAgentsMultiagent20261001Params { Workflows = null },
});
Console.WriteLine($"Description: {clearedAgent.Description}");
```
```go Go
// Metadata ist eine map[string]string, also sende das null für team als Request-Option.
clearedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{
Description: param.Null[string](),
Multiagent: anthropic.BetaManagedAgentsMultiagentParamsUnion{
OfMultiagent20261001: &anthropic.BetaManagedAgentsMultiagent20261001Params{
Workflows: param.NullStruct[anthropic.BetaManagedAgentsMultiagentWorkflowsParamsUnion](),
},
},
}, option.WithJSONSet("metadata.team", nil))
if err != nil {
panic(err)
}
fmt.Printf("Description: %q\n", clearedAgent.Description)
```
```java Java
var clearedAgent = client.beta().agents().update(
agent.id(),
AgentUpdateParams.builder()
.description(Optional.empty())
.metadata(
AgentUpdateParams.Metadata.builder()
.putAdditionalProperty("team", JsonValue.from(null))
.build()
)
.multiagent(
BetaManagedAgentsMultiagent20261001Params.builder()
.workflows(Optional.empty())
.build()
)
.build()
);
IO.println("Description: " + clearedAgent.description().orElse(null));
```
```php PHP
// update() verwirft null-Argumente, übergib die nulls daher in extraBodyParams.
$clearedAgent = $client->beta->agents->update(
$agent->id,
requestOptions: [
'extraBodyParams' => [
'description' => null,
'metadata' => ['team' => null],
'multiagent' => ['type' => 'multiagent_20261001', 'workflows' => null],
],
],
);
echo 'Description: ' . json_encode($clearedAgent->description) . "\n";
```
```ruby Ruby
cleared_agent = client.beta.agents.update(
agent.id,
description: nil,
metadata: {team: nil},
multiagent: {type: :multiagent_20261001, workflows: nil}
)
puts "Description: #{cleared_agent.description.inspect}"
```
## Lebenszyklus eines Agenten
| Operation | Verhalten |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Aktualisieren** | Erzeugt eine neue Agentenversion, wenn sich die Konfiguration ändert. |
| **Versionen auflisten** | Gibt den vollständigen Versionsverlauf zurück, damit du Änderungen im Zeitverlauf nachverfolgen kannst. |
| **Archivieren** | Macht den Agenten schreibgeschützt. Neue Sessions können ihn nicht referenzieren, aber bestehende Sessions laufen weiter. |
### 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.
```bash cURL
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"
```
```bash CLI
ant beta:agents:versions list --agent-id "$AGENT_ID"
```
```python Python
for version in client.beta.agents.versions.list(agent.id):
print(f"Version {version.version}: {version.updated_at.isoformat()}")
```
```typescript TypeScript
for await (const version of client.beta.agents.versions.list(agent.id)) {
console.log(`Version ${version.version}: ${version.updated_at}`);
}
```
```csharp C#
var versions = await client.Beta.Agents.Versions.List(agent.ID);
await foreach (var version in versions.Paginate())
{
Console.WriteLine($"Version {version.Version}: {version.UpdatedAt:O}");
}
```
```go Go
iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{})
for iter.Next() {
version := iter.Current()
fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339))
}
if err := iter.Err(); err != nil {
panic(err)
}
```
```java Java
for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) {
IO.println("Version " + version.version() + ": " + version.updatedAt());
}
```
```php PHP
foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) {
echo "Version {$version->version}: {$version->updatedAt->format(\DateTimeInterface::ATOM)}\n";
}
```
```ruby Ruby
client.beta.agents.versions.list(agent.id).auto_paging_each do |agent_version|
puts "Version #{agent_version.version}: #{agent_version.updated_at.iso8601}"
end
```
### 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` (java, php: `archivedAt`; csharp, go: `ArchivedAt`) auf den Zeitstempel der Archivierung.
```bash cURL
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"
```
```bash CLI
ant beta:agents archive --agent-id "$AGENT_ID"
```
```python Python
archived = client.beta.agents.archive(agent.id)
print(f"Archived at: {archived.archived_at.isoformat()}")
```
```typescript TypeScript
const archived = await client.beta.agents.archive(agent.id);
console.log(`Archived at: ${archived.archived_at}`);
```
```csharp C#
var archived = await client.Beta.Agents.Archive(agent.ID);
Console.WriteLine($"Archived at: {archived.ArchivedAt:O}");
```
```go Go
archived, err := client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{})
if err != nil {
panic(err)
}
fmt.Printf("Archived at: %s\n", archived.ArchivedAt.Format(time.RFC3339))
```
```java Java
var archived = client.beta().agents().archive(agent.id());
IO.println("Archived at: " + archived.archivedAt().orElseThrow());
```
```php PHP
$archived = $client->beta->agents->archive($agent->id);
echo "Archived at: {$archived->archivedAt->format(\DateTimeInterface::ATOM)}\n";
```
```ruby Ruby
archived = client.beta.agents.archive(agent.id)
puts "Archived at: #{archived.archived_at.iso8601}"
```
## Nächste Schritte
Konfiguriere die Tools, die deinem Agenten zur Verfügung stehen.
Statte deinen Agenten mit wiederverwendbarer, dateisystembasierter Expertise für domänenspezifische Workflows aus.
Erstelle eine Session, um deinen Agenten auszuführen und mit der Bearbeitung von Aufgaben zu beginnen.
Event-Typen, CLI-Flags für selbst gehostete Worker, unterstützte MCP-Servertypen, Ratenlimits und Branding-Richtlinien für Claude Managed Agents.