watsonx Orchestrate ADK: Wie man loslegt und echte Agenten und Workflows baut

Anfang dieses Jahres hatte ich die Gelegenheit, an einem IBM watsonx Orchestrate Workshop teilzunehmen. Danach habe ich weitergemacht und das Agent Development Kit (ADK) lokal aufgesetzt, einen echten Multi-Agenten-Workflow gebaut und ihn mit Tools verbunden. Dieser Beitrag richtet sich an alle, die mit watsonx Orchestrate und dem ADK einsteigen wollen oder einfach neugierig sind, wie das Entwickeln auf einer agentischen Plattform in der Praxis aussieht.

Das ADK

Das ADK ist die Pro-Code Variante von watsonx Orchestrate, also eine CLI, eine lokale Server-Runtime, Agenten definiert in YAML und Tools geschrieben in Python. Man kann einen vollständigen Orchestrate-Server lokal betreiben und ihn mit Cloud-LLMs oder lokalen Modellen über Ollama verbinden.

Unter der Haube besteht das ADK im Wesentlichen aus zwei Dingen: der orchestrate-CLI und der watsonx Orchestrate Developer Edition als lokal laufende Serverinstanz. Mit der CLI verwaltet man die Umgebungen. Das kann eine SaaS-Instanz auf IBM Cloud oder AWS sein, eine On-Premises-Installation oder die lokale Developer Edition – und man nutzt dieselben Befehle, um Agenten und Tools zu importieren, Chats zu starten und die Runtime auf verschiedene Modell-Provider zu richten. Die Developer Edition selbst läuft containerisiert via Docker/Compose und liefert eine vollständige Orchestrate-Umgebung für Entwicklung und Tests auf dem eigenen Rechner, während die eigentlichen LLMs über Modell-Provider erreicht werden: IBM-gehostete Modelle auf watsonx.ai, Drittanbieter oder lokale Ollama-Modelle, die man am AI Gateway registriert.

Die Einrichtung selbst ist unkompliziert:

1pip install ibm-watsonx-orchestrate
2orchestrate server start -e server.env -f docker-compose.yml

Zwei Dinge, die man vor dem Start wissen sollte: Der Server ist recht ressourcenintensiv. Empfohlen werden 8 Kerne und 32 GB RAM, und in meiner Erfahrung verbraucht der Server allein – ohne jedes LLM – bis zu 15 GB. Auf einem gut ausgestatteten Rechner ist das kein Problem, auf einem Standard-Entwicklerlaptop kann es eng werden. Außerdem erfordert das ADK ein gültiges watsonx Orchestrate Abonnement und einen API-Schlüssel. Einen vollständig kostenlosen Offline-Tier gibt es nicht.

Wie Agenten und Tools strukturiert sind

Agenten werden über YAML-Dateien erstellt und verwaltet. Tools sind Python-Funktionen mit dem Decorator @tool. Beides kann in der Versionsverwaltung liegen, beides wird per CLI-Befehlen deployt. Das fügt sich natürlich in einen Engineering-Workflow ein – Code Review, CI/CD, der übliche Ablauf.

Eine typische Agentendefinition:

 1spec_version: v1
 2kind: native
 3style: react
 4name: some_agent
 5llm: groq/openai/gpt-oss-120b
 6instructions: |-
 7  You are responsible for X.
 8  When given Y, do Z and return the result.
 9collaborators:
10  - other_agent
11tools:
12  - some_tool

Ein Feld in diesem Beispiel, das leicht übersehen wird, ist style. watsonx Orchestrate unterstützt drei Styles für native Agenten: default, react und planner. Der default-Style nutzt das eingebaute Reasoning des Modells in einem eher leichtgewichtigen, tool-zentrischen Loop und eignet sich gut für einfachere, locker geordnete Aufgaben. Der react-Style implementiert ein explizites „Denken → Handeln → Beobachten"-Muster und ist für komplexere oder mehrdeutige Probleme gedacht, bei denen jeder Schritt vom vorherigen Ergebnis abhängt. Der planner-Style geht noch einen Schritt weiter: Der Agent erstellt zunächst einen Plan und führt ihn dann Schritt für Schritt aus. Das ist nützlich, wenn man einen transparenten, mehrstufigen Ablauf möchte, den man nachvollziehen und erklären kann. In den Beispielen hier habe ich react verwendet, weil es sich natürlich auf mehrstufige Workflows abbilden lässt, die stark auf Tools und Collaborators angewiesen sind.

