API-Referenz¶

Dieses Dokument bietet umfassende Dokumentation fuer die Symbiont Runtime-APIs. Das Symbiont-Projekt stellt zwei unterschiedliche API-Systeme bereit, die fuer verschiedene Anwendungsfaelle und Entwicklungsstadien konzipiert sind.

Ueberblick¶

Symbiont bietet zwei API-Schnittstellen:

1. Runtime HTTP API - Eine vollstaendige API fuer direkte Runtime-Interaktion, Agent-Management und Workflow-Ausfuehrung
2. Tool Review API (Produktion) - Eine umfassende, produktionsbereite API fuer KI-gesteuerte Tool-Review- und Signaturworkflows

Runtime HTTP API¶

Die Runtime HTTP API bietet direkten Zugang zur Symbiont Runtime fuer Workflow-Ausfuehrung, Agent-Management und Systemueberwachung. Alle Endpunkte sind vollstaendig implementiert und produktionsbereit, wenn das http-api Feature aktiviert ist.

Basis-URL¶

http://127.0.0.1:8080/api/v1

Authentifizierung¶

Runtime-Routen ausser Gesundheitspruefungen erfordern Bearer-Authentifizierung. Konfigurieren Sie eine private API-Schluesseldatei oder das bisherige Betreiber-Token SYMBIONT_API_TOKEN.

Authorization: Bearer <your-token>

