KI-Agent in Python bauen: Schritt für Schritt in 76 Zeilen

👁 118 Aufrufe

Ein KI-Agent in Python ist im Grunde eine Schleife: Das Modell erhält eine Aufgabe und eine Liste von Werkzeugen (Tools), wählt ein passendes Tool aus, Ihr Code führt es aus, das Ergebnis geht zurück an das Modell, und dieses entscheidet über den nächsten Schritt. Ich habe einen solchen Agenten in 76 Zeilen Code komplett ohne Framework gebaut: Er durchsucht Dateien, führt Berechnungen durch, liest Webseiten aus, besitzt ein Schrittlimit und schreibt ein detailliertes Protokoll aller Entscheidungen. Anschließend habe ich denselben Agenten auf das OpenAI Agents SDK und das Claude Agent SDK portiert. Alle nachfolgenden Programmdurchläufe stammen aus realen Tests vom 4. Oktober 2026. Dies ist der dritte Teil unserer Reihe KI-Agenten von Grund auf.

Wie sich ein Agent von einem einfachen KI-Skript unterscheidet

Ein gewöhnliches KI-Skript folgt fest definierten Schritten: „E-Mail abrufen, zusammenfassen, speichern“. Das Sprachmodell füllt dabei lediglich eine vordefinierte Lücke aus. Bei einem KI-Agenten bestimmt das Modell die Reihenfolge der Arbeitsschritte selbstständig. Es erhält ein Ziel („Berechne die Gesamtausgaben aus allen Rechnungen“) sowie eine Reihe von Werkzeugen. Das Modell entscheidet eigenständig, zuerst das Dateisystem zu scannen, anschließend Wechselkurse abzurufen und am Ende die Gesamtsumme zu berechnen. Weitere Hintergründe dazu finden Sie im Artikel KI-Agenten: Was sie sind und wie sie funktionieren.

Technisch betrachtet basiert ein Agent auf Function Calling innerhalb einer Kontrollschleife. Wenn Sie noch nicht vertraut damit sind, wie Sprachmodelle Funktionsaufrufe strukturieren, empfiehlt sich zuerst die Lektüre des Artikels zum Thema Function Calling.

Die Agentenschleife in vier Phasen

1. Modell: Liest die Aufgabenstellung und den bisherigen Verlauf.
2. Entscheidung: Fordert entweder ein Tool mit konkreten Argumenten an oder entscheidet, dass die Aufgabe gelöst ist, und formuliert die finale Antwort.
3. Werkzeug (Tool): Ihr lokaler Python-Code führt die angeforderte Funktion aus.
4. Beobachtung (Observation): Das Funktionsergebnis wird an den Gesprächsverlauf angehängt, und die Schleife kehrt zu Schritt 1 zurück.

Zusätzlich sind zwei Sicherheitsmechanismen unerlässlich: Ein striktes Schrittlimit (um Endlosschleifen und unkontrollierte API-Kosten zu verhindern) sowie ein lückenloses Decision-Log (um im Nachhinein jede Entscheidung und jeden Zwischenschritt nachvollziehen zu können).

Schritt 1: Entwicklungsumgebung vorbereiten

1. Installieren Sie Python 3.11 bis 3.13 von python.org (aktivieren Sie die Option „Add python.exe to PATH“).
2. Erstellen Sie im Projektverzeichnis eine virtuelle Umgebung: python -m venv .venv, gefolgt von .venv\Scripts\activate.
3. Installieren Sie die benötigten Pakete: pip install openai requests beautifulsoup4 python-dotenv.
4. Erstellen Sie einen API-Schlüssel bei OpenRouter und hinterlegen Sie ihn in einer .env-Datei als OPENROUTER_API_KEY=.... Setzen Sie dort zur Sicherheit ein Ausgabenlimit, etwa 2 USD (ca. 1,79 EUR; EZB-Referenzkurs: 1 EUR = 1,1181 USD). Details dazu gibt es im Beitrag zu OpenRouter.
5. Legen Sie im Ordner dane/faktury einige Testdateien ab. Im Starterpaket befinden sich drei Beispieldokumente: zwei Rechnungen in Fremdwährung und eine über 120 EUR.

Schritt 2: Werkzeuge als reguläre Python-Funktionen