Kürzlich habe ich einen Meeting-Workflow gebaut, bei dem dieses Muster sehr konkret wird. Ein zentraler meetingmanager-Agent orchestriert fünf spezialisierte Agenten – zum Beispiel für Transkript-Bereinigung, Extraktion von Action Items, Protokollschreiben und Task-Erstellung. Die Orchestrierung wird vollständig als Prozessbeschreibung in den instructions ausgedrückt, zum Beispiel (gekürzt):

 1name: meetingmanager
 2style: react
 3llm: groq/openai/gpt-oss-120b
 4instructions: |-
 5  You orchestrate end-to-end meeting processing with five specialist agents.
 6
 7  CRITICAL Input handling
 8  - Transcript is expected in the first user message.
 9  - Do not ask for it twice.
10  - If missing, ask once for transcript + project key.
11
12  Orchestration flow
13  - Step 1: transcriptcleaner – clean raw transcript (VTT/plain text).
14  - Step 2: transcriptanalyst – extract action items, decisions, questions.
15  - Step 3: minuteswriter – generate customer-facing minutes (Markdown).
16  - Step 4: taskwriter – create one task per action item using project key.
17  - Step 5: wikiwriter – create wiki page when wiki params are provided.
18
19collaborators:
20  - transcriptcleaner
21  - transcriptanalyst
22  - minuteswriter
23  - taskwriter
24  - wikiwriter
25tools:
26  - create_project

Der Abschnitt „CRITICAL" ist keine Dekoration, er war notwendig, damit der Orchestrator nicht in Schleifen hängen bleibt und nach dem Transkript fragt, nachdem es bereits geliefert wurde. Die Lösung besteht darin, sehr explizit zu formulieren, was die Eingabeerwartungen sind und wie der Ablauf sein soll.

Guidelines: strukturierte Verhaltensregeln

Instructions sind das freiformige „Betriebshandbuch" eines Agenten. Ergänzend dazu bietet Orchestrate eine strukturiertere Möglichkeit, Verhalten zu kodieren: Guidelines. Guidelines sind kleine, konditionale Regeln nach dem Muster „wenn ... dann ..." und können optional einen bestimmten Tool-Aufruf vorschreiben.

Ein vereinfachtes Beispiel:

1guidelines:
2  - condition: "User asks for a status update on a task"
3    action: "Summarise the current status briefly before asking a follow-up question if needed."
4    tool: "get_task_status"

Die Idee ist, Guidelines für Verhalten zu nutzen, das konsistent und wiederholbar sein muss, zum Beispiel immer ein bestimmtes Tool aufrufen, wenn eine bestimmte Bedingung erfüllt ist, oder in bestimmten Kontexten bestimmte Inhalte konsequent vermeiden. Offenes Reasoning und Tonalität bleiben in den instructions. In der Praxis kann das eine sauberere Alternative sein, als jedes „Wenn X, dann Y" in einen riesigen Instruction-Block zu schreiben, und es erleichtert das spätere Überprüfen und Anpassen des Agentenverhaltens.

Die zentrale Designentscheidung in Orchestrate ist, dass Orchestrierung und Agenten-Instruktion in natürlichsprachlichen Instructions ausgedrückt werden – nicht als Graph oder Regelmaschine. Ein Orchestrator-Agent erhält Instructions, die den Prozess beschreiben: Welche Sub-Agenten aufgerufen werden, in welcher Reihenfolge, was zwischen ihnen weitergegeben wird und das LLM löst das zur Laufzeit auf. Für alles Vorhersehbare und klar Sequenzierte funktioniert das gut. Worauf es dabei ankommt: Die Instructions müssen eindeutig genug sein, damit das Modell Schritte nicht umsortiert oder überspringt.

Ein praktisches Muster, das sich bewährt hat: Agenten eng halten. Ein Agent pro kognitiver Aufgabe, ein Toolset pro Agent. Ein koordinierender Agent darüber, der zwischen ihnen vermittelt. Das macht einzelne Agenten leichter testbar und ihr Verhalten besser nachvollziehbar.

