Guia do REPL do Symbiont¶

Status de execução desta branch: Os builtins assíncronos preservam a identidade de quem fez a chamada. A ponte congela a raiz do seu projeto, e as chamadas padrão de reason()/tool_call() exigem journals de execução protegidos e retornam referências públicas de auditoria. Chamadas diretas de inferência também exigem journals; :audit lista as referências públicas delas. Declarações de funções e de comportamentos persistem entre entradas, e comportamentos em execução mantêm um snapshot de seus auxiliares. A sintaxe legada do REPL não implementa a seleção canônica de sandbox por agente. Requisitos explícitos não suportados de tier, sandbox, recursos e políticas de execução agora falham no registro. Veja contexto de invocação do DSL e o guia da branch para a cobertura atual.

Outros idiomas¶

Procurando uma TUI interativa? symbi shell (Beta) envolve o mesmo motor repl_core que este guia cobre, mais um orquestrador LLM, um catálogo completo de comandos (/spawn, /run, /chain, …) e attach remoto. Use o REPL quando quiser uma superfície JSON-RPC scriptável para integração com IDEs; use o shell quando quiser autoria conversacional contra o mesmo runtime.

Funcionalidades¶

• Avaliação Interativa de DSL: Execute código DSL do Symbiont em tempo real
• Gerenciamento de Ciclo de Vida de Agentes: Criar, iniciar, parar, pausar, retomar e destruir agentes
• Monitoramento de Execução: Monitoramento em tempo real da execução de agentes com estatísticas e traces
• Imposição de Políticas: Verificação de políticas e controle de capacidades integrados
• Gerenciamento de Sessão: Snapshot e restauração de sessões do REPL
• Protocolo JSON-RPC: Acesso programático via JSON-RPC sobre stdio
• Suporte LSP: Language Server Protocol para integração com IDEs

Primeiros Passos¶

Iniciando o REPL¶

# Modo REPL interativo
symbi repl

# Modo servidor JSON-RPC sobre stdio (para integração com IDE)
symbi repl --stdio

Nota: A flag --config ainda não é suportada. A configuração é lida do local padrão symbiont.toml. Suporte a configuração personalizada está planejado para uma versão futura.

Uso Básico¶

Digite cada declaração em uma única linha:

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

Substitua <id> pelo UUID impresso para Greeter. O último comando retorna HELLO. Declarar e iniciar não executam o comportamento. Argumentos opcionais de comando chegam como uma única string chamada args. As definições persistem; variáveis locais e argumentos não são levados para a próxima invocação. Um registro de módulo malsucedido não substitui definições anteriores. Erros de runtime permanecem visíveis e o cliente pode aceitar o próximo comando. Os diagnósticos de print() vão para o stderr, independentemente da resposta estruturada.

A linguagem canônica agent name(...) { with ... } usada por symbi run é um caminho de parsing separado. Os tiers de segurança e modos de sandbox legados do REPL não são as configurações de execução dela. O registro recusa modos legados explícitos de tier/sandbox, recursos preenchidos e políticas de execução, antes de publicar qualquer definição. Blocos de restrição e listas de capacidades duplicados também falham no parsing. Declarações apenas de capacidades mantêm suas verificações existentes. Os efeitos de ferramentas usam o limite do projeto e o despachante governado; sem um gate permissivo configurado, as requisições de ferramentas são negadas. Chamadas diretas de LLM, de composição e de padrões exigem um journal assinado para cada chamada ao provedor. Os tipos de resultado existentes permanecem inalterados; use :audit para as referências públicas. A comunicação exige um gate configurado e um destinatário registrado. O send_to confirma a inicialização durável, enquanto o journal terminal dele registra a conclusão posterior. O race retorna o primeiro sucesso e cancela as chamadas pendentes. Esses controles não estabelecem seleção canônica de fonte nem orçamentos agregados de inferência.

Para reproduzir os smoke tests de RPC e de terminal após um build do workspace:

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

Comandos do REPL¶

Gerenciamento de Agentes¶

Comandos de Monitoramento¶

Comandos de Memória¶

Comandos de Webhook¶

Comandos de Gravação¶

Comandos de Sessão¶

Funcionalidades da DSL¶

Definições de Agentes¶

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);
  }
}

O comportamento do agente reside no bloco with do agente (e em definições de function) — não há uma construção behavior separada. As regras de política (allow / deny / require / audit) controlam o que o agente pode fazer. Veja o Guia DSL e a Especificação DSL para a gramática completa.

Funções Integradas¶

Funções integradas planejadas: Funções avançadas de E/S como read_file(), read_csv(), write_results(), analyze() e transform_data() ainda não foram implementadas. Estão planejadas para uma versão futura.

Tipos de Dados¶

# Tipos básicos
let name = "Alice"          # String
let age = 30               # Integer
let height = 5.8           # Number
let active = true          # Boolean
let empty = null           # Null

