KI-Agent mit dem Claude Agent SDK entwickeln und sicher an Zoho anbinden

Einen KI-Agenten mit dem Claude Agent SDK entwickeln Sie, indem Sie zuerst drei Dinge festlegen: Werkzeuge, Freigaben und Tests. Erst danach installieren Sie das SDK, binden ein Geschäftssystem wie Zoho CRM über MCP an und schreiben den Agenten in Python oder TypeScript. Wer diese Reihenfolge umdreht, muss zu weit gefasste Rechte später mühsam zurückbauen.

Das Claude Agent SDK ist eine Bibliothek von Anthropic, die Ihnen dieselben Werkzeuge, dieselbe Agentenschleife und dieselbe Kontextverwaltung gibt, auf denen Claude Code läuft. Claude Code ist das Werkzeug von Anthropic, dem Entwickler Programmieraufgaben übertragen. Programmieren lässt sich das SDK laut der Übersicht zum Agent SDK in Python und TypeScript.

Dieser Beitrag ist Teil 2 einer dreiteiligen Reihe über KI-Agenten in der Praxis. Teil 1 zeigt, wie Sie einen KI-Agenten mit Claude ganz ohne Code erstellen. Teil 3 behandelt den laufenden Betrieb von Agenten. Was ein KI-Agent grundsätzlich ist, erklärt der Beitrag über Aufbau, Grenzen und Kontrolle von KI-Agenten.

Der Leitfaden richtet sich an Unternehmen mit eigener Entwicklung oder einem technischen Dienstleister. Sie brauchen keine Vorkenntnisse zum SDK, sollten aber Code lesen können.

Anthropic bietet für Agenten drei Bausteine an, die sich vor allem darin unterscheiden, wer die Agentenschleife betreibt. Die Agentenschleife ist der wiederkehrende Ablauf, in dem das Modell Werkzeuge aufruft, Ergebnisse liest und den nächsten Schritt plant. Die folgende Tabelle ordnet die drei Wege ein.

Das Claude Agent SDK bringt eingebaute Werkzeuge, Hooks, Subagenten, MCP-Server, Berechtigungen und Sitzungen mit. Hooks sind eigener Code, der an festen Punkten im Ablauf des Agenten läuft. Subagenten sind spezialisierte Agenten, die der Hauptagent für Teilaufgaben startet. Anthropic hat das frühere Claude Code SDK am 29. September 2025 in Claude Agent SDK umbenannt.

Offizielle Client SDKs gibt es laut der Übersicht der Anthropic-SDKs für sieben Sprachen, darunter C#, Go und Java. Das Agent SDK selbst gibt es nur für Python und TypeScript. Aus anderen Sprachen starten Sie die Kommandozeile als Unterprozess mit dem Schalter -p und --output-format json.

Das Claude Agent SDK arbeitet in einer festen Rückkopplungsschleife: Kontext sammeln, handeln, die Arbeit prüfen und wiederholen. Anthropic beschreibt diese Schleife im Beitrag zum Bau von Agenten mit dem Claude Agent SDK. Das Leitprinzip dahinter lautet, dem Agenten einen Computer zu geben, damit er wie ein Mensch arbeiten kann.

Was das SDK in der Schleife übernimmt

Das SDK übernimmt Orchestrierung, Werkzeugausführung, Kontextverwaltung und Wiederholungsversuche. Ihr Code liest nur den Strom der Nachrichten mit. Nähert sich ein Gespräch der Kontextgrenze, fasst die Compact-Funktion frühere Nachrichten automatisch zusammen. Subagenten arbeiten in eigenen, getrennten Kontextfenstern und melden nur das Relevante zurück.

Wie die Schleife bei einem Zoho-Vorgang aussieht

Bei einer Kundenanfrage sammelt der Agent zuerst Kontext, etwa den Kontakt und offene Angebote im CRM. Dann handelt er, zum Beispiel mit einem Antwortentwurf. Beim Prüfen vergleicht er den Entwurf mit festen Regeln wie Pflichtfeldern oder Preisgrenzen. Ein zweites Sprachmodell als alleiniger Richter ist laut Anthropic meist wenig robust und kann viel Latenz kosten.

