---
title: Workflow-Runs
url: https://platform.claude.com/docs/de/managed-agents/workflow-runs
description: "Verfolge die Workflow-Runs eines Agenten: ihre Zustände und Events, wann die Arbeit erledigt ist, Anfragen, während ein Run offen ist, Budgets und Limits."
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
Ein **Workflow** ist ein Programm, das ein Agent schreibt, um viele Agenten auszuführen und zu kombinieren, was sie zurückgeben. Ein **„workflow run“ (Workflow-Run)** ist die Ausführung eines Workflows. **[„Dynamic workflows“ (dynamische Workflows)](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#dynamic-workflows)** ist die Funktion, mit der ein Agent Workflows schreiben und Runs starten kann. Du schaltest sie mit der Einstellung `workflows` (csharp, go: `Workflows`) im `multiagent` (csharp, go: `Multiagent`)-Block des Agenten ein oder aus.
Der Server führt einen Workflow im Hintergrund aus. Seine Agenten arbeiten in [Session-Threads](https://platform.claude.com/docs/de/managed-agents/session-threads), die der Server erstellt, sobald der Workflow sie benötigt. Du verfolgst Runs im [Event-Stream](https://platform.claude.com/docs/de/managed-agents/events-and-streaming) der Session. Um einen Run zu stoppen, bitte den Agenten, ihn zu stoppen (siehe [Eine Session mit offenen Runs unterbrechen](https://platform.claude.com/docs/de/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)).
## Wie dynamische Workflows funktionieren
Der Agent, den die Session ausführt, schreibt jeden Workflow für die Arbeit, die du beschreibst. Ein Workflow ist ein Programm: Er führt andere Agenten aus, sammelt, was jeder zurückgibt, und kombiniert die Ergebnisse. So kann der Agent eine Aufgabe übernehmen, die für eine einzelne Konversation zu groß ist, etwa die Prüfung von Hunderten von Dokumenten. Während eines Runs kann der Agent weiterarbeiten oder seinen Turn beenden, und er kann den Stand des Runs prüfen.
Das Diagramm zeigt ein Beispiel. Jeder Workflow, den der Agent schreibt, hat seine eigenen Phasen und Agenten. Ein Run hat diese Ebenen:
* **Workflow-Run:** Der Server führt den Workflow im Hintergrund als einen Workflow-Run aus. Eine Session kann mehrere Runs gleichzeitig offen haben.
* **Phasen:** Ein Workflow kann seine Arbeit in Phasen aufteilen. Eine Phase ist ein benannter Abschnitt des Runs, etwa „Read the contracts" (Verträge lesen). Du verfolgst den Fortschritt eines Runs anhand seiner Phasen-Events.
* **Agent-Threads:** In einer Phase führt das Programm Agenten aus. Jeder Agent arbeitet in seinem eigenen [Session-Thread](https://platform.claude.com/docs/de/managed-agents/session-threads), mit einem Prompt, den das Programm geschrieben hat. Ein Agent in einem Run kann ein Inline-Agent sein, den das Programm selbst definiert, oder ein vordefinierter Agent, den du in der [`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Liste von `workflows` (csharp, go: `Workflows`)](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#predefined-and-inline-agents) aufführst. Was jeder Thread zeigt, findest du unter [Die Threads eines Runs](https://platform.claude.com/docs/de/managed-agents/workflow-runs#a-runs-threads).
Das Programm kann Folgendes tun:
* **Agenten gleichzeitig ausführen:** Das Programm kann viele Agenten gleichzeitig ausführen, was als „fanning out" (Auffächern) bezeichnet wird. Im Diagramm lesen drei Agenten in der ersten Phase Verträge.
* **Ergebnisse von einem Agenten an einen anderen weitergeben:** Jeder Agent gibt sein Ergebnis an das Programm zurück. Das Programm kann dieses Ergebnis an einen anderen Agenten weitergeben. Im Diagramm arbeitet der Agent in der zweiten Phase mit dem, was die ersten drei zurückgegeben haben. Die Agenten eines Runs arbeiten außerdem mit denselben Dateien, in der Sandbox der Session.
* **Den nächsten Schritt selbst gehen:** Das Ergebnis eines Agenten geht an das Programm, nicht an den Agenten, den die Session ausführt. Das Programm bestimmt, welche Agenten als Nächstes laufen, und schreibt ihre Prompts.
* **Wiederholen und wählen:** Innerhalb einer Phase kann das Programm Arbeit wiederholen und seinen nächsten Schritt anhand dessen wählen, was ein Agent zurückgegeben hat. Zum Beispiel kann es einen Entwurf überarbeiten lassen, bis er eine Prüfung besteht oder eine festgelegte Anzahl von Runden aufgebraucht ist. Im Diagramm kann das Programm einen Schritt innerhalb der zweiten Phase wiederholen.
* **Einen fehlgeschlagenen Agenten behandeln:** Wenn einer seiner Agenten fehlschlägt, führt der Server diesen Agenten in der Regel noch einmal aus, in einem neuen Thread, während die anderen Agenten des Runs weiterarbeiten. Schlägt er erneut fehl, kann das Programm den Fehler behandeln oder ihn den Run beenden lassen. Wenn das Programm einen Fehler behandelt, kann der Run trotzdem mit `completed` enden, also weise den Agenten, den die Session ausführt, an, zu berichten, was fehlgeschlagen ist.
Wenn der Run endet, bekommt der Agent, den die Session ausführt, einen Turn, um zu lesen, was der Run getan hat. Er kann dir dann antworten oder einen weiteren Run starten. [Run-Events](https://platform.claude.com/docs/de/managed-agents/workflow-runs#run-events) listet die Fälle auf, in denen dieser Turn später oder gar nicht kommt.
Du kannst steuern, wie ein Run die Arbeit erledigt, zum Beispiel wie er die Arbeit aufteilt und was er tut, wenn ein Agent fehlschlägt. Siehe [Dem Agenten mitteilen, wann er einen Run verwenden soll](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run).
Es gibt keinen Genehmigungsschritt, bevor ein Run startet: Der Agent startet einen Run im selben Turn, in dem er den Workflow schreibt. Um zuerst einen Plan zu prüfen, weise den Agenten an, den Run zu beschreiben und auf dein Okay zu warten. Beim Start eines Runs zeigt `workflow_run.created` seinen Namen, seine Beschreibung und seine Phasen. Wenn ein Run startet, den du nicht genehmigt hast, bitte den Agenten, ihn zu stoppen (siehe [Eine Session mit offenen Runs unterbrechen](https://platform.claude.com/docs/de/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)).
## Wie ein Run seine Zustände durchläuft
Ein Run startet als laufend oder als inaktiv. Das Erreichen des Budgets zum Beispiel pausiert einen laufenden Run, wodurch er inaktiv wird; das Erhöhen oder Entfernen des Budgets lässt ihn dann wieder laufen, es sei denn, eine Unterbrechung hat ihn ebenfalls pausiert. Ein laufender Run endet, wenn sein Workflow fertig ist, der Agent ihn stoppt, er fehlschlägt, seine Lebensdauer abläuft oder die Session archiviert wird. Auch ein inaktiver Run kann enden, zum Beispiel wenn der Agent ihn stoppt oder die Session archiviert wird.
Ein Run ist **offen** von seinem `workflow_run.created`-Event bis zu seinem `workflow_run.status_ended`-Event, egal ob er läuft oder inaktiv ist. Ein Run ist inaktiv, während er pausiert ist, zum Beispiel beim Budget der Session. Ein Run hat eine [Lebensdauer](https://platform.claude.com/docs/de/managed-agents/workflow-runs#limits), die der Agent beim Start des Runs festlegen kann. Zeit, die ein Run mit Warten auf deinen Client verbringt, zählt zu dieser Lebensdauer. Eine Pause hält die Lebensdauer eines Runs nicht an, sodass ein Run, der pausiert bleibt, mit `timeout_error` enden kann. Die folgenden Events melden den Start eines Runs, seine Phasen und sein Ende. Eine Pause beim Budget sendet ebenfalls eines. Eine Pause nach einer Unterbrechung sendet möglicherweise keines. Jedes `workflow_run.*`-Event enthält `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), das nur bei einem `workflow_run.error`, wenn kein Run erstellt wurde, `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) ist.
## Run-Events
Run-Events kommen im Event-Stream der Session an, also im Stream des primären Threads, und auch das Auflisten der Events der Session gibt sie zurück. Run-Events lösen keine [Webhooks](https://platform.claude.com/docs/de/managed-agents/webhooks) aus. Status-Events der Threads des Runs kommen im selben Stream an. Jedes nennt seinen Thread in `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`), und die Threads eines Runs sind diejenigen, deren `session.thread_created`-Event die `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) des Runs hatte.
| Event | Wann es ankommt | Was zu tun ist |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_run.created` | Der Agent hat einen Run gestartet. Enthält `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) (`wrun_…`), `name` (csharp, go: `Name`) und `description` (csharp, go: `Description`) des Runs sowie `phases` (csharp, go: `Phases`), die Phasen, die der Workflow deklariert, jeweils mit einer `id` (csharp, go: `ID`), einem `name` (csharp, go: `Name`) und einer `description` (csharp, go: `Description`). Eine `description` (csharp, go: `Description`) ist `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`), wenn der Workflow keine angibt. `phases` (csharp, go: `Phases`) ist immer vorhanden und kann leer sein. `name` (csharp, go: `Name`) und `description` (csharp, go: `Description`) des Runs und der Phasen sind Text, den das Modell geschrieben hat, daher können sie Wörter aus deiner Anfrage wiederholen. Der `name` (csharp, go: `Name`) eines Runs kann auch einer sein, den der Server vergeben hat. | Verfolge den Run als offen. Zeige seinen `name` (csharp, go: `Name`) und den Fortschritt anhand von `phases` (csharp, go: `Phases`) an. |
| `workflow_run.status_running` | Wenn der Run mit der Ausführung beginnt, was eine Weile nach `created` sein kann, und jedes Mal, wenn er nach einer Pause beim Budget fortgesetzt wird. Eine Fortsetzung nach einer Unterbrechung sendet es möglicherweise nicht. Ein Run, der inaktiv startet, bekommt möglicherweise zuerst `workflow_run.status_idle`. | Zeige den Run als laufend an. |
| `workflow_run.status_idle` | Der Run wurde pausiert, zum Beispiel beim Budget der Session. Das Event sagt nicht, warum. Eine Pause nach einer Unterbrechung sendet es möglicherweise nicht. | Um fortzufahren, siehe [Kosten und Budgets](https://platform.claude.com/docs/de/managed-agents/workflow-runs#cost-and-budgets) oder [Eine Session mit offenen Runs unterbrechen](https://platform.claude.com/docs/de/managed-agents/workflow-runs#interrupt-a-session-with-runs-open). |
| `workflow_run.phase_started`, `workflow_run.phase_ended` | Der Workflow hat eine Phase betreten oder verlassen, oder das Ende des Runs hat eine Phase geschlossen, die noch offen war. Das End-Event sagt nicht, ob die Arbeit der Phase abgeschlossen wurde. Beide enthalten `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`). Das Ende hat außerdem `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`), die `id` (csharp, go: `ID`) des Start-Events, das es schließt. Keines hat den Namen der Phase: Schlage ihn anhand von `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`) in den `phases` (csharp, go: `Phases`) von `workflow_run.created` nach. | Aktualisiere den Fortschritt. Phasen laufen nacheinander, in der Reihenfolge von `phases` (csharp, go: `Phases`), jede höchstens einmal, aber die API garantiert das nicht. Ordne das Ende einer Phase ihrem Start anhand von `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`) zu. Behandle mehr als eine offene Phase, eine Phase, die nicht in `phases` (csharp, go: `Phases`) steht, und eine aufgeführte Phase, die nie startet, selbst in einem Run, der abgeschlossen wird. Jede Phase, die startet, endet auch, und zwar vor dem `workflow_run.status_ended` des Runs. |
| `workflow_run.status_ended` | Der Run ist beendet. Immer das letzte der `workflow_run.*`-Events des Runs. Enthält `result` (csharp, go: `Result`). | Lies `result` (csharp, go: `Result`) (nächste Tabelle). Der Agent erhält dann einen Turn, um zu lesen, wie der Run geendet hat. Beim Budget oder während der primäre Thread auf deinen Client wartet, kommt dieser Turn später. Nach einer Unterbrechung kommt dieser Turn möglicherweise nicht: Sende eine `user.message` oder lies `result` (csharp, go: `Result`) selbst. Nach einer Archivierung oder Beendigung kommt er nicht. |
| `workflow_run.error` | Der Server meldet einen Fehler eines Runs oder einen Start, den er abgelehnt hat. Ein Run, der mit `error` endet, erhält dieses Event mit demselben Fehler vor seinem `workflow_run.status_ended`. Enthält `error` (csharp, go: `Error`): einen `type` (csharp, go: `Type`) und eine `message` (csharp, go: `Message`), die sicher protokolliert werden kann. `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) ist `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`), wenn kein Run erstellt wurde. | Protokolliere es und betrachte es nicht als Ende des Runs. Wenn `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) ist, wurde kein Run gestartet. Andernfalls verfolge den Run weiter bis zu seinem `workflow_run.status_ended`. |
| `result` | Bedeutung |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{"type": "completed"}` | Der Workflow wurde vollständig ausgeführt. Das Ergebnis sagt nicht, ob die Arbeit erfolgreich war. Ein Run kann mit `completed` enden, obwohl Arbeit in seinen Threads fehlgeschlagen ist oder ein Thread nicht erstellt werden konnte. Um fehlgeschlagene Arbeit zu finden, lies die Events jedes der [Threads des Runs](https://platform.claude.com/docs/de/managed-agents/workflow-runs#a-runs-threads). |
| `{"type": "stopped"}` | Der Agent hat den Run gestoppt, oder die Session wurde archiviert. Das Event sagt nicht, was davon zutrifft. Betrachte diese nicht als die einzigen Ursachen. |
| `error` mit `timeout_error` | Der Run hat seine [Lebensdauer](https://platform.claude.com/docs/de/managed-agents/workflow-runs#limits) erreicht, die der Agent festlegen kann. |
| `error` mit `program_error` | Der Workflow ist fehlgeschlagen. Sein Code ist fehlgeschlagen, oder er hat eine Regel für Workflows verletzt, die kein Limit ist. Oder einer der Threads des Runs ist fehlgeschlagen oder konnte nicht erstellt werden, und der Workflow hat dadurch den Run enden lassen. |
| `error` mit `thread_limit_error` | Der Run hat sein [Limit für die Agenten, die ein Workflow startet](https://platform.claude.com/docs/de/managed-agents/workflow-runs#limits), überschritten. |
| `error` mit `unknown_error` | Der Server konnte den Run nicht fortsetzen, oder der Run hat eines der anderen Limits des Servers für Workflows überschritten. |
Ein Fehlerergebnis sieht so aus: `{"type": "error", "error": {"type": "timeout_error", "message": "..."}}`, wobei `message` sicher protokolliert werden kann. Behandle einen unbekannten `result.type` als Run, der auf andere Weise geendet hat, und einen unbekannten `error.type` als Fehler. Wenn etwas fehlschlägt, von dem die Session abhängt, etwa das Modell, ein MCP-Server, Anmeldedaten oder die Abrechnung, bekommt der Stream des fehlschlagenden Threads einen `session.error`. Das beendet einen Run nicht von selbst. Wenn es aber einen der Threads des Runs fehlschlagen lässt und der Workflow dadurch den Run enden lässt, endet der Run mit `program_error`.
Zum Beispiel fragst du den [Vertragsprüfungs-Agenten](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows), welche von 300 Verträgen eine Change-of-Control-Klausel enthalten, und der Agent startet einen Run:
1. `workflow_run.created` benennt den Run „Find change-of-control clauses“ und listet die Phasen „Read the contracts“ und „Reconcile the findings“ in `phases` (csharp, go: `Phases`) auf. Dann folgt `workflow_run.status_running`.
2. Phasen-Events markieren jede Phase, und jeder Thread, den der Run erstellt, sendet `session.thread_created` mit der `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) des Runs.
3. `workflow_run.status_ended` kommt mit `result: {"type": "completed"}` an.
4. Der Agent antwortet: „41 der 300 Verträge enthalten eine", und `session.status_idle` kommt mit `end_turn` an.
Das erste Event des Runs listet seine Phasen auf:
```json
{
"type": "workflow_run.created",
"id": "sevt_01abc...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"name": "Find change-of-control clauses",
"description": "Reads each contract and lists those that have the clause.",
"phases": [
{
"id": "wrph_01Kd3a1f3",
"name": "Read the contracts",
"description": "Reads each contract for the clause."
},
{ "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
],
"processed_at": "2026-10-09T14:01:45Z"
}
```
Jedes Phasen-Event nennt seine Phase über `workflow_run_phase_id`. Das ist eine `id` in `phases`, aber die API garantiert das nicht:
```json
{
"type": "workflow_run.phase_started",
"id": "sevt_01def...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"workflow_run_phase_id": "wrph_01Kd3a1f3",
"processed_at": "2026-10-09T14:01:46Z"
}
```
Das letzte Event des Runs meldet, wie er geendet hat:
```json
{
"type": "workflow_run.status_ended",
"id": "sevt_01ghi...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"result": { "type": "completed" },
"processed_at": "2026-10-09T14:09:12Z"
}
```
## Die Threads eines Runs
Jeder Agent in einem Run arbeitet in seinem eigenen [Session-Thread](https://platform.claude.com/docs/de/managed-agents/session-threads), den der Server erstellt, sobald der Workflow ihn benötigt. Du kannst die Threads eines Runs wie jeden Kind-Thread auflisten, lesen und streamen und ihre „tool calls“ (Tool-Aufrufe) aus dem primären Stream beantworten. Um sie zu stoppen, bitte den Agenten, den Run zu stoppen (siehe [Eine Session mit offenen Runs unterbrechen](https://platform.claude.com/docs/de/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)).
* **Gruppierung:** Ein Thread eines Runs hat die `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) des Runs, ebenso wie das `session.thread_created`-Event, das ihn ankündigt. Bei anderen Threads und den `session.thread_created`-Events, die sie ankündigen, ist `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) auf `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) gesetzt.
* **Agent:** `agent` (csharp, go: `Agent`) zeigt den Agenten, den der Thread ausführt. Für einen Agenten, den du in der [`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`)-Liste von `workflows` (csharp, go: `Workflows`)](https://platform.claude.com/docs/de/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) in `multiagent` (csharp, go: `Multiagent`) aufgeführt hast, hat `agent` (csharp, go: `Agent`) die `id` (csharp, go: `ID`) und `version` (csharp, go: `Version`) dieses Agenten, wie beim Thread eines Subagenten, den du aufgeführt hast. Für einen Agenten, den der Workflow definiert (einen Inline-Agenten), hat `agent` (csharp, go: `Agent`) den `type` `inline` und keine `id` (csharp, go: `ID`) oder `version` (csharp, go: `Version`). Er hat den „system prompt“ (System-Prompt), den der Workflow geschrieben hat, nicht den des Session-Agenten. Er hat außerdem den Namen und die Beschreibung, die der Workflow ihm gegeben hat. Der Server vergibt einen Namen, wenn der Workflow keinen angegeben hat. Er verwendet das Modell des Session-Agenten, also des Agenten, den die Session ausführt. Seine Tools, MCP-Server und Skills sind eine Teilmenge derjenigen des Session-Agenten. Er erhält alle davon, aber die API garantiert das nicht. Seine Tools behalten ihre Berechtigungsrichtlinien.
* **Was die Threads teilen:** Die Threads eines Runs arbeiten in der Sandbox der Session, sodass jeder Thread mit denselben Dateien arbeitet. Dazu gehören die Dateien eines Memory Stores, den die Session einbindet. Ein Agent, den der Workflow definiert, verwendet seine MCP-Server mit den Anmeldedaten, die die Session für sie auflöst. Jeder Thread hat seinen eigenen Gesprächsverlauf.
* **Events:** Die Events `session.thread_created`, `session.thread_status_running`, `session.thread_status_idle` und `session.thread_status_terminated` eines Run-Threads kommen auch im primären Stream an (siehe [Run-Events](https://platform.claude.com/docs/de/managed-agents/workflow-runs#run-events)). Seine Nachrichten-Events bleiben in seinem eigenen Stream. Seine Thread-Webhooks werden wie bei jedem Kind-Thread gesendet. Was der eigene Stream des Threads aufzeichnet, erfährst du unter [Session-Thread-Events](https://platform.claude.com/docs/de/managed-agents/session-threads#session-thread-events).
* **Phasen:** Kein Event und kein Feld gibt an, in welcher Phase ein Thread arbeitet, und Threads eines Runs können denselben `agent_name` haben. Verfolge den Fortschritt eines Runs anhand seiner Phasen-Events und unterscheide seine Threads anhand von `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`).
* **Archivierung:** Der Server archiviert jeden Thread spätestens am Ende seines Runs. Er kann einen Thread früher archivieren, sobald der Thread sein Ergebnis zurückgibt oder der Run mit ihm fertig ist. Wenn der Thread zu diesem Zeitpunkt noch läuft oder auf deinen Client wartet, stoppt der Server ihn zuerst. Ein archivierter Thread bleibt in der Thread-Liste, mit dem Status `terminated`. Du musst die Threads eines Runs nicht selbst archivieren.
* **Tools:** Ein Run kann mehr als einen Thread für dasselbe Arbeitspaket erstellen, also sorge dafür, dass die Tools, die deine Agenten aufrufen, gefahrlos zweimal aufgerufen werden können.
Du kannst den Agenten nach dem Workflow fragen, den er für deine Anfrage geschrieben hat. Warte, bis der Run beendet ist und die Session `idle` ist. Sende dann eine `user.message`, die den Agenten bittet, den Workflow, mit dem er den Run gestartet hat, Wort für Wort auszugeben und keinen weiteren Run zu starten.
```text wrap
Print the workflow that you started the run with, word for word, in one code block. Do not start another run.
```
## Erkennen, wann die Arbeit erledigt ist
Während ein Run läuft, erwarte, dass die Session `running` bleibt, selbst wenn keiner ihrer Threads arbeitet. Sie wechselt zu `idle` mit `requires_action`, wenn kein Thread arbeitet und ein Thread auf deinen Client wartet. Ein Idle allein bedeutet nicht, dass die Arbeit erledigt ist. Die Arbeit ist erledigt, wenn beides zutrifft:
1. Jeder Run, dessen Erstellung du gesehen hast, hat sein `workflow_run.status_ended`.
2. Danach kommt ein `session.status_idle` mit `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`) `end_turn` an, und deine eigene Anfrage, etwa eine Unterbrechung, hat es nicht verursacht. Nachdem du unterbrochen hast, zähle nur ein Idle, das nach deiner nächsten `user.message` oder `user.define_outcome` kommt.
* **Pausierte Runs:** Ein pausierter Run hält die Session nicht auf `running`, sodass die Session inaktiv werden kann, während der Run noch offen ist. Beim Budget zum Beispiel wird die Session mit `budget_reached` inaktiv. Die Arbeit ist erst erledigt, wenn der Run endet.
* **Ein weiterer Run:** Der Agent kann einen neuen Run starten, wenn er ein Ergebnis liest, also prüfe erneut.
* **Outcomes:** Wenn du ein [Outcome definiert hast](https://platform.claude.com/docs/de/managed-agents/define-outcomes), startet keine Auswertung, während ein Run offen ist, egal ob er läuft oder inaktiv ist. Der Turn, in dem der Agent das Ergebnis des Runs liest, kann eine starten.
* **`retries_exhausted`:** Der Turn des Agenten ist an einem Fehler gescheitert: Die Wiederholungsversuche sind aufgebraucht, oder bei dem Fehler ist kein erneuter Versuch möglich, etwa bei einem Abrechnungsfehler. Ein Run läuft möglicherweise noch, wenn dieses Idle kommt. Wenn ein Run beendet ist und der Agent sein Ergebnis noch nicht gelesen hat, startet der Server einen neuen Turn ohne Eingabe von dir. Die Session wechselt wieder zu `running`, also warte auf das nächste Idle. Wenn die Session inaktiv bleibt, lies den `session.error`, der davor kam, und behebe die Ursache. Sende dann eine `user.message` oder lies das `result` (csharp, go: `Result`) jedes Runs selbst.
## Einen Run verfolgen
Dieses Beispiel verfolgt eine Session von deiner Nachricht bis zur Antwort des Agenten. Es öffnet den Stream und sendet die Nachricht. Dann tut es Folgendes:
* **Verfolgt jeden Run** von seinem `workflow_run.created` bis zu seinem `workflow_run.status_ended` und gibt jede Phase aus, sobald sie startet.
* **Beantwortet benutzerdefinierte Tool-Aufrufe**, wenn jedes `agent.custom_tool_use` ankommt, weil ein Thread eines Runs auf deinen Client warten kann, während die Session `running` bleibt. Wenn die Tools deines Agenten [um Bestätigung bitten](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#tool-confirmation), füge einen Zweig hinzu, der jedes `agent.tool_use` oder `agent.mcp_tool_use` beantwortet, dessen `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) `ask` ist. Das Beispiel hat keinen, weil ein Zweig, der jeden Aufruf erlaubt, `always_ask` in „immer erlauben“ verwandeln würde.
* **Stoppt**, wenn die [Arbeit erledigt ist](https://platform.claude.com/docs/de/managed-agents/workflow-runs#know-when-the-work-is-done): Kein Run ist offen, und die Session wird mit `end_turn` inaktiv. Es stoppt auch, wenn die Session beendet wird. Bei einem Idle mit einem anderen Stop-Grund außer `requires_action`, etwa `budget_reached`, `retries_exhausted` oder `refusal`, gibt es den Grund aus und stoppt, also behandle diese in deinem eigenen Code. Es stoppt bei `retries_exhausted` selbst dann, wenn der Server gleich von selbst einen neuen Turn starten wird. Es wartet weiter bei `requires_action` und bei `end_turn`, während ein Run offen ist.
Dieser Workflow erfordert mehr Logik als ein einzelner Shell-Befehl. Verwende das [Claude SDK](https://platform.claude.com/docs/de/cli-sdks-libraries/overview), um ihn auszuführen.
Dieser Workflow erfordert mehr Logik als ein einzelner Shell-Befehl. Verwende das [Claude SDK](https://platform.claude.com/docs/de/cli-sdks-libraries/overview), um ihn auszuführen.
```python Python
open_runs: dict[str, str] = {} # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {} # (run ID, phase ID) -> phase name
# Öffne zuerst den Stream und sende dann die Benutzernachricht
with client.beta.sessions.events.stream(session_id) as stream:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Which contracts in /contracts have a change-of-control clause?",
},
],
},
],
)
for event in stream:
match event.type:
case "workflow_run.created":
open_runs[event.workflow_run_id] = event.name
for phase in event.phases:
phase_names[event.workflow_run_id, phase.id] = phase.name
print(f"Run started: {event.name}")
case "workflow_run.phase_started":
phase_id = event.workflow_run_phase_id
key = (event.workflow_run_id, phase_id)
print(f" Phase: {phase_names.get(key, phase_id)}")
case "workflow_run.status_ended":
name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
print(f"Run ended: {name} ({event.result.type})")
case "agent.custom_tool_use":
# Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
# Client warten, während die Session weiterläuft.
result = call_tool(event.name, event.input)
try:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.custom_tool_result",
"custom_tool_use_id": event.id,
"content": [{"type": "text", "text": result}],
},
],
)
except anthropic.BadRequestError as error:
# Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
# den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
print(f" Answer to {event.name} refused: {error.message}")
case "session.status_idle":
# Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
if not open_runs and event.stop_reason.type == "end_turn":
break
# Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
# Bei jedem anderen Stop-Grund gib ihn aus und brich ab.
if event.stop_reason.type not in ("end_turn", "requires_action"):
print(f"Session idle: {event.stop_reason.type}")
break
case "session.status_terminated":
break
```
```typescript TypeScript
const openRuns = new Map(); // workflow_run_id -> run name
const phaseNames = new Map(); // "run ID:phase ID" -> phase name
// Öffne zuerst den Stream und sende dann die Benutzernachricht
const stream = await client.beta.sessions.events.stream(sessionId);
await client.beta.sessions.events.send(sessionId, {
events: [
{
type: "user.message",
content: [
{
type: "text",
text: "Which contracts in /contracts have a change-of-control clause?"
}
]
}
]
});
events: for await (const event of stream) {
switch (event.type) {
case "workflow_run.created":
openRuns.set(event.workflow_run_id, event.name);
for (const phase of event.phases) {
phaseNames.set(`${event.workflow_run_id}:${phase.id}`, phase.name);
}
console.log(`Run started: ${event.name}`);
break;
case "workflow_run.phase_started": {
const phaseId = event.workflow_run_phase_id;
const phaseName = phaseNames.get(`${event.workflow_run_id}:${phaseId}`);
console.log(` Phase: ${phaseName ?? phaseId}`);
break;
}
case "workflow_run.status_ended": {
const name = openRuns.get(event.workflow_run_id) ?? event.workflow_run_id;
openRuns.delete(event.workflow_run_id);
console.log(`Run ended: ${name} (${event.result.type})`);
break;
}
case "agent.custom_tool_use": {
// Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
// Client warten, während die Session weiterläuft.
const result = await callTool(event.name, event.input);
try {
await client.beta.sessions.events.send(sessionId, {
events: [
{
type: "user.custom_tool_result",
custom_tool_use_id: event.id,
content: [{ type: "text", text: result }]
}
]
});
} catch (error) {
// Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
// den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
if (!(error instanceof Anthropic.BadRequestError)) {
throw error;
}
console.log(` Answer to ${event.name} refused: ${error.message}`);
}
break;
}
case "session.status_idle": {
// Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
const reason = event.stop_reason.type;
if (openRuns.size === 0 && reason === "end_turn") {
break events;
}
// Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
// Bei jedem anderen Stop-Grund gib ihn aus und beende.
if (reason !== "end_turn" && reason !== "requires_action") {
console.log(`Session idle: ${reason}`);
break events;
}
break;
}
case "session.status_terminated":
break events;
}
}
```
```csharp C#
var openRuns = new Dictionary(); // workflow_run_id -> run name
var phaseNames = new Dictionary<(string, string), string>(); // (run ID, phase ID) -> phase name
// Öffne zuerst den Stream und sende dann die Nutzernachricht. Der Raw-Response-Aufruf
// öffnet den Stream sofort. Der einfache Aufruf würde auf den ersten Lesevorgang warten.
using var stream = await client.Beta.Sessions.Events.WithRawResponse.StreamStreaming(sessionId);
await client.Beta.Sessions.Events.Send(sessionId, new()
{
Events =
[
new BetaManagedAgentsUserMessageEventParams
{
Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
Content =
[
new BetaManagedAgentsTextBlock
{
Type = BetaManagedAgentsTextBlockType.Text,
Text = "Which contracts in /contracts have a change-of-control clause?",
},
],
},
],
});
await foreach (var streamEvent in stream.Enumerate())
{
if (streamEvent.Value is BetaManagedAgentsWorkflowRunCreatedEvent created)
{
openRuns[created.WorkflowRunID] = created.Name;
foreach (var listed in created.Phases)
{
phaseNames[(created.WorkflowRunID, listed.ID)] = listed.Name;
}
Console.WriteLine($"Run started: {created.Name}");
}
else if (streamEvent.Value is BetaManagedAgentsWorkflowRunPhaseStartedEvent phase)
{
var phaseId = phase.WorkflowRunPhaseID;
var key = (phase.WorkflowRunID, phaseId);
Console.WriteLine($" Phase: {phaseNames.GetValueOrDefault(key, phaseId)}");
}
else if (streamEvent.Value is BetaManagedAgentsWorkflowRunStatusEndedEvent ended)
{
var name = openRuns.GetValueOrDefault(ended.WorkflowRunID, ended.WorkflowRunID);
openRuns.Remove(ended.WorkflowRunID);
var outcome = ended.Result.Value switch
{
BetaManagedAgentsWorkflowRunResultCompleted => "completed",
BetaManagedAgentsWorkflowRunResultStopped => "stopped",
BetaManagedAgentsWorkflowRunResultError => "error",
_ => "ended",
};
Console.WriteLine($"Run ended: {name} ({outcome})");
}
else if (streamEvent.Value is BetaManagedAgentsAgentCustomToolUseEvent toolUse)
{
// Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
// Client warten, während die Session weiterläuft.
var result = await CallTool(toolUse.Name, toolUse.Input);
try
{
await client.Beta.Sessions.Events.Send(sessionId, new()
{
Events =
[
new BetaManagedAgentsUserCustomToolResultEventParams
{
Type = BetaManagedAgentsUserCustomToolResultEventParamsType.UserCustomToolResult,
CustomToolUseID = toolUse.ID,
Content =
[
new BetaManagedAgentsTextBlock
{
Type = BetaManagedAgentsTextBlockType.Text,
Text = result,
},
],
},
],
});
}
catch (AnthropicBadRequestException error)
{
// Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
// den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
Console.WriteLine($" Answer to {toolUse.Name} refused: {error.Message}");
}
}
else if (streamEvent.Value is BetaManagedAgentsSessionStatusIdleEvent idle)
{
// Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
var finished = idle.StopReason?.Value is BetaManagedAgentsSessionEndTurn;
if (openRuns.Count == 0 && finished)
{
break;
}
// Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
// Bei jedem anderen Stop-Grund gib ihn aus und brich ab.
if (!finished && idle.StopReason?.Value is not BetaManagedAgentsSessionRequiresAction)
{
var reason = idle.StopReason?.Json.GetProperty("type").GetString();
Console.WriteLine($"Session idle: {reason}");
break;
}
}
else if (streamEvent.Value is BetaManagedAgentsSessionStatusTerminatedEvent)
{
break;
}
}
```
```go Go
openRuns := map[string]string{} // workflow_run_id -> run name
phaseNames := map[[2]string]string{} // {run ID, phase ID} -> phase name
// Öffne zuerst den Stream und sende dann die Benutzernachricht
stream := client.Beta.Sessions.Events.StreamEvents(ctx, sessionID, anthropic.BetaSessionEventStreamParams{})
defer stream.Close()
if _, err := client.Beta.Sessions.Events.Send(ctx, sessionID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: "Which contracts in /contracts have a change-of-control clause?",
},
}},
},
}},
}); err != nil {
panic(err)
}
events:
for stream.Next() {
switch event := stream.Current().AsAny().(type) {
case anthropic.BetaManagedAgentsWorkflowRunCreatedEvent:
openRuns[event.WorkflowRunID] = event.Name
for _, phase := range event.Phases {
phaseNames[[2]string{event.WorkflowRunID, phase.ID}] = phase.Name
}
fmt.Printf("Run started: %s\n", event.Name)
case anthropic.BetaManagedAgentsWorkflowRunPhaseStartedEvent:
phaseName, ok := phaseNames[[2]string{event.WorkflowRunID, event.WorkflowRunPhaseID}]
if !ok {
phaseName = event.WorkflowRunPhaseID
}
fmt.Printf(" Phase: %s\n", phaseName)
case anthropic.BetaManagedAgentsWorkflowRunStatusEndedEvent:
name, ok := openRuns[event.WorkflowRunID]
if !ok {
name = event.WorkflowRunID
}
delete(openRuns, event.WorkflowRunID)
fmt.Printf("Run ended: %s (%s)\n", name, event.Result.Type)
case anthropic.BetaManagedAgentsAgentCustomToolUseEvent:
// Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
// Client warten, während die Session weiterläuft.
result := callTool(event.Name, event.Input)
if _, err := client.Beta.Sessions.Events.Send(ctx, sessionID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserCustomToolResult: &anthropic.BetaManagedAgentsUserCustomToolResultEventParams{
Type: anthropic.BetaManagedAgentsUserCustomToolResultEventParamsTypeUserCustomToolResult,
CustomToolUseID: event.ID,
Content: []anthropic.BetaManagedAgentsUserCustomToolResultEventParamsContentUnion{{
OfText: &anthropic.BetaManagedAgentsTextBlockParam{
Type: anthropic.BetaManagedAgentsTextBlockTypeText,
Text: result,
},
}},
},
}},
}); err != nil {
// Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
// den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
var apiErr *anthropic.Error
if !errors.As(err, &apiErr) || apiErr.StatusCode != http.StatusBadRequest {
panic(err)
}
fmt.Printf(" Answer to %s refused: %v\n", event.Name, err)
}
case anthropic.BetaManagedAgentsSessionStatusIdleEvent:
// Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
switch event.StopReason.AsAny().(type) {
case anthropic.BetaManagedAgentsSessionEndTurn:
if len(openRuns) == 0 {
break events
}
// Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
// Bei jedem anderen Stop-Grund gib ihn aus und brich ab.
case anthropic.BetaManagedAgentsSessionRequiresAction:
default:
fmt.Printf("Session idle: %s\n", event.StopReason.Type)
break events
}
case anthropic.BetaManagedAgentsSessionStatusTerminatedEvent:
break events
}
}
if err := stream.Err(); err != nil {
panic(err)
}
```
```java Java
var openRuns = new HashMap(); // workflow_run_id -> run name
var phaseNames = new HashMap(); // "run ID:phase ID" -> phase name
// Öffne zuerst den Stream und sende dann die Benutzernachricht
try (var stream = client.beta().sessions().events().streamStreaming(sessionId)) {
client.beta().sessions().events().send(
sessionId,
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserMessageEventParams.builder()
.type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
.addTextContent("Which contracts in /contracts have a change-of-control clause?")
.build())
.build()
);
Iterable events = stream.stream()::iterator;
events:
for (var event : events) {
switch (event.type().value()) {
case WORKFLOW_RUN_CREATED -> {
var created = event.asWorkflowRunCreated();
openRuns.put(created.workflowRunId(), created.name());
created.phases().forEach(phase ->
phaseNames.put(created.workflowRunId() + ":" + phase.id(), phase.name()));
IO.println("Run started: " + created.name());
}
case WORKFLOW_RUN_PHASE_STARTED -> {
var started = event.asWorkflowRunPhaseStarted();
var phaseId = started.workflowRunPhaseId();
var key = started.workflowRunId() + ":" + phaseId;
IO.println(" Phase: " + phaseNames.getOrDefault(key, phaseId));
}
case WORKFLOW_RUN_STATUS_ENDED -> {
var ended = event.asWorkflowRunStatusEnded();
var name = openRuns.getOrDefault(ended.workflowRunId(), ended.workflowRunId());
openRuns.remove(ended.workflowRunId());
var result = ended.result();
var outcome = result.isCompleted() ? "completed"
: result.isStopped() ? "stopped"
: result.isError() ? "error"
: "ended";
IO.println("Run ended: " + name + " (" + outcome + ")");
}
case AGENT_CUSTOM_TOOL_USE -> {
// Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
// Client warten, während die Session weiterläuft.
var toolUse = event.asAgentCustomToolUse();
var result = callTool(toolUse.name(), toolUse.input());
try {
client.beta().sessions().events().send(
sessionId,
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserCustomToolResultEventParams.builder()
.type(BetaManagedAgentsUserCustomToolResultEventParams.Type.USER_CUSTOM_TOOL_RESULT)
.customToolUseId(toolUse.id())
.addTextContent(result)
.build())
.build());
} catch (BadRequestException e) {
// Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
// den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
IO.println(" Answer to " + toolUse.name() + " refused: " + e.getMessage());
}
}
case SESSION_STATUS_IDLE -> {
// Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
var stopReason = event.asSessionStatusIdle().stopReason();
if (openRuns.isEmpty() && stopReason.isEndTurn()) {
break events;
}
// Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
// Bei jedem anderen Stop-Grund gib ihn aus und brich ab.
if (!stopReason.isEndTurn() && !stopReason.isRequiresAction()) {
IO.println("Session idle: " + stopReason.type().asString());
break events;
}
}
case SESSION_STATUS_TERMINATED -> {
break events;
}
default -> {}
}
}
}
```
```php PHP
$openRuns = []; // workflow_run_id => run name
$phaseNames = []; // run ID => [phase ID => phase name]
// Öffne zuerst den Stream und sende dann die Benutzernachricht
$stream = $client->beta->sessions->events->streamStream($sessionId);
$client->beta->sessions->events->send(
$sessionId,
events: [
[
'type' => 'user.message',
'content' => [
['type' => 'text', 'text' => 'Which contracts in /contracts have a change-of-control clause?'],
],
],
],
);
foreach ($stream as $event) {
switch (true) {
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsWorkflowRunCreatedEvent:
$openRuns[$event->workflowRunID] = $event->name;
foreach ($event->phases as $phase) {
$phaseNames[$event->workflowRunID][$phase->id] = $phase->name;
}
echo "Run started: {$event->name}", PHP_EOL;
break;
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsWorkflowRunPhaseStartedEvent:
$phaseId = $event->workflowRunPhaseID;
echo ' Phase: ', $phaseNames[$event->workflowRunID][$phaseId] ?? $phaseId, PHP_EOL;
break;
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsWorkflowRunStatusEndedEvent:
$name = $openRuns[$event->workflowRunID] ?? $event->workflowRunID;
unset($openRuns[$event->workflowRunID]);
echo "Run ended: {$name} ({$event->result->type})", PHP_EOL;
break;
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsAgentCustomToolUseEvent:
// Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
// Client warten, während die Session weiterläuft.
$result = callTool($event->name, $event->input);
try {
$client->beta->sessions->events->send(
$sessionId,
events: [
[
'type' => 'user.custom_tool_result',
'custom_tool_use_id' => $event->id,
'content' => [['type' => 'text', 'text' => $result]],
],
],
);
} catch (\Anthropic\Core\Exceptions\BadRequestException $error) {
// Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
// den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
echo " Answer to {$event->name} refused: {$error->getMessage()}", PHP_EOL;
}
break;
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusIdleEvent:
// Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
$finished = $event->stopReason->type === 'end_turn';
if (!$openRuns && $finished) {
break 2;
}
// Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
// Bei jedem anderen Stop-Grund gib ihn aus und brich ab.
if (!$finished && $event->stopReason->type !== 'requires_action') {
echo "Session idle: {$event->stopReason->type}", PHP_EOL;
break 2;
}
break;
case $event instanceof \Anthropic\Beta\Sessions\Events\ManagedAgentsSessionStatusTerminatedEvent:
break 2;
}
}
$stream->close();
```
```ruby Ruby
open_runs = {} # workflow_run_id => run name
phase_names = {} # [run ID, phase ID] => phase name
# Öffne zuerst den Stream und sende dann die Nutzernachricht
stream = client.beta.sessions.events.stream_events(session_id)
client.beta.sessions.events.send_(
session_id,
events: [{
type: "user.message",
content: [{type: "text", text: "Which contracts in /contracts have a change-of-control clause?"}]
}]
)
stream.each do |event|
case event
when Anthropic::Beta::Sessions::BetaManagedAgentsWorkflowRunCreatedEvent
open_runs[event.workflow_run_id] = event.name
event.phases.each { |phase| phase_names[[event.workflow_run_id, phase.id]] = phase.name }
puts "Run started: #{event.name}"
when Anthropic::Beta::Sessions::BetaManagedAgentsWorkflowRunPhaseStartedEvent
phase_id = event.workflow_run_phase_id
puts " Phase: #{phase_names.fetch([event.workflow_run_id, phase_id], phase_id)}"
when Anthropic::Beta::Sessions::BetaManagedAgentsWorkflowRunStatusEndedEvent
name = open_runs.delete(event.workflow_run_id) || event.workflow_run_id
puts "Run ended: #{name} (#{event.result.type})"
when Anthropic::Beta::Sessions::BetaManagedAgentsAgentCustomToolUseEvent
# Antworte, wenn das Event eintrifft. Der Thread eines Runs kann auf deinen
# Client warten, während die Session weiterläuft.
result = call_tool.call(event.name, event.input)
begin
client.beta.sessions.events.send_(
session_id,
events: [{
type: "user.custom_tool_result",
custom_tool_use_id: event.id,
content: [{type: "text", text: result}]
}]
)
rescue Anthropic::Errors::BadRequestError => error
# Der Server lehnt ein Ergebnis ab, das zu spät kommt, nachdem er
# den Thread des Aufrufs archiviert hat. Verfolge den Run weiter.
puts " Answer to #{event.name} refused: #{error.message}"
end
when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusIdleEvent
reason = event.stop_reason.type.to_sym
# Fertig, wenn jeder Run beendet ist und der Agent seinen Turn abgeschlossen hat
break if open_runs.empty? && reason == :end_turn
# Ein Idle mit requires_action wartet auf deinen Client, also lies weiter.
# Bei jedem anderen Stop-Grund gib ihn aus und beende.
unless %i[end_turn requires_action].include?(reason)
puts "Session idle: #{reason}"
break
end
when Anthropic::Beta::Sessions::BetaManagedAgentsSessionStatusTerminatedEvent
break
end
end
```
## Eine Session mit offenen Runs unterbrechen
Sende [`user.interrupt`](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#interrupt-the-agent) ohne `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) oder mit der ID des primären Threads. Es stoppt den Turn des Agenten. Es beendet keinen Run. Die Runs der Session werden möglicherweise pausiert oder laufen weiter, und ihre Events zeigen möglicherweise nicht, was davon zutrifft. Die Lebensdauer eines pausierten Runs läuft weiter, sodass der Run mit `timeout_error` enden kann, während er pausiert ist.
* **Wartende Tool-Aufrufe:** Nach der Unterbrechung wartet ein Tool-Aufruf eines Run-Threads möglicherweise noch auf deinen Client. Beantworte jeden davon. Um einen Aufruf abzubrechen, der um Bestätigung bittet, lehne ihn ab. Um einen benutzerdefinierten Tool-Aufruf abzubrechen, sende ein Ergebnis, bei dem `is_error` (java, php: `isError`; csharp, go: `IsError`) auf `true` gesetzt ist und ein Text in `content` (csharp, go: `Content`) den Grund nennt. Während die Session `idle` mit `requires_action` ist, gibt eine `user.message` 400 zurück, also beantworte zuerst die Aufrufe.
* **Um die Runs zu stoppen:** Sende eine `user.message`, die den Agenten bittet, seine Runs zu stoppen. Ein gestoppter Run endet mit `result` `{"type": "stopped"}`. Während die Session `idle` mit `budget_reached` ist, gibt eine `user.message` 400 zurück, bis du das Budget erhöhst oder entfernst. Das Erhöhen oder Entfernen setzt auch die Runs fort, die das Budget pausiert hat, es sei denn, die Unterbrechung hat sie ebenfalls pausiert.
* **Um fortzufahren:** Sende eine `user.message`, die den Agenten bittet, seine Runs fortzusetzen. Nach einer Unterbrechung warten die Runs möglicherweise auf diese Nachricht. Wenn die Session `idle` mit `budget_reached` ist, erhöhe oder entferne zuerst das Budget.
* **Run-Ergebnisse:** Ein Run, der nach der Unterbrechung endet, sendet trotzdem `workflow_run.status_ended`.
## Während ein Run offen ist
| Anfrage | Während ein Run offen ist | Was zu tun ist |
| ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Die Session archivieren oder löschen | Gibt möglicherweise 400 zurück, während ein Run offen ist, unabhängig vom Status der Session. Der `error.details.error_code` des Fehlers kann `"workflow_run_open"` sein. Kann auch erfolgreich sein. | Bitte den Agenten, seine Runs zu stoppen, oder warte, bis jeder Run beendet ist. Ein pausierter Run endet nur dann von selbst, wenn seine Lebensdauer abläuft. Sende die Anfrage dann, sobald die Session `idle` ist. Eine erfolgreiche Archivierung beendet jeden offenen Run mit `{"type": "stopped"}`. Nach einer Archivierung kommen das `workflow_run.status_ended` eines Runs und das `workflow_run.phase_ended` einer noch offenen Phase nicht im Stream an. Liste die Events der Session auf, um sie zu lesen. Nach einem erfolgreichen Löschen meldet kein `workflow_run`-Event das Ende der Runs der Session. |
| Einen der Threads eines Runs archivieren | Gibt 400 mit `error.details.error_code: "workflow_run_open"` zurück, während der Run offen ist, laufend oder inaktiv, es sei denn, der Server hat den Thread bereits archiviert. | Nichts. Der Server archiviert die Threads eines Runs. |
| Den `agent` (csharp, go: `Agent`) der Session aktualisieren | Gibt 400 mit `error.details.error_code: "workflow_run_open"` zurück, während irgendein Run offen ist, selbst ein pausierter. Das Aktualisieren des zugrunde liegenden Agenten wird weiterhin akzeptiert, und die Session behält ihre eigene Kopie. Eine Anfrage, die auch andere Felder sendet, etwa `budget` (csharp, go: `Budget`), wird vollständig abgelehnt. | Warte, bis jeder Run sein `workflow_run.status_ended` hat, oder bitte den Agenten, seine Runs zu stoppen. |
| Einen Tool-Aufruf oder eine Tool-Bestätigung aus einem Thread eines Runs beantworten | Erlaubt. Er kommt im primären Stream an, und seine `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) nennt den Thread. | Antworte, sobald das Event ankommt, und übergib die `id` (csharp, go: `ID`) des Events als `tool_use_id` (java: `toolUseId`; php: `toolUseID`; csharp, go: `ToolUseID`) oder `custom_tool_use_id` (java: `customToolUseId`; php: `customToolUseID`; csharp, go: `CustomToolUseID`). Warte nicht auf `session.status_idle`: Die Session kann `running` bleiben, während die anderen Threads des Runs arbeiten. Sobald der Server den Thread archiviert hat, hat ein Tool-Ergebnis für einen seiner Aufrufe keine Wirkung, und es kann 400 zurückgeben. Wenn ein Tool-Ergebnis 400 zurückgibt, suche den Thread des Aufrufs in der Thread-Liste. Wenn sein Status `terminated` ist, kam das Ergebnis zu spät, also verwirf es. Sende jedes Tool-Ergebnis in einer eigenen Anfrage, weil der Server eine ganze Anfrage ablehnt, wenn er eines ihrer Events ablehnt. Eine Tool-Bestätigung, die zu spät kommt, gibt 200 zurück, was nicht bedeutet, dass das Tool ausgeführt wurde. |
### Run-Zustand nach dem erneuten Verbinden wiederherstellen
Stelle den Zustand jedes Runs aus den Events der Session wieder her. Der Stream spielt nicht erneut ab, was du verpasst hast: Eine neue Verbindung liefert nur Events, die nach ihrem Öffnen ausgegeben wurden. Liste die Events daher mit einem `types` (curl: `types[]`; cli: `--type`; csharp, go: `Types`)-Filter auf, mit einem Eintrag für jeden Event-Typ, wie in [Vergangene Events auflisten](https://platform.claude.com/docs/de/managed-agents/events-and-streaming#list-past-events). Übergib das `next_page` (ruby: `next_page_`; java, php: `nextPage`; csharp, go: `NextPage`) jeder Antwort als `page` (cli: `--page`; csharp, go: `Page`), bis `next_page` (ruby: `next_page_`; java, php: `nextPage`; csharp, go: `NextPage`) `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) ist oder fehlt. `workflow_run.created`, `workflow_run.status_running`, `workflow_run.status_idle` und `workflow_run.status_ended` geben den Zustand jedes Runs an, mit der Ausnahme, dass ein nach einer Unterbrechung pausierter Run möglicherweise noch als laufend angezeigt wird. `workflow_run.phase_started` und `workflow_run.phase_ended` stellen den Fortschritt wieder her. Ein Run ohne bisheriges Status-Event hat noch nicht mit der Ausführung begonnen. Es gibt keinen Endpunkt, der Runs auflistet.
## Kosten und Budgets
Die Modellanfragen eines Runs zählen zum [Budget der Session](https://platform.claude.com/docs/de/managed-agents/budgets). Ein Run hat keinen eigenen Preis. Die Token, die seine Agenten verwenden, werden wie die anderen Token der Session abgerechnet, zu den Tarifen des jeweiligen Modells. Alle Kosten einer Session findest du unter [Preise für Claude Managed Agents](https://platform.claude.com/docs/de/about-claude/pricing#claude-managed-agents-pricing).
* **Nutzung eines Runs:** Liste die Threads der Session auf und addiere die Token-Zahlen in `usage` (csharp, go: `Usage`) der Threads mit der `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) des Runs. Die Liste enthält archivierte Threads, deren Status `terminated` ist, sodass die Threads eines beendeten Runs mitgezählt werden. Übergib das `next_page` (ruby: `next_page_`; java, php: `nextPage`; csharp, go: `NextPage`) jeder Antwort als `page` (cli: `--page`; csharp, go: `Page`), bis `next_page` (ruby: `next_page_`; java, php: `nextPage`; csharp, go: `NextPage`) `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) ist oder fehlt, und überspringe einen Thread ohne `usage` (csharp, go: `Usage`). Wenn du stattdessen die `list_cost` (java, php: `listCost`; csharp, go: `ListCost`) der Threads addierst, lässt die Summe die Session-Laufzeit außen vor, und jeder Wert wird separat gerundet.
* **Beim Erreichen des Budgets:** Jeder offene Run pausiert, und die Session meldet `idle` mit `budget_reached` oder `requires_action`, wenn zusätzlich ein Tool-Aufruf wartet. Jeder Thread schließt die bereits begonnene Modellanfrage ab, sodass ein Run das Budget um eine Anfrage pro arbeitendem Thread überschreiten kann. Das Erhöhen oder Entfernen des Budgets setzt die dadurch pausierten Runs fort, es sei denn, eine Unterbrechung hat sie ebenfalls pausiert. Wenn die Nutzung der Session ein Modell ohne Listenpreis umfasst, bewirkt dies nur das Entfernen des Budgets; siehe [Modelle ohne Listenpreis](https://platform.claude.com/docs/de/managed-agents/budgets#models-without-a-list-price). Die Lebensdauer eines pausierten Runs läuft weiter, sodass der Run während der Pause mit `timeout_error` enden kann.
## Limits
| Limit | Wert | Beim Limit |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Gleichzeitig arbeitende Threads in einem Run | 64 | Der Run erstellt keine weiteren, bis einer fertig ist. Die API garantiert diese Zahl nicht. |
| Agenten, die ein Workflow über die gesamte Lebensdauer des Runs startet | 1.000 | Wenn der Workflow mehr anfordert, startet der Server keinen weiteren Agenten, und der Run endet mit `thread_limit_error`. Der Server kann einen fehlgeschlagenen Agenten in einem neuen Thread erneut ausführen, sodass ein Run mehr als 1.000 Threads haben kann. |
| Lebensdauer eines Runs | Standardmäßig 24 Stunden oder die Lebensdauer, die der Agent festlegt | Der Run endet mit `timeout_error`. Kein Event sagt, welche Lebensdauer der Agent festgelegt hat. |
| Gleichzeitig offene Runs in einer Session | Standardmäßig 10 | Der Server lehnt es ab, einen weiteren Run zu starten. Der Tool-Aufruf des Agenten bekommt einen Fehler, und du bekommst einen `workflow_run.error`, dessen `error.type` `max_workflow_runs_error` ist. Inaktive Runs zählen zum Limit. |
Der Server kürzt den `name` (csharp, go: `Name`) eines Runs oder einer Phase auf 64 Zeichen und die `description` (csharp, go: `Description`) auf 256. Der Server hat weitere Limits für Workflows sowie Regeln dafür, die hier nicht aufgeführt sind. Was du siehst, hängt davon ab, wann der Server das Problem feststellt:
| Was passiert | Was du siehst |
| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Der Workflow überschreitet eines der anderen Limits, wenn der Agent den Run startet | Der Start wird abgelehnt. Du bekommst einen `workflow_run.error` und keinen Run. |
| Der Run überschreitet später eines der anderen Limits | Du bekommst einen `workflow_run.error`, und danach kann der Run mit `unknown_error` enden. |
| Der Server stellt nach dem Start fest, dass der Workflow eine Regel für Workflows verletzt, die kein Limit ist | Du bekommst einen `workflow_run.error`, und der Run kann danach mit `program_error` enden. |
Eine Session kann über ihre Lebensdauer beliebig viele Runs starten.
* **Runs starten:** Nur der Agent im primären Thread der Session startet Runs. Ein Agent, der im Thread eines Runs arbeitet, kann keinen eigenen Run starten, sodass Runs nicht verschachtelt werden.
* **Runs beenden:** Kein Event, das du sendest, beendet einen Run; das Archivieren der Session kann es.
* **Die Threads eines Runs:** Du kannst keinen davon [über seine ID stoppen](https://platform.claude.com/docs/de/managed-agents/session-threads#interrupt-a-session-thread) und keinen archivieren, solange sein Run offen ist.
* **Thread-Limit:** Die Threads eines Runs sind vom [Kind-Thread-Limit](https://platform.claude.com/docs/de/managed-agents/session-threads#primary-thread-and-session-threads) der Session ausgenommen.
* **Sichtbarkeit:** Du siehst den Code des Workflows nicht, kannst den Agenten aber nach dem Workflow fragen, wie der Tipp in [Die Threads eines Runs](https://platform.claude.com/docs/de/managed-agents/workflow-runs#a-runs-threads) beschreibt. Du siehst auch nicht die Tool-Aufrufe, die der Agent zum Starten und Verwalten von Runs macht, oder das Ergebnis, das jeder Thread an den Workflow zurückgibt.
### Ratenlimits
Die Arbeit eines Runs zählt zu den „rate limits" (Ratenlimits), die deine Organisation bereits hat.
| Was | Zählt zu | Was zu tun ist |
| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Die Anfragen deines Clients zum Abrufen oder Auflisten der Session, ihrer Threads und deren Events | Dem Leselimit für [Managed-Agents-Endpunkte](https://platform.claude.com/docs/de/managed-agents/reference#rate-limits) | Verfolge einen Run im Event-Stream der Session, statt zu pollen. |
| Modellanfragen aus den Threads eines Runs | Deinen [Ratenlimits der Messages API](https://platform.claude.com/docs/de/api/rate-limits) für das Modell, das jeder Thread verwendet, zusammen mit deinem übrigen Traffic | Lass in diesen Limits Platz für einen Run oder [fordere höhere Limits an](https://platform.claude.com/docs/de/api/rate-limits#requesting-higher-limits). |
Wenn eine Modellanfrage aus einem der Threads eines Runs durch ein Ratenlimit begrenzt wird oder das Modell überlastet ist, kann der eigene Stream des Threads einen `session.error` vom Typ `model_rate_limited_error` oder `model_overloaded_error` bekommen:
* Wenn sein `retry_status.type` `retrying` ist, wiederholt der Server die Anfrage, und der Thread arbeitet noch.
* Wenn er `exhausted` ist, ist der Thread fehlgeschlagen. Wenn der Workflow diesen Fehler den Run beenden lässt, endet der Run mit `program_error`, was die Ursache nicht nennt. Lies die Events der fehlgeschlagenen Threads, um sie zu finden.
Der Server begrenzt außerdem, wie viel alle Sessions deiner Organisation pro Minute tun. Ein Thread, der dieses Limit erreicht, stoppt, mit einem `session.error` in seinem eigenen Stream, dessen Nachricht ein Ratenlimit nennt. Warte eine Minute, bevor du den Agenten bittest, fortzufahren.