Symbiont REPL-Leitfaden¶

Ausfuehrungsstatus dieses Branches: Asynchrone Builtins behalten die Identitaet des aufrufenden Callers. Die Bridge friert ihr Projekt-Root ein, und standardmaessige reason()/tool_call()-Aufrufe erfordern geschuetzte Lauf-Journale und liefern oeffentliche Audit-Referenzen zurueck. Direkte Inferenzaufrufe erfordern ebenfalls Journale; :audit listet deren oeffentliche Referenzen auf. Funktions- und Behavior-Deklarationen bleiben ueber Eingaben hinweg bestehen, und laufende Behaviors behalten einen Snapshot ihrer Hilfsfunktionen. Die aeltere REPL-Syntax implementiert keine kanonische Sandbox-Auswahl pro Agent. Explizite nicht unterstuetzte Anforderungen an Tier, Sandbox, Ressourcen und Ausfuehrungsrichtlinien fuehren jetzt zum Fehlschlagen der Registrierung. Siehe DSL-Aufrufkontext und den Branch-Leitfaden fuer die aktuelle Abdeckung.

Andere Sprachen¶

Die Symbiont-REPL (Read-Eval-Print Loop) bietet eine interaktive Umgebung zum Entwickeln, Testen und Debuggen von Symbiont-Agenten und DSL-Code.

Suchen Sie eine interaktive TUI? symbi shell (Beta) umhuellt dieselbe repl_core-Engine, die dieser Leitfaden behandelt, plus einen LLM-Orchestrator, einen vollstaendigen Befehlskatalog (/spawn, /run, /chain, …) und Remote-Attach. Verwenden Sie die REPL, wenn Sie eine skriptbare JSON-RPC-Oberflaeche fuer die IDE-Integration moechten; verwenden Sie die Shell, wenn Sie konversationelle Autorenerstellung gegen dasselbe Runtime moechten.

Funktionen¶

• Interaktive DSL-Auswertung: Symbiont-DSL-Code in Echtzeit ausfuehren
• Agenten-Lebenszyklus-Verwaltung: Agenten erstellen, starten, stoppen, pausieren, fortsetzen und zerstoeren
• Ausfuehrungsueberwachung: Echtzeitueberwachung der Agentenausfuehrung mit Statistiken und Traces
• Policy-Durchsetzung: Integrierte Policy-Pruefung und Capability-Gating
• Sitzungsverwaltung: REPL-Sitzungen als Snapshot sichern und wiederherstellen
• JSON-RPC-Protokoll: Programmatischer Zugriff ueber JSON-RPC via stdio
• LSP-Unterstuetzung: Language Server Protocol fuer IDE-Integration

Erste Schritte¶

REPL starten¶

# Interaktiver REPL-Modus
symbi repl

# JSON-RPC-Servermodus ueber stdio (fuer IDE-Integration)
symbi repl --stdio

Hinweis: Das --config-Flag wird noch nicht unterstuetzt. Die Konfiguration wird vom Standard-symbiont.toml-Speicherort gelesen. Unterstuetzung fuer benutzerdefinierte Konfiguration ist fuer ein zukuenftiges Release geplant.

Grundlegende Verwendung¶

Geben Sie jede Deklaration in einer Zeile ein:

agent Greeter {}
function greet(value: string) { return upper(value) }
behavior Welcome { steps { return greet(args) } }
:agents
:agent start <id>
:agent execute <id> Welcome hello

Ersetzen Sie <id> durch die fuer Greeter ausgegebene UUID. Der letzte Befehl liefert HELLO. Deklaration und Start fuehren das Behavior nicht aus. Optionale Befehlsargumente treffen als eine einzelne Zeichenkette namens args ein. Definitionen bleiben bestehen; lokale Variablen und Argumente werden nicht in den naechsten Aufruf uebernommen. Eine fehlgeschlagene Modulregistrierung ersetzt keine frueheren Definitionen. Laufzeitfehler bleiben sichtbar, und der Client kann den naechsten Befehl entgegennehmen. print()-Diagnosen gehen unabhaengig von der strukturierten Antwort nach stderr.

Die kanonische Sprache agent name(...) { with ... }, die symbi run verwendet, ist ein separater Parsing-Pfad. Die aelteren REPL-Sicherheitsstufen und Sandbox-Modi sind nicht deren Ausfuehrungseinstellungen. Die Registrierung verweigert explizite aeltere Tier-/Sandbox-Modi, befuellte Ressourcen und Ausfuehrungsrichtlinien, bevor irgendwelche Definitionen veroeffentlicht werden. Doppelte Constraint-Bloecke und Capability-Listen fuehren ebenfalls zu einem Parsing-Fehler. Reine Capability-Deklarationen behalten ihre bisherigen Pruefungen. Tool-Effekte verwenden die Projektgrenze und den kontrollierten Dispatcher; ohne ein konfiguriertes erlaubendes Gate werden Tool-Anfragen abgelehnt. Direkte LLM-Aufrufe sowie Kompositions- und Pattern-Aufrufe erfordern fuer jeden Provider-Aufruf ein signiertes Journal. Ihre bisherigen Ergebnistypen bleiben unveraendert; verwenden Sie :audit fuer oeffentliche Referenzen. Die Kommunikation erfordert ein konfiguriertes Gate und einen registrierten Empfaenger. send_to bestaetigt den dauerhaften Start, waehrend das abschliessende Journal die spaetere Fertigstellung festhaelt. race liefert den ersten Erfolg und bricht ausstehende Aufrufe ab. Diese Kontrollen etablieren weder eine kanonische Quellenauswahl noch aggregierte Inferenzbudgets.

