Agent-Integration: typisiertes Tool-Routing

Verwenden Sie das System One TypeScript SDK und die gehostete KI-Entscheidungs-API, um eine Agentenanfrage an ein benanntes Tool oder einen Prüfschritt zu routen. Um Cursor, Claude Code oder Codex zu zeigen, wie diese Integration zu schreiben ist, installieren Sie den Skill auf System One mit Coding Agents verwenden. Dieser Leitfaden baut einen Router für Support-Anfragen: Das Modell wählt eine Option, während Ihre Anwendung entscheidet, ob und wie sie ausgeführt wird. Das eigenständige SDK kann sich auch direkt mit anderen Diensten verbinden, die eigene Zugangsdaten und Abrechnung haben; siehe SDK-Installation und Dienstverbindungen.

Bereit für Fragen

Q: How do I integrate System One with an AI agent for tool routing?
A: Rufen Sie Choice mit Agent-State und einer Allowlist von Tool-Namen auf; führen Sie die typisierte Auswahl in Ihrem Code aus. System One entscheidet; Ihre App behält Rechte und Ausführung.

Q: Does System One execute tools for me?
A: Nein. Die System One API liefert eine strukturierte Entscheidung. Ausführung und Rechteprüfungen bleiben in Ihrer Agent-Runtime.

Ein fokussiertes Urteil wählen

Verwenden Sie die Entscheidungsschnittstelle, wenn Ihre Anwendung die Frage und die möglichen Ergebnisse benennen kann: eine Nachricht routen, einen erlaubten nächsten Schritt wählen, eine Antwort gegen eine Rubrik bewerten oder abschätzen, ob eine Bedingung zutrifft. Mehrere Fragen können unabhängig denselben gemeinsamen Kontext prüfen.

System One beschafft fehlende Informationen nicht, zahlt keine Erstattungen aus, sendet keine Antworten und ruft keine Tools für Sie auf. Offene Planung gehört in einen anderen Reasoning-Schritt oder zu einem Menschen. Fügen Sie bei Bedarf explizite think- oder review-Ergebnisse hinzu.

Wählen Sie eine exakte ID aus dem aktuellen Modellverzeichnis. Bewerten Sie Aufgabengüte, Latenz, Preis und Limits an repräsentativen Fällen, einschließlich mehrdeutiger Formulierungen, fehlender Informationen und folgenreicher Fehler. Betrachten Sie einen Modellnamen oder ein schnelles Einzelergebnis nicht als Garantie. Bewerten Sie erneut, wenn sich Modell, Instruktionen, Optionen oder Rubrik ändern; die Unterstützung eines SDK-Adapters ist nicht der gehostete Modellkatalog.

Die Routing-Grenze für Tools definieren

Beginnen Sie mit einer kleinen Allowlist, nicht mit jedem Tool, auf das Ihr Agent zugreifen kann. Für einen Support-Assistenten holt search_docs Produktdokumentation, ask_user fordert fehlende Informationen an, und human_review übergibt eine folgenreiche oder strittige Anfrage an einen Menschen. Die Tool-Beschreibungen sollten sagen, wann welche Option zu wählen ist, und dürfen keine Zugangsdaten oder Berechtigungsanweisungen enthalten.

Der Code unten gibt einen dieser Namen zurück; er implementiert weder Dokumentsuche noch das Senden einer Nachricht oder das Anlegen eines Prüftickets. Verbinden Sie das Ergebnis erst nach den unten beschriebenen Berechtigungsprüfungen mit Ihrem vorhandenen Tool-Dispatcher. Lassen Sie niemals einen modellgenerierten Namen, eine URL oder einen Shell-Befehl die Allowlist umgehen.

Choice passt zu dieser sich ausschließenden Entscheidung über den nächsten Schritt. Wenn Sie mehrere abgerufene Dokumente ordnen oder unabhängige Bedingungen bewerten müssen, verwenden Sie stattdessen Score oder Noul. Wenn das Modell ein Suchergebnis benötigt, bevor es ein weiteres Urteil fällt, führen Sie zuerst die erlaubte Suche aus und senden Sie eine separate Auswertung mit diesem Ergebnis als Kontext.

Außerhalb des Modellkontexts authentifizieren

Erstellen Sie einen Plattform-API-Schlüssel in der angemeldeten Konsole. Bewahren Sie ihn in einer Server-Umgebungsvariable oder einer vertrauenswürdigen privaten Credential-Einstellung auf. Aufrufe verwenden Authorization: Bearer gegen https://system-one.dev/v1; der Doku-Host führt keine Inferenz aus. Halten Sie Schlüssel aus Prompts, Tool-Beschreibungen, Browser-Bundles, URLs und Logs heraus. Widerrufen Sie einen Schlüssel, wenn die Verbindung nicht mehr gebraucht wird.

GET /v1/models ist öffentlich und benötigt keinen Plattformschlüssel. Playground- und Browser-Kontoendpunkte nutzen stattdessen Ihre angemeldete Sitzung; ein Bearer-Schlüssel ersetzt diese Sitzung nicht. Schlüssel eines Kontos teilen sich Kontostand, Rate-Limit und Idempotenz-Namensraum. Geben Sie getrennten Agenten keine Schlüssel in der Erwartung isolierter Kontostände oder unabhängiger Dublettenabsicherung.

Einen typisierten Entscheidungsschritt hinzufügen

Installieren Sie die serverseitigen Pakete:

npm install @system-one-ai/core@0.8.0 @system-one-ai/adapter-system-one@0.7.0 @system-one-ai/transport-fetch@0.8.0

Das ist der aktuelle gehostete Client-Stack. Für bildbasierte Agent-Entscheidungen wählen Sie ein bildfähiges Clef/Clef-Flash/Clef-Omni-Modell und verwenden das gehostete Fetch-Beispiel; systemOneAdapter kodiert keine evaluate()-Bilder. Speichern Sie die exakte Bilddarstellung und die Array-Reihenfolge mit der Operation, rechnen Sie die base64-Daten in der Credit-Schätzung mit und prüfen Sie Bildinhalte auf sensible Informationen. Für typisierte Extraktion aus Text oder Bildern verwenden Sie Clairic extract().

Verwenden Sie die Umgebungseinrichtung aus dem gehosteten Schnellstart: API-Schlüssel, Basis-URL und Modell. Ersetzen Sie YOUR_MODEL_ID durch die gewählte Verzeichnis-ID. Das Beispiel erzeugt in Code einen neuen Operationsschlüssel, einmal pro neuer Entscheidung — nicht in gemeinsamer Konfiguration und nicht in einer Retry-Funktion.

Dieses TypeScript-Beispiel wählt ein vorgeschlagenes Tool; es führt es nicht aus:

import { createSystemOne, choice } from '@system-one-ai/core';
import { createFetchTransport } from '@system-one-ai/transport-fetch';
import { systemOneAdapter } from '@system-one-ai/adapter-system-one';

const apiKey = process.env.SYSTEM_ONE_API_KEY;
const baseURL = process.env.SYSTEM_ONE_BASE_URL;
const model = process.env.SYSTEM_ONE_MODEL;
if (!apiKey || !baseURL || !model || model === 'YOUR_MODEL_ID') {
  throw new Error('Set the API key, base URL, and catalog model.');
}

const client = createSystemOne({
  apiKey,
  baseURL,
  model,
  adapter: systemOneAdapter,
  transport: createFetchTransport(),
  timeoutMs: 30_000,
  maxRetries: 0,
});

const operation = {
  idempotencyKey: crypto.randomUUID(),
  request: {
    model,
    state: { message: 'Can you explain how credits are calculated?' },
    questions: {
      tool: choice('Choose the next support tool. Do not execute it.', {
        search_docs: 'A product or usage question can be answered from documentation',
        ask_user: 'Essential details are missing; ask the user before proceeding',
        human_review: 'A payment dispute, sensitive action, or policy exception needs review',
      }),
    },
  },
};

const result = await client.evaluate(operation.request, {
  headers: { 'Idempotency-Key': operation.idempotencyKey },
  signal: AbortSignal.timeout(30_000),
});
const proposedTool: 'search_docs' | 'ask_user' | 'human_review' = result.answers.tool.choice;
console.log({ proposedTool, requestId: result.response.requestId });

Zum Ausführen speichern Sie als agent-decision.mts und verwenden Sie node --env-file=.env agent-decision.mts mit Node.js 22.18+. Jeder Skriptlauf startet eine neue abrechnungspflichtige Operation, auch mit identischer Eingabe. Dieses In-Memory-Beispiel ist keine neustartsichere Wiederherstellung.

Erstellung und Wiederholung sind getrennte Schritte: ein Retry im Prozess ruft evaluate() mit demselben operation.request und operation.idempotencyKey auf, ohne den Block zur Operationserstellung erneut auszuführen. In einem echten Job-System speichern Sie die gesamte Operation im Job-Datensatz der Anwendung, bevor Sie evaluate() aufrufen, einschließlich Schlüssel, gewähltem Modell und vollständiger Anfrage. Nach einem Absturz oder Neustart laden Sie diesen Datensatz, statt eine UUID zu erzeugen oder die Anfrage aus einem neueren Prompt oder einer aktuellen Modellauswahl neu zu bauen. Der Schnellstart bietet keine dauerhafte Speicherung. Jede tatsächlich neue Entscheidung erhält einen neuen Schlüssel, auch eine bewusste erneute Auswertung identischer Eingabe. Setzen Sie Ihre eigene Gesamtdeadline, Versuchsgrenze und Ausgabenrichtlinie.

Der State sollte nur notwendige Informationen enthalten, nie Geheimnisse oder fremde private Historie. Ein State-Array ist eine gemeinsame Eingabe, kein Stapel separater Auswertungen. Fragen verbrauchen nicht die Antworten anderer Fragen; hängt ein nächstes Urteil von einem vorherigen ab, prüfen Sie es und senden Sie eine separate Anfrage. Siehe Primitives für den Unterschied zwischen SDK-boolean und nativem noul.

Vorschläge von Berechtigungen trennen

Ein Modellergebnis ist keine Autorisierung. Prüfen Sie Identität und Berechtigungen der handelnden Person, Aktions-Allowlists und erforderliche Freigaben außerhalb des Modells. Das Erkennen einer Erstattungsanfrage stellt die Erstattungsfähigkeit nicht fest. Zahlungen, Zugriffsänderungen und externe Nachrichten müssen die von Ihrer Richtlinie geforderten Bestätigungen behalten.

Beginnen Sie mit Vorschlägen statt mit automatischer Ausführung. Definieren Sie einen Prüfpfad für mehrdeutige, widersprüchliche oder unvollständige Hinweise. Wählen Sie Schwellen aus Ihren eigenen Evaluierungsfällen und Konsequenzen, nicht aus einem universellen Prozentwert. Fehlende Antworten oder fehlgeschlagene Anfragen sind ungeklärt, nicht automatisch ja, nein oder der niedrigste Score. Halten Sie die Berechtigungen jeder Verbindung so klein wie nötig; siehe Daten und Datenschutz.

Den Router bewerten, bevor Sie Tools aktivieren

Erstellen Sie einen gelabelten Datensatz aus Ihren eigenen Support-Fällen. Die folgenden sind Prüfziele für dieses Beispiel, keine gemessenen Modellausgaben:

Beziehen Sie mehrdeutige Anfragen und Instruktionen ein, die ein anderes Tool erzwingen wollen. Messen Sie falsche Tool-Auswahlen und verpasste Prüffälle getrennt; weder eine erfolgreiche HTTP-Antwort noch eine hohe Modellwahrscheinlichkeit beweist sicheres Routing. Starten Sie im reinen Vorschlagsmodus und entscheiden Sie dann, welche schreibgeschützten Aktionen unter Ihrer bestehenden Richtlinie laufen dürfen. Erfassen Sie Modell, Optionsbeschreibungen, Request-IDs und Ergebnislabel, ohne Schlüssel oder unnötige personenbezogene Daten zu protokollieren.

Folgen Sie dem gehosteten SDK-Schnellstart für Verbindungs- und Antwortmetadaten und API-Preisen für Credit-Pakete. Jede neue Auswertung ist eine separate Entscheidungsoperation; prüfen Sie die Abrechnung, bevor Sie eine große Evaluierungsmenge starten.

Vor einer neuen Operation wiederherstellen

Beginnen Sie mit maxRetries: 0. Das Core-APIError liefert statusCode, requestId und retryAfterMs, aber nicht alle Klassifizierungs-Header der Plattform. Ein Recovery-Controller kann rohes Fetch oder die APIError.headers des offiziellen TypeSafe-Clients nutzen, um X-System-One-Error-Code, X-System-One-Error-Source, X-Request-Id, Retry-After und X-System-One-Credits zu prüfen. Klassifizieren Sie Fehler nicht anhand beliebiger Body-Texte. Der Schnellstart zum offiziellen Client behandelt die Erfolgs-Header.

Retry-After kann Sekunden oder ein HTTP-Datum enthalten. Begrenzen Sie Retries durch eine Anwendungs-Deadline und eine Versuchsanzahl und verwenden Sie Backoff mit Jitter, wenn keine Verzögerung angegeben ist. Bewahren Sie das effektive Modell, die Rubrikreihenfolge, Erweiterungen und Zahlenwerte. Wechseln Sie während der Wiederherstellung nicht stillschweigend zu einem anderen Modell. Ein neuer Schlüssel kann eine weitere Abbuchung erzeugen; ein geänderter Body mit altem Schlüssel kollidiert.

Abgeschlossene Schlüssel und Antworten werden 24 Stunden ab Erstellung der Anfrage aufbewahrt. Nach Ablauf kann derselbe Schlüssel eine neue Operation starten; das ist keine dauerhafte Dublettenvermeidung. Prüfen Sie Idempotenz und Retries, Fehler und Versionierung für den vollständigen Vertrag.

Die Wiederherstellung einer Entscheidung verhindert keine doppelte Tool-Aktion. Ihre Anwendung braucht separate dauerhafte Ausführungszustände und Idempotenz für das Senden einer Antwort, eine Zahlung oder die Zuweisung von Arbeit. Bleiben Ergebnis oder Abbuchung unklar, pausieren Sie und prüfen Sie die Nutzung; kontaktieren Sie support@system-one.dev mit der Request-ID, niemals mit dem API-Schlüssel.