Jev AI API und KI-Agenten: Praxisleitfaden für zuverlässige Agent-Workflows

Ein KI-Agent braucht mehr als ein Sprachmodell, das plausible Antworten formulieren kann. Er muss auch entscheiden, welches Modell aufgerufen wird, ob ein Tool sicher eingesetzt werden kann, wann zusätzlicher Kontext nötig ist und wann ein Mensch übernehmen sollte. Die Jev-AI-API ist für diese Entscheidungsebene konzipiert: Du sendest einen State und typisierte Fragen und verwendest die strukturierten Antworten anschließend im Anwendungscode.

Dieser Leitfaden erklärt, wie du die Jev-AI-API mit einem KI-Agenten verbindest – beginnend mit einer einzelnen, klar begrenzten Entscheidung bis hin zu Routing, Schutzprüfungen vor Tool-Aufrufen und menschlicher Prüfung. Wenn du das Modell noch nicht kennst, lies zunächst die Anleitung zur Verwendung des Jev-AI-Modells, bevor du die folgenden Agent-Muster umsetzt.

Inhaltsverzeichnis

• Warum Jev AI in eine Agent-Architektur gehört
• Eine minimale Architektur
• Schritt 1: Entscheidungen vor den Tools definieren
• Schritt 2: State und Fragen gestalten
• Schritt 3: Die Jev-AI-API aufrufen
• Schritt 4: Antworten mit dem Agent-Ablauf verbinden
• Schritt 5: Den Jev Agent Skill hinzufügen
• Schutzprüfungen für Tool-Aufrufe
• Menschliche Prüfung und Evaluierung
• Checkliste für den Produktivbetrieb
• Häufige Fragen

Warum Jev AI in eine Agent-Architektur gehört

Ein Agent-Workflow umfasst üblicherweise mindestens zwei unterschiedliche Aufgaben:

1. Generierung und Schlussfolgern – eine Anfrage verstehen, Inhalte entwerfen, Informationen zusammenfassen oder eine Aktionsfolge planen.
2. Begrenzte Entscheidungen – einen Ablauf auswählen, ein Risiko bewerten, eine Bedingung prüfen oder entscheiden, ob ein Tool-Aufruf genehmigt werden muss.

Generative LLMs eignen sich für die erste Aufgabe, Jev für die zweite. Jev liefert typisierte Entscheidungen, die eine Anwendung direkt verarbeiten kann, statt Code einen Absatz analysieren oder einer uneingeschränkten JSON-Antwort vertrauen zu lassen.

Diese Trennung ist wichtig: Ein Agent sollte nicht dasselbe offen formulierte Modell einen Plan erstellen und anschließend stillschweigend jede darin enthaltene Aktion genehmigen lassen. Eine separate Entscheidungsebene macht die Zuständigkeiten deutlich:

• Der Agent kann eine Aktion vorschlagen.
• Jev kann eine klar begrenzte Bedingung beurteilen.
• Anwendungscode kann Berechtigungen durchsetzen und die finale Aktion auswählen.

Es geht nicht darum, bei jedem Schritt einen zusätzlichen Modellaufruf einzubauen. Isoliere vielmehr die Entscheidungen, bei denen eine falsche Aktion teuer, unsicher oder schwer zu prüfen wäre.

Eine minimale Architektur für Jev-AI-Agents

Ein praktischer Jev-gestützter Agent lässt sich in fünf Komponenten gliedern:

Komponente	Aufgabe
Agent-Orchestrator	Verwaltet Ablauf, Kontext und Planung der nächsten Schritte
Jev-AI-API	Beantwortet typisierte Fragen zum aktuellen State
Generatives Modell	Schreibt, fasst zusammen, schlussfolgert oder erstellt einen Plan
Anwendungsberechtigungen	Entscheiden, welche Tools und Aktionen zulässig sind
Menschliche Prüfung	Übernimmt unsichere oder besonders folgenreiche Fälle

Der Orchestrator sollte den kleinstmöglichen sinnvollen State an Jev übergeben. Dazu können die Nutzeranfrage, Tool-Argumente, Kontorichtlinien, vorherige Prüfergebnisse oder der aktuelle Workflow-Schritt gehören. Wenn eine fokussierte Datenstruktur für die Entscheidung genügt, muss Jev nicht den gesamten Gesprächsverlauf des Agents erhalten.