# Coleções
let items = [1, 2, 3]      # List
let config = {             # Map
  "host": "localhost",
  "port": 8080
}

# Unidades de tempo e tamanho
let timeout = 30s          # Duration
let max_size = 100MB       # Size

Arquitetura¶

Componentes¶

symbi repl
├── repl-cli/          # Interface CLI e servidor JSON-RPC
├── repl-core/         # Motor principal do REPL e avaliador
├── repl-proto/        # Definições do protocolo JSON-RPC
└── repl-lsp/          # Implementação do Language Server Protocol

Componentes Principais¶

• DslEvaluator: Executa programas DSL com integração ao runtime
• ReplEngine: Coordena avaliação e tratamento de comandos
• ExecutionMonitor: Rastreia estatísticas e traces de execução
• RuntimeBridge: Integra com o runtime do Symbiont para imposição de políticas
• SessionManager: Gerencia snapshots e estado da sessão

Protocolo JSON-RPC¶

O REPL suporta JSON-RPC 2.0 para acesso programático:

// Avaliar código DSL
{
  "jsonrpc": "2.0",
  "method": "evaluate",
  "params": {"input": "let x = 42"},
  "id": 1
}

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

Segurança e Imposição de Políticas¶

Verificação de Capacidades¶

O REPL impõe requisitos de capacidade definidos nos blocos de segurança dos agentes:

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

behavior ReadFile {
  input { path: string }
  output { content: string }
  steps {
    # Isto verificará se o agente possui a capacidade "filesystem"
    require capability("filesystem")
    # NOTA: read_file() é uma função integrada planejada (ainda não implementada).
    # Este exemplo ilustra como a verificação de capacidades funciona.
    let content = read_file(path)
    return content
  }
}

Integração com Políticas¶

O REPL integra-se com o motor de políticas do Symbiont para impor controles de acesso e requisitos de auditoria.

Depuração e Monitoramento¶

Traces de Execução¶

: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]

Estatísticas¶

: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

Depuração de Agentes¶

: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

Integração com IDEs¶

Language Server Protocol¶

O REPL oferece suporte LSP para integração com IDEs através do crate repl-lsp. O servidor LSP é iniciado separadamente do REPL em si:

# O servidor LSP é fornecido pelo crate repl-lsp e iniciado
# pela configuração do cliente LSP do seu editor (não via flags do symbi repl).

Nota: A flag --lsp não é suportada no symbi repl. O LSP é implementado no crate repl-lsp e deve ser configurado através das configurações de LSP do seu editor.

Funcionalidades Suportadas¶

• Destaque de sintaxe
• Diagnósticos de erros
• Sincronização de texto

Funcionalidades planejadas (ainda não implementadas): - Autocompletar código - Informações ao passar o cursor - Ir para definição - Busca de símbolos

Boas Práticas¶

Fluxo de Desenvolvimento¶

1. Comece com Expressões Simples: Teste construções básicas da DSL
2. Defina Agentes Incrementalmente: Comece com definições mínimas de agentes
3. Teste Comportamentos Separadamente: Defina e teste comportamentos antes da integração
4. Use o Monitoramento: Aproveite o monitoramento de execução para depuração
5. Crie Snapshots: Salve estados importantes da sessão

Dicas de Desempenho¶

• Use :monitor clear periodicamente para limpar dados de monitoramento
• Limite o histórico de traces com :monitor traces <limit>
• Destrua agentes não utilizados para liberar recursos
• Use snapshots para estados complexos de sessão

Considerações de Segurança¶

• Sempre defina capacidades apropriadas para os agentes
• Teste a imposição de políticas durante o desenvolvimento
• Use o modo sandbox para código não confiável
• Monitore traces de execução para eventos de segurança

Solução de Problemas¶

Problemas Comuns¶

Falha na Criação do Agente

Error: Missing capability: filesystem

Timeout de Execução

Error: Maximum execution depth exceeded

Violação de Política

Error: Policy violation: data access denied

Comandos de Depuração¶

# Verificar estado do agente
:agent debug <agent-id>

# Ver traces de execução
:monitor traces 50

# Verificar estatísticas do sistema
:monitor stats

# Criar snapshot de depuração
:snapshot

Exemplos¶

Agente Simples¶

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

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

# Testar o comportamento
let result = Add(5, 3)
print("5 + 3 =", result)

Agente de Processamento de Dados¶

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")

    # NOTA: read_csv(), transform_data() e write_results() são funções
    # integradas planejadas (ainda não implementadas). Este exemplo ilustra
    # o padrão pretendido para comportamentos de processamento de dados.
    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"
    }
  }
}

Veja Também¶

• Guia DSL - Referência completa da linguagem DSL
• Arquitetura de Runtime - Visão geral da arquitetura do sistema
• Modelo de Segurança - Detalhes da implementação de segurança
• Referência da API - Documentação completa da API