Unser Agent erhält drei Hilfsfunktionen. Jede davon ist eine gewöhnliche Python-Funktion, die einen Textstring zurückgibt:

• szukaj_plikow (Dateisuche): Listet .txt-Dateien im Verzeichnis dane/ auf. Der Agent hat keinen Zugriff auf übergeordnete Verzeichnisse.
• kalkulator (Rechner): Berechnet mathematische Ausdrücke sicher über das Modul ast (ohne das unsichere eval). Da Sprachmodelle bei Kopfrechnen fehleranfällig sind, lagern wir Rechenoperationen strikt an das Tool aus.
• czytaj_strone (Webseite lesen): Lädt Webseiteninhalte oder API-Antworten herunter und kürzt sie auf maximal 4000 Zeichen, da jedes Zeichen als kostenpflichtiges Token in den Kontext einfließt.

Schritt 3: Der vollständige Agent in 76 Zeilen

"""02 - KI-Agent ohne Framework: Schleife Modell -> Tool -> Beobachtung -> Entscheidung.
Aufruf: python 02_agent_bez_frameworka.py "Summiere die Bruttobetraege der Rechnungen im Ordner dane/faktury."
"""
import ast, json, operator, os, pathlib, sys, time
import requests
from bs4 import BeautifulSoup
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
MODEL, MAX_KROKOW = os.getenv("MODEL", "openai/gpt-5.6-luna"), int(os.getenv("MAX_KROKOW", 8))
client = OpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"])
KATALOG = pathlib.Path("dane").resolve()  # Agent sieht ausschliesslich diesen Ordner

def szukaj_plikow(fraza: str = "") -> str:
    """Dateien in dane/ auflisten (inkl. Inhalt), optional gefiltert nach Suchbegriff."""
    wynik = []
    for p in sorted(KATALOG.rglob("*.txt")):
        tekst = p.read_text(encoding="utf-8")
        if fraza.lower() in tekst.lower() or fraza.lower() in p.name.lower():
            wynik.append(f"== {p.relative_to(KATALOG)} ==\n{tekst[:1500]}")
    return "\n".join(wynik) or "keine Dateien gefunden"

OPS = {ast.Add: operator.add, ast.Sub: operator.sub, ast.Mult: operator.mul, ast.Div: operator.truediv, ast.USub: operator.neg}
def kalkulator(wyrazenie: str) -> str:
    def licz(n):
        if isinstance(n, ast.Constant): return n.value
        if isinstance(n, ast.BinOp): return OPS[type(n.op)](licz(n.left), licz(n.right))
        if isinstance(n, ast.UnaryOp): return OPS[type(n.op)](licz(n.operand))
        raise ValueError("nur Zahlen und Grundrechenarten (+ - * /)")
    return str(round(licz(ast.parse(wyrazenie, mode="eval").body), 4))

def czytaj_strone(url: str) -> str:
    r = requests.get(url, timeout=20, headers={"User-Agent": "agenten-starter-paket/1.0"})
    tekst = BeautifulSoup(r.text, "html.parser").get_text(" ", strip=True)
    return tekst[:4000]  # Kuerzen: Zu lange Seiten verbrauchen unnoetig Token

NARZEDZIA = {"szukaj_plikow": szukaj_plikow, "kalkulator": kalkulator, "czytaj_strone": czytaj_strone}
def opis(nazwa, tekst, param, typ="string"):
    return {"type": "function", "function": {"name": nazwa, "description": tekst,
            "parameters": {"type": "object", "properties": {param: {"type": typ}}, "required": [param]}}}
TOOLS = [opis("szukaj_plikow", "Zeigt .txt-Dateien aus dem Ordner dane/ und deren Inhalt. Leere Phrase = alle Dateien.", "fraza"),
         opis("kalkulator", "Berechnet einen mathematischen Ausdruck, z. B. 2214+1180.8. Immer dieses Tool zum Rechnen nutzen.", "wyrazenie"),
         opis("czytaj_strone", "Ruft den Text einer Webseite oder eine API-Antwort unter der URL ab.", "url")]