Geschuetzte Endpunkte: - Alle Endpunkte unter /api/v1/agents/* erfordern Authentifizierung - Nur Gesundheitspruefungen sind oeffentlich. Workflow-Einreichungen und Metriken erfordern Administratorrechte.

Verfuegbare Endpunkte¶

Gesundheitspruefung¶

GET /api/v1/health

Gibt den aktuellen Systemgesundheitsstatus und grundlegende Runtime-Informationen zurueck.

Response (200 OK):

{
  "status": "healthy",
  "uptime_seconds": 3600,
  "timestamp": "2024-01-15T10:30:00Z",
  "version": "1.0.0"
}

Response (500 Interner Serverfehler):

{
  "status": "unhealthy",
  "error": "Database connection failed",
  "timestamp": "2024-01-15T10:30:00Z"
}

Verfuegbare Endpunkte¶

Workflow-Ausfuehrung¶

POST /api/v1/workflows/execute

Administratoren uebermitteln rohen DSL-Quelltext in workflow_id; parameters wird als Eingabe des Aufrufs verwendet. Lassen Sie agent_id weg, um eine Registrierung zu vergeben, oder geben Sie eine ID an, um sie zu erstellen oder zu ersetzen. Auf Agenten beschraenkte Schluessel erhalten hier 403 ADMIN_REQUIRED und koennen ihren registrierten Quelltext ueber /agents/{id}/execute aufrufen. Eine queued-Antwort bestaetigt die Aufnahme; ordnen Sie execution_id in /agents/{id}/history zu, um das endgueltige Ergebnis zu erhalten. Siehe den Workflow-Vertrag fuer Details zu Quellenauswahl, Validierung und Migration.

Ohne Sandbox-Angabe bleibt Docker/Tier1 der Registrierungsstandard. Mit with sandbox = "landlock" wird das native beaufsichtigte Backend explizit ausgewaehlt; Landlock erfuellt keine Container- oder VM-Stufenanforderung.

Request Body:

{
  "workflow_id": "agent report() { with sandbox = \"docker\" {} }",
  "parameters": {},
  "agent_id": null
}

Response (200 OK):

{
  "status": "queued",
  "workflow_id": "agent report() { with sandbox = \"docker\" {} }",
  "agent_id": "19b183f7-97c4-4e42-9c62-5e9c940bfae3",
  "execution_id": "c7022f13-7140-4a09-8e30-b1941e0cbb32",
  "metadata": {}
}

Agent-Management¶

Alle Agent-Management-Endpunkte erfordern Authentifizierung ueber den Authorization: Bearer <token> Header.

Agenten auflisten¶

GET /api/v1/agents
Authorization: Bearer <your-token>

Ruft eine Liste aller aktiven Agenten in der Runtime ab.

Response (200 OK):

[
  "agent-id-1",
  "agent-id-2",
  "agent-id-3"
]

Agent-Status abrufen¶

GET /api/v1/agents/{id}/status
Authorization: Bearer <your-token>

Ruft den Scheduler-Status fuer einen bestimmten Agenten ab. CPU und Speicher sind nullable; der aktuelle Scheduler besitzt keinen Sampler pro Agent und liefert null fuer interne und externe Agenten. Clients duerfen diese Werte nicht als Nullauslastung darstellen.

Response (200 OK):

{
  "agent_id": "uuid",
  "state": "Running",
  "last_activity": "2024-01-15T10:30:00Z",
  "resource_usage": {
    "memory_bytes": null,
    "cpu_percent": null,
    "active_tasks": 1
  },
  "execution_mode": "Ephemeral"
}

active_tasks zaehlt die vom Scheduler verwalteten Aufgaben. last_activity ist kein Zeitstempel einer Ressourcenmessung. Die Fleet Overview zeigt Nicht erfasst fuer fehlende CPU- und Speicherwerte an; Worker-Kapazitaet liefert separat erfasste Worker-Auslastung und reservierte Kapazitaet. Diese Worker-Werte sind keine Summen pro Agent.

Neue Agent-Zustaende: - running: Agent fuehrt aktiv mit einem laufenden Prozess aus - ready: Agent ist initialisiert und bereit zur Ausfuehrung - waiting: Agent wartet in der Warteschlange auf Ausfuehrung - failed: Agent-Ausfuehrung fehlgeschlagen oder Gesundheitspruefung fehlgeschlagen - completed: Agent-Aufgabe erfolgreich abgeschlossen - terminated: Agent wurde ordnungsgemaess oder erzwungen beendet

Agent erstellen¶

POST /api/v1/agents
Authorization: Bearer <your-token>

Erstellt einen neuen Agenten mit der angegebenen Konfiguration.

Request Body:

{
  "name": "my-agent",
  "dsl": "agent definition in DSL format"
}

Response (200 OK):

{
  "id": "uuid",
  "status": "created"
}

Agent aktualisieren¶

PUT /api/v1/agents/{id}
Authorization: Bearer <your-token>

Aktualisiert die Konfiguration eines bestehenden Agenten. Mindestens ein Feld muss angegeben werden.

Request Body:

{
  "name": "updated-agent-name",
  "dsl": "updated agent definition in DSL format"
}

Response (200 OK):

{
  "id": "uuid",
  "status": "updated"
}

Agent loeschen¶

DELETE /api/v1/agents/{id}
Authorization: Bearer <your-token>

Loescht einen bestehenden Agenten aus der Runtime.

Response (200 OK):

{
  "id": "uuid",
  "status": "deleted"
}

Agent ausfuehren¶

POST /api/v1/agents/{id}/execute
Idempotency-Key: <UUID retained for retries>
Authorization: Bearer <your-token>

Reicht einen einzelnen Aufruf des ausgewaehlten Agenten ein. Verwenden Sie dieselbe UUID und denselben Request erneut, um ein gespeichertes Ergebnis oder ein explizites Resultat vom Typ active/unresolved/reconciled/conflict abzurufen. Siehe Scheduler-Wiederholungszustaende.

Request Body:

{}

Response (200 OK):

{
  "execution_id": "uuid",
  "status": "queued"
}

Agenten-Ausfuehrungshistorie abrufen¶

GET /api/v1/agents/{id}/history
Authorization: Bearer <your-token>

Ruft die Ausfuehrungshistorie fuer einen bestimmten Agenten ab.

Response (200 OK):

{
  "history": [
    {
      "execution_id": "uuid",
      "status": "completed",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}

Agent-Heartbeat¶

POST /api/v1/agents/{id}/heartbeat
Authorization: Bearer <your-token>

Sendet einen Heartbeat von einem laufenden Agenten, um seinen Gesundheitsstatus zu aktualisieren.

Event an Agent senden¶

POST /api/v1/agents/{id}/events
Authorization: Bearer <your-token>

Sendet ein externes Event an einen laufenden Agenten fuer ereignisgesteuerte Ausfuehrung.

System-Metriken¶

GET /api/v1/metrics

Ruft einen umfassenden Metriken-Snapshot ab, der Scheduler, Task-Manager, Load Balancer und Systemressourcen abdeckt.

Response (200 OK):

{
  "timestamp": "2026-02-16T12:00:00Z",
  "scheduler": {
    "total_jobs": 12,
    "active_jobs": 8,
    "paused_jobs": 2,
    "failed_jobs": 1,
    "total_runs": 450,
    "successful_runs": 445,
    "dead_letter_count": 2
  },
  "task_manager": {
    "queued_tasks": 3,
    "running_tasks": 5,
    "completed_tasks": 1200,
    "failed_tasks": 15
  },
  "load_balancer": {
    "total_workers": 4,
    "active_workers": 3,
    "requests_per_second": 12.5
  },
  "system": {
    "cpu_usage_percent": 45.2,
    "memory_usage_bytes": 536870912,
    "memory_total_bytes": 17179869184,
    "uptime_seconds": 3600
  }
}

Der Metriken-Snapshot kann auch in Dateien (atomischer JSON-Schreibvorgang) oder OTLP-Endpunkte exportiert werden, indem das MetricsExporter-System der Runtime verwendet wird. Siehe den Abschnitt Metriken und Telemetrie weiter unten.

Metriken und Telemetrie¶

Symbiont unterstuetzt den Export von Laufzeitmetriken an mehrere Backends:

Datei-Exporter¶

Schreibt Metriken-Snapshots als atomische JSON-Dateien (tempfile + rename):

use symbi_runtime::metrics::{FileMetricsExporter, MetricsExporterConfig};

let exporter = FileMetricsExporter::new("/var/lib/symbi/metrics.json");
exporter.export(&snapshot)?;

OTLP-Exporter¶

Sendet Metriken an jeden OpenTelemetry-kompatiblen Endpunkt (erfordert das metrics Feature):

use symbi_runtime::metrics::{OtlpExporter, OtlpExporterConfig, OtlpProtocol};

let config = OtlpExporterConfig {
    endpoint: "http://localhost:4317".to_string(),
    protocol: OtlpProtocol::Grpc,
    ..Default::default()
};

Composite-Exporter¶

Fan-Out an mehrere Backends gleichzeitig -- einzelne Export-Fehler werden protokolliert, blockieren aber andere Exporter nicht:

use symbi_runtime::metrics::CompositeExporter;

let composite = CompositeExporter::new(vec![
    Box::new(file_exporter),
    Box::new(otlp_exporter),
]);

Hintergrund-Sammlung¶

Der MetricsCollector laeuft als Hintergrund-Thread und sammelt periodisch Snapshots und exportiert sie:

use symbi_runtime::metrics::MetricsCollector;

let collector = MetricsCollector::new(exporter, interval);
collector.start();
// ... spaeter ...
collector.stop();

Skill-Scanning (ClawHavoc)¶

Der SkillScanner untersucht Agent-Skill-Inhalte auf boeswillige Muster, bevor sie geladen werden. Er wird mit 40 integrierten ClawHavoc-Verteidigungsregeln in 10 Angriffskategorien ausgeliefert:

Siehe das Sicherheitsmodell fuer die vollstaendige Regelliste und das Schweregrad-Modell.

Verwendung¶

use symbi_runtime::skills::SkillScanner;

let scanner = SkillScanner::new(); // enthaelt alle 40 Standardregeln
let result = scanner.scan_skill("/path/to/skill/");

if !result.passed {
    for finding in &result.findings {
        eprintln!("[{}] {}: {} (line {})",
            finding.severity, finding.rule, finding.message, finding.line);
    }
}

Benutzerdefinierte Deny-Muster koennen neben den Standards hinzugefuegt werden:

let scanner = SkillScanner::with_custom_rules(vec![
    ("custom-pattern".into(), r"my_dangerous_pattern".into(),
     ScanSeverity::Warning, "Custom rule description".into()),
]);

Server-Konfiguration¶

Der Runtime HTTP API-Server kann mit den folgenden Optionen konfiguriert werden:

• Standard-Bind-Adresse: 127.0.0.1:8080
• CORS-Unterstuetzung: Konfigurierbar fuer Entwicklung
• Request-Tracing: Aktiviert ueber Tower-Middleware
• Feature Gate: Verfuegbar hinter dem http-api Cargo-Feature

Feature-Konfigurationsreferenz¶

Cloud-LLM-Inferenz (cloud-llm)¶

Verbindung zu Cloud-LLM-Anbietern ueber OpenRouter fuer Agent-Reasoning:

cargo build --features cloud-llm

Umgebungsvariablen: - OPENROUTER_API_KEY -- Ihr OpenRouter-API-Schluessel (erforderlich) - OPENROUTER_MODEL -- Zu verwendendes Modell (Standard: google/gemini-2.0-flash-001) - OPENROUTER_REFERER -- Optional. Setzt den HTTP-Referer-Header bei OpenRouter-Anfragen (App-Zuordnung). Nicht setzen fuer nicht zugeordneten Traffic. - OPENROUTER_TITLE -- Optional. Setzt den X-Title-Header. Siehe OpenRouter app attribution.

Der Cloud-LLM-Anbieter integriert sich in die execute_actions()-Pipeline der Reasoning-Schleife. Er unterstuetzt Streaming-Antworten, automatische Wiederholungsversuche mit exponentiellem Backoff und Token-Nutzungsverfolgung.

Standalone Agent-Modus (standalone-agent)¶

Meta-Feature, das Cloud-LLM-Inferenz fuer Cloud-native Agenten aktiviert:

cargo build --features standalone-agent
# Aktiviert: cloud-llm

Umgebungsvariablen: - OPENROUTER_API_KEY -- OpenRouter API-Schluessel

Note: Composio MCP and SymbiBot integration were removed in this version due to security concerns — see SECURITY_AUDIT.md C3 for context.

Cedar Policy Engine (cedar)¶

Formale Autorisierung mit der Cedar-Richtliniensprache:

cargo build --features cedar

Cedar-Richtlinien integrieren sich in die Gate-Phase der Reasoning-Schleife und bieten feingranulare Autorisierungsentscheidungen. Siehe das Sicherheitsmodell fuer Richtlinienbeispiele.

Vektordatenbank-Konfiguration¶

Symbiont wird mit LanceDB als Standard-eingebettetem Vektor-Backend ausgeliefert -- kein externer Dienst erforderlich. Fuer skalierte Deployments ist Qdrant als optionales Backend verfuegbar.

LanceDB (Standard):

[vector_db]
enabled = true
backend = "lancedb"
collection_name = "symbi_knowledge"

Keine zusaetzliche Konfiguration erforderlich. Daten werden lokal neben der Runtime gespeichert.

Qdrant (optional):

cargo build --features vector-qdrant

[vector_db]
enabled = true
backend = "qdrant"
collection_name = "symbi_knowledge"
url = "http://localhost:6333"

Umgebungsvariablen: - SYMBIONT_VECTOR_BACKEND -- lancedb (Standard) oder qdrant - QDRANT_URL -- Qdrant-Server-URL (nur bei Verwendung von Qdrant)

Erweiterte Reasoning-Primitiven (orga-adaptive)¶

Tool-Kuratierung, Stuck-Loop-Erkennung, Kontext-Pre-Fetch und verzeichnisspezifische Konventionen aktivieren:

cargo build --features orga-adaptive

Siehe den orga-adaptive-Leitfaden fuer die vollstaendige Konfigurationsreferenz.

Datenstrukturen¶

Kern-Typen¶

// Workflow-Ausfuehrungsanfrage
WorkflowExecutionRequest {
    workflow_id: String,
    parameters: serde_json::Value,
    agent_id: Option<AgentId>
}

// Agent-Status-Response
AgentStatusResponse {
    agent_id: AgentId,
    state: AgentState,
    last_activity: DateTime<Utc>,
    resource_usage: ResourceUsage
}

// Gesundheitspruefungs-Response
HealthResponse {
    status: String,
    uptime_seconds: u64,
    timestamp: DateTime<Utc>,
    version: String
}

// Agent-Erstellungsanfrage
CreateAgentRequest {
    name: String,
    dsl: String
}

// Agent-Erstellungsantwort
CreateAgentResponse {
    id: String,
    status: String
}

// Agent-Aktualisierungsanfrage
UpdateAgentRequest {
    name: Option<String>,
    dsl: Option<String>
}

// Agent-Aktualisierungsantwort
UpdateAgentResponse {
    id: String,
    status: String
}

// Agent-Loeschantwort
DeleteAgentResponse {
    id: String,
    status: String
}

// Agent-Ausfuehrungsanfrage
ExecuteAgentRequest {
    // Leere Struktur vorerst
}

// Agent-Ausfuehrungsantwort
ExecuteAgentResponse {
    execution_id: String,
    status: String
}

// Agent-Ausfuehrungseintrag
AgentExecutionRecord {
    execution_id: String,
    status: String,
    timestamp: String
}

// Agenten-Ausfuehrungshistorie-Response
GetAgentHistoryResponse {
    history: Vec<AgentExecutionRecord>
}

Runtime Provider Interface¶

Die API implementiert ein RuntimeApiProvider Trait mit den folgenden erweiterten Methoden:

• execute_workflow() - Fuehrt einen Workflow mit gegebenen Parametern aus
• get_agent_status() - Ruft detaillierten Status mit Echtzeit-Ausfuehrungsmetriken ab
• get_system_health() - Ruft den allgemeinen Systemgesundheitsstatus mit Scheduler-Statistiken ab
• list_agents() - Listet alle Agenten auf (laufend, wartend und abgeschlossen)
• shutdown_agent() - Ordnungsgemaesses Herunterfahren mit Ressourcenbereinigung und Timeout-Behandlung
• get_metrics() - Ruft umfassende Systemmetriken einschliesslich Aufgabenstatistiken ab
• create_agent() - Erstellt Agenten mit Ausfuehrungsmodus-Spezifikation
• update_agent() - Aktualisiert Agent-Konfiguration mit Persistenz
• delete_agent() - Loescht Agenten mit ordnungsgemaesser Bereinigung laufender Prozesse
• execute_agent() - Startet Ausfuehrung mit Ueberwachung und Gesundheitspruefungen
• get_agent_history() - Ruft detaillierte Ausfuehrungshistorie mit Leistungsmetriken ab

Scheduling-API¶

Alle Scheduling-Endpunkte erfordern Authentifizierung. Erfordert das cron Feature.

Zeitplaene auflisten¶

GET /api/v1/schedules
Authorization: Bearer <your-token>

Response (200 OK):

[
  {
    "job_id": "uuid",
    "name": "daily-report",
    "cron_expression": "0 0 9 * * *",
    "timezone": "America/New_York",
    "status": "active",
    "enabled": true,
    "next_run": "2026-03-04T09:00:00Z",
    "run_count": 42
  }
]

Zeitplan erstellen¶

POST /api/v1/schedules
Authorization: Bearer <your-token>

Request Body:

{
  "name": "daily-report",
  "cron_expression": "0 0 9 * * *",
  "timezone": "America/New_York",
  "agent_name": "report-agent",
  "policy_ids": ["policy-1"],
  "one_shot": false
}

Der cron_expression verwendet sechs Felder: sec min hour day month weekday (optionales siebtes Feld fuer Jahr).

Response (200 OK):

{
  "job_id": "uuid",
  "next_run": "2026-03-04T09:00:00Z",
  "status": "created"
}

Zeitplan aktualisieren¶

PUT /api/v1/schedules/{id}
Authorization: Bearer <your-token>

Request Body (alle Felder optional):

{
  "cron_expression": "0 */10 * * * *",
  "timezone": "UTC",
  "policy_ids": ["policy-2"],
  "one_shot": true
}

