Erste Schritte¶

Symbiont 2.0: Lesen Sie vor dem Upgrade die Migrationsanleitung und Release-Verifizierung. Prompt-Caching und gesteuerte Verbesserungen bleiben ausdrücklich optional; bestehende Agenten werden nicht automatisch umgestellt.

Fuehren Sie Agenten unter Containment aus? Beginnen Sie mit dem Containment-Betreiberleitfaden fuer Ausfuehrungsvoraussetzungen, Aenderungen bei Genehmigungen und die aktuelle Abdeckung.

Dieser Leitfaden fuehrt Sie durch die Einrichtung von Symbi und die Erstellung Ihres ersten KI-Agenten.

▶ Zum Einstieg das Walkthrough-Video ansehen:

Inhaltsverzeichnis¶

Voraussetzungen¶

Was Sie benoetigen, haengt davon ab, wie Sie Symbi installieren und ausfuehren.

Zur Ausfuehrung der vorkompilierten Binaerdatei¶

Die vorkompilierten Binaerdateien sind bereits fertig kompiliert -- Sie benoetigen kein Rust, protobuf oder Git, um sie zu installieren oder auszufuehren. Installieren Sie sie mit Homebrew, dem Installationsskript (curl) oder per manuellem Download von GitHub Releases.

• Docker wird nur zur Laufzeit benoetigt, wenn Sie Agenten in der Standard-Sandbox-Stufe (tier1, Docker-basiert) ausfuehren. Es wird nicht benoetigt, um Symbi zu installieren oder um symbi init, symbi dsl oder symbi --version auszufuehren.

Zum Erstellen aus dem Quellcode¶

Nur erforderlich, wenn Sie ueber cargo install installieren oder das Repository selbst bauen:

• Rust 1.89+
• protobuf-compiler (apt install protobuf-compiler unter Ubuntu, brew install protobuf unter macOS)
• Git (zum Klonen des Repositories)

Optional¶

• symbi-claude-code (Claude Code Governance-Plugin)
• symbi-gemini-cli (Gemini CLI Governance-Erweiterung)

Hinweis: Vektorsuche ist integriert. Symbi wird mit LanceDB als eingebetteter Vektordatenbank ausgeliefert -- kein externer Dienst erforderlich.

Installation¶

Option 1: Vorgefertigte Binärdateien¶

macOS (Homebrew):

brew tap thirdkeyai/tap
brew install symbi

Linux / macOS (Repository-Installer):

curl -fsSL https://raw.githubusercontent.com/ThirdKeyAI/Symbiont/main/scripts/install.sh | bash
export PATH="$HOME/.symbi/bin:$PATH"
symbi --version

Das Skript benötigt Bash, curl oder wget, tar sowie sha256sum oder shasum. Fehlende oder mehrdeutige Manifesteinträge und falsche Prüfsummen brechen die Installation ab.

Der Repository-Installer prüft die SHA-256-Prüfsumme aus dem HTTPS-Release-Manifest vor dem Entpacken mit sha256sum oder shasum. Er installiert die neueste Version unter ~/.symbi/bin und führt keine unabhängige Sigstore-Identitätsprüfung durch. Setzen Sie SYMBI_INSTALL_DIR für den bash-Prozess, um ein anderes Stammverzeichnis zu wählen. Für eine feste Version verwenden Sie einen manuellen Download.

Manuelle Downloads unterstützen Linux x86_64/ARM64, macOS ARM64 und Windows x86_64. Verwenden Sie unter Windows das ZIP-Archiv. Folgen Sie der Release-Verifizierung, bevor Sie die Binärdatei in PATH aufnehmen.

Landlock wird pro Linux-Projekt mit symbi init --sandbox landlock gewählt. Erforderlich sind Landlock ABI 6+, seccomp, unprivilegierte Benutzer-, Mount- und Netzwerk-Namespaces, delegierte cgroup v2 und ein systemd-Benutzermanager. Siehe Linux-Einrichtung (Englisch).

Option 2: Docker (Empfohlen)¶

Der schnellste Weg zu einem lauffaehigen Runtime ist, den Container das Projekt fuer Sie erstellen zu lassen:

# 1. symbiont.toml, agents/, policies/, docker-compose.yml und
#    eine .env mit einem frisch generierten SYMBIONT_MASTER_KEY erzeugen.
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

# 2. Runtime starten. Liest .env automatisch.
docker compose up

