Definiere deinen Agenten

Ein Agent ist eine wiederverwendbare, versionierte Konfiguration, die Persona und Fähigkeiten definiert. Er bündelt das Modell, den System-Prompt, die 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. Siehe Agentenkonfiguration für eine Session überschreiben.



Einen Agenten erstellen

Das folgende Beispiel definiert einen Coding-Agenten, der Claude Opus 4.8 mit Zugriff auf das vorgefertigte Agenten-Toolset verwendet. Das Toolset ermöglicht es dem Agenten, Code zu schreiben, Dateien zu lesen, das Web zu durchsuchen und mehr. Siehe die Agenten-Tools-Referenz 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 Quickstart die Installation und Client-Einrichtung.

agent=$(ant beta:agents create \
  --name "Coding Assistant" \
  --model '{id: claude-opus-4-8}' \
  --system "You are a helpful coding agent." \
  --tool '{type: agent_toolset_20260401}' \
  --format json)

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

Die Antwort gibt deine Konfiguration zurück und fügt die Felder id, type, version, created_at, updated_at und archived_at hinzu. Die version beginnt bei 1 und wird bei jedem Update, das den Agenten ändert, erhöht.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "name": "Coding Assistant",
  "model": {
    "id": "claude-opus-4-8",
    "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
}

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



Einen Agenten aktualisieren

Das Aktualisieren eines Agenten erzeugt eine neue Version, wenn sich die Konfiguration ändert. Das Feld version ist erforderlich und muss mit der aktuellen Version des Agenten übereinstimmen, sodass du immer von einem bekannten Zustand aus aktualisierst. Eine Versionsabweichung gibt einen 409-Fehler zurück, und Updates an archivierten Agenten werden abgelehnt.

ant beta:agents update \
  --agent-id "$AGENT_ID" \
  --version "$AGENT_VERSION" \
  --system "You are a helpful coding agent. Always write tests."



Update-Semantik

• Ausgelassene 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 Pflichtfelder und können nicht gelöscht werden.

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

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

• Metadaten werden auf Key-Ebene zusammengeführt. Keys, die du angibst, werden hinzugefügt oder aktualisiert. Keys, die du auslässt, bleiben erhalten. Um einen bestimmten Key zu löschen, setze seinen Wert auf null.

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

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



Agenten-Lebenszyklus



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.

ant beta:agents:versions list --agent-id "$AGENT_ID"



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.

ant beta:agents archive --agent-id "$AGENT_ID"



Nächste Schritte