Zeitplan pausieren / fortsetzen / ausloesen¶

POST /api/v1/schedules/{id}/pause
POST /api/v1/schedules/{id}/resume
POST /api/v1/schedules/{id}/trigger
Authorization: Bearer <your-token>
Idempotency-Key: <invocation-uuid>

Manuelle Ausfuehrungen erfordern ein administratives Token und eine UUID im Header Idempotency-Key. Sie liefern queued, ein gespeichertes Ergebnis oder einen expliziten Zustand in_progress / unresolved / reconciled / conflict. Verwenden Sie bei Wiederholungen dieselbe UUID. Pausieren und Fortsetzen behalten die folgende Antwort; ungeklaerte Ausfuehrungen verhindern das Fortsetzen. Siehe Cron-Wiederherstellung.

Response (200 OK):

{
  "job_id": "uuid",
  "action": "paused",
  "status": "ok"
}

Zeitplan loeschen¶

DELETE /api/v1/schedules/{id}
Authorization: Bearer <your-token>

Response (200 OK):

{
  "job_id": "uuid",
  "deleted": true
}

Zeitplan-Historie abrufen¶

GET /api/v1/schedules/{id}/history
Authorization: Bearer <your-token>

Response (200 OK):

{
  "job_id": "uuid",
  "history": [
    {
      "run_id": "uuid",
      "started_at": "2026-03-03T09:00:00Z",
      "completed_at": "2026-03-03T09:01:23Z",
      "status": "completed",
      "error": null,
      "execution_time_ms": 83000
    }
  ]
}