def agent(zadanie: str) -> str:
    messages = [{"role": "system", "content": "Du bist ein Agent. Loese die Aufgabe mithilfe von Werkzeugen. Schreibe vor "
                 "jedem Werkzeugaufruf in einem Satz, warum du es nutzt. Waehrungskurse via NBP-API abrufen: "
                 "https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json."},
                {"role": "user", "content": zadanie}]
    log = open("agent_log.jsonl", "a", encoding="utf-8")
    koszt = 0.0
    for krok in range(1, MAX_KROKOW + 1):
        r = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
        koszt += getattr(r.usage, "cost", 0) or 0
        msg = r.choices[0].message
        messages.append(msg.model_dump(exclude_none=True))
        if not msg.tool_calls:
            print(f"--- Beendet nach {krok} Schritten, Kosten: {koszt:.5f} USD")
            return msg.content
        if msg.content: print(f"[Schritt {krok}] GEDANKE: {msg.content.strip()[:300]}")
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments or "{}")
            try:
                obs = NARZEDZIA[call.function.name](**args)
            except Exception as e:
                obs = f"FEHLER: {e}"
            print(f"[Schritt {krok}] AKTION: {call.function.name}({json.dumps(args, ensure_ascii=False)})")
            print(f"[Schritt {krok}] BEOBACHTUNG: {obs[:160]!r}")
            log.write(json.dumps({"t": time.strftime("%H:%M:%S"), "krok": krok, "narzedzie": call.function.name,
                                  "args": args, "obserwacja": obs[:500]}, ensure_ascii=False) + "\n")
            messages.append({"role": "tool", "tool_call_id": call.id, "content": obs})
    return f"Abgebrochen: Schrittlimit von {MAX_KROKOW} erreicht (Kosten: {koszt:.5f} USD)."

if __name__ == "__main__":
    print("\nERGEBNIS:\n" + agent(" ".join(sys.argv[1:]) or "Summiere die Bruttobetraege der Rechnungen im Ordner dane/faktury."))

Zentrale Bestandteile der Implementierung:

• for krok in range(1, MAX_KROKOW + 1): Die Ausführungsschleife mit hartem Limit (Standard: 8 Durchläufe).
• if not msg.tool_calls: Verlangt das Modell keine weiteren Tool-Aufrufe mehr, gilt die Aufgabe als gelöst und die Antwort wird ausgegeben.
• Fehlerbehandlung: Schlägt ein Tool fehl, stürzt das Skript nicht ab, sondern liefert „FEHLER: …“ als Beobachtung an das Modell zurück. Das Modell korrigiert sich in der Regel selbst.
• Jeder Schritt wird strukturiert in agent_log.jsonl abgelegt (Zeitstempel, Schritt, Werkzeug, Argumente, Rückgabe).
• Der System-Prompt weist das Modell an, vor jedem Tool-Einsatz kurz zu begründen, warum es das Werkzeug aufruft. Dies erleichtert das spätere Debugging enorm.

Testlauf 1: Rechnungen in gemischten Währungen

Hinweis: Der Testlauf wurde ursprünglich mit polnischen Prompts durchgeführt. Die nachfolgende Konsolenausgabe ist eine getreue Übersetzung des Testprotokolls.

> python 02_agent_bez_frameworka.py "Berechne die Gesamtausgaben der Rechnungen aus dem Ordner dane. Rechne die Euro-Rechnung zum heutigen NBP-Wechselkurs um."
[Schritt 1] GEDANKE: Zuerst lese ich alle Rechnungsdateien aus dem Ordner `dane` und rufe den aktuellen EUR-Kurs ueber die NBP-API ab, um die Betraege zusammenzurechnen.
[Schritt 1] AKTION: szukaj_plikow({"fraza": ""})
[Schritt 1] BEOBACHTUNG: '== faktury\\FV_2026_09_014.txt ==\nRECHNUNG Nr. FV/2026/09/014 (Beispieldaten)\nAusstellungsdatum: 2026-09-12\nVerkaeufer: Studio Beispiel Sp. z o.o.\nKaeufer'
[Schritt 1] AKTION: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"})
[Schritt 1] BEOBACHTUNG: '{"table":"A","currency":"euro","code":"EUR","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":4.3745}]}'
[Schritt 2] GEDANKE: Jetzt rechne ich die 120-EUR-Rechnung zum Kurs von 4,3745 um und addiere sie zu den beiden anderen Rechnungen ueber 2214,00 und 1180,80.
[Schritt 2] AKTION: kalkulator({"wyrazenie": "2214+1180.8+120*4.3745"})
[Schritt 2] BEOBACHTUNG: '3919.74'
--- Beendet nach 3 Schritten, Kosten: 0.00104 USD