Für die Suche in Daten empfiehlt Anthropic, mit agentischer Suche zu beginnen. Dabei sucht der Agent selbst mit seinen Werkzeugen. Semantische Suche zerlegt Inhalte in Abschnitte und durchsucht sie als Vektoren. Sie lohnt sich erst, wenn Sie schnellere Ergebnisse oder mehr Varianten brauchen.

Bevor jemand Code schreibt, sollte feststehen, was der Agent lesen, was er ändern und was er nur vorschlagen darf. Diese Entscheidungen bestimmen später die Optionen allowed_tools, disallowed_tools und den Berechtigungsmodus. Die Tabelle fasst die Fragen und die Antworten aus der Dokumentation zusammen.

Bei Svennis schreiben wir diese Entscheidungen vor Projektbeginn in eine Werkzeugliste mit getrennten Spalten für Lesen, Schreiben und Freigabe. Am häufigsten sehen wir bei Kunden, dass ein Platzhalter über alle Werkzeuge eines MCP-Servers nebenbei auch Schreibwerkzeuge freigibt.

Für das Claude Agent SDK brauchen Sie Python 3.10 oder neuer, alternativ Node.js 18 oder neuer, und ein Anthropic-Konto. Das Python-Paket heißt claude-agent-sdk, das TypeScript-Paket @anthropic-ai/claude-agent-sdk. Die folgenden zwei Zeilen führen Sie im Terminal aus; sie installieren das SDK und setzen den API-Schlüssel.

pip install claude-agent-sdk
export ANTHROPIC_API_KEY=your-api-key

Ersetzen Sie your-api-key durch Ihren eigenen Schlüssel. Das SDK liest den Schlüssel aus der Umgebung des Prozesses und lädt keine .env-Dateien automatisch. Beide SDKs enthalten ein Claude-Code-Programm, eine separate Installation entfällt meist. Installiert pip jedoch das Quellpaket statt eines Plattformpakets, etwa unter Windows auf ARM64, fehlt dieses Programm.

Der folgende Agent stammt aus dem Schnellstart des Agent SDK. Speichern Sie ihn als Python-Datei in einem leeren Arbeitsordner und starten Sie ihn dort.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentenschleife: liefert Nachrichten, waehrend Claude arbeitet
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # ohne Rueckfrage erlaubt
            permission_mode="acceptEdits",  # Dateiaenderungen ohne Rueckfrage
        ),
    ):
        # Lesbare Ausgabe anzeigen
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Ueberlegungen von Claude
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # aufgerufenes Werkzeug
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Endergebnis


asyncio.run(main())

Ändern werden Sie vor allem drei Zeilen. In prompt steht die Aufgabe. In allowed_tools stehen die Werkzeuge ohne Rückfrage. Der Modus acceptEdits gibt Dateiänderungen im Arbeitsordner frei; für einen Agenten an Geschäftsdaten ersetzen Sie ihn meist durch einen strengeren Modus.

