Começando

🌐 Outros idiomas

English

中文简体

Español

Português

日本語

Deutsch

---

Este guia irá orientá-lo na configuração do Symbi e na criação do seu primeiro agente de IA.

Índice

1. Pré-requisitos
   1. Dependências Obrigatórias
   2. Dependências Opcionais
2. Instalação
   1. Opção 1: Docker (Recomendado)
   2. Opção 2: Instalação Local
   3. Verificar Instalação
3. Seu Primeiro Agente
   1. 1. Criar Definição do Agente
   2. 2. Executar o Agente
4. Entendendo o DSL
   1. Bloco de Metadados
   2. Definição do Agente
   3. Definições de Política
   4. Contexto de Execução
5. Próximos Passos
   1. Explorar Exemplos
   2. Habilitar Recursos Avançados
      1. API HTTP (Opcional)
      2. Integração de Banco de Dados Vetorial
6. Configuração
   1. Variáveis de Ambiente
   2. Configuração de Runtime
7. Problemas Comuns
   1. Problemas com Docker
   2. Problemas de Construção com Rust
   3. Problemas de Runtime
8. Obtendo Ajuda
   1. Documentação
   2. Suporte da Comunidade
   3. Modo de Debug
9. O Que Vem a Seguir?

---

Pré-requisitos

Antes de começar com o Symbi, certifique-se de ter o seguinte instalado:

Dependências Obrigatórias

• Docker (para desenvolvimento containerizado)
• Rust 1.88+ (se compilando localmente)
• Git (para clonar o repositório)

Dependências Opcionais

• Qdrant banco de dados vetorial (para capacidades de busca semântica)
• SchemaPin Go CLI (para verificação de ferramentas)

---

Instalação

Opção 1: Docker (Recomendado)

A maneira mais rápida de começar é usando Docker:

# Clonar o repositório
git clone https://github.com/thirdkeyai/symbiont.git
cd symbiont

# Construir o container unificado symbi
docker build -t symbi:latest .

# Ou usar container pré-construído
docker pull ghcr.io/thirdkeyai/symbi:latest

# Executar o ambiente de desenvolvimento
docker run --rm -it -v $(pwd):/workspace symbi:latest bash

Opção 2: 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

---

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

Criar um novo arquivo my_agent.dsl:

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

# Executar o agente no runtime
cd crates/runtime && cargo run --example basic_agent -- --agent ../../my_agent.dsl

---

Entendendo o DSL

O DSL do Symbi tem vários componentes principais:

Bloco de Metadados

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

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

with memory = "persistent", privacy = "high" {
    // implementação do agente
}

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
• POST /api/v1/workflows/execute - Executar fluxos de trabalho

Integração de Banco de Dados Vetorial

Para capacidades de busca semântica:

# Iniciar banco de dados vetorial Qdrant
docker run -p 6333:6333 qdrant/qdrant

# Executar agente com capacidades RAG
cd crates/runtime && cargo run --example rag_example

---

Configuração

Variáveis de Ambiente

Configure seu ambiente para performance ideal:

# Configuração básica
export SYMBI_LOG_LEVEL=info
export SYMBI_RUNTIME_MODE=development

# Banco de dados vetorial (opcional)
export QDRANT_URL=http://localhost:6333

# Integração MCP (opcional)
export MCP_SERVER_URLS="http://localhost:8080"

Configuração de Runtime

Criar 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
url = "http://localhost:6333"
collection_name = "symbi_knowledge"

---

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

# Solução: Verificar logs do Docker
docker logs <container_id>

Problemas de Construção com Rust

Problema: Construção do Cargo falha com erros de dependência

# Solução: Atualizar Rust e limpar cache de construção
rustup update
cargo clean
cargo build

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

# 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, habilitar 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:

1. Guia DSL - Aprenda recursos avançados do DSL
2. Arquitetura de Runtime - Entenda os internos do sistema
3. Modelo de Segurança - Implemente políticas de segurança
4. Contribuindo - Contribua para o projeto

Pronto para construir algo incrível? Comece com nossos projetos de exemplo ou mergulhe na especificação completa.