Tools in Python

Tools sind der Ort, an dem Integrationen leben. Ein Tool ist eine gewöhnliche Python-Funktion mit dem Decorator @tool. Das Framework generiert das JSON-Schema und exponiert es automatisch an Agenten:

1from ibm_watsonx_orchestrate.agent_builder.tools import tool
2
3@tool(
4    name="create_task",
5    description="Creates a task in the project tracker.",
6)
7def create_task(project_key: str, title: str, description: str, assignee: str = "") -> str:
8    # your integration logic here
9    ...

Aus Agentensicht sieht es nur ein benanntes Tool mit einer Beschreibung. API-Aufrufe, Authentifizierung, Fehlerbehandlung und Datenmapping passieren in Python. Das ist nützlich, wenn vorgefertigte Konnektoren die spezifischen Anforderungen der eigenen Umgebung nicht abdecken. Man schreibt eine Funktion, importiert sie, und sie steht jedem Agenten zur Verfügung, dem man sie zuweist.

Das ADK selbst unterstützt mehrere Tool-Typen. Python-Tools wie das obige geben vollständige Kontrolle über Logik und Fehlerbehandlung im Code. OpenAPI-Tools erlauben es, eine OpenAPI-3.0-Spezifikation für eine JSON-basierte HTTP-API ohne Integrationscode in ein oder mehrere Tools umzuwandeln. MCP-Toolkits ermöglichen es, externe MCP-Server, die selbst ganze Systeme abbilden können, als Tools für Agenten bereitzustellen. Und Langflow-Tools erlauben es, visuelle LLM-Flows aus Langflow zu importieren und als Tools innerhalb von Orchestrate zu behandeln. Das ist praktisch, wenn man dort bereits komplexe RAG- oder Agenten-Chains modelliert hat.

Als konkretes Beispiel: In einem Workflow musste ich OpenProject-Nutzer anhand ihres Anzeigenamens nachschlagen und natürlichsprachliche Prioritätsangaben auf interne IDs mappen, bevor Tasks erstellt wurden. Beides sind wenige Zeilen Python.

Der Entwicklungsalltag

Der tägliche Zyklus sieht so aus:

1. Eine Agenten-YAML oder eine Tool-Python-Datei bearbeiten
2. Neu importieren:

   1orchestrate tools import -k python -f tools/my_tool.py
   2orchestrate agents import -f agents/my_agent.yaml
   

3. Die Chat-UI starten (falls noch nicht offen):

   1orchestrate chat start
   

4. Chat-Session neu laden und testen

Über die Chat-UI lassen sich neben dem eigentlichen Testen auch Agenten, Tools und Verbindungen direkt verwalten – man muss dafür nicht jedes Mal auf die CLI wechseln.

Bei einem Multi-Agenten-Setup über mehrere Dateien hinweg summiert sich Schritt 2. Ein Wrapper-Skript, das alles in der richtigen Reihenfolge und mit konfigurierbaren LLM-Targets importiert, reduziert das auf einen einzelnen Befehl. Es kann sich also lohnen, ein solches Skript zu bauen.

Für einfache Flows reicht dieser „Bearbeiten → Importieren → Chatten"-Loop. Sobald Agenten mehrere Tools aufrufen oder miteinander kollaborieren, wird Observability wichtig. watsonx Orchestrate kann Traces an Langfuse senden, einen Open-Source-Observability-Stack für LLM-Anwendungen: Jeder Agenten-Run wird zu einem Trace mit Spans für Prompts, Tool-Aufrufe und Zwischenergebnisse sowie Timing- und Fehlerinformationen. In der Praxis verwandelt das „Das Modell hat etwas Seltsames gemacht" in „Schritt 3 dieses Runs hat das falsche Tool mit diesen Parametern aufgerufen" – genau das, was man beim Debuggen von Multi-Agenten-Setups oder bei der Erklärung von Verhalten gegenüber anderen Teams braucht.

Was sich bei mir bewährt hat: ein kleines Set „kanonischer" Meeting-Transkripte und Projekt-Keys, die ich regelmäßig durch den Workflow laufen lasse, plus Langfuse-Traces zur Überprüfung von Tool-Auswahl, Schrittfolge und Ausgabeformaten. Das ist noch kein vollständiges automatisiertes Test-Suite, kommt aber einer Regressionstestsammlung nahe, die später über die Orchestrate-APIs statt über die Chat-UI ausgeführt werden kann.