Um die RPC- und Terminal-Smoke-Tests nach einem Workspace-Build zu reproduzieren:

python3 scripts/test-repl-session.py --binary target/debug/repl-cli --report /tmp/repl-session.json

REPL-Befehle¶

Agentenverwaltung¶

Ueberwachungsbefehle¶

Speicherbefehle¶

Webhook-Befehle¶

Aufzeichnungsbefehle¶

Sitzungsbefehle¶

DSL-Funktionen¶

Agenten-Definitionen¶

metadata {
  version = "2.1.0"
  description = "Analyzes datasets with privacy protection"
}

agent data_analyzer(data: DataSet, options: AnalysisOptions) -> AnalysisResults {
  capabilities = ["data_read", "analysis"]

  policy privacy {
    allow: read(data) if true
    deny: write(any)
  }

  with memory = "ephemeral", sandbox = "tier1" {
    return analyze(data, options);
  }
}

Das Agentenverhalten lebt im with-Block des Agenten (und in function-Definitionen) -- es gibt kein separates behavior-Konstrukt. Richtlinienregeln (allow / deny / require / audit) steuern, was der Agent tun darf. Siehe den DSL-Leitfaden und die DSL-Spezifikation fuer die vollstaendige Grammatik.

Eingebaute Funktionen¶

Geplante eingebaute Funktionen: Erweiterte E/A-Funktionen wie read_file(), read_csv(), write_results(), analyze() und transform_data() sind noch nicht implementiert. Diese sind fuer ein zukuenftiges Release geplant.

Datentypen¶

# Grundtypen
let name = "Alice"          # String
let age = 30               # Integer
let height = 5.8           # Number
let active = true          # Boolean
let empty = null           # Null

# Sammlungen
let items = [1, 2, 3]      # Liste
let config = {             # Map
  "host": "localhost",
  "port": 8080
}

# Zeit- und Groesseneinheiten
let timeout = 30s          # Dauer
let max_size = 100MB       # Groesse

Architektur¶

Komponenten¶

symbi repl
├── repl-cli/          # CLI-Schnittstelle und JSON-RPC-Server
├── repl-core/         # Kern-REPL-Engine und Evaluator
├── repl-proto/        # JSON-RPC-Protokolldefinitionen
└── repl-lsp/          # Language Server Protocol Implementierung

Kernkomponenten¶

• DslEvaluator: Fuehrt DSL-Programme mit Laufzeitintegration aus
• ReplEngine: Koordiniert Auswertung und Befehlsverarbeitung
• ExecutionMonitor: Verfolgt Ausfuehrungsstatistiken und Traces
• RuntimeBridge: Integriert sich mit der Symbiont-Laufzeit fuer Policy-Durchsetzung
• SessionManager: Verwaltet Snapshots und Sitzungszustand

JSON-RPC-Protokoll¶

Die REPL unterstuetzt JSON-RPC 2.0 fuer programmatischen Zugriff:

// DSL-Code auswerten
{
  "jsonrpc": "2.0",
  "method": "evaluate",
  "params": {"input": "let x = 42"},
  "id": 1
}

// Antwort
{
  "jsonrpc": "2.0",
  "result": {"value": "42", "type": "integer"},
  "id": 1
}

Sicherheit & Policy-Durchsetzung¶

Capability-Pruefung¶

Die REPL erzwingt Capability-Anforderungen, die in Agenten-Sicherheitsbloecken definiert sind:

agent SecureAgent {
  name: "Secure Agent"
  security {
    capabilities: ["filesystem", "network"]
  }
}

behavior ReadFile {
  input { path: string }
  output { content: string }
  steps {
    # Dies prueft, ob der Agent die Capability "filesystem" hat
    require capability("filesystem")
    # HINWEIS: read_file() ist eine geplante eingebaute Funktion (noch nicht implementiert).
    # Dieses Beispiel veranschaulicht, wie Capability-Pruefung funktioniert.
    let content = read_file(path)
    return content
  }
}

Policy-Integration¶

Die REPL integriert sich mit der Symbiont-Policy-Engine, um Zugriffskontrollen und Audit-Anforderungen durchzusetzen.

Debugging & Ueberwachung¶

Ausfuehrungs-Traces¶

:monitor traces 10

Recent Execution Traces:
  14:32:15.123 - AgentCreated [Agent: abc-123] (2ms)
  14:32:15.125 - AgentStarted [Agent: abc-123] (1ms)
  14:32:15.130 - BehaviorExecuted [Agent: abc-123] (5ms)
  14:32:15.135 - AgentPaused [Agent: abc-123]