Naechste Laeufe abrufen¶

GET /api/v1/schedules/{id}/next?count=5
Authorization: Bearer <your-token>

Response (200 OK):

{
  "job_id": "uuid",
  "next_runs": [
    "2026-03-04T09:00:00Z",
    "2026-03-05T09:00:00Z"
  ]
}

Scheduler-Gesundheit¶

GET /api/v1/health/scheduler

Gibt Scheduler-spezifische Gesundheits- und Statistikdaten zurueck.

Channel-Adapter-API¶

Alle Channel-Endpunkte erfordern Authentifizierung. Verbindet Agenten mit Slack, Microsoft Teams und Mattermost.

Channels auflisten¶

GET /api/v1/channels
Authorization: Bearer <your-token>

Response (200 OK):

[
  {
    "id": "uuid",
    "name": "slack-general",
    "platform": "slack",
    "status": "running"
  }
]

Channel registrieren¶

POST /api/v1/channels
Authorization: Bearer <your-token>

Request Body:

{
  "name": "slack-general",
  "platform": "slack",
  "config": {
    "webhook_url": "https://hooks.slack.com/...",
    "channel": "#general"
  }
}

Unterstuetzte Plattformen: slack, teams, mattermost.

Response (200 OK):

{
  "id": "uuid",
  "name": "slack-general",
  "platform": "slack",
  "status": "registered"
}

