KI-Agenten-Builder

Diese Seite ist der kanonische Leitfaden zum Bau von LLM-Agenten mit dem AI Agent Builder von DevUtilities. Nutzen Sie den geführten Workflow oben beim Lesen oder springen Sie zu einem Thema unten. Schemas, MCP-JSON, Prompts und Token-Zählungen bleiben in Ihrem Browser — nichts wird für Inferenz hochgeladen.

AI Agent Builder ist eine clientseitige Werkstatt zum Zusammenstellen produktionsreifer Agent-Configs: JSON-Schema-Tools für OpenAI Function Calling, mcpServers-Validierung für Cursor und Claude Desktop, System-Prompts, kombinierte Token-Budgets und exportierbare Artefakte für die Team-Übergabe.

Was Sie erhalten

• Vier Workflow-Modi: voller Agent, nur Function Calling, MCP-Setup, strukturierte Antwort
• Starter-Templates: Filesystem MCP, OpenAI Function Calling, strukturierter Klassifikator
• Beispiel-JSON → JSON-Schema-Inferenz mit optionalem strict additionalProperties: false
• Lokales MCP-Lint mit JSON-Pointer-Fehlern und Warnungen
• Kombiniertes Token-Budget über Prompt, minifizierte Tools und MCP-JSON
• Exports: OpenAI tools JSON, response_format, MCP-Config, Markdown-Zusammenfassung, volles Bundle

Nutzen Sie diesen Builder, wenn

• Sie brauchen OpenAI tools JSON und wollen JSON Schema nicht von Hand schreiben
• Sie verdrahten Cursor- oder Claude-Desktop-MCP-Server und wollen Lint vor dem Einfügen
• Sie müssen beweisen, dass Prompt + Tools eines Agenten noch in ein Kontextfenster passen
• Sie wollen eine persistierte Sitzung, die Schema → MCP → Prompt → Export verkettet

Bevorzugen Sie ein Standalone-Tool, wenn

• Sie brauchen nur tiefen Encoding-Vergleich oder Kostenrechnung → LLM Token Counter
• Sie brauchen nur einmaliges MCP-Lint ohne Prompts → MCP Validator
• Sie brauchen nur Schema-Inferenz aus einer Stichprobe → Structured Output Generator

Wählen Sie einen Modus, bevor Sie Tools definieren. Modi blenden irrelevante Schritte aus, damit Sie nicht gegen leere Panels kämpfen.

Erstmaliger Durchlauf für einen vollen Agenten. Template-Shortcuts überspringen mehrere dieser Schritte.

1. Wählen Sie Voller Agent (oder laden Sie das OpenAI-Function-Calling-Template).
2. Unter Tools definieren fügen Sie jedes Tool mit klarem Namen, Beschreibung und repräsentativem Beispiel-JSON für Argumente hinzu.
3. Prüfen Sie das inferierte JSON Schema — aktivieren Sie den Strict-Modus für OpenAI Structured Outputs / Strict Tool Calling.
4. Fügen Sie mcpServers-JSON ein oder bearbeiten Sie es, wenn der Agent in Cursor oder Claude Desktop läuft; beheben Sie jeden Fehler vor dem Weitergehen.
5. Schreiben Sie System Instructions, die dem Modell sagen, wann welches Tool aufzurufen ist und was nie erfunden werden darf.
6. Öffnen Sie Token-Budget, wählen Sie cl100k_base oder o200k_base und bestätigen Sie, dass die kombinierte Summe zu Ihrem Modell passt.
7. Exportieren Sie OpenAI tools JSON für die API, MCP-Config für den Desktop-Client und eine Markdown-Zusammenfassung für das Team.
8. Optional exportieren Sie das volle Bundle-JSON, damit ein anderer Engineer denselben Sitzungszustand später neu laden kann.

Problem: Sie brauchen einen Kundensupport-Agenten, der Wetter und Bestellungen per OpenAI Function Calling nachschlagen kann, aber handgeschriebenes JSON Schema scheitert weiter an der strikten Validierung.

So löst dieses Tool es

1. Wählen Sie den Function-Calling-Modus oder laden Sie das OpenAI-Function-Calling-Template (Wetter + Bestellabfrage).
2. Bearbeiten Sie das Beispiel-JSON so, dass jedes Feld, das Sie in Produktion brauchen, mindestens einmal vorkommt — fehlende Keys werden keine required Properties.
3. Aktivieren Sie den Strict-Modus, damit jedes Objekt additionalProperties: false ausgibt.
4. Straffen Sie den System-Prompt: Bestell-IDs bestätigen, nie Tool-Ergebnisse erfinden, Antworten knapp halten.
5. Prüfen Sie das Token-Budget unter o200k_base, wenn Sie auf GPT-4o deployen.
6. Exportieren Sie OpenAI tools JSON und fügen Sie es in Ihren Chat-Completions- oder Responses-API-Client ein.

Ergebnis: ein striktes, API-bereites Tools-Array plus ein Prompt, der zu den Schemas passt — ohne separaten Schema-Editor.

