SDK auswählen
Identischer Funktionsumfang auf beiden Laufzeiten. Wählen Sie eine Option — die Beispiele passen sich automatisch an.
Installation
npm install @execlave/sdkKeine Laufzeit-Abhängigkeiten. Unterstützt Node.js 18+ sowie moderne Bundler für die Verwendung im Browser. TypeScript-Typen sind enthalten.
Initialisierung
import { Execlave } from '@execlave/sdk'; const ag = new Execlave({ apiKey: process.env.EXECLAVE_API_KEY!, // erforderlich baseUrl: 'https://api.execlave.com', // Standard environment: 'production', // Standard asyncMode: true, // Standard: Traces puffern batchSize: 100, // max. Traces pro Flush flushIntervalMs: 10_000, // 10-Sekunden-Flush-Intervall debug: false, // ausführliche Protokollierung enableControlChannel: true, // Kill-Switch-Polling pollIntervalMs: 15_000, // Poll-Intervall enableInjectionScan: true, // versieht Traces mit Injection-Score (blockiert NICHT) enforcementOnOutage: 'fail_open', // fail_open | fail_closed policyCacheTtlMs: 60_000, // Cache-TTL für Richtlinienentscheidungen});Erstellen Sie eine einzige Execlave-Instanz und teilen Sie diese in Ihrer gesamten Anwendung. Das SDK verwaltet Connection-Pooling, Batching und Hintergrund-Flushing intern.
Methoden
registerAgent
ag.registerAgent(config: AgentConfig): Promise<Agent>Registriert einen neuen Agenten oder aktualisiert einen vorhandenen. Idempotent — kann bei jedem Anwendungsstart sicher aufgerufen werden.
§ Parameter
agentIdstringEindeutiger Bezeichner des AgentennamestringAnzeigenametype?stringchatbot | copilot | autonomous | workflow | data_processingplatform?stringcustom | openai | anthropic | langchainenvironment?'development' | 'staging' | 'production'Standard ist development. Im Produktivbetrieb auf production festlegen.description?stringBeschreibung des AgentenownerEmail?stringWird im Dashboard und bei Richtlinienverstößen in Benachrichtigungen angezeigt.allowedDataSources?string[]Governance-Allowlist der Datenquellen, auf die der Agent zugreifen darf (z.B. ["s3://bucket-x", "postgres://orders"]). Wird durch Datenzugriffsrichtlinien durchgesetzt.allowedActions?string[]Governance-Allowlist der Tool-/Aktionsnamen, die dieser Agent aufrufen darf. Alles, was nicht auf der Liste steht, wird standardmäßig blockiert.requiresHumanApprovalFor?string[]Aktionsnamen, die unabhängig vom Richtlinienergebnis immer in die menschliche Genehmigungswarteschlange gehen (z.B. ["wire_transfer", "delete_customer"]).tags?string[]Tags zum Filternmetadata?Record<string, unknown>Frei definierbare Metadaten, die im Agentendatensatz gespeichert werden (Kostenstellen-IDs, verantwortliches Team, Ticket-Links).§ Rückgabewert
Promise<Agent>await ag.registerAgent({ agentId: 'support-bot', name: 'Customer Support Bot', type: 'chatbot', platform: 'openai', environment: 'production', ownerEmail: 'support-team@example.com', allowedDataSources: ['postgres://customers'], allowedActions: ['search_kb', 'create_ticket'], requiresHumanApprovalFor: ['issue_refund'], tags: ['support', 'tier-1'], metadata: { costCenter: 'CS-101' },});enforcePolicy
ag.enforcePolicy(opts): Promise<EnforcementDecision>Synchrone Richtlinienprüfung vor der Ausführung. Rufen Sie diese Methode VOR jedem LLM-Aufruf auf. Wirft PolicyBlockedError bei einer Verletzung im Block-Modus, AgentPausedError wenn der Agent per Kill-Switch pausiert wurde, und EnforcementUnavailableError nur wenn enforcementOnOutage auf 'fail_closed' gesetzt ist. Tracing allein blockiert nicht — diese Methode ist das eigentliche Tor.
§ Parameter
agentIdstringAgent, der den Aufruf durchführtinputstringBenutzereingabe, die an das LLM gesendet wirdenvironment?EnvironmentÜberschreibt die Client-Umgebung für diese Prüfungmetadata?Record<string, unknown>Optionale Metadaten für benutzerdefinierte ValidatorenestimatedCost?numberGeschätzte Aufrufkosten in USD (für Budgetrichtlinien)tools?string[]Tool-Namen, die der Agent verwenden möchte (für action_approval-Richtlinien)§ Rückgabewert
Promise<EnforcementDecision>. Wirft PolicyBlockedError wenn blockiert.import { AgentPausedError, PolicyBlockedError } from '@execlave/sdk'; try { await ag.enforcePolicy({ agentId: 'support-bot', input: userQuestion }); const answer = await llm.call(userQuestion);} catch (err) { if (err instanceof PolicyBlockedError) { // err.violations: Liste von { policyType, policyName, severity, message, enforcementMode } return 'Ihre Eingabe wurde durch unsere Inhaltsrichtlinien blockiert.'; } if (err instanceof AgentPausedError) { return 'Dienst vorübergehend nicht verfügbar.'; } throw err;}startTrace
ag.startTrace(opts: TraceOptions): TraceStartet einen neuen Trace zur Aufzeichnung einer LLM-Interaktion. Gibt ein verkettbares Trace-Objekt zurück. Tracing erfolgt nachträglich — es blockiert den LLM-Aufruf NICHT. Kombinieren Sie es mit enforcePolicy(), um Anfragen tatsächlich zu blockieren.
§ Parameter
agentIdstringAgent, der den Trace durchführtsessionId?stringTraces zu Gesprächen zusammenfassen§ Rückgabewert
Traceconst trace = ag.startTrace({ agentId: 'support-bot' });trace .setInput('How do I reset my password?') .setOutput('Go to Settings > Security...') .setModel('gpt-4') .setTokens(150, 320) .setCost(0.0045) .finish(); // Oder mit Fehler abschließen:trace.finish('error', 'LLM call timed out');wrap
ag.wrap<T>(fn, opts): (input: string) => Promise<T>Umschließt eine Funktion mit automatischem Tracing. Eingabe und Ausgabe werden erfasst, und der Trace wird bei Rückgabe oder Fehler abgeschlossen.
§ Parameter
fnFunctionAsynchrone Funktion, die umschlossen werden sollopts.agentIdstringAgent, der den Aufruf durchführt§ Rückgabewert
Umschlossene Funktion mit derselben Signaturconst tracedAnswer = ag.wrap( async (question: string) => { const res = await openai.chat.completions.create({ model: 'gpt-4', messages: [{ role: 'user', content: question }], }); return res.choices[0].message.content; }, { agentId: 'support-bot' }); // Verwendung — vollständig automatisch getracktconst answer = await tracedAnswer('How do I upgrade?');shutdown
ag.shutdown(): Promise<void>Leert alle gepufferten Traces und schließt Verbindungen. Beim Beenden des Prozesses aufrufen.
§ Rückgabewert
Promise<void>process.on('SIGTERM', async () => { await ag.shutdown(); process.exit(0);});Fehlertypen
Wird ausgelöst, wenn ein Trace für einen Agenten gestartet wird, der über den Kill-Switch pausiert wurde. Ihre Anwendung sollte diesen Fehler abfangen und dem Nutzer eine angemessene Rückmeldung zurückgeben.
Wird ausgelöst, wenn eine Richtlinienprüfung vor der Ausführung die Anfrage blockiert. Enthält den Namen der verletzten Richtlinie und den Durchsetzungsmodus.
Datenschutz & PII-Bereinigung
Das TypeScript-SDK kann jede Eingabe auf Prompt-Injection-Wahrscheinlichkeit bewerten und den resultierenden Trace mit diesem Score versehen. Dies sind ausschließlich Metadaten — der LLM-Aufruf wird dadurch nicht blockiert. Um Injection-Versuche tatsächlich zu blockieren, erstellen Sie eine injection_scan-Richtlinie im block-Modus und rufen Sie ag.enforcePolicy() vor Ihrem LLM-Aufruf auf. Die serverseitige PII-Bereinigung wird vom Verarbeitungsdienst bei der Aufnahme durchgeführt.
const ag = new Execlave({ apiKey: process.env.EXECLAVE_API_KEY!, enableInjectionScan: true, // versieht Traces mit Injection-Score (blockiert NICHT)}); // Zum Blockieren: block-Modus-Richtlinie injection_scan im Dashboard erstellen,// dann jeden LLM-Aufruf mit enforcePolicy() absichern.await ag.enforcePolicy({ agentId: 'support-bot', input: userQuestion });OpenTelemetry-Integration
Schalten Sie das SDK auf OTLP-Transport um, indem Sie mode: 'otlp' setzen und otlpEndpoint auf die Basis-URL Ihres OTLP-Collectors zeigen lassen (das SDK hängt /v1/traces automatisch an). Verwenden Sie einen OTLP-fähigen Collector — zeigen Sie nicht auf die Execlave REST-API.
import { Execlave } from '@execlave/sdk'; const exe = new Execlave({ apiKey: process.env.EXECLAVE_API_KEY!, mode: 'otlp', // Basis-URL Ihres OTLP-Collectors — Exporter hängt /v1/traces an. // z.B. http://localhost:4317 oder die Basis-URL Ihres verwalteten Collectors. otlpEndpoint: process.env.OTLP_ENDPOINT!,}); // Vom SDK ausgesendete Traces werden per OTLP statt über// den nativen REST-Ingest exportiert und fließen so durch Ihre// bestehende Collector-Pipeline zusammen mit Ihrer übrigen Telemetrie.