ERGEBNIS:
Gesamtausgaben: **3 919,74** (in der Basiswaehrung).

Berechnung:
- Rechnung 1: **2 214,00**
- Rechnung 2: **1 180,80**
- Rechnung in EUR: 120 x 4,3745 = **524,94**

**Summe: 2 214,00 + 1 180,80 + 524,94 = 3 919,74**

Angewandter EUR-Kurs: **4,3745** (Stand: 02.10.2026).

Der Agent erstellte seinen Ablaufplan selbstständig: In Schritt 1 las er parallel die Dateien ein und fragte den Wechselkurs über die offizielle API ab (Tabelle 192/A/NBP/2026 vom 2. Oktober, da der 4. Oktober ein Sonntag war). Im zweiten Schritt berechnete er das Gesamtergebnis über das Rechner-Tool. In Schritt 3 folgte die Ausgabe. Das Ergebnis von 3919,74 stimmt exakt: 2214 + 1180,80 + 120 × 4,3745 = 3919,74. Gesamtkosten für drei API-Anfragen: rund 0,001 USD (ca. 0,0009 EUR; EZB-Kurs: 1 EUR = 1,1181 USD).

Testlauf 2: Externe Webseite plus lokale Dateien

Hinweis: Übersetzung des ursprünglichen Testprotokolls auf Basis polnischer Eingaben.

> python 02_agent_bez_frameworka.py "Lies die Seite https://pl.wikipedia.org/wiki/Model_Context_Protocol und fasse in 3 Punkten zusammen, wozu MCP dient. Pruefe dann im Ordner dane, ob eine Notiz mit einer Frist existiert, und nenne die verbleibenden Tage ab dem 4. Oktober 2026."
[Schritt 1] GEDANKE: Ich lese die angegebene Wikipedia-Seite, um in 3 Punkten zusammenzufassen, wozu MCP dient.
[Schritt 1] AKTION: czytaj_strone({"url": "https://pl.wikipedia.org/wiki/Model_Context_Protocol"})
[Schritt 1] BEOBACHTUNG: 'Model Context Protocol - Wikipedia, die freie Enzyklopaedie Zum Inhalt springen Hauptmenue Navigation Hauptseite Zufaelliger Artikel'
[Schritt 2] GEDANKE: Ich durchsuche den Ordner dane nach einer Notiz mit Fristangabe.
[Schritt 2] AKTION: szukaj_plikow({"fraza": ""})
[Schritt 2] BEOBACHTUNG: '== faktury\\FV_2026_09_014.txt ==\nRECHNUNG Nr. FV/2026/09/014 (Beispieldaten)\nAusstellungsdatum: 2026-09-12\nVerkaeufer: Studio Beispiel Sp. z o.o.\nKaeufer'
[Schritt 3] GEDANKE: Ich berechne die Differenz zwischen dem 4. und dem 7. Oktober 2026, um die genaue Anzahl an Tagen anzugeben.
[Schritt 3] AKTION: kalkulator({"wyrazenie": "7-4"})
[Schritt 3] BEOBACHTUNG: '3'
--- Beendet nach 4 Schritten, Kosten: 0.00130 USD

ERGEBNIS:
**MCP dient folgenden Zwecken:**
1. Standardisierung der Art und Weise, wie KI-Systeme und Large Language Models mit externen Werkzeugen, Systemen und Datenquellen interagieren.
2. Bereitstellung einer einheitlichen Schnittstelle fuer Modelle, um Dateien zu lesen, Funktionen aufzurufen und Kontext abzufragen.
3. Nahtlose Integration von KI in Praxisanwendungen wie Unternehmensdokumente, CRM-Systeme, Datenbanken und Entwicklungsumgebungen.

In der Datei `dane/faktury/notatka.txt` wurde folgende Frist gefunden: **Rechnungen fuer September bis zum 7. Oktober 2026 an die Buchhaltung senden**.