Die Runtime-API ist jetzt unter http://localhost:8080 und HTTP Input unter http://localhost:8081 erreichbar.

Wenn Sie lieber aus einem Klon arbeiten moechten (um das Image selbst zu bauen oder Tests auszufuehren):

git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont

# Einheitlichen symbi-Container erstellen
docker build -t symbi:latest .

# Entwicklungsumgebung ausfuehren
docker run --rm -it -v $(pwd):/workspace symbi:latest bash

Option 3: Lokale Installation¶

Fuer lokale Entwicklung:

# Repository klonen
git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont

# Rust-Abhaengigkeiten installieren und kompilieren
cargo build --release

# Tests ausfuehren, um die Installation zu ueberpruefen
cargo test

Installation ueberpruefen¶

Testen Sie, ob alles korrekt funktioniert:

# DSL-Parser testen
cd crates/dsl && cargo run && cargo test

# Laufzeitsystem testen
cd ../runtime && cargo test

# Beispiel-Agenten ausfuehren
cargo run --example basic_agent
cargo run --example full_system

# Einheitliche symbi CLI testen
cd ../.. && cargo run -- dsl --help
cargo run -- mcp --help

# Mit Docker-Container testen
docker run --rm symbi:latest --version
docker run --rm -v $(pwd):/workspace symbi:latest dsl parse --help
docker run --rm symbi:latest mcp --help

Ohne API-Schluessel ausprobieren¶

Zwei Dinge funktionieren offline, bevor Sie einen Modellanbieter konfigurieren. Beide zeigen, was Symbiont tatsaechlich tut — beginnen Sie hier.

Ein Tool definieren und im Trockenlauf pruefen. Argumenttypen, Scope-Grenzen und Injection-Pruefungen werden erzwungen, bevor irgendetwas ausgefuehrt wird:

symbi tools init greet
symbi tools validate
symbi tools test greet --arg target=example

greet                                    OK

  ✓ target (string): example → OK

  Command:   greet example
  Cedar:     Tool::Greet / execute_tool

  [dry run — command not executed]

Einen Agenten auszufuehren erfordert einen Modellanbieter — entweder einen Cloud-Schluessel oder ein lokales Modell, beides unten beschrieben.

Projektinitialisierung¶

Der schnellste Weg, ein neues Symbiont-Projekt zu starten, ist symbi init:

symbi init

Dies startet einen interaktiven Assistenten, der Sie durch Folgendes fuehrt: - Profilauswahl: minimal, assistant, dev-agent oder multi-agent - SchemaPin-Modus: tofu (Trust-On-First-Use), strict oder disabled - Sandbox-Stufe: landlock (natives Linux), tier0 (keine, nur Entwicklung), tier1 (Docker), tier2 (gVisor / runsc) oder tier3 (Firecracker microVM)

Mit --sandbox landlock --profile dev-agent fragt der Assistent zusaetzlich nach dem Quell-Repository, der installierten Claude-Code-Binaerdatei, der Messages-kompatiblen Inferenz-URL, dem Modell und dem Namen der Anmeldedaten-Umgebungsvariablen. Er erzeugt ein schreibgeschuetztes Review-Setup in einem separaten, leeren Steuerverzeichnis. Nichtinteraktive Aufrufer muessen --source, --managed-executable, --inference-url, --inference-model und --inference-key-env angeben. Siehe Linux-Entwickler-Onboarding.

Was init erzeugt¶

Jeder Durchlauf schreibt:

Mit --no-docker-compose ueberspringen Sie die Compose-Datei, und mit --dir <PATH> schreiben Sie in ein anderes als das aktuelle Verzeichnis (unverzichtbar innerhalb eines Docker-Containers — siehe unten).

Nicht-interaktiver Modus¶

Fuer CI/CD oder skriptbasierte Setups:

symbi init --profile assistant --schemapin tofu --sandbox tier1 --no-interact

init innerhalb von Docker ausfuehren¶

Da das WORKDIR des Images /var/lib/symbi ist, verwenden Sie --dir, um in Ihr gemountetes Volume zu schreiben:

docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
  init --profile assistant --no-interact --dir /workspace

Das fuellt das aktuelle Verzeichnis des Hosts mit dem vollstaendigen Projektbaum.

Profile¶

Aus dem Katalog importieren¶