Problem: Cursor oder Claude Desktop lehnt Ihre mcp.json ab, oder der Filesystem-Server startet mit dem falschen Verzeichnis und sieht zu viel der Festplatte.

So löst dieses Tool es

1. Wählen Sie den MCP-Setup-Modus oder laden Sie das Filesystem-MCP-Template.
2. Ersetzen Sie /path/to/allowed/dir durch einen absoluten Pfad zum einzigen Verzeichnis, das der Agent anfassen darf.
3. Führen Sie die Validierung aus — beheben Sie fehlende command/args, ungültige URLs und nicht-string env-Werte.
4. Nutzen Sie Platzhalter-env-Werte (keine Produktions-Secrets) während des Lints im Browser.
5. Exportieren Sie validiertes mcpServers-JSON in Ihre Cursor- oder Claude-Desktop-Config.
6. Fügen Sie System Instructions hinzu, die vor destruktiven Dateioperationen eine Bestätigung verlangen.

Ergebnis: eine gelintete MCP-Client-Config und ein Prompt, der zu den Server-Fähigkeiten passt, bevor Sie die Desktop-App neu starten.

Problem: Das Modell soll Sentiment, Konfidenz, Themen und eine kurze Zusammenfassung als JSON zurückgeben — Freitext-Antworten brechen Ihren Downstream-Parser.

So löst dieses Tool es

1. Wählen Sie den Modus Strukturierte Antwort oder laden Sie das Template für den strukturierten Klassifikator.
2. Bearbeiten Sie das Beispiel-JSON so, dass es exakt der Form entspricht, die Ihre Pipeline erwartet.
3. Aktivieren Sie den Strict-Modus, damit undeclared Keys zur Validierungszeit abgelehnt werden.
4. Schreiben Sie einen System-Prompt, der Prosa außerhalb des JSON-Objekts verbietet.
5. Exportieren Sie response_format json_schema für OpenAI Structured Outputs.
6. Prüfen Sie, dass das Token-Budget noch Platz für das Eingabedokument lässt, das Sie klassifizieren.

Ergebnis: ein einzelnes Ausgabe-Schema, das Sie in Structured-Output-APIs mit passenden Instructions einsetzen können.

Problem: Nach drei Tools und einer langen MCP-Config passt der kombinierte Prompt des Agenten nicht mehr in das praktische Budget von GPT-4o, sobald Chat-Historie enthalten ist.

So löst dieses Tool es

1. Öffnen Sie den Token-Budget-Schritt und notieren Sie die kombinierte Summe aus Prompt + minifizierte Tools + MCP-JSON.
2. Kürzen Sie Tool-Beschreibungen und entfernen Sie ungenutzte Beispiel-Felder, die required Schemas aufblähen.
3. Verschieben Sie ausführlichen Policy-Text aus dem immer aktiven System-Prompt in On-Demand-Retrieval.
4. Wenn Sie nur tiefere Encoding-Mathematik brauchen, kopieren Sie die zusammengestellte Payload in LLM Token Counter.
5. Exportieren Sie erst neu, wenn das Budget komfortablen Spielraum für Historie und Completions zeigt.

Ergebnis: Sie fangen Überlauf im Builder ab — nicht nach dem ersten Produktions-400-Fehler.

Beispiel-JSON muss striktes JSON sein. Nur Keys im Beispiel werden required Properties. Verschachtelte Objekte und Arrays inferieren Typen aus den Sample-Werten.

Faustregeln

• Nehmen Sie jedes Feld auf, das das Modell senden dürfen soll — Auslassen heißt „nicht required“, nicht „optional mit Default“.
• Nutzen Sie realistische Enums als String-Samples und bearbeiten Sie das Schema von Hand, wenn Sie ein explizites Enum-Array brauchen.
• Aktivieren Sie den Strict-Modus, um additionalProperties: false auf jedem Objekt auszugeben — empfohlen für OpenAI Structured Outputs und Strict Tool Calling.
• Leere Arrays inferieren schwache Item-Typen — fügen Sie mindestens ein repräsentatives Element hinzu.

Stdio-Server brauchen command und typischerweise args. Remote-Server brauchen eine gültige http- oder https-url. Env-Werte müssen Strings sein. Fehler blockieren Export-Vertrauen; Warnungen verdienen einen manuellen Durchgang.

Übliche Client-Envelopes

• Top-Level-Key muss "mcpServers" nach Cursor- und Claude-Desktop-Konventionen sein
• Filesystem-Server sollten absolute Allow-List-Pfade nutzen
• Bevorzugen Sie Env-Platzhalter beim Bearbeiten im Browser; echte Secrets nur auf der lokalen Maschine injizieren

Token-Zählungen kombinieren System-Prompt, minifizierte Tool-Schemas und MCP-JSON. Wählen Sie cl100k_base für GPT-4-/Claude-Näherung oder o200k_base für GPT-4o. Zählungen nutzen lokale tiktoken-Tabellen — keine API-Aufrufe.