Channel abrufen / aktualisieren / loeschen¶

GET    /api/v1/channels/{id}
PUT    /api/v1/channels/{id}
DELETE /api/v1/channels/{id}
Authorization: Bearer <your-token>

Channel starten / stoppen¶

POST /api/v1/channels/{id}/start
POST /api/v1/channels/{id}/stop
Authorization: Bearer <your-token>

Response (200 OK):

{
  "id": "uuid",
  "action": "started",
  "status": "ok"
}

Channel-Gesundheit¶

GET /api/v1/channels/{id}/health
Authorization: Bearer <your-token>

Response (200 OK):

{
  "id": "uuid",
  "connected": true,
  "platform": "slack",
  "workspace_name": "my-team",
  "channels_active": 3,
  "last_message_at": "2026-03-03T15:42:00Z",
  "uptime_secs": 86400
}

Identitaetszuordnungen¶

GET  /api/v1/channels/{id}/mappings
POST /api/v1/channels/{id}/mappings
Authorization: Bearer <your-token>

Ordnet Plattform-Benutzer Symbiont-Identitaeten fuer Agent-Interaktionen zu.

Channel-Audit-Log¶

GET /api/v1/channels/{id}/audit
Authorization: Bearer <your-token>

Scheduler-Features¶

Echte Aufgabenausfuehrung: - Prozess-Spawning mit sicheren Ausfuehrungsumgebungen - Ressourcenueberwachung (Speicher, CPU) mit 5-Sekunden-Intervallen - Gesundheitspruefungen und automatische Fehlererkennung - Unterstuetzung fuer ephemere, persistente, geplante und ereignisgesteuerte Ausfuehrungsmodi