Vorgefertigte Agenten neben allgemeinen Profilen importieren (der schreibgeschuetzte Landlock-Entwicklungsinitialisierer kombiniert keine Katalogimporte):

symbi init --profile minimal --no-interact
symbi init --catalog assistant,dev

Verfuegbare Katalog-Agenten auflisten:

symbi init --catalog list

Nach der Initialisierung validieren und starten:

symbi dsl -f agents/assistant.symbi   # Ihren Agenten validieren
symbi run assistant -i '{"query": "hello"}'  # Einen einzelnen Agenten testen
symbi up                             # Runtime lokal starten
docker compose up                    # ...oder in Docker starten (liest .env)

Einen einzelnen Agenten ausfuehren¶

Verwenden Sie symbi run, um einen Agenten auszufuehren, ohne den vollstaendigen Laufzeit-Server zu starten:

symbi run <agent-name-oder-datei> --input <json>

Der Befehl loest Agentennamen auf, indem er zuerst den direkten Pfad und dann das agents/-Verzeichnis durchsucht. Er richtet Cloud-Inferenz ueber Umgebungsvariablen (OPENROUTER_API_KEY, OPENAI_API_KEY oder ANTHROPIC_API_KEY) ein, fuehrt die ORGA-Reasoning-Schleife aus und beendet sich.

symbi run assistant -i 'Summarize this document'
symbi run agents/recon.symbi -i '{"target": "10.0.1.5"}' --max-iterations 5

Tool-Befehle, Parser, MCP und PTY-Ausfuehrung erfordern das ausgewaehlte Container-Backend, ein zwischengespeichertes Image mit den deklarierten Binaerdateien sowie explizite Daten-Mounts. Nicht verfuegbare Backends koennen nicht auf Host-Ausfuehrung zurueckfallen. Ausgewaehlte Agenteneinstellungen und Projektstandards werden vor der Inferenz geprueft. Durchlaeufe benoetigen zudem geschuetzten .symbiont/governed/-Speicher und geben ihre oeffentliche Audit-Referenz aus. Siehe Befehlskonfiguration und Durchlauf-Audit.

Ein lokales Modell verwenden¶

Der Anbieter muss kein Cloud-Dienst sein. Richten Sie OPENAI_BASE_URL auf einen beliebigen OpenAI-kompatiblen Server — Ollama, vLLM, LM Studio und llama.cpp bieten alle einen an — und es ist kein Cloud-Schluessel beteiligt:

export OPENAI_API_KEY=ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export CHAT_MODEL=llama3.1

symbi run assistant -i 'hello'

Dieselben drei Variablen gelten fuer symbi up. Symbiont warnt, wenn eine Basis-URL unverschluesseltes http:// verwendet, da der Schluessel mitgesendet wird. Bei einem Modell auf dem eigenen Rechner ist das erwartet.

Aus einer Vorlage starten (symbi new)¶

symbi init erstellt ein generisches Projekt; symbi new erstellt ein Projekt rund um eine von mehreren aufgabenorientierten Vorlagen. Nuetzlich, wenn Sie die Art des benoetigten Agenten kennen, bevor Sie wissen, welche Agenten Sie brauchen.

symbi new --list                     # verfuegbare Vorlagen anzeigen
symbi new <template> <project-name>  # neues Projekt aus einer Vorlage erstellen

Mitgelieferte Vorlagen:

symbi new und symbi init ergaenzen sich: new liefert einen aufgabenspezifischen Ausgangspunkt, init (+ --catalog) einen governance-spezifischen. Sie koennen beides kombinieren -- mit new einsteigen und anschliessend symbi init --catalog ... verwenden, um zusaetzliche vorgefertigte Agenten aus dem Katalog einzubinden.

Ihr erster Agent¶

Lassen Sie uns einen einfachen Datenanalyse-Agenten erstellen, um die Grundlagen von Symbi zu verstehen.

1. Agenten-Definition erstellen¶

Erstellen Sie eine neue Datei my_agent.symbi:

metadata {
    version = "1.0.0"
    author = "your-name"
    description = "My first Symbi agent"
}

agent greet_user(name: String) -> String {
    capabilities = ["greeting", "text_processing"]

    policy safe_greeting {
        allow: read(name) if name.length <= 100
        deny: store(name) if name.contains_sensitive_data
        audit: all_operations with signature
    }

    with memory = "ephemeral", privacy = "low" {
        if (validate_name(name)) {
            greeting = format_greeting(name);
            audit_log("greeting_generated", greeting.metadata);
            return greeting;
        } else {
            return "Hello, anonymous user!";
        }
    }
}