Schritt 1: Entscheidungen vor den Tools definieren

Liste vor der API-Integration die Entscheidungen auf, die dein Agent regelmäßig trifft. Die besten ersten Anwendungsfälle haben einen klaren Antwortbereich und eine eindeutige nächste Aktion.

Modell-Routing

Verwende Choice, um zu entscheiden, ob eine Anfrage an ein schnelles Modell, ein Modell für tiefere Schlussfolgerungen, einen Retrieval-Ablauf oder einen Fallback gehen soll. Anschließend kann der Agent das ausgewählte Modell im Code aufrufen.

Risiko eines Tool-Aufrufs

Nutze Noul, um zu prüfen, ob eine vorgeschlagene Aktion sensibel ist oder genehmigt werden muss. Beispiele sind das Löschen von Datensätzen, das Senden externer Nachrichten, Änderungen an Kontoeinstellungen oder das Auslösen einer Zahlung.

Aufgabenschwere und Priorität

Verwende Score, wenn der Agent eine geordnete Stufe wie niedrig, mittel, hoch oder kritisch benötigt. Der Score kann die Warteschlangenpriorität steuern, ohne das generative Modell eine Zahl erfinden zu lassen.

Abschluss- und Kontextprüfung

Mit einer typisierten Frage lässt sich beurteilen, ob der aktuelle State genügend Belege für den nächsten Schritt enthält, ob ein Ergebnis aus einer langen Sitzung gespeichert werden sollte oder ob der Agent den Nutzer um Klärung bitten muss.

Vermeide als erste Frage: „Was soll der Agent tun?“ Die Antwort ist zu offen, um sie sicher durchzusetzen. Frage lieber: „Welcher freigegebene Ablauf ist passend?“ oder „Erfordert genau dieser Tool-Aufruf eine menschliche Genehmigung?“

Schritt 2: State und Fragen gestalten

Die Jev-AI-API akzeptiert State als Text, JSON-Objekt oder Textarray. Für Agents ist ein JSON-Objekt meist der übersichtlichste Einstieg, weil es Nutzeranfrage, vorgeschlagene Aktion, Richtlinie und Belege voneinander trennt.

{
  "state": {
    "user_request": "Please remove all duplicate contacts from the workspace.",
    "proposed_tool": "delete_contacts",
    "record_count": 1842,
    "has_backup": false,
    "policy": "Destructive bulk actions require approval"
  },
  "model": "jev-latest",
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which execution path is appropriate?",
      "criteria": {
        "proceed": "The action is allowed and can run automatically",
        "confirm": "Ask the user or an operator for confirmation",
        "reject": "The action violates policy or is not supported"
      }
    },
    "needs_human": {
      "type": "noul",
      "instructions": "Does this proposed action require human approval?"
    }
  }
}

Halte jede Frage atomar. Mehrere Fragen können denselben State nutzen und parallel ausgewertet werden. So kann eine Anfrage Routing-, Risiko- und Prüfsignale zurückgeben, ohne drei getrennte Aufrufe miteinander zu verketten.

Setze die drei Fragetypen gezielt ein:

• Choice wählt eine Option aus einer vorgegebenen Auswahl.
• Score bewertet den State anhand einer geordneten Skala von niedrig bis hoch.
• Noul gibt die Wahrscheinlichkeit zurück, dass eine konkrete Aussage zutrifft.

Den Frageschlüssel wählt deine Anwendung; in answers wird derselbe Schlüssel wiederverwendet. Halte Schlüssel stabil, damit Protokolle, Kennzahlen und nachgelagerter Code über Versionen hinweg vergleichbar bleiben.

Schritt 3: Die Jev-AI-API aufrufen

Sobald State und Fragen in der Jev-AI-Spielwiese funktionieren, verbindest du sie mit deinem Server. Der Evaluierungsendpunkt lautet:

POST https://thejevai.com/v1/systemone

Die Anfrage benötigt einen Bearer-API-Schlüssel, den Inhaltstyp application/json und drei Felder auf oberster Ebene: state, model und questions. Die aktuelle API-Referenz nennt jev-latest als Spitzenmodell.

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": {
      "user_request": "Please remove all duplicate contacts from the workspace.",
      "proposed_tool": "delete_contacts",
      "has_backup": false,
      "policy": "Destructive bulk actions require approval"
    },
    "questions": {
      "route": {
        "type": "choice",
        "instructions": "Which execution path is appropriate?",
        "criteria": {
          "proceed": "Allowed and safe to run automatically",
          "confirm": "Needs user or operator confirmation",
          "reject": "Not allowed or not supported"
        }
      },
      "needs_human": {
        "type": "noul",
        "instructions": "Does this proposed action require human approval?"
      }
    }
  }'

Bewahre JEV_API_KEY in einer serverseitigen Umgebungsvariable auf. Füge den Schlüssel niemals in Browsercode, Agent-Transkripte, öffentliche Prompts oder ein Repository ein. Die API-Antwort enthält eine typisierte Antwort pro Frageschlüssel sowie – soweit der Fragetyp sie unterstützt – Wahrscheinlichkeits- und Konfidenzfelder.

Schritt 4: Antworten mit dem Agent-Ablauf verbinden

Jev liefert ein Signal; Ausführung bleibt Aufgabe des Orchestrators und der Anwendungsberechtigungen. Eine einfache Routing-Grenze könnte so aussehen:

const route = result.answers.route.choice;
const humanProbability = result.answers.needs_human.noul;

if (route === 'reject') {
  return respondSafely('This action is not allowed.');
}

if (route === 'confirm' || humanProbability >= 0.8) {
  return queueForHumanReview({ ticketId, result });
}

if (route === 'proceed') {
  return executeAllowedTool({ name: proposedTool, args, requestId });
}

return askForMoreContext();

Lass den finalen Tool-Aufruf weiterhin durch deterministische Prüfungen laufen. Validiere Tool-Namen, Argumente, Nutzerberechtigungen, Ressourcenumfang und Request-ID im Anwendungscode – auch wenn Jev eine Genehmigung mit hoher Wahrscheinlichkeit zurückgibt.

Schritt 5: Den Jev Agent Skill hinzufügen

Für Coding-Agents und kompatible Agent-Umgebungen bietet der offizielle Jev Agent Skill eine wiederverwendbare Möglichkeit, klar begrenzte Entscheidungen anzufragen, während die Ausführung in der Host-Anwendung bleibt. Installiere ihn so:

npx skills add jev-ai/jev-agent-skill

Konfiguriere API-Schlüssel und Sprache in der Umgebung:

export JEV_API_KEY="sk_your_key_here"
export JEV_LANGUAGE="en-US"

Der Skill kann einen Agenten dabei unterstützen, Choice, Score oder Noul auszuwählen, den kleinstmöglichen sinnvollen State zu senden und das strukturierte Ergebnis zu interpretieren. Er erteilt Jev keine Berechtigung, eine Zahlung auszuführen, Daten zu löschen oder das Freigabesystem der Host-Anwendung zu umgehen.

Nutze die Jev-AI-Dokumentation für aktuelle API-Felder, die Einführung in den Agent Skill, Antwortformate und Fehlerverhalten. Betrachte den Skill als Schnittstelle für Entscheidungen, nicht als Ersatz für Authentifizierung und Berechtigungen auf Anwendungsebene.

Schutzprüfungen für Tool-Aufrufe

Ein Agent darf aus generiertem Text keine Berechtigung ableiten. Prüfe vor der Ausführung eines Tools die vorgeschlagene Absicht, Richtlinien, den Umfang und das Risiko. Jev kann ein typisiertes Prüfsignal liefern, während die Anwendung die Regeln durchsetzt.

Eine sinnvolle Schutzkette sieht so aus:

1. Den vorgeschlagenen Tool-Namen und seine Argumente normalisieren.
2. Jev eine eng gefasste Risiko- oder Genehmigungsfrage stellen.
3. Deterministische Freigabelisten und Berechtigungsprüfungen anwenden.
4. Unsichere Fälle zur Bestätigung oder menschlichen Prüfung weiterleiten.
5. Das Tool mit Idempotenzschlüssel und Audit-Eintrag ausführen.

Bei destruktiven oder extern sichtbaren Aktionen sollten mehrere Kontrollen übereinstimmen müssen. Verlasse dich nicht auf einen einzelnen Wahrscheinlichkeitsschwellenwert. Die Richtlinienebene muss eine Aktion auch dann ablehnen können, wenn ein Modellsignal sicher wirkt.

Menschliche Prüfung und Evaluierung

Wahrscheinlichkeit und Konfidenz sind Routing-Signale, keine Garantie für geschäftliche Genauigkeit. Nutze historische Beispiele, um Schwellenwerte festzulegen, und überwache nach dem Start falsch positive und falsch negative Ergebnisse sowie das Prüfvolumen.

Eine praktische Richtlinie lautet:

• hohe Konfidenz, geringe Auswirkungen → automatisch fortfahren;
• mehrdeutiger oder unbekannter Fall → weiteren Kontext anfordern;
• Aktion mit großen Auswirkungen oder destruktive Aktion → Genehmigung verlangen;
• nicht unterstützte oder fehlerhafte Eingabe → sicher abbrechen.

Speichere genug Metadaten, um eine Entscheidung nachvollziehen zu können: Frageversion, State-Schema-Version, ausgewählte Antwort, Wahrscheinlichkeiten, Konfidenz, finale Aktion und ob ein Mensch das Ergebnis geändert hat. Protokolliere weder API-Schlüssel noch unnötige personenbezogene Daten.

Checkliste für den Produktivbetrieb

Prüfe vor dem Produktivstart einer Jev-AI-API- und Agent-Integration:

• Die Entscheidungen des Agents haben klar begrenzte Antwortbereiche.
• Der State enthält nur den Kontext, den die jeweilige Frage benötigt.
• Choice, Score und Noul werden für die passenden Entscheidungsformen verwendet.
• Der API-Schlüssel liegt serverseitig und erscheint nicht in Agent-Transkripten.
• Timeouts, Wiederholungen, Ratenbegrenzungen und API-Fehler haben sichere Fallbacks.
• Tool-Namen und Argumente werden außerhalb des Modells validiert.
• Aktionen mit großen Auswirkungen erfordern Berechtigungen und gegebenenfalls menschliche Genehmigung.
• Jeder Tool-Aufruf besitzt eine Idempotenzstrategie und einen Audit-Trail.
• Schwellenwerte werden mit repräsentativen und adversarialen Beispielen getestet.
• Evaluierungsdaten sind von Produktivgeheimnissen und personenbezogenen Daten getrennt.
• Protokolle können Jevs Antwort mit der finalen Anwendungsaktion verknüpfen.

Häufige Fragen

Ist die Jev-AI-API eine weitere Chat-Completions-API?

Nein. Die API wertet einen State anhand typisierter Fragen aus und gibt strukturierte Antworten zurück. Sie soll zu einer Entscheidung innerhalb einer Anwendung werden, nicht zu einem Chat-Transkript, das ein Mensch interpretieren muss.

Sollte Jev das LLM meines Agents ersetzen?

In der Regel nicht. Verwende ein generatives Modell für sprachintensive Aufgaben und Jev für klar begrenzte Klassifizierung, Routing, Bewertung und Sicherheitsentscheidungen. Beide können in einem orchestrierten Workflow zusammenarbeiten.

Führt der Agent Skill Tools für mich aus?

Nein. Er unterstützt kompatible Coding-Agents dabei, Jev klar begrenzte Fragen zu stellen. Die finale Aktion sollte weiterhin vom Agent-Host, den Anwendungsberechtigungen, deterministischen Richtlinienprüfungen und menschlichen Genehmigungen kontrolliert werden.

Kann ich mehrere Agent-Fragen in einer Anfrage stellen?

Ja. Mehrere Fragen können denselben State verwenden und parallel ausgewertet werden. Das ist hilfreich, wenn der Agent vor dem nächsten Schritt Routing, einen Risikowert und ein Signal für menschliche Prüfung benötigt.

Fazit

Am besten kombinierst du die Jev-AI-API und einen KI-Agenten, indem du jeder Komponente eine klare Aufgabe gibst. Agent und LLM übernehmen Interpretation und Planung. Jev beantwortet kleine, typisierte Fragen mit Wahrscheinlichkeiten. Anwendungscode setzt Berechtigungen durch und führt die finale Aktion aus.

Beginne mit einem risikoarmen Workflow, validiere ihn in der Spielwiese, verbinde ihn über /v1/systemone und ergänze Routing, Schutzprüfungen für Tools und menschliche Prüfung Schritt für Schritt. So entsteht ein Agent, der leichter zu testen, sicherer zu betreiben und im Produktivbetrieb besser vorhersehbar ist.