Ordnungsgemaesses Herunterfahren: - 30-Sekunden-Frist fuer ordnungsgemaesse Beendigung - Erzwungene Beendigung fuer nicht reagierende Prozesse - Ressourcenbereinigung und Metriken-Persistenz - Warteschlangenbereinigung und Zustandssynchronisierung

Erweiterte Kontextverwaltung¶

Erweiterte Suchfaehigkeiten:

{
  "query_type": "keyword|temporal|similarity|hybrid",
  "search_terms": ["term1", "term2"],
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "memory_types": ["factual", "procedural", "episodic"],
  "relevance_threshold": 0.7,
  "max_results": 10
}

Wichtigkeitsberechnung: - Multi-Faktor-Bewertung mit Zugriffshaeufigkeit, Aktualitaet und Benutzerfeedback - Speichertyp-Gewichtung und Alterungsabklingfaktoren - Vertrauensbewertungsberechnung fuer geteiltes Wissen

Zugriffskontrollintegration: - Richtlinien-Engine verbunden mit Kontextoperationen - Agentenspezifischer Zugriff mit sicheren Grenzen - Wissensaustausch mit granularen Berechtigungen

Tool Review API (Produktion)¶

Die Tool Review API bietet einen vollstaendigen Workflow zur sicheren Ueberpruefung, Analyse und Signierung von MCP (Model Context Protocol) Tools unter Verwendung KI-gesteuerter Sicherheitsanalyse mit menschlichen Ueberwachungsfaehigkeiten.

Basis-URL¶

https://your-symbiont-instance.com/api/v1

Authentifizierung¶

Alle Endpunkte erfordern Bearer JWT-Authentifizierung:

Authorization: Bearer <your-jwt-token>

Kern-Workflow¶

Die Tool Review API folgt diesem Request/Response-Flow:

graph TD
    A[Tool Einreichen] --> B[Sicherheitsanalyse]
    B --> C{Risikobewertung}
    C -->|Geringes Risiko| D[Auto-Genehmigung]
    C -->|Hohes Risiko| E[Menschliche Review-Warteschlange]
    E --> F[Menschliche Entscheidung]
    F --> D
    D --> G[Code-Signierung]
    G --> H[Signiertes Tool Bereit]

Endpunkte¶

Review-Sitzungen¶

Tool zur Ueberpruefung einreichen¶

POST /sessions

Reicht ein MCP-Tool zur Sicherheitsueberpruefung und -analyse ein.

Request Body:

{
  "tool_name": "string",
  "tool_version": "string",
  "source_code": "string",
  "metadata": {
    "description": "string",
    "author": "string",
    "permissions": ["array", "of", "permissions"]
  }
}

Response:

{
  "review_id": "uuid",
  "status": "submitted",
  "created_at": "2024-01-15T10:30:00Z"
}

Review-Sitzungen auflisten¶

GET /sessions

Ruft eine paginierte Liste von Review-Sitzungen mit optionaler Filterung ab.

Query-Parameter: - page (integer): Seitennummer fuer Paginierung - limit (integer): Anzahl der Elemente pro Seite - status (string): Nach Review-Status filtern - author (string): Nach Tool-Autor filtern

Response:

{
  "sessions": [
    {
      "review_id": "uuid",
      "tool_name": "string",
      "status": "string",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "has_next": true
  }
}

Review-Sitzungsdetails abrufen¶

GET /sessions/{reviewId}

Ruft detaillierte Informationen ueber eine bestimmte Review-Sitzung ab.

Response:

{
  "review_id": "uuid",
  "tool_name": "string",
  "tool_version": "string",
  "status": "string",
  "analysis_results": {
    "risk_score": 85,
    "findings": ["array", "of", "security", "findings"],
    "recommendations": ["array", "of", "recommendations"]
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:00:00Z"
}

Sicherheitsanalyse¶

Analyseergebnisse abrufen¶

GET /analysis/{analysisId}

Ruft detaillierte Sicherheitsanalyseergebnisse fuer eine bestimmte Analyse ab.

Response:

{
  "analysis_id": "uuid",
  "review_id": "uuid",
  "risk_score": 85,
  "analysis_type": "automated",
  "findings": [
    {
      "severity": "high",
      "category": "code_injection",
      "description": "Potential code injection vulnerability detected",
      "location": "line 42",
      "recommendation": "Sanitize user input before execution"
    }
  ],
  "rag_insights": [
    {
      "knowledge_source": "security_kb",
      "relevance_score": 0.95,
      "insight": "Similar patterns found in known vulnerabilities"
    }
  ],
  "completed_at": "2024-01-15T10:45:00Z"
}

Menschlicher Review-Workflow¶

Review-Warteschlange abrufen¶

GET /review/queue

Ruft Elemente ab, die auf menschliche Ueberpruefung warten, typischerweise hochriskante Tools, die manuelle Inspektion erfordern.

Response:

{
  "pending_reviews": [
    {
      "review_id": "uuid",
      "tool_name": "string",
      "risk_score": 92,
      "priority": "high",
      "assigned_to": "reviewer@example.com",
      "escalated_at": "2024-01-15T11:00:00Z"
    }
  ],
  "queue_stats": {
    "total_pending": 5,
    "high_priority": 2,
    "average_wait_time": "2h 30m"
  }
}

Review-Entscheidung einreichen¶

POST /review/{reviewId}/decision

Reicht die Entscheidung eines menschlichen Reviewers zu einem Tool-Review ein.

Request Body:

{
  "decision": "approve|reject|request_changes",
  "comments": "Detailed review comments",
  "conditions": ["array", "of", "approval", "conditions"],
  "reviewer_id": "reviewer@example.com"
}

Response:

{
  "review_id": "uuid",
  "decision": "approve",
  "processed_at": "2024-01-15T12:00:00Z",
  "next_status": "approved_for_signing"
}

Tool-Signierung¶

Signierungsstatus abrufen¶

GET /signing/{reviewId}

Ruft den Signierungsstatus und Signaturinformationen fuer ein ueberprueftes Tool ab.

Response:

{
  "review_id": "uuid",
  "signing_status": "completed",
  "signature_info": {
    "algorithm": "RSA-SHA256",
    "key_id": "signing-key-001",
    "signature": "base64-encoded-signature",
    "signed_at": "2024-01-15T12:30:00Z"
  },
  "certificate_chain": ["array", "of", "certificates"]
}

Signiertes Tool herunterladen¶

GET /signing/{reviewId}/download

Laedt das signierte Tool-Paket mit eingebetteter Signatur und Verifizierungsmetadaten herunter.

Response: Binaerer Download des signierten Tool-Pakets.

Statistiken und Ueberwachung¶

Workflow-Statistiken abrufen¶

GET /stats

Ruft umfassende Statistiken und Metriken zum Review-Workflow ab.

Response:

{
  "workflow_stats": {
    "total_reviews": 1250,
    "approved": 1100,
    "rejected": 125,
    "pending": 25
  },
  "performance_metrics": {
    "average_review_time": "45m",
    "auto_approval_rate": 0.78,
    "human_review_rate": 0.22
  },
  "security_insights": {
    "common_vulnerabilities": ["sql_injection", "xss", "code_injection"],
    "risk_score_distribution": {
      "low": 45,
      "medium": 35,
      "high": 20
    }
  }
}

Rate Limiting¶

Die Tool Review API implementiert Rate Limiting pro Endpunkt-Typ:

• Einreichungs-Endpunkte: 10 Anfragen pro Minute
• Abfrage-Endpunkte: 100 Anfragen pro Minute
• Download-Endpunkte: 20 Anfragen pro Minute

Rate Limit-Header sind in allen Responses enthalten:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642248000

Fehlerbehandlung¶

Die API verwendet Standard-HTTP-Statuscodes und gibt detaillierte Fehlerinformationen zurueck:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Tool source code is required",
    "details": {
      "field": "source_code",
      "reason": "missing_required_field"
    }
  }
}

CLI-Subcommands¶

Neben der langlebigen HTTP-Oberflaeche stellt symbi mehrere reine CLI-Subcommands fuer einmalige Operationen bereit. Der vollstaendige Katalog findet sich in symbi --help; die fuer Integration und Richtliniendurchsetzung relevantesten sind:

symbi schemapin¶

TOFU-Integritaetspinning (Trust-On-First-Use) fuer MCP-Server-Konfigurationen. Konzipiert fuer den Aufruf aus SessionStart-Hooks, damit sich der Konfigurations-Hash eines MCP-Servers zwischen Sitzungen nicht unbemerkt aendern kann, ohne dass der Operator zustimmt.

# Gepinnten Hash fuer einen oder alle MCP-Server in .mcp.json verifizieren
symbi schemapin verify [--mcp-server <NAME>] [--config <PATH>]

# Aktuellen Konfigurations-Hash fuer einen Server pinnen
symbi schemapin pin --mcp-server <NAME> [--config <PATH>] [--force]

# Alle gepinnten Server unter ~/.symbiont/schemapin/mcp/ auflisten
symbi schemapin list

# Einen Pin-Eintrag entfernen
symbi schemapin unpin --mcp-server <NAME>

Pins werden unter ~/.symbiont/schemapin/mcp/ als JSON-Eintraege gespeichert. verify beendet mit 0 bei Uebereinstimmung, mit einem Wert ungleich Null bei Abweichung oder fehlendem Pin — geeignet fuer den Einsatz in Pre-Session-Skripten.

symbi policy¶

Cedar-Richtlinienevaluierung gegen Tool-Call-Events. Liest ein einzelnes Event als JSON, entscheidet allow / deny gegenueber einem Richtlinienverzeichnis und beendet sich mit einem fuer Skripting geeigneten Statuscode.

# Ein von stdin gelesenes Event evaluieren
echo '{"principal":"Agent::\"dev\"", "action":"write", "resource":{...}}' \
  | symbi policy evaluate --stdin --policies ./policies

# Ein aus einer Datei gelesenes Event evaluieren
symbi policy evaluate --input event.json --policies ./policies

# Nur strukturiertes JSON ausgeben (geeignet fuer programmatische Nutzung)
symbi policy evaluate --stdin --policies ./policies --json

Die Standardausgabe ist das blosse Urteil auf stdout mit strukturierten Details auf stderr; --json fasst alles zu stdout-JSON zusammen. Das ist dieselbe Cedar-Entscheidungslogik, die das Runtime inline verwendet — nuetzlich fuer Shift-Left-Richtlinientests in CI und zum Debuggen von Ablehnungen ausserhalb eines laufenden Runtimes.

symbi agents-md¶

Regeneriert AGENTS.md aus den aktuellen agents/*.symbi-Dateien (das Legacy-Format .dsl wird ebenfalls erfasst). Laeuft automatisch waehrend symbi init; rufen Sie es manuell nach dem Hinzufuegen oder Bearbeiten von Agentendefinitionen auf.

symbi agents-md generate --dir . --output AGENTS.md

Erste Schritte¶

Runtime HTTP API¶

1. Das symbi-Binary bauen (das http-api-Feature ist in der Binary-Crate standardmaessig aktiv):

   cargo build --release
   

2. Runtime starten -- die API lauscht auf :8080, HTTP Input auf :8081:

   ./target/release/symbi up --http-bind 0.0.0.0
   

Fuer ein vorgeneriertes Projekt und den empfohlenen Docker-Ablauf siehe Erste Schritte.

1. Ueberpruefen, ob der Server laeuft:

   curl http://127.0.0.1:8080/api/v1/health
   

2. Authentifizierten Endpunkt testen -- symbi up gibt das erzeugte Bearer-Token beim Start aus (oder setzen Sie eines explizit mit --http.token):

   curl -H "Authorization: Bearer $SYMBI_HTTP_TOKEN" \
        http://127.0.0.1:8080/api/v1/agents
   

Tool Review API¶

1. API-Anmeldedaten von Ihrem Symbiont-Administrator erhalten
2. Tool zur Ueberpruefung ueber den /sessions Endpunkt einreichen
3. Review-Fortschritt ueber /sessions/{reviewId} ueberwachen
4. Signierte Tools von /signing/{reviewId}/download herunterladen

Support¶

Fuer API-Support und Fragen: - Ueberpruefen Sie die Runtime-Architektur-Dokumentation - Konsultieren Sie die Sicherheitsmodell-Dokumentation - Melden Sie Probleme im GitHub-Repository des Projekts

Ein abgeglichener (reconciled) Aufruf liefert HTTP 409 und die separat signierte Betreiber-resolution; er liefert niemals einen konstruierten Runtime-Abschluss. Die Cron-Historie behaelt den Status Reconciled, den urspruenglichen Fehler samt Audit sowie das Resolution-Objekt. Der Job bleibt bis zum expliziten Fortsetzen pausiert. Siehe Betreiber-Abgleich.