2. Agent ausfuehren¶

# Agenten-Definition parsen und validieren
cargo run -- dsl parse my_agent.symbi

# Agent in der Laufzeitumgebung ausfuehren
cd crates/runtime && cargo run --example basic_agent -- --agent ../../my_agent.symbi

Die DSL verstehen¶

Die Symbi DSL hat mehrere Hauptkomponenten:

Metadaten-Block¶

metadata {
    version = "1.0.0"
    author = "developer"
    description = "Agent description"
}

Stellt wesentliche Informationen ueber Ihren Agenten fuer Dokumentation und Laufzeitverwaltung bereit.

Agenten-Definition¶

agent agent_name(parameter: Type) -> ReturnType {
    capabilities = ["capability1", "capability2"]
    // Agenten-Implementierung
}

Definiert die Schnittstelle, Faehigkeiten und das Verhalten des Agenten.

Richtlinien-Definitionen¶

policy policy_name {
    allow: action_list if condition
    deny: action_list if condition
    audit: operation_type with audit_method
}

Deklarative Sicherheitsrichtlinien, die zur Laufzeit durchgesetzt werden.

Ausfuehrungskontext¶

with memory = "persistent", privacy = "high" {
    // Agenten-Implementierung
}

Spezifiziert Laufzeitkonfiguration fuer Speicherverwaltung und Datenschutzanforderungen.

Naechste Schritte¶

Beispiele erkunden¶

Das Repository enthaelt mehrere Beispiel-Agenten:

# Grundlegender Agent-Beispiel
cd crates/runtime && cargo run --example basic_agent

# Vollstaendige Systemdemonstration
cd crates/runtime && cargo run --example full_system

# Kontext- und Speicher-Beispiel
cd crates/runtime && cargo run --example context_example

# RAG-verstaerkter Agent
cd crates/runtime && cargo run --example rag_example

Erweiterte Funktionen aktivieren¶

HTTP API (Optional)¶

# HTTP API-Funktion aktivieren
cd crates/runtime && cargo build --features http-api

# Mit API-Endpunkten ausfuehren
cd crates/runtime && cargo run --features http-api --example full_system

Wichtige API-Endpunkte: - GET /api/v1/health - Gesundheitspruefung und Systemstatus - GET /api/v1/agents - Alle aktiven Agenten mit Echtzeit-Ausfuehrungsstatus auflisten - GET /api/v1/agents/{id}/status - Detaillierte Agent-Ausfuehrungsmetriken abrufen - POST /api/v1/workflows/execute - Workflows ausfuehren

Neue Agent-Management-Funktionen: - Echtzeit-Prozessueberwachung und Gesundheitspruefungen - Ordnungsgemaesse Shutdown-Faehigkeiten fuer laufende Agenten - Umfassende Ausfuehrungsmetriken und Ressourcennutzungsverfolgung - Unterstuetzung verschiedener Ausfuehrungsmodi (ephemer, persistent, geplant, ereignisgesteuert)

Cloud-LLM-Inferenz¶

Verbindung zu Cloud-LLM-Anbietern ueber OpenRouter:

# Cloud-Inferenz aktivieren
cargo build --features cloud-llm

# API-Schluessel und Modell festlegen
export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="google/gemini-2.0-flash-001"  # optional

Standalone Agent-Modus¶

Einzeiler fuer Cloud-native Agenten mit LLM-Inferenz:

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

Hinweis: Die Composio-MCP- und SymbiBot-Integration wurden in dieser Version aus Sicherheitsgruenden entfernt -- siehe SECURITY_AUDIT.md C3 fuer den Hintergrund.

Erweiterte Reasoning-Primitiven¶

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 Dokumentation.

Cedar Policy Engine¶