Noch ein Punkt, den man einkalkulieren sollte: Große unstrukturierte Eingaben können das Kontextfenster belasten. In meinem Fall führten rohe VTT-Meeting-Dateien dazu, dass Agenten in Schleifen liefen. Das Vorverarbeiten der Eingabe zu sauberem Text hat das gelöst – das kann aber in anderen Szenarien ebenfalls auftreten. Der allgemeine Punkt: Große oder rauschbehaftete Eingaben brauchen oft einen Bereinigungsschritt, bevor sie einen Agenten erreichen – aber das gilt für agentische Systeme generell, nicht spezifisch für diese Plattform.

Was man beachten sollte

Programmatisches Auslösen. Der ADK-Workflow läuft über die Orchestrate-Chat-UI. Das Auslösen eines Agenten-Flows von einem externen System, einem Webhook oder CI/CD aus erfordert zusätzliche Arbeit, die man selbst zusammenstellt. Das ist wichtig zu wissen, wenn programmatischer Aufruf eine harte Anforderung ist.

Prompt Engineering braucht Iterationen. Die Flexibilität der natürlichsprachlichen Orchestrierung ist auch der Ort, an dem Dinge driften können, wenn Instructions nicht präzise genug sind. Konsistente Schrittfolge und zuverlässige Tool-Auswahl bei unterschiedlichen Eingaben zu erreichen, erfordert echte Testzyklen. Das ist keine Überraschung, wenn man Erfahrung mit agentischen Systemen hat, aber es ist auch keine Aufgabe für einen Nachmittag. Guidelines können helfen, wenn man Muster entdeckt, die konsistent durchgesetzt werden müssen, zum Beispiel „wenn der User nach einem Ticket-Status fragt, immer zuerst das Status-Tool aufrufen" – anstatt jedes solche Muster in prosaischen Instructions zu kodieren.

Ausgabekonsistenz bei lokalen LLMs. Wenn man lokale Modelle über Ollama betreibt, ist die Variabilität im Ausgabeformat höher als bei einem Cloud-LLM im JSON-Modus. Parser und Bereinigungsschritte sind oft notwendig. Der Wechsel zu einem Cloud-Modell beseitigt den Großteil dieser Reibung.

Lokale vs. Cloud-LLMs. Die Developer Edition verleitet dazu, alles lokal zu betreiben, besonders mit Ollama als schneller Weg, Modelle auf der eigenen Hardware zu starten. Für Experimente, interne Tools oder unkritische Workflows ist das großartig: niedrige Latenz, kein externer API-Traffic und volle Kontrolle darüber, wohin Daten fließen. Sobald man größere strukturierte Ausgaben in nachgelagerte Systeme einspeist oder Flows an Kunden exponiert, werden SLAs und Stabilität wichtig. In diesen Fällen sind gehostete Modelle mit einem ordentlichen JSON-Modus und Durchsetzung von Ausgabeformaten die sicherere Wahl, auch wenn das bedeutet, etwas Souveränität aufzugeben und pro Token zu bezahlen.

Selbst ausprobieren

watsonx Orchestrate bietet einen 30-tägigen kostenlosen Trial, und die lokale Developer Edition lässt sich in wenigen Schritten einrichten:

1. pip install ibm-watsonx-orchestrate
2. Umgebungsvariablen für die wxO-Instanz und den API-Schlüssel setzen
3. orchestrate server start -e server.env -f docker-compose.yml
4. orchestrate chat start – die Chat-UI öffnet sich im Browser
5. Ein einfaches Tool in Python und einen einfachen Agenten in YAML schreiben, beides importieren und im Chat testen – Agenten und Tools lassen sich auch direkt in der UI verwalten

Die ADK-Dokumentation beschreibt das Setup ausführlicher. Wer Inspiration sucht – was man bauen kann oder wie man anfängt – kann auf den vollständigen Code des Meeting-Workflows zugreifen oder uns direkt kontaktieren. Wir helfen gerne dabei, deine KI-Automatisierungsreise voranzubringen.