Vom **4. Oktober 2026** bis zu dieser Frist verbleiben noch **3 Tage**.

Hier hat der Agent zwei getrennte Informationsquellen kombiniert. Ein interessantes Detail aus dem Log: Der Anfang der Wikipedia-Seite bestand zunächst aus Navigationsmenüs („Zum Inhalt springen…“). Durch das Limit von 4000 Zeichen blieb ausreichend Platz für den eigentlichen Inhalt; bei umfangreicheren Webseiten empfiehlt es sich jedoch, gezielt nur den <main>- oder <article>-Tag auszulesen. Die Subtraktion 7 - 4 über den Taschenrechner wirkt trivial, ist aber exakt das gewünschte Verhalten: Das Modell soll verlässlich rechnen statt schätzen.

Testlauf 3: Agent erreicht das Schrittlimit

Für diesen Testlauf habe ich das Limit auf 2 Schritte reduziert und eine zusätzliche Währungskonvertierung verlangt:

> MAX_KROKOW=2 python 02_agent_bez_frameworka.py "Berechne die Gesamtausgaben aus dem Ordner dane. Rechne die Euro-Rechnung um, frage zusaetzlich den Dollarkurs ab und gib die Gesamtsumme auch in USD an."
[Schritt 1] GEDANKE: Zuerst lese ich den Inhalt aller Dateien im Ordner `dane` und frage parallel die aktuellen EUR- und USD-Kurse ab.
[Schritt 1] AKTION: szukaj_plikow({"fraza": ""})
[Schritt 1] BEOBACHTUNG: '== faktury\\FV_2026_09_014.txt ==\nRECHNUNG Nr. FV/2026/09/014 (Beispieldaten)\nAusstellungsdatum: 2026-09-12\nVerkaeufer: Studio Beispiel Sp. z o.o.\nKaeufer'
[Schritt 1] AKTION: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"})
[Schritt 1] BEOBACHTUNG: '{"table":"A","currency":"euro","code":"EUR","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":4.3745}]}'
[Schritt 1] AKTION: czytaj_strone({"url": "https://api.nbp.pl/api/exchangerates/rates/a/usd/?format=json"})
[Schritt 1] BEOBACHTUNG: '{"table":"A","currency":"US-Dollar","code":"USD","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":3.8881}]}'
[Schritt 2] GEDANKE: Anhand der Rechnungen erfasse ich die drei Betraege und berechne die Gesamtsumme.
[Schritt 2] AKTION: kalkulator({"wyrazenie": "2214+1180.80+120*4.3745"})
[Schritt 2] BEOBACHTUNG: '3919.74'

ERGEBNIS:
Abgebrochen: Schrittlimit von 2 erreicht (Kosten: 0.00079 USD).

Da die Schritte aufgebraucht waren, beendete das Skript die Schleife kontrolliert mit einer klaren Meldung, anstatt unbegrenzt weiterzulaufen. In Produktivumgebungen empfiehlt sich ein Puffer von 8 bis 15 Schritten sowie das Speichern des kompletten Status im Log, um abgebrochene Läufe wieder aufnehmen zu können. Ein Auszug aus der Logdatei dieses Durchlaufs:

> type agent_log.jsonl   (letzte 3 Eintraege)
{"t": "13:50:52", "krok": 1, "narzedzie": "czytaj_strone", "args": {"url": "https://api.nbp.pl/api/exchangerates/rates/a/eur/?format=json"}, "obserwacja": "{\"table\":\"A\",\"currency\":\"euro\",\"code\":\"EUR\",\"rates\":[{\"no\":\"192/A/NBP/2026\",\"effectiveDate\":\"2026-10-02\",\"mid\":4.3745}]}"}
{"t": "13:50:52", "krok": 1, "narzedzie": "czytaj_strone", "args": {"url": "https://api.nbp.pl/api/exchangerates/rates/a/usd/?format=json"}, "obserwacja": "{\"table\":\"A\",\"currency\":\"US-Dollar\",\"code\":\"USD\",\"rates\":[{\"no\":\"192/A/NBP/2026\",\"effectiveDate\":\"2026-10-02\",\"mid\":3.8881}]}"}
{"t": "13:50:56", "krok": 2, "narzedzie": "kalkulator", "args": {"wyrazenie": "2214+1180.80+120*4.3745"}, "obserwacja": "3919.74"}