• Behandeln Sie die Zahl als Untergrenze: Chat-Historie und Tool-Ergebnisse kommen zur Laufzeit hinzu
• Prüfen Sie nach jeder Schema- oder Prompt-Änderung erneut
• Nutzen Sie LLM Token Counter, wenn Sie Boundary-Maps oder monatliche Kostenkarten auf einer Custom-Payload brauchen

Symptome: OpenAI lehnt die Tools-Payload ab, oder das Modell kann Argumente nicht übergeben, die Ihre App tatsächlich braucht.

Warum es passiert

Strikte Schemas lehnen undeclared Keys ab. Fehlte ein Feld im Beispiel-JSON, wurde es nie eine Property. Ist der Strict-Modus aus, können OpenAI-Structured-Output-Limits offene Objekte trotzdem ablehnen.

Diagnose

Vergleichen Sie die inferierten Schema-Properties mit den Argumenten, die Ihre Anwendung sendet. Prüfen Sie, dass der Strict-Modus aktiv ist, wenn Sie OpenAI Structured Outputs ansteuern.

Fixes

1. Fügen Sie fehlende Keys zum Beispiel-JSON hinzu und generieren Sie das Schema neu.
2. Aktivieren Sie den Strict-Modus, damit additionalProperties: false über verschachtelte Objekte konsistent ist.
3. Kürzen Sie nicht unterstützte Konstrukte (tief verschachteltes oneOf, exotische Typen) gemäß OpenAIs Structured-Output-Limits.
4. Exportieren Sie tools JSON neu und testen Sie mit einer bekannten gültigen Argument-Payload erneut.

Symptome: Validierungsfehler bei command/url, Client startet den Server nicht, oder Remote-Transport verbindet nie.

Warum es passiert

Stdio-Einträge ohne command, Remote-Einträge ohne http(s)-URLs, numerische Env-Werte oder falsche Top-Level-Keys brechen Client-Parser.

Diagnose

Lesen Sie den JSON-Pointer jedes Lint-Fehlers. Bestätigen Sie, dass der Envelope mcpServers nutzt und jeder Server entweder stdio (command) oder remote (url) ist — kein kaputtes Hybrid.

Fixes

1. Fügen Sie command und args für Stdio-Server hinzu; setzen Sie alle Env-Werte als Strings in Anführungszeichen.
2. Nutzen Sie http://- oder https://-URLs für Remote-MCP-Transports.
3. Korrigieren Sie den Top-Level-Key-Namen zu mcpServers.
4. Validieren Sie erneut, bis Fehler weg sind; priorisieren Sie Warnungen vor dem Shipping.

Symptome: API-Keys erscheinen in exportiertem JSON, Git-Diffs oder Screenshots des Builders.

Warum es passiert

MCP-Env-Blöcke sind Plain-JSON. Produktions-Secrets in ein Browser-Tool einzufügen — auch ein lokales — erhöht Leak-Risiko über Zwischenablage, Screen-Share und versehentliche Commits.

Diagnose

Durchsuchen Sie Exports und das MCP-Panel nach sk-, Bearer- oder Vendor-Key-Mustern. Prüfen Sie, dass committed Configs nur Platzhalter enthalten.

Fixes

1. Ersetzen Sie Secrets durch ${ENV_VAR}-Platzhalter im Builder.
2. Injizieren Sie echte Werte nur im lokalen Desktop-Client oder Deployment-Secret-Store.
3. Rotieren Sie jeden Key, der in Chat, Tickets oder geteilte Screens eingefügt wurde.
4. Fügen Sie einen Pre-Commit-Secret-Scan für mcp.json und Agent-Bundle-Dateien hinzu.

Dieser Workspace lädt Ihre Config nicht hoch — aber Zwischenablage und Git können sie trotzdem leaken.

• Committen Sie nie API-Keys in MCP-Env-Blöcken — nutzen Sie Umgebungsvariablen-Platzhalter
• Nutzen Sie absolute Least-Privilege-Pfade für Filesystem-MCP-Server
• Prüfen Sie das Token-Budget, bevor Sie große Few-Shot-Beispiele in Produktions-Prompts aufnehmen
• Bevorzugen Sie strikte Schemas, damit Tools keine unerwarteten Keys akzeptieren
• Behandeln Sie exportierte Bundles als sensibel, wenn sie interne Tool-Namen oder Infra-Hosts enthalten

• Starten Sie von einem Template und löschen Sie unnötige Tools — kleinere Schemas sind günstiger und sicherer
• Benennen Sie Tools mit klaren Verben (lookup_order, get_weather), die zu den System-Prompt-Instructions passen
• Halten Sie eine Single Source of Truth: exportieren Sie aus diesem Builder statt divergenter Schema-Kopien
• Validieren Sie MCP nach jeder Pfad- oder Command-Änderung erneut
• Dokumentieren Sie das Token-Budget im Markdown-Export, damit Reviewer Kostenwirkung in PRs sehen
• Nutzen Sie LLM Token Counter für tiefe Encoding-Diffs; nutzen Sie diesen Builder für den zusammengestellten Agenten