Começando¶
Symbiont 2.0: Antes de atualizar, leia o guia de migração e a verificação da versão. O cache de prompts e as melhorias governadas continuam opcionais e exigem ativação explícita; agentes existentes não aderem automaticamente.
Vai executar agentes sob contenção? Comece pelo guia de operação de contenção para os pré-requisitos de execução, as mudanças de aprovação e a cobertura atual.
Este guia irá orientá-lo na configuração do Symbi e na criação do seu primeiro agente de IA.
▶ Assista ao tutorial de introdução:
Índice¶
Pré-requisitos¶
O que você precisa depende de como instala e executa o Symbi.
Para executar o binário pré-compilado¶
Os binários pré-compilados já estão compilados — você não precisa de Rust, protobuf ou Git para instalá-los ou executá-los. Instale com o Homebrew, o script de instalação (curl) ou um download manual a partir do GitHub Releases.
- Docker só é necessário em tempo de execução se você executar agentes sob o sandbox tier padrão (
tier1, baseado em Docker). Não é necessário para instalar o Symbi ou para executarsymbi init,symbi dslousymbi --version.
Para compilar a partir do código-fonte¶
Necessário apenas se você instalar via cargo install ou compilar o repositório você mesmo:
- Rust 1.89+
- protobuf-compiler (
apt install protobuf-compilerno Ubuntu,brew install protobufno macOS) - Git (para clonar o repositório)
Opcional¶
- symbi-claude-code (plugin de governança do Claude Code)
- symbi-gemini-cli (extensão de governança do Gemini CLI)
Nota: A busca vetorial é integrada. O Symbi inclui o LanceDB como banco de dados vetorial embutido -- nenhum serviço externo é necessário.
Instalação¶
Opção 1: Binários pré-compilados¶
macOS (Homebrew):
Linux / macOS (instalador do repositório):
curl -fsSL https://raw.githubusercontent.com/ThirdKeyAI/Symbiont/main/scripts/install.sh | bash
export PATH="$HOME/.symbi/bin:$PATH"
symbi --version
O script exige Bash, curl ou wget, tar e sha256sum ou shasum. Entradas ausentes ou ambíguas e falhas de checksum interrompem a instalação.
O instalador do repositório verifica a soma SHA-256 do manifesto HTTPS antes da extração, usando sha256sum ou shasum. Ele instala a versão mais recente em ~/.symbi/bin e não faz a verificação independente de identidade Sigstore. Defina SYMBI_INSTALL_DIR para o processo bash se precisar de outra raiz de instalação. Use um download manual para fixar a versão.
Os downloads manuais oferecem Linux x86_64/ARM64, macOS ARM64 e Windows x86_64. No Windows, use o arquivo ZIP. Siga a verificação da versão antes de adicionar o binário ao PATH.
Landlock é selecionado por projeto Linux com symbi init --sandbox landlock. Exige Landlock ABI 6+, seccomp, namespaces de usuário, montagem e rede sem privilégios, delegação de cgroup v2 e um gerenciador systemd de usuário. Consulte a configuração no Linux (em inglês).
Opção 2: Docker (Recomendado)¶
A maneira mais rápida de obter um runtime funcional é deixar o container fazer o scaffolding do projeto para você:
# 1. Gera symbiont.toml, agents/, policies/, docker-compose.yml e
# um .env com SYMBIONT_MASTER_KEY recém-gerada.
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
init --profile assistant --no-interact --dir /workspace
# 2. Inicia o runtime. Lê o .env automaticamente.
docker compose up
A API do runtime ficará em http://localhost:8080 e a HTTP Input em http://localhost:8081.
Se você prefere trabalhar a partir de um clone (para construir a imagem ou rodar testes):
git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont
# Construir o container unificado symbi
docker build -t symbi:latest .
# Executar o ambiente de desenvolvimento
docker run --rm -it -v $(pwd):/workspace symbi:latest bash
Opção 3: Instalação Local¶
Para desenvolvimento local:
# Clonar o repositório
git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont
# Instalar dependências do Rust e compilar
cargo build --release
# Executar testes para verificar a instalação
cargo test
Verificar Instalação¶
Testar se tudo está funcionando corretamente:
# Testar o analisador DSL
cd crates/dsl && cargo run && cargo test
# Testar o sistema de runtime
cd ../runtime && cargo test
# Executar agentes de exemplo
cargo run --example basic_agent
cargo run --example full_system
# Testar o CLI unificado symbi
cd ../.. && cargo run -- dsl --help
cargo run -- mcp --help
# Testar com container Docker
docker run --rm symbi:latest --version
docker run --rm -v $(pwd):/workspace symbi:latest dsl parse --help
docker run --rm symbi:latest mcp --help
Experimente sem chave de API¶
Duas coisas funcionam offline, antes de configurar qualquer provedor de modelo. Ambas demonstram o que o Symbiont realmente faz — comece por aqui.
Defina uma ferramenta e faça um dry-run. Tipos de argumento, limites de escopo e verificações de injeção são aplicados antes de qualquer execução:
greet OK
✓ target (string): example → OK
Command: greet example
Cedar: Tool::Greet / execute_tool
[dry run — command not executed]
Executar um agente exige um provedor de modelo — uma chave na nuvem ou um modelo local, ambos cobertos abaixo.
Inicialização de Projeto¶
A maneira mais rápida de iniciar um novo projeto Symbiont é symbi init:
Isso inicia um assistente interativo que o guia por:
- Seleção de perfil: minimal, assistant, dev-agent ou multi-agent
- Modo SchemaPin: tofu (Trust-On-First-Use), strict ou disabled
- Camada de sandbox: landlock (nativo do Linux), tier0 (nenhuma, somente desenvolvimento), tier1 (Docker), tier2 (gVisor / runsc) ou tier3 (microVM Firecracker)
Com --sandbox landlock --profile dev-agent, o assistente também pergunta pelo
repositório de código-fonte, pelo executável instalado do Claude Code, pela URL de
inferência compatível com a API Messages, pelo modelo e pelo nome da variável de
ambiente com a credencial. Ele gera uma configuração de revisão somente leitura em
um diretório de controle separado e vazio. Chamadas não interativas devem fornecer
--source, --managed-executable, --inference-url, --inference-model e
--inference-key-env. Veja onboarding de desenvolvimento no Linux.
O que init produz¶
Toda execução escreve:
| Arquivo | Propósito |
|---|---|
symbiont.toml |
Configuração de runtime e políticas |
policies/default.cedar |
Política Cedar deny-by-default |
agents/*.symbi |
Definições de agentes específicas do perfil (a extensão legada .dsl também é reconhecida; exceto minimal) |
AGENTS.md |
Índice gerado automaticamente dos agentes declarados |
.symbiont/audit/ |
Diretório do log de auditoria à prova de adulteração |
.gitignore |
Acrescido com entradas específicas do Symbiont, incluindo .env |
.env |
SYMBIONT_MASTER_KEY gerada a partir de /dev/urandom (permissões 0600) |
.env.example |
Template seguro para commit mostrando as variáveis de ambiente necessárias |
docker-compose.yml |
Arquivo compose com montagens de volume e fiação de env; omitido no caso do Landlock |
Passe --no-docker-compose para pular o arquivo compose, e --dir <PATH> para escrever em um diretório diferente do atual (essencial dentro de um container Docker — veja abaixo).
Modo não interativo¶
Para CI/CD ou configurações por script:
Executando init dentro do Docker¶
Como o WORKDIR da imagem é /var/lib/symbi, use --dir para escrever no volume montado:
docker run --rm -v $(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest \
init --profile assistant --no-interact --dir /workspace
Isso popula o diretório atual do host com a árvore completa do projeto.
Perfis¶
| Perfil | O que cria |
|---|---|
minimal |
symbiont.toml + política Cedar padrão |
assistant |
+ agente assistente governado individual |
dev-agent |
+ agente de CLI gerenciada; com o Landlock, acrescenta ferramentas configuradas de leitura/listagem/busca, políticas com escopo e DEVELOPMENT.md |
multi-agent |
+ agentes coordenador/worker com políticas inter-agente |
Importando do catálogo¶
Importe agentes pré-construídos junto com os perfis gerais (o inicializador de desenvolvimento somente leitura do Landlock não combina com importações do catálogo):
Listar agentes disponíveis no catálogo:
Após a inicialização, valide e inicie:
symbi dsl -f agents/assistant.symbi # validar seu agente
symbi run assistant -i '{"query": "hello"}' # testar um único agente
symbi up # iniciar o runtime localmente
docker compose up # ...ou iniciar no Docker (lê o .env)
Executando um único agente¶
Use symbi run para executar um agente sem iniciar o servidor de runtime completo:
O comando resolve nomes de agentes pesquisando: caminho direto, depois o diretório agents/. Ele configura a inferência em nuvem a partir de variáveis de ambiente (OPENROUTER_API_KEY, OPENAI_API_KEY ou ANTHROPIC_API_KEY), executa o loop de raciocínio ORGA e encerra.
symbi run assistant -i 'Summarize this document'
symbi run agents/recon.symbi -i '{"target": "10.0.1.5"}' --max-iterations 5
Comandos de ferramentas, parsers e a execução de MCP e PTY exigem o backend de
contêiner selecionado, uma imagem em cache com os executáveis declarados e
montagens de dados explícitas. Backends indisponíveis não podem recorrer à
execução no host. As configurações do agente selecionado e os padrões do projeto
são verificados antes da inferência. As execuções também exigem o armazenamento
protegido .symbiont/governed/ e imprimem a sua referência pública de auditoria.
Veja configuração de comandos e
auditoria de execução.
Usando um modelo local¶
O provedor não precisa ser um serviço na nuvem. Aponte OPENAI_BASE_URL para qualquer servidor compatível com OpenAI — Ollama, vLLM, LM Studio e llama.cpp expõem um — e nenhuma chave de nuvem é usada:
export OPENAI_API_KEY=ollama
export OPENAI_BASE_URL=http://localhost:11434/v1
export CHAT_MODEL=llama3.1
symbi run assistant -i 'hello'
As mesmas três variáveis valem para symbi up. O Symbiont avisa quando uma URL base usa http:// em texto puro, pois a chave viaja junto com a requisição. Isso é esperado para um modelo na sua própria máquina.
Partindo de um template (symbi new)¶
symbi init gera um projeto genérico; symbi new gera um projeto em torno de um dos vários templates orientados por tarefa. Útil quando você sabe que tipo de agente precisa antes de saber exatamente quais agentes precisa.
symbi new --list # mostra os templates disponíveis
symbi new <template> <project-name> # cria um novo projeto a partir de um template
Templates incluídos:
| Template | O que você obtém |
|---|---|
webhook-min |
Agente mínimo acionado por webhook — configuração de HTTP Input + uma DSL de handler |
webscraper-agent |
Agente de scraping com políticas de acesso Cedar e uma ferramenta de scraping ToolClad |
slm-first |
Padrão de roteador + allow-list SLM + fallback por confiança |
rag-lite |
Scripts de ingestão baseados em Qdrant mais um agente de busca |
symbi new e symbi init são complementares: new fornece um ponto de partida específico para a tarefa, init (+ --catalog) fornece um ponto de partida específico para governança. Você também pode combiná-los — gere o scaffold com new e, em seguida, symbi init --catalog ... para incorporar agentes pré-construídos adicionais do catálogo.
Seu Primeiro Agente¶
Vamos criar um agente simples de análise de dados para entender os conceitos básicos do Symbi.
1. Criar Definição do Agente¶
Crie um novo arquivo 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. Executar o Agente¶
# Analisar e validar a definição do agente
cargo run -- dsl parse my_agent.symbi
# Executar o agente no runtime
cd crates/runtime && cargo run --example basic_agent -- --agent ../../my_agent.symbi
Entendendo o DSL¶
O DSL do Symbi tem vários componentes principais:
Bloco de Metadados¶
Fornece informações essenciais sobre o seu agente para documentação e gerenciamento do runtime.
Definição do Agente¶
agent agent_name(parameter: Type) -> ReturnType {
capabilities = ["capability1", "capability2"]
// implementação do agente
}
Define a interface, capacidades e comportamento do agente.
Definições de Política¶
policy policy_name {
allow: action_list if condition
deny: action_list if condition
audit: operation_type with audit_method
}
Políticas de segurança declarativas que são aplicadas em tempo de execução.
Contexto de Execução¶
Especifica a configuração de runtime para gerenciamento de memória e requisitos de privacidade.
Próximos Passos¶
Explorar Exemplos¶
O repositório inclui vários agentes de exemplo:
# Exemplo de agente básico
cd crates/runtime && cargo run --example basic_agent
# Demonstração completa do sistema
cd crates/runtime && cargo run --example full_system
# Exemplo de contexto e memória
cd crates/runtime && cargo run --example context_example
# Agente potenciado por RAG
cd crates/runtime && cargo run --example rag_example
Habilitar Recursos Avançados¶
API HTTP (Opcional)¶
# Habilitar o recurso de API HTTP
cd crates/runtime && cargo build --features http-api
# Executar com endpoints de API
cd crates/runtime && cargo run --features http-api --example full_system
Principais Endpoints da API:
- GET /api/v1/health - Verificação de saúde e status do sistema
- GET /api/v1/agents - Listar todos os agentes ativos com status de execução em tempo real
- GET /api/v1/agents/{id}/status - Obter métricas detalhadas de execução do agente
- POST /api/v1/workflows/execute - Executar fluxos de trabalho
Novos Recursos de Gerenciamento de Agentes: - Monitoramento de processos em tempo real e verificações de saúde - Capacidades de desligamento gracioso para agentes em execução - Métricas de execução abrangentes e rastreamento de uso de recursos - Suporte para diferentes modos de execução (efêmero, persistente, agendado, orientado a eventos)
Inferência LLM em Nuvem¶
Conecte a provedores de LLM em nuvem via OpenRouter:
# Habilitar inferência em nuvem
cargo build --features cloud-llm
# Definir chave de API e modelo
export OPENROUTER_API_KEY="sk-or-..."
export OPENROUTER_MODEL="google/gemini-2.0-flash-001" # opcional
Modo Agente Autônomo¶
Linha única para agentes cloud-native com inferência LLM:
Note: Composio MCP and SymbiBot integration were removed in this version due to security concerns — see SECURITY_AUDIT.md C3 for context.
Primitivas de Raciocínio Avançado¶
Habilite curadoria de ferramentas, detecção de loops travados, pré-busca de contexto e convenções com escopo:
Veja o guia orga-adaptive para documentação completa.
Motor de Políticas Cedar¶
Autorização formal com a linguagem de políticas Cedar. Habilitado por padrão desde v1.14.x: os binários symbi publicados (crates.io, Docker, tarballs do GitHub Release) incluem o Cedar, e symbi up / symbi run auto-conectam o CedarPolicyGate a partir de arquivos policies/*.cedar no startup; se nenhum estiver presente, o runtime recorre ao DefaultPolicyGate fail-closed. Para compilar sem o Cedar (por exemplo, quando você pretende conectar o OpaPolicyGateBridge ou um ReasoningPolicyGate personalizado), use:
Banco de Dados Vetorial (Integrado)¶
O Symbi inclui o LanceDB como banco de dados vetorial embutido sem configuração. A busca semântica e o RAG funcionam imediatamente -- nenhum serviço separado para iniciar:
# Executar agente com capacidades RAG (a busca vetorial funciona automaticamente)
cd crates/runtime && cargo run --example rag_example
# Testar gerenciamento de contexto com busca avançada
cd crates/runtime && cargo run --example context_example
Build mínimo: O LanceDB é incluído por padrão, mas pode ser excluído para binários mais leves:
cargo build --no-default-features. O runtime recorre de forma transparente a um backend vetorial no-op.Implantações em escala: O Qdrant está disponível como backend opcional. Compile com
--features vector-qdrante definaSYMBIONT_VECTOR_BACKEND=qdrant.
Recursos de Gerenciamento de Contexto: - Busca Multi-Modal: Modos de busca por palavra-chave, temporal, similaridade e híbrido - Cálculo de Importância: Algoritmo de pontuação sofisticado considerando padrões de acesso, recência e feedback do usuário - Controle de Acesso: Integração com motor de políticas e controles de acesso com escopo de agente - Arquivamento Automático: Políticas de retenção com armazenamento comprimido e limpeza - Compartilhamento de Conhecimento: Compartilhamento seguro de conhecimento entre agentes com pontuações de confiança
Referência de Feature Flags¶
| Feature | Descrição | Padrão |
|---|---|---|
keychain |
Integração com chaveiro do SO para segredos | Sim |
vector-lancedb |
Backend vetorial embutido LanceDB | Sim |
vector-qdrant |
Backend vetorial distribuído Qdrant | Não |
embedding-models |
Modelos de embedding locais via Candle | Não |
http-api |
API REST com Swagger UI | Não |
http-input |
Servidor de webhook com autenticação JWT | Não |
cloud-llm |
Inferência LLM em nuvem (OpenRouter) | Não |
standalone-agent |
Meta-feature Cloud LLM | Não |
cedar |
Motor de políticas Cedar — auto-conecta a partir de policies/*.cedar no startup |
Sim |
orga-adaptive |
Primitivas de raciocínio avançado | Não |
cron |
Agendamento cron persistente | Não |
cli-executor |
Subprocessos de CLI de IA governados (Claude Code etc.) — Modo B | Sim |
native-sandbox |
Sandboxing nativo de processos | Não |
metrics |
Métricas/rastreamento OpenTelemetry | Não |
mcp-client |
Execução de ferramentas ToolClad baseada em MCP via stdio (verificado via SchemaPin) | No |
toolclad-browser |
Backend ToolClad de navegador (CDP) — apenas esqueleto de implementação; retorna um erro explícito até que o backend CDP esteja disponível | No |
interactive |
Prompts interativos para symbi init (dialoguer) |
Sim |
full |
Todos os recursos opcionais de runtime, vetor e política | Não |
# Compilar com features específicas
cargo build --features "cloud-llm,orga-adaptive,cedar"
# Compilar com tudo
cargo build --features full
Plugins de Assistente de IA¶
O Symbiont fornece plugins de governança de primeira mão para assistentes de codificação de IA populares, com três camadas progressivas de proteção:
- Awareness (padrão) — registro consultivo de todas as chamadas de ferramenta que modificam estado
- Protection — um hook de bloqueio aplica uma deny list local (
.symbiont/local-policy.toml) - Governance — avaliação de políticas Cedar quando o
symbiestá no PATH
A configuração da deny list é agnóstica em relação à ferramenta — o mesmo .symbiont/local-policy.toml funciona com ambos os plugins:
[deny]
paths = [".env", ".ssh/", ".aws/"]
commands = ["rm -rf", "git push --force"]
branches = ["main", "master", "production"]
Claude Code¶
# Instalar a partir do marketplace
/plugin marketplace add https://github.com/thirdkeyai/symbi-claude-code
# Skills disponíveis: /symbi-init, /symbi-policy, /symbi-verify, /symbi-audit, /symbi-dsl
Veja symbi-claude-code para detalhes.
Modo B: subprocesso Claude Code governado¶
Um agente com metadata { executor = "claude_code" } executa seu filho de CLI no
contêiner Docker/gVisor selecionado, com armazenamento temporário e canais
privados de inferência e de ferramentas do runtime. O code_reviewer incluído é o
agente de referência. Configure primeiro uma imagem de CLI/Python em cache,
montagens explícitas do código-fonte no backend, ferramentas ToolClad registradas
e políticas Cedar, além de [managed_cli.inference]. Veja
contenção da CLI gerenciada para um exemplo completo.
# /srv/source deve corresponder a uma montagem explícita de backend no projeto de controle.
symbi run code_reviewer --target /srv/source --max-turns 12 --budget-timeout 15m
# Adicione a revisão pelo operador para ferramentas que exigem aprovação.
symbi run code_reviewer --target /srv/source --approval-terminal
O filho não recebe montagem direta do código-fonte, acesso à rede externa, estado
de login do host nem credencial do provedor. As ferramentas registradas
intermediam o acesso permitido a arquivos e ao Git. As ferramentas embutidas e a
descoberta automática ficam desativadas. Toda ação exige autorização do runtime;
uma aprovação de spawn não autoriza as ações seguintes. Plugins não são
carregados e --plugin-dir é rejeitado.
| Flag / configuração | Propósito |
|---|---|
--target |
Diretório de código-fonte mapeado para uma montagem explícita no backend |
--max-turns |
Limite de conversa; padrão 12 |
--budget-timeout |
Limite de wall-clock incluindo a inicialização; padrão 15m |
--budget-tokens |
Cota reservada de tokens de saída da inferência; padrão 100000, não o total de tokens faturados |
--approval-terminal |
Revisão opt-in no terminal de controle para aprovações obrigatórias |
[managed_cli.inference] |
Endpoint explícito do provedor, modelo e variável de credencial; a credencial permanece no runtime |
Os journals de sessão assinados obrigatórios ficam no armazenamento privado
.symbiont/governed/. O runtime imprime a chave pública de verificação. Aprovação
ausente, armazenamento de auditoria inseguro, um backend indisponível ou uma
limpeza malsucedida não podem reportar sucesso silenciosamente. As respostas de
inferência são bufferizadas, inclusive SSE, de modo que a saída transmitida é
atrasada.
Gemini CLI¶
A extensão do Gemini CLI fornece defesa em profundidade adicional via bloqueio de manifesto excludeTools e aplicação nativa de policies/*.toml no nível da plataforma.
Veja symbi-gemini-cli para detalhes.
Configuração¶
Variáveis de Ambiente¶
Configure seu ambiente para performance ideal:
# Obrigatório: chave hex de 32 bytes usada para criptografar o estado persistente.
# Gere com: openssl rand -hex 32
# `symbi init` escreve uma no .env automaticamente.
export SYMBIONT_MASTER_KEY="..."
# Configuração básica
export SYMBI_LOG_LEVEL=info
export SYMBI_RUNTIME_MODE=development
# A busca vetorial funciona automaticamente com o backend LanceDB integrado.
# Para usar o Qdrant em vez disso (opcional, habilite a feature `vector-qdrant`):
# export SYMBIONT_VECTOR_BACKEND=qdrant
# export QDRANT_URL=http://localhost:6333
# Integração MCP (opcional)
export MCP_SERVER_URLS="http://localhost:8080"
Variáveis de Ambiente Relacionadas à Segurança (após auditoria v1.13.0)¶
| Variável | Padrão | Efeito |
|---|---|---|
SYMBI_INSECURE_ALLOW_ALL |
não definida | Quando definida como 1, symbi up / symbi run usam o policy gate permissivo (toda chamada de ferramenta e delegação é permitida). Equivalente à flag --insecure-allow-all. Um banner ruidoso é impresso em stderr. Apenas para desenvolvimento local. Sem isso, o loop de raciocínio é fail-closed e rejeita chamadas de ferramentas e delegações até que um backend de política explícito seja conectado. |
SYMBI_REJECT_LEGACY_API_KEYS |
não definida | Quando definida como 1, o validador de chaves de API curto-circuita o escaneamento O(n) Argon2 depreciado para chaves sem prefixo. Use isso imediatamente após reemitir cada chave no formato keyid.secret. O caminho legado será removido na próxima release minor de qualquer forma. |
SYMBI_UNSAFE_NATIVE_SANDBOX |
não definida | Necessária (além de SYMBI_ENV=production-não-definida) para construir o runner de sandbox native. A feature Cargo native-sandbox também falha em compilar em builds de release. O runner nativo não oferece isolamento e destina-se apenas a depuração local. |
SYMBI_TRUSTED_PROXIES |
não definida | Allowlist CIDR para proxies reversos confiáveis; X-Forwarded-For é honrado apenas a partir desses endereços. |
As seguintes variáveis de ambiente foram removidas:
SYMBIONT_ALLOW_NO_JWT_AUDIENCE— o verificador JWT agora sempre exigeaud. (Removida na auditoria pós-v1.13.0; era um escape hatch inseguro.)COMPOSIO_API_KEY,COMPOSIO_MCP_URL— a integração Composio MCP foi removida por completo. VejaSECURITY_AUDIT.mdC3.
Configuração de Runtime¶
Crie um arquivo de configuração symbi.toml:
[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" # padrão; também suporta "qdrant"
collection_name = "symbi_knowledge"
# url = "http://localhost:6333" # necessário apenas quando backend = "qdrant"
Aprovações com humano no circuito¶
Os requisitos de aprovação de manifesto/subcomando permanecem obrigatórios mesmo quando o Cedar permite a chamada. A fila compartilhada retém cada requisição até uma decisão autorizada, a expiração ou o cancelamento. Um notificador travado não pode bloquear outra superfície de aprovação.
- CLI comum/gerenciada: acrescente
--approval-terminal, opcionalmente com--approval-timeout 120(1–3600 segundos). Revise o JSON escapado completo e digite exatamenteapprove <request-id>no terminal de controle. Sem a flag, as chamadas que exigem aprovação falham de forma fechada. - REST:
GET /api/v1/approvals,POST /api/v1/approvals/{id}/approvee.../denyautenticados resolvem as requisições pendentes. - Shell: Ctrl+G abre o painel Gate mesmo durante um turno ocupado. Selecione
com ↑/↓, pressione Enter para revisar a requisição completa, role e então
pressione
aoud./gatetambém abre o painel. Uma linha da lista, sozinha, não aprova. - Chat: um remetente na allowlist usa
/symbi gate show <id>e então copia/symbi gate approve <id> <review-digest>da revisão completa, ou envia/symbi gate deny <id>. Aprovações apenas com o ID são rejeitadas. Mensagens grandes demais exigem outra superfície de revisão conectada.
Requisições alteradas, expiradas ou removidas exigem uma nova revisão. A TUI reporta explicitamente erros de resolução e desfechos desconhecidos. A aprovação é a permissão para seguir através do gate; verifique a execução real na auditoria assinada da execução. O Slack exige um signing secret não vazio e assinaturas de callback válidas em todos os ambientes. A antiga sobrescrita de callbacks não assinados não é mais suportada. Veja ciclo de vida de aprovação para os limites e as premissas de confiança.
Configure o timeout e os canais de aprovação por chat em symbiont.toml:
[escalation]
timeout_seconds = 120
[[escalation.approval_channels]]
platform = "slack"
channel_id = "C0APPROVERS"
approvers = ["U0ALICE", "U0BOB"] # ids de remetentes na allowlist; vazio = ninguém pode aprovar via chat
Problemas Comuns¶
Problemas com Docker¶
Problema: Construção do Docker falha com erros de permissão
# Solução: Garantir que o daemon do Docker está rodando e o usuário tem permissões
sudo systemctl start docker
sudo usermod -aG docker $USER
Problema: Container sai imediatamente
Problemas de Construção com Rust¶
Problema: Construção do Cargo falha com erros de dependência
Problema: Dependências do sistema em falta
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install build-essential pkg-config libssl-dev
# macOS
brew install pkg-config openssl
Problemas de Runtime¶
Problema: Agente falha ao iniciar
# Verificar sintaxe da definição do agente
cargo run -- dsl parse your_agent.symbi
# Habilitar logging de debug
RUST_LOG=debug cd crates/runtime && cargo run --example basic_agent
Obtendo Ajuda¶
Documentação¶
- Guia DSL - Referência completa do DSL
- Arquitetura de Runtime - Detalhes da arquitetura do sistema
- Modelo de Segurança - Documentação de segurança e políticas
Suporte da Comunidade¶
- Issues: GitHub Issues
- Discussões: GitHub Discussions
- Documentação: Referência Completa da API
Modo de Debug¶
Para solução de problemas, habilite logging detalhado:
# Habilitar logging de debug
export RUST_LOG=symbi=debug
# Executar com saída detalhada
cd crates/runtime && cargo run --example basic_agent 2>&1 | tee debug.log
O Que Vem a Seguir?¶
Agora que você tem o Symbi rodando, explore estes tópicos avançados:
- Guia DSL - Aprenda recursos avançados do DSL
- Guia do Loop de Raciocínio - Entenda o ciclo ORGA
- Raciocínio Avançado (orga-adaptive) - Curadoria de ferramentas, detecção de loops travados, pré-hidratação
- Arquitetura de Runtime - Entenda os internos do sistema
- Modelo de Segurança - Implemente políticas de segurança
- Contribuindo - Contribua para o projeto
Pronto para construir algo incrível? Comece com nossos projetos de exemplo ou mergulhe na especificação completa.