Statistiken¶

:monitor stats

Execution Monitor Statistics:
  Total Executions: 42
  Successful: 38
  Failed: 4
  Success Rate: 90.5%
  Average Duration: 12.3ms
  Total Duration: 516ms
  Active Executions: 2

Agenten-Debugging¶

:agent debug abc-123

Agent Debug Information:
  ID: abc-123-def-456
  Name: Data Analyzer
  Version: 2.1.0
  State: Running
  Created: 2024-01-15 14:30:00 UTC
  Description: Analyzes datasets with privacy protection
  Author: data-team@company.com
  Available Functions/Behaviors: 5
  Required Capabilities: 2
    - data_read
    - analysis
  Resource Configuration:
    Memory: 512MB
    CPU: 2
    Storage: 1GB

IDE-Integration¶

Language Server Protocol¶

Die REPL bietet LSP-Unterstuetzung fuer IDE-Integration ueber das repl-lsp Crate. Der LSP-Server wird separat von der REPL selbst gestartet:

# Der LSP-Server wird vom repl-lsp Crate bereitgestellt und durch
# die LSP-Client-Konfiguration Ihres Editors gestartet (nicht ueber symbi repl Flags).

Hinweis: Das --lsp-Flag wird bei symbi repl nicht unterstuetzt. LSP ist im repl-lsp Crate implementiert und sollte ueber die LSP-Einstellungen Ihres Editors konfiguriert werden.

Unterstuetzte Funktionen¶

• Syntaxhervorhebung
• Fehlerdiagnose
• Textsynchronisation

Geplante Funktionen (noch nicht implementiert): - Code-Vervollstaendigung - Hover-Informationen - Gehe zu Definition - Symbolsuche

Bewaehrte Praktiken¶

Entwicklungsworkflow¶

1. Mit einfachen Ausdruecken beginnen: Grundlegende DSL-Konstrukte testen
2. Agenten schrittweise definieren: Mit minimalen Agentendefinitionen starten
3. Verhalten einzeln testen: Verhalten vor der Integration definieren und testen
4. Ueberwachung nutzen: Ausfuehrungsueberwachung zum Debuggen einsetzen
5. Snapshots erstellen: Wichtige Sitzungszustaende sichern

Performance-Tipps¶

• :monitor clear regelmaessig verwenden, um Ueberwachungsdaten zurueckzusetzen
• Trace-Verlauf mit :monitor traces <limit> begrenzen
• Ungenutzte Agenten zerstoeren, um Ressourcen freizugeben
• Snapshots fuer komplexe Sitzungszustaende verwenden

Sicherheitsueberlegungen¶

• Immer geeignete Capabilities fuer Agenten definieren
• Policy-Durchsetzung in der Entwicklung testen
• Sandbox-Modus fuer nicht vertrauenswuerdigen Code verwenden
• Ausfuehrungs-Traces auf Sicherheitsereignisse ueberwachen

Fehlerbehebung¶

Haeufige Probleme¶

Agentenerstellung schlaegt fehl

Error: Missing capability: filesystem

Ausfuehrungs-Timeout

Error: Maximum execution depth exceeded

Policy-Verletzung

Error: Policy violation: data access denied

Debug-Befehle¶

# Agentenstatus pruefen
:agent debug <agent-id>

# Ausfuehrungs-Traces anzeigen
:monitor traces 50

# Systemstatistiken pruefen
:monitor stats

# Debug-Snapshot erstellen
:snapshot

Beispiele¶

Einfacher Agent¶

agent Calculator {
  name: "Basic Calculator"
  version: "1.0.0"
}

behavior Add {
  input { a: number, b: number }
  output { result: number }
  steps {
    return a + b
  }
}

# Das Verhalten testen
let result = Add(5, 3)
print("5 + 3 =", result)

Datenverarbeitungs-Agent¶

agent DataProcessor {
  name: "Data Processing Agent"
  version: "1.0.0"

  security {
    capabilities: ["data_read", "data_write"]
  }

}

behavior ProcessCsv {
  input { file_path: string }
  output { summary: ProcessingSummary }

  steps {
    require capability("data_read")

    # HINWEIS: read_csv(), transform_data() und write_results() sind geplante
    # eingebaute Funktionen (noch nicht implementiert). Dieses Beispiel veranschaulicht
    # das beabsichtigte Muster fuer Datenverarbeitungsverhalten.
    let data = read_csv(file_path)
    let processed = transform_data(data)

    require capability("data_write")
    write_results(processed)

    return {
      "rows_processed": len(data),
      "status": "completed"
    }
  }
}

Siehe auch¶

• DSL-Leitfaden - Vollstaendige DSL-Sprachreferenz
• Laufzeit-Architektur - Systemarchitektur-Uebersicht
• Sicherheitsmodell - Sicherheitsimplementierungsdetails
• API-Referenz - Vollstaendige API-Dokumentation