Typische Fehlerquellen bei Agenten (und Lösungen)

Derselbe Agent mit dem OpenAI Agents SDK

Sobald das Prinzip der Agentenschleife verstanden ist, verliert ein Framework seinen Zauber. Das OpenAI Agents SDK bildet exakt dieselben 76 Zeilen ab: Es sendet Anfragen an das Modell, führt Werkzeuge aus, überwacht das Schrittlimit (max_turns) und protokolliert den Verlauf. Die Funktionsdefinition wird direkt aus der Signatur und dem Docstring per Decorator @function_tool abgeleitet. Auch Modelle von Drittanbietern lassen sich anbinden, sofern der Client auf OpenRouter verweist:

"""03 - Identischer Agent wie in 02, portiert auf das OpenAI Agents SDK (openai-agents).
Schleife, Tool-Ausfuehrung und Schrittbegrenzung uebernimmt der Runner.
Aufruf: python 03_agent_openai_sdk.py "Berechne die Gesamtausgaben der Rechnungen im Ordner dane."
"""
import asyncio, os, sys
from dotenv import load_dotenv
from openai import AsyncOpenAI
from agents import Agent, OpenAIChatCompletionsModel, Runner, function_tool, set_tracing_disabled

import importlib
narz = importlib.import_module("02_agent_bez_frameworka")  # Wiederverwendung der bestehenden Tools

load_dotenv()
set_tracing_disabled(True)  # Tracing sendet Telemetrie an OpenAI - bei OpenRouter deaktivieren
model = OpenAIChatCompletionsModel(
    model=os.getenv("MODEL", "openai/gpt-5.6-luna"),
    openai_client=AsyncOpenAI(base_url="https://openrouter.ai/api/v1", api_key=os.environ["OPENROUTER_API_KEY"]))

@function_tool
def szukaj_plikow(fraza: str = "") -> str:
    """Zeigt .txt-Dateien aus dem Ordner dane/ und deren Inhalt. Leere Phrase = alle Dateien."""
    return narz.szukaj_plikow(fraza)

@function_tool
def kalkulator(wyrazenie: str) -> str:
    """Berechnet einen mathematischen Ausdruck, z. B. 2214+1180.8. Immer dieses Tool zum Rechnen nutzen."""
    return narz.kalkulator(wyrazenie)

@function_tool
def czytaj_strone(url: str) -> str:
    """Ruft den Text einer Webseite oder eine API-Antwort unter der URL ab."""
    return narz.czytaj_strone(url)

agent = Agent(
    name="Rechnungs-Assistent",
    instructions="Loese die Aufgabe mit den Werkzeugen. Waehrungskurse via: https://api.nbp.pl/api/exchangerates/rates/a/{kod}/?format=json.",
    model=model, tools=[szukaj_plikow, kalkulator, czytaj_strone])

async def main():
    zadanie = " ".join(sys.argv[1:]) or "Berechne die Gesamtausgaben der Rechnungen im Ordner dane."
    wynik = await Runner.run(agent, zadanie, max_turns=8)
    for item in wynik.new_items:  # Protokoll der Zwischenschritte
        if item.type == "tool_call_item":
            print("AKTION:", item.raw_item.name, item.raw_item.arguments)
        elif item.type == "tool_call_output_item":
            print("BEOBACHTUNG:", str(item.output)[:120].replace("\n", " "))
    u = wynik.context_wrapper.usage
    print(f"\nERGEBNIS:\n{wynik.final_output}\n\nModellanfragen: {u.requests}, Token: {u.input_tokens} In / {u.output_tokens} Out")

asyncio.run(main())

Hinweis: Konsolenprotokoll übersetzt aus dem ursprünglichen Testlauf.

> python 03_agent_openai_sdk.py "Berechne die Gesamtausgaben der Rechnungen im Ordner dane. Rechne die Euro-Rechnung um."
AKTION: szukaj_plikow {"fraza":""}
AKTION: czytaj_strone {"url":"https://api.nbp.pl/api/exchangerates/rates/a/EUR/?format=json"}
BEOBACHTUNG: == faktury\FV_2026_09_014.txt == RECHNUNG Nr. FV/2026/09/014 (Beispieldaten) Ausstellungsdatum: 2026-09-12 Verkaeufer
BEOBACHTUNG: {"table":"A","currency":"euro","code":"EUR","rates":[{"no":"192/A/NBP/2026","effectiveDate":"2026-10-02","mid":4.3745}]}
AKTION: kalkulator {"wyrazenie":"2214+1180.8"}
AKTION: kalkulator {"wyrazenie":"120*4.3745"}
AKTION: kalkulator {"wyrazenie":"2214+1180.8+120*4.3745"}
BEOBACHTUNG: 3394.8
BEOBACHTUNG: 524.94
BEOBACHTUNG: 3919.74

ERGEBNIS:
Gesamtausgaben: **3 919,74**.

Berechnung:
- Rechnungen Basiswaehrung: 2 214,00 + 1 180,80 = **3 394,80**
- Rechnung in Euro: 120 EUR x Kurs 4,3745 = **524,94**
- Gesamt: **3 394,80 + 524,94 = 3 919,74**

Modellanfragen: 3, Token: 1970 In / 323 Out

Das Ergebnis ist identisch: 3 Modellanfragen, 1970 Input- und 323 Output-Token. Zwei wichtige Aspekte für die Praxis:

• set_tracing_disabled(True): Das SDK sendet Tracing-Daten standardmäßig an OpenAI. Bei der Nutzung von OpenRouter ohne separaten OpenAI-Key führt dies zu Konsolenfehlern. Auch bei sensiblen Unternehmensdaten sollte dieser Datenabfluss unterbunden werden.
• OpenAIChatCompletionsModel: Das SDK adressiert standardmäßig die Responses-API von OpenAI. Da viele Drittanbieter (darunter OpenRouter) auf Chat Completions aufsetzen, kapseln wir den Client in diese Modellklasse.

Umsetzung mit dem Claude Agent SDK

Das Claude Agent SDK stellt die Kernengine von Claude Code als Python-Bibliothek bereit. Dateizugriffe und Konsolenbefehle sind direkt integriert; eigene Tools lassen sich über einen lokalen MCP-Server im Arbeitsspeicher anbinden. Den Code dazu finden Sie im Starterpaket unter frameworki/e_claude_agent_sdk.py, eine ausführliche Gegenüberstellung aller Bibliotheken im Beitrag Frameworks für KI-Agenten im Vergleich. Unter Windows traten im Test zwei Besonderheiten auf:

• Das SDK startet den claude-Prozess im Hintergrund und blockiert aus Sicherheitsgründen den Start der Datei claude.cmd, die von npm angelegt wird. Die Lösung besteht darin, claude.exe explizit über den Parameter cli_path anzugeben oder Claude Code nativ einzurichten.
• Das SDK lädt Konfigurationsparameter automatisch aus ~/.claude/settings.json. Ist dort ein abweichender ANTHROPIC_BASE_URL hinterlegt, werden Aufrufe dorthin umgeleitet. Das lässt sich mit setting_sources=[] verhindern.

Mit Claude Haiku 4.5 via OpenRouter benötigte die Rechnungsaufgabe im Test 15 bis 18 Sekunden und verursachte Kosten von 0,013 bis 0,018 USD (ca. 0,0116-0,0161 EUR; EZB-Kurs: 1 EUR = 1,1181 USD) über drei Testläufe. Meine schlanke 76-Zeilen-Schleife ohne Framework benötigte mit demselben Haiku-Modell lediglich 7,1 Sekunden bei ca. 0,0063 EUR (0,007 USD). Dieser Mehraufwand rührt von den umfangreichen Systemprompts und Reasoning-Schleifen der Claude-Code-Engine her. Im Gegenzug stehen fertige Berechtigungsverwaltungen, Dateitools und Sub-Agenten zur Verfügung.

Wann selbst schreiben, wann ein SDK nutzen?

• Eigener Code: Zum Lernen unverzichtbar, für fokussierte Agenten mit 2 bis 5 Tools und immer dann, wenn Sie volle Kontrolle über jedes übertragene Token benötigen.
• OpenAI Agents SDK: Wenn Sie strukturierte Übergaben zwischen mehreren Agenten (Handoffs), Guardrails und Tracing benötigen.
• Claude Agent SDK: Wenn der Agent primär direkt im Dateisystem und auf der Konsole arbeiten soll, vergleichbar mit Claude Code.
• LangGraph: Wenn komplexe, verzweigte Abläufe mit Speicherpunkten (Checkpoints) und menschlichen Freigaben (Human-in-the-loop) gefragt sind.
• No-Code-Lösungen: Tools wie n8n, Make oder Gumloop eignen sich für visuelle Workflows ohne Programmierung.

Häufige Fragen (FAQ)

Muss man programmieren können, um einen KI-Agenten zu bauen?

Um die Funktionsweise zu verstehen, genügen grundlegende Programmierkenntnisse. Das Skript in dieser Anleitung umfasst lediglich 76 Zeilen und ist sofort lauffähig. Für Workflows ganz ohne Code bieten sich Plattformen wie n8n oder Gumloop an.

Was kostet der Betrieb eines KI-Agenten?

Die Kosten hängen vom gewählten Modell und der Anzahl der Iterationen ab. Unser schlanker Agent mit einem kostengünstigen Modell benötigte rund 0,001 USD (ca. 0,0009 EUR; EZB: 1 EUR = 1,1181 USD) pro Durchlauf. Dieselben Schritte auf Claude Haiku kosteten zwischen 0,007 und 0,018 USD (ca. 0,0063-0,0161 EUR). Bei High-End-Modellen mit Preisen um ca. 4,47 EUR (5 USD) pro Million Input-Token steigen die Kosten entsprechend. Da mit jedem Schritt der gesamte bisherige Verlauf erneut übertragen wird, wachsen die Gesamtkosten progressiv.

Welches Sprachmodell eignet sich am besten für Agenten?

Voraussetzung ist eine zuverlässige Unterstützung von Function Calling. Für erste Experimente reicht ein günstiges Modell mit Tool-Support über OpenRouter. Für anspruchsvolle Aufgaben mit vielen Zwischenschritten sind leistungsfähigere Modelle ratsam, da sie den Gesamtplan seltener aus dem Blick verlieren.

Funktioniert der Agent auch mit lokalen Modellen?

Ja. Programme wie Ollama stellen eine OpenAI-kompatible API bereit (http://localhost:11434/v1). Im Python-Code müssen Sie dazu lediglich base_url und den Modellnamen anpassen. Kleinere lokale Modelle neigen allerdings häufiger zu fehlerhaften Tool-Argumenten.

Wie lässt sich verhindern, dass der Agent unerwünschte Aktionen ausführt?

Geben Sie dem Agenten ausschließlich notwendige Werkzeuge an die Hand, im Idealfall rein lesende Funktionen. Beschränken Sie Verzeichnispfade strikt auf Arbeitsordner. Irreversible Aktionen wie Lösch- oder Schreibvorgänge sollten stets eine manuelle Bestätigung durch den Nutzer erfordern. Protokollieren Sie zudem sämtliche Schritte.

Funktioniert die Agentenlogik unabhängig von der Sprache?

Ja. System-Prompts, Tool-Beschreibungen und Ausgaben können flexibel formuliert werden. Wir haben die Tests mit polnischsprachigen Prompts und Daten durchgeführt; moderne Modelle handhaben unterschiedliche Sprachen problemlos. Funktions- und Variablennamen im Code sollten zur Vermeidung von Kodierungsproblemen idealerweise auf Standard-ASCII-Zeichen beschränkt bleiben.

Quellen und Prüfdatum

• Anthropic: Building effective agents (geprüft am 04.10.2026).
• OpenAI Agents SDK Dokumentation (geprüft am 04.10.2026).
• Claude Agent SDK Dokumentation (geprüft am 04.10.2026).
• Wechselkursdaten: NBP API, Tabelle A.
• Testläufe: Lokale Testumgebung, 4. Oktober 2026, 13:50-13:55 Uhr.

// weiterlesenLinear Schritt für Schritt: Team, Cycles, Roadmap und GitHubAnleitungenRailway Schritt für Schritt: App deployen mit GitHub und DatenbankAnleitungenTypeless Schritt für Schritt: Berechtigungen, Shortcuts und WörterbuchAnleitungen

Kinetyra