Das Model Context Protocol (MCP) ist ein offener Standard, der KI-Agenten mit externen Werkzeugen und Datenquellen verbindet. MCP-Server laufen als lokale Prozesse, werden über HTTP angesprochen oder direkt in Ihrer Anwendung definiert. Der folgende Code aus der MCP-Dokumentation des Agent SDK verbindet einen Server über HTTP. Sie fügen ihn als eigene Python-Datei ein.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={
            "claude-code-docs": {
                "type": "http",
                "url": "https://code.claude.com/docs/mcp",
            }
        },
        allowed_tools=["mcp__claude-code-docs__*"],
    )

    async for message in query(
        prompt="Use the docs MCP server to explain what hooks are in Claude Code",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

In der Praxis ersetzen Sie Namen und url durch den MCP-Server, über den Ihr Unternehmen CRM oder Postfach anbindet. MCP-Werkzeuge heißen nach dem Muster mcp__<server-name>__<tool-name>. Ohne ausdrückliche Erlaubnis sieht Claude diese Werkzeuge, kann sie aber nicht aufrufen. Listen Sie statt des Sterns besser die einzelnen lesenden Werkzeuge auf.

Der Modus acceptEdits gibt MCP-Werkzeuge nicht frei. Das SDK öffnet keinen Browser und führt keinen interaktiven OAuth-Ablauf aus, die Anmeldung erledigen Sie also vorab. Verbindungen brechen standardmäßig nach 30 Sekunden ab. Nach fünf gescheiterten Wiederverbindungen meldet ein Server failed oder needs-auth.

Das Claude Agent SDK prüft jeden Werkzeugaufruf in sechs festen Schritten: Hooks, Sperrregeln, Rückfrageregeln, Berechtigungsmodus, Erlaubnisregeln und zuletzt der Callback canUseTool. Ein Callback ist eine Funktion Ihres Codes, die das SDK zur Entscheidung aufruft. Die Dokumentation zu Berechtigungen beschreibt die Modi so:

Nutzen Sie bypassPermissions für nichts, was Kunden oder Geld berührt. Selbst allowed_tools=["Read"] gibt in diesem Modus jedes Werkzeug frei, auch Bash und Write. Eine Sperrregel greift dagegen immer. Ein reiner Name in disallowed_tools entfernt das Werkzeug sogar aus der Anfrage, sodass Claude es nicht sieht. Ein ungebundener Eintrag wie "*" wird ignoriert und gibt nichts frei.

Der Callback canUseTool ist die Stelle, an der eine Person eine Aktion des Agenten freigibt oder ablehnt. Er erhält Werkzeugname und Eingabe und hält die Ausführung an, bis er antwortet. Der folgende TypeScript-Ausschnitt aus der Dokumentation zu Freigaben und Rückfragen zeigt den Entscheidungsteil. Sie setzen ihn in die Optionen Ihres query-Aufrufs ein.

canUseTool: async (toolName, input) => {
  // ... vorgeschlagene Aktion einer Person zeigen und Antwort lesen ...
  if (response.toLowerCase() === "y") {
    return { behavior: "allow", updatedInput: input };
  } else {
    return { behavior: "deny", message: "User denied this action" };
  }
}

Die Variable response liefert Ihre eigene Oberfläche, etwa ein Formular oder eine Chatnachricht. Den Text in message formulieren Sie selbst. Claude liest ihn und kann seinen Ansatz anpassen.

Wichtig ist eine Regel: Für automatisch freigegebene Werkzeuge feuert der Callback nie. Das Senden gehört also nicht in allowed_tools. Der Callback darf beliebig lange warten. Soll der Prozess dazwischen enden, liefert ein PreToolUse-Hook die Entscheidung defer und der Agent setzt später aus der gespeicherten Sitzung fort. Der PermissionRequest-Hook kann Ihr Team per Slack oder E-Mail benachrichtigen.

Der Lieferanten-E-Mail-Agent aus Teil 1 liest Mails von Lieferanten, ordnet sie dem richtigen Datensatz zu und bereitet eine Antwort vor. Im Claude Agent SDK entsteht daraus ein Python-Programm mit zwei MCP-Servern. Einer verbindet das Postfach in Zoho Mail, der andere Zoho CRM.

Werkzeuge und Freigaben des Lieferanten-Agenten

In allowed_tools stehen nur die lesenden Werkzeuge beider Server, jeweils einzeln benannt. Das Werkzeug zum Senden fehlt in dieser Liste. Jeder Sendeversuch erreicht deshalb canUseTool, und eine Person aus dem Einkauf entscheidet. Soll der Agent nur Entwürfe schreiben, tragen Sie das Sendewerkzeug stattdessen in disallowed_tools ein.

Ablauf eines Durchgangs

Der Agent sammelt Kontext aus der Mail und dem Lieferantendatensatz. Er entwirft die Antwort und prüft sie gegen Ihre Regeln, etwa bekannte Ansprechpartner und offene Bestellungen. Lehnt die Einkäuferin ab, erklärt die Ablehnungsnachricht den Grund, und Claude überarbeitet den Entwurf. Ein PermissionRequest-Hook meldet wartende Freigaben im Teamkanal.

Testen Sie diesen Agenten zuerst im Modus plan mit echten, alten Mails. Den Modus ändern Sie während einer Sitzung mit set_permission_mode(). Die Änderung gilt sofort für alle folgenden Werkzeugaufrufe.

Die Kosten eines Agenten mit dem Claude Agent SDK entstehen aus den verbrauchten Tokens des gewählten Modells. Tokens sind Textstücke, die das Modell verarbeitet. Die Preisseite von Anthropic nennt diese Preise in US-Dollar je Million Tokens, ohne Steuern:

Die Modellübersicht von Anthropic rät, im Zweifel mit Claude Opus 5.5 zu beginnen. Claude Haiku 4.5 wird nicht vor dem 15. Oktober 2026 abgekündigt. Planen Sie einen Wechsel also früh ein.

Ein Treffer im Prompt-Cache kostet 10 % des normalen Eingabepreises. Die Batch API halbiert die Preise für große, nicht eilige Mengen.

Claude Managed Agents rechnet zusätzlich zur Token-Nutzung 0,08 $ je Sitzungsstunde ab. Beim Claude Agent SDK betreiben Sie den Prozess selbst, die Laufzeit zahlen Sie also bei Ihrem eigenen Server oder Rechenzentrum.

Für Unternehmen in Deutschland zählt vor allem, wo der Agent läuft und welcher Vertrag gilt. Das Claude Agent SDK läuft in einem Prozess, den Sie selbst betreiben. Sie bestimmen damit Server, Protokolle und Zugänge zu Ihren Systemen. Die Modellaufrufe gehen weiter an Anthropic oder an eine Cloud, die Sie wählen.

Das SDK unterstützt die Anmeldung über Amazon Bedrock, Claude Platform on AWS, die Agent Platform von Google Cloud und Microsoft Foundry. Welcher Weg zu Ihrer Datenschutzprüfung passt, klären Sie vor dem Start mit Ihrem Datenschutzverantwortlichen. Claude Managed Agents kommt derzeit nicht für Zero Data Retention in Frage, weil der Dienst Sitzungen dauerhaft speichert.

Für den Vertrag gelten die kommerziellen Nutzungsbedingungen von Anthropic, auch wenn Sie den Agenten Ihren eigenen Kunden anbieten. Ihr Produkt darf etwa „Ihr Agentenname Powered by Claude“ heißen, aber nicht „Claude Code“. Eine Anmeldung über claude.ai dürfen Sie ohne vorherige Genehmigung nicht anbieten.

Für Fertigungsbetriebe zeigt die Seite zu KI in der Produktion, wo solche Agenten im Betriebsalltag ansetzen.

Der erste Agent mit dem Claude Agent SDK gelingt am sichersten mit einem einzigen, klar umrissenen Vorgang. Gehen Sie in dieser Reihenfolge vor:

1. Wählen Sie einen Vorgang mit messbarem Ergebnis, etwa die Zuordnung von Lieferantenmails.
2. Füllen Sie die Entscheidungstabelle zu Werkzeugen, Freigaben, Modus und Tests aus.
3. Bauen Sie einen Prototyp nur mit lesenden Werkzeugen und lassen Sie ihn im Modus plan laufen.
4. Ergänzen Sie canUseTool für jede Aktion, die Kunden oder Geld berührt.
5. Prüfen Sie die Ergebnisse mit echten, alten Fällen gegen feste Regeln.

Wenn Sie vorher wissen möchten, ob Ihre Systeme und Daten dafür bereit sind, beginnen Sie mit dem KI-Readiness-Check für Ihr Unternehmen. Wie aus einem Prototyp ein angebundener Ablauf wird, beschreibt die Seite zur KI-Automatisierung für den Mittelstand.