Formale Autorisierung mit der Cedar-Richtliniensprache. Standardmaessig aktiv seit v1.14.x: Veroeffentlichte symbi-Binaries (crates.io, Docker, GitHub-Release-Tarballs) enthalten Cedar, und symbi up / symbi run verdrahten CedarPolicyGate beim Start automatisch aus policies/*.cedar-Dateien; sind keine vorhanden, faellt die Runtime auf den fail-closed DefaultPolicyGate zurueck. Um ohne Cedar zu bauen (z. B. wenn Sie stattdessen OpaPolicyGateBridge oder ein eigenes ReasoningPolicyGate anbinden moechten), verwenden Sie:

cargo build --no-default-features --features "keychain,vector-lancedb"  # cedar weglassen

Vektordatenbank (integriert)¶

Symbi enthaelt LanceDB als konfigurationsfreie eingebettete Vektordatenbank. Semantische Suche und RAG funktionieren sofort -- kein separater Dienst erforderlich:

# Agent mit RAG-Funktionen ausfuehren (Vektorsuche funktioniert sofort)
cd crates/runtime && cargo run --example rag_example

# Kontextverwaltung mit erweiterter Suche testen
cd crates/runtime && cargo run --example context_example

Minimaler Build: LanceDB ist standardmaessig enthalten, kann aber fuer schlankere Binaries ausgeschlossen werden: cargo build --no-default-features. Die Runtime faellt sauber auf ein No-op-Vektor-Backend zurueck.

Skalierte Deployments: Qdrant ist als optionales Backend verfuegbar. Bauen Sie mit --features vector-qdrant und setzen Sie SYMBIONT_VECTOR_BACKEND=qdrant.

Kontextverwaltungsfunktionen: - Multi-modale Suche: Schluesselwort-, zeitliche, Aehnlichkeits- und Hybrid-Suchmodi - Wichtigkeitsberechnung: Ausgefeilter Bewertungsalgorithmus unter Beruecksichtigung von Zugriffsmustern, Aktualitaet und Benutzerfeedback - Zugriffskontrolle: Integration der Richtlinien-Engine mit agentenspezifischen Zugriffskontrollen - Automatische Archivierung: Aufbewahrungsrichtlinien mit komprimiertem Speicher und Bereinigung - Wissensaustausch: Sicherer agentenuebergreifender Wissensaustausch mit Vertrauensbewertungen

Feature Flags Referenz¶

# Mit bestimmten Features kompilieren
cargo build --features "cloud-llm,orga-adaptive,cedar"

# Mit allem kompilieren
cargo build --features full

KI-Assistenten-Plugins¶

Symbiont bietet First-Party-Governance-Plugins fuer gaengige KI-Coding-Assistenten mit drei progressiven Schutzstufen:

1. Awareness (Standard) — beratende Protokollierung aller zustandsaendernden Tool-Aufrufe
2. Protection — ein blockierender Hook setzt eine lokale Deny-Liste durch (.symbiont/local-policy.toml)
3. Governance — Cedar-Richtlinienauswertung, wenn symbi im PATH liegt

Die Deny-Listen-Konfiguration ist tool-unabhaengig — dieselbe .symbiont/local-policy.toml funktioniert mit beiden Plugins:

[deny]
paths = [".env", ".ssh/", ".aws/"]
commands = ["rm -rf", "git push --force"]
branches = ["main", "master", "production"]

Claude Code¶

# Install from marketplace
/plugin marketplace add https://github.com/thirdkeyai/symbi-claude-code

# Available skills: /symbi-init, /symbi-policy, /symbi-verify, /symbi-audit, /symbi-dsl

Siehe symbi-claude-code fuer Details.

Mode B: verwalteter Claude-Code-Subprozess¶

Ein Agent mit metadata { executor = "claude_code" } fuehrt sein CLI-Kindprozess im ausgewaehlten Docker-/gVisor-Container mit Scratch-Speicher und privaten Inferenz- und Tool-Kanaelen der Runtime aus. Der mitgelieferte code_reviewer ist der Referenzagent. Konfigurieren Sie zuerst ein zwischengespeichertes CLI-/Python-Image, explizite Backend-Quell-Mounts, registrierte ToolClad-Tools und Cedar-Richtlinien sowie [managed_cli.inference]. Siehe Managed-CLI-Containment fuer ein vollstaendiges Beispiel.

# /srv/source must map to an explicit backend mount in the control project.
symbi run code_reviewer --target /srv/source --max-turns 12 --budget-timeout 15m

# Add operator review for tools that require approval.
symbi run code_reviewer --target /srv/source --approval-terminal

Der Kindprozess erhaelt keinen direkten Quell-Mount, keinen externen Netzwerkzugriff, keinen Host-Anmeldezustand und keine Anbieter-Anmeldedaten. Registrierte Tools vermitteln den erlaubten Datei- und Git-Zugriff. Eingebaute Tools und automatische Erkennung sind deaktiviert. Jede Aktion erfordert eine Autorisierung durch die Runtime; eine Start-Genehmigung autorisiert keine nachfolgenden Aktionen. Plugins werden nicht geladen und --plugin-dir wird abgelehnt.

Erforderliche signierte Sitzungsjournale liegen im privaten .symbiont/governed/-Speicher. Die Runtime gibt den oeffentlichen Verifizierungsschluessel aus. Eine fehlende Genehmigung, unsicherer Audit-Speicher, ein nicht verfuegbares Backend oder eine fehlgeschlagene Bereinigung koennen keinen stillen Erfolg melden. Inferenz-Antworten werden gepuffert, auch SSE, sodass sich gestreamte Ausgabe verzoegert.

Gemini CLI¶

# Install extension
gemini extensions install https://github.com/thirdkeyai/symbi-gemini-cli

Die Gemini-CLI-Erweiterung bietet zusaetzliche Defense-in-Depth durch excludeTools-Manifest-Blockierung und native policies/*.toml-Durchsetzung auf Plattformebene.

Siehe symbi-gemini-cli fuer Details.

Konfiguration¶

Umgebungsvariablen¶

Richten Sie Ihre Umgebung fuer optimale Leistung ein:

# Erforderlich: 32-Byte-Hex-Schluessel zum Verschluesseln persistenter Zustaende.
# Generieren mit: openssl rand -hex 32
# `symbi init` schreibt automatisch einen in .env.
export SYMBIONT_MASTER_KEY="..."

# Grundkonfiguration
export SYMBI_LOG_LEVEL=info
export SYMBI_RUNTIME_MODE=development

# Vektorsuche funktioniert sofort mit dem integrierten LanceDB-Backend.
# Um stattdessen Qdrant zu verwenden (optional, aktiviert das `vector-qdrant`-Feature):
# export SYMBIONT_VECTOR_BACKEND=qdrant
# export QDRANT_URL=http://localhost:6333

# MCP-Integration (optional)
export MCP_SERVER_URLS="http://localhost:8080"

Sicherheitsrelevante Umgebungsvariablen (nach dem v1.13.0-Audit)¶

Folgende Umgebungsvariablen wurden entfernt:

• SYMBIONT_ALLOW_NO_JWT_AUDIENCE -- der JWT-Verifizierer verlangt jetzt immer aud. (Im Audit nach v1.13.0 entfernt; war ein unsicherer Notausgang.)
• COMPOSIO_API_KEY, COMPOSIO_MCP_URL -- die Composio-MCP-Integration wurde vollstaendig entfernt. Siehe SECURITY_AUDIT.md C3.

Laufzeitkonfiguration¶

Erstellen Sie eine symbi.toml-Konfigurationsdatei:

[runtime]
max_agents = 1000
memory_limit_mb = 512
execution_timeout_seconds = 300

[security]
default_sandbox_tier = "docker"
audit_enabled = true
policy_enforcement = "strict"

[vector_db]
enabled = true
backend = "lancedb"              # Standard; unterstuetzt auch "qdrant"
collection_name = "symbi_knowledge"
# url = "http://localhost:6333"  # nur erforderlich bei backend = "qdrant"

Human-in-the-Loop-Genehmigungen¶

Genehmigungspflichten aus Manifest und Subcommand bleiben verbindlich, auch wenn Cedar einen Aufruf erlaubt. Die gemeinsame Warteschlange haelt jede Anfrage bis zu einer autorisierten Entscheidung, zum Ablauf oder zum Abbruch. Ein blockierter Notifier kann keine andere Genehmigungsoberflaeche blockieren.

• Gewoehnliche/verwaltete CLI: Fuegen Sie --approval-terminal hinzu, optional mit --approval-timeout 120 (1–3600 Sekunden). Pruefen Sie das vollstaendige escapte JSON und geben Sie approve <request-id> exakt auf dem steuernden Terminal ein. Ohne das Flag schlagen genehmigungspflichtige Aufrufe fail-closed fehl.
• REST: Authentifiziertes GET /api/v1/approvals, POST /api/v1/approvals/{id}/approve und .../deny loesen ausstehende Anfragen auf.
• Shell: Ctrl+G oeffnet das Gate-Panel auch waehrend eines laufenden Turns. Waehlen Sie mit ↑/↓, druecken Sie Enter, um die vollstaendige Anfrage zu pruefen, scrollen Sie, und druecken Sie dann a oder d. /gate oeffnet das Panel ebenfalls. Eine Listenzeile allein kann nicht genehmigen.
• Chat: Ein auf der Allowlist stehender Absender verwendet /symbi gate show <id> und kopiert dann /symbi gate approve <id> <review-digest> aus der vollstaendigen Pruefung, oder sendet /symbi gate deny <id>. Genehmigungen nur per ID werden abgelehnt. Uebergrosse Nachrichten benoetigen eine weitere angebundene Pruefoberflaeche.

Geaenderte, abgelaufene oder entfernte Anfragen erfordern eine neue Pruefung. Die TUI meldet Aufloesungsfehler und unbekannte Ergebnisse explizit. Eine Genehmigung ist die Erlaubnis, das Gate zu passieren; pruefen Sie die tatsaechliche Ausfuehrung im signierten Durchlauf-Audit. Slack erfordert in jeder Umgebung ein nicht leeres Signing Secret und gueltige Callback-Signaturen. Die frueher moegliche Umgehung unsignierter Callbacks wird nicht mehr unterstuetzt. Siehe Genehmigungslebenszyklus fuer Grenzen und Vertrauensannahmen.

Konfigurieren Sie das Timeout und die Chat-Genehmigungskanaele in symbiont.toml:

[escalation]
timeout_seconds = 120

[[escalation.approval_channels]]
platform   = "slack"
channel_id = "C0APPROVERS"
approvers  = ["U0ALICE", "U0BOB"]   # allowlisted sender ids; empty = nobody may approve via chat

Haeufige Probleme¶

Docker-Probleme¶

Problem: Docker-Build schlaegt mit Berechtigungsfehlern fehl

# Loesung: Sicherstellen, dass Docker-Daemon laeuft und Benutzer Berechtigungen hat
sudo systemctl start docker
sudo usermod -aG docker $USER

Problem: Container beendet sich sofort

# Loesung: Docker-Logs ueberpruefen
docker logs <container_id>

Rust-Build-Probleme¶

Problem: Cargo-Build schlaegt mit Abhaengigkeitsfehlern fehl

# Loesung: Rust aktualisieren und Build-Cache loeschen
rustup update
cargo clean
cargo build

Problem: Fehlende Systemabhaengigkeiten

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev

# macOS
brew install pkg-config openssl

Laufzeit-Probleme¶

Problem: Agent startet nicht

# Agenten-Definitionssyntax ueberpruefen
cargo run -- dsl parse your_agent.symbi

# Debug-Protokollierung aktivieren
RUST_LOG=debug cd crates/runtime && cargo run --example basic_agent

Hilfe erhalten¶

Dokumentation¶

• DSL-Leitfaden - Vollstaendige DSL-Referenz
• Laufzeit-Architektur - Details zur Systemarchitektur
• Sicherheitsmodell - Sicherheits- und Richtliniendokumentation

Community-Support¶

• Issues: GitHub Issues
• Diskussionen: GitHub Discussions
• Dokumentation: Vollstaendige API-Referenz

Debug-Modus¶

Fuer die Fehlerbehebung detaillierte Protokollierung aktivieren:

# Debug-Protokollierung aktivieren
export RUST_LOG=symbi=debug

# Mit detaillierter Ausgabe ausfuehren
cd crates/runtime && cargo run --example basic_agent 2>&1 | tee debug.log

Was kommt als naechstes?¶

Jetzt, da Sie Symbi zum Laufen gebracht haben, erkunden Sie diese fortgeschrittenen Themen:

1. DSL-Leitfaden - Erweiterte DSL-Funktionen lernen
2. Reasoning-Loop-Leitfaden - Den ORGA-Zyklus verstehen
3. Erweitertes Reasoning (orga-adaptive) - Tool-Kuratierung, Stuck-Loop-Erkennung, Pre-Hydration
4. Laufzeit-Architektur - Systeminternas verstehen
5. Sicherheitsmodell - Sicherheitsrichtlinien implementieren
6. Beitragen - Zum Projekt beitragen

Bereit, etwas Grossartiges zu bauen? Beginnen Sie mit unseren Beispielprojekten oder tauchen Sie in die vollstaendige Spezifikation ein.