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.
pip install execlave-sdkFür die OpenTelemetry-Integration installieren Sie das Paket mit Extras:
pip install execlave-sdk[otel]Erfordert Python 3.9+. Das Kernpaket hat minimale Abhängigkeiten.
Initialisierung
import { Execlave } from '@execlave/sdk'; const exe = 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.
from execlave import Execlave exe = Execlave( api_key=os.environ["EXECLAVE_API_KEY"], # erforderlich base_url="https://api.execlave.com", # Standard environment="production", # Standard privacy={ # PII-Bereinigung (deaktiviert, außer enabled=True) "enabled": True, "scrub_fields": ["input", "output"], # zu bereinigende Felder "hash_pii": True, # PII-Zusammenfassung als Hash an Metadaten anhängen }, enable_injection_scan=True, # versieht Traces mit Injection-Score (blockiert NICHT) async_mode=True, # Hintergrund-Flush-Thread; False für synchronen Modus mode="native", # native | otlp (Transport) enforcement_on_outage="fail_open", # fail_open | fail_closed policy_cache_ttl_seconds=60, # Cache-TTL (Sekunden))Methoden
registerAgent
exe.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 exe.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
exe.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 exe.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
exe.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 = exe.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
exe.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 = exe.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
exe.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 exe.shutdown(); process.exit(0);});register_agent
exe.register_agent(**kwargs) -> AgentRegistriert einen neuen Agenten oder aktualisiert einen vorhandenen. Idempotent.
§ Parameter
agent_idstrEindeutiger BezeichnernamestrAnzeigenametypestrchatbot | copilot | autonomous | workflow | data_processingplatformstrcustom | openai | anthropic | langchain | ...descriptionstrBeschreibung des Agentenowner_emailstrWird im Dashboard und in Benachrichtigungen angezeigtallowed_data_sourceslist[str]Governance-Allowlist der Datenquellen, auf die dieser Agent zugreifen darf.allowed_actionslist[str]Governance-Allowlist der Tool-/Aktionsnamen. Alles, was nicht auf der Liste steht, wird blockiert.requires_human_approval_forlist[str]Aktionsnamen, die immer menschliche Genehmigung erfordern.tagslist[str]Tags zum FilternmetadatadictFrei definierbare Metadaten, die im Agentendatensatz gespeichert werden.§ Rückgabewert
Agentagent = exe.register_agent( agent_id="support-bot", name="Customer Support Bot", type="chatbot", platform="langchain", owner_email="support-team@example.com", allowed_actions=["search_kb", "create_ticket"], requires_human_approval_for=["issue_refund"], tags=["support", "production"],)enforce_policy
exe.enforce_policy(agent_id, input, *, environment=None, metadata=None, estimated_cost=None, tools=None) -> dictSynchrone 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 enforcement_on_outage='fail_closed'. Tracing allein blockiert nicht — diese Methode ist das eigentliche Tor.
§ Parameter
agent_idstrAgent, der den Aufruf durchführtinputstrBenutzereingabe, die an das LLM gesendet wirdenvironmentstr | NoneÜberschreibt die Client-Umgebung für diese Prüfungmetadatadict | NoneOptionale Metadaten für benutzerdefinierte Validatorenestimated_costfloat | NoneGeschätzte Aufrufkosten in USD (für Budgetrichtlinien)toolslist[str] | NoneTool-Namen, die der Agent verwenden möchte (für action_approval-Richtlinien)§ Rückgabewert
dict (Entscheidungs-Payload). Wirft PolicyBlockedError wenn blockiert.from execlave import AgentPausedError, PolicyBlockedError try: exe.enforce_policy(agent_id="support-bot", input=user_question) response = llm.invoke(user_question)except PolicyBlockedError as e: # e.violations: Liste von {policyType, policyName, severity, message, enforcementMode} return "Ihre Eingabe wurde durch unsere Inhaltsrichtlinien blockiert."except AgentPausedError: return "Dienst vorübergehend nicht verfügbar."@exe.trace
@exe.trace(*, agent_id=None, session_id=None, user_id=None, metadata=None, tags=None, environment=None, parent_trace_id=None, span_type=None)Dekorator / Kontextmanager, der Funktionsaufrufe automatisch trackt. Argumente werden zur Trace-Eingabe, der Rückgabewert wird zur Ausgabe.
§ Parameter
agent_idstr | NoneÜberschreibt die Standard-Agenten-IDsession_idstr | NoneTraces zu einer Sitzung zusammenfassenuser_idstr | NoneDen Trace einem Endnutzer zuordnenmetadatadict | NoneBeliebige Metadaten, die dem Trace angehängt werdentagslist[str] | NoneTags zum Filtern von Tracesenvironmentstr | NoneÜberschreibt die Client-Umgebung für diesen Traceparent_trace_idstr | NoneVerknüpft diesen Span mit einem übergeordneten Trace (Verschachtelung)span_typestr | Noneroot | agent | llm_call | tool_call | retrieval | middleware | custom§ Rückgabewert
Dekorierte Funktion (oder TraceContext bei Verwendung als Kontextmanager)@exe.tracedef answer(question: str) -> str: return llm.invoke(question) # Sitzung + Benutzerzuordnung:@exe.trace(session_id="sess_123", user_id="user_42")def handle(query: str) -> str: return db.execute(query)start_trace
exe.start_trace(agent_id: str) -> TraceContextKontextmanager für manuelles Tracing mit vollständiger Kontrolle über alle Trace-Felder.
§ Parameter
agent_idstrAgent, der den Trace durchführt§ Rückgabewert
TraceContext (Kontextmanager)with exe.start_trace(agent_id="support-bot") as trace: trace.set_input(user_question) response = llm.invoke(user_question) trace.set_output(response) trace.set_model("gpt-4") trace.set_tokens(input=150, output=320) trace.set_cost(0.0045) trace.add_metadata({"intent": "password_reset"})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 exe.enforcePolicy() vor Ihrem LLM-Aufruf auf. Die serverseitige PII-Bereinigung wird vom Verarbeitungsdienst bei der Aufnahme durchgeführt.
const exe = 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 exe.enforcePolicy({ agentId: 'support-bot', input: userQuestion });Das Python-SDK kann PII bereinigen, bevor Traces Ihre Anwendung verlassen, und jede Eingabe auf Prompt-Injection-Wahrscheinlichkeit bewerten (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 exe.enforce_policy() vor Ihrem LLM-Aufruf auf.
exe = Execlave( api_key=os.environ["EXECLAVE_API_KEY"], privacy={ "enabled": True, "scrub_fields": ["input", "output"], # welche Trace-Felder bereinigt werden "hash_pii": False, # gefundene Werte maskieren vs. hashen }, enable_injection_scan=True, # versieht Traces mit Injection-Score (blockiert NICHT)) # Zum Blockieren: block-Modus-Richtlinie injection_scan im Dashboard erstellen,# dann jeden LLM-Aufruf mit enforce_policy() absichern.exe.enforce_policy(agent_id="support-bot", input=user_question)PII wird clientseitig vor der Übertragung bereinigt, sodass sensible Daten den Execlave-Server niemals erreichen.
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.Schalten Sie das SDK auf OTLP-Transport um, indem Sie mode="otlp" und einen otlp_endpoint übergeben, der auf die Basis-URL Ihres OTLP-Collectors zeigt (das SDK hängt /v1/traces automatisch an). Verwenden Sie einen OTLP-fähigen Collector — zeigen Sie nicht auf die Execlave REST-API.
import osfrom execlave import Execlave exe = Execlave( api_key=os.environ["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. otlp_endpoint=os.environ["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.