Suna AI: o Agente de IA Geral de Código Aberto

O campo da inteligência artificial está cada vez mais se movendo em direção a agentes que podem fazer mais do que apenas processar informações – eles podem agir. A Suna AI surge neste espaço como um agente de IA generalista de código aberto e atraente, projetado para funcionar como um companheiro digital capaz de entender instruções em linguagem natural e executar tarefas complexas do mundo real diretamente em seu nome. Desenvolvida pela Kortix AI e lançada sob a licença permissiva Apache 2.0, a Suna se diferencia ao combinar um poderoso conjunto de ferramentas com uma interface de conversação, visando fechar a lacuna entre a intenção do usuário e a ação digital tangível.

Diferente das ferramentas de IA especializadas, a força da Suna está em sua versatilidade. Ela foi construída para orquestrar várias capacidades – desde navegar na web e gerenciar arquivos até executar código e interagir com APIs – tudo impulsionado por seus comandos de conversa. Este artigo fornece uma visão geral das principais capacidades e arquitetura da Suna, seguida de um tutorial detalhado, passo a passo, sobre como configurar e executar sua própria instância localmente, permitindo que você aproveite este poderoso agente de IA em seu próprio ambiente.

O que é a Suna AI e como a Suna AI funciona?

Para entender o que a Suna pode fazer, é essencial compreender as ferramentas que ela possui. Essas capacidades permitem que ela interaja com o mundo digital muito semelhante a um usuário humano, mas de forma automatizada e movida por IA.

1. Automação de Navegador (via Playwright): A Suna pode iniciar e controlar uma instância de navegador da web dentro de seu ambiente seguro. Isso significa que ela pode navegar para URLs específicos, fazer login em sites (se as credenciais forem fornecidas de forma segura), clicar em botões, preencher formulários, rolar páginas e, crucialmente, extrair dados diretamente do conteúdo da página da web. Essa capacidade desbloqueia a vasta quantidade de informações e funcionalidades disponíveis na web para automação.
2. Gerenciamento de Arquivos: O agente não se limita apenas a dados da web. Ele possui a habilidade de interagir com um sistema de arquivos dentro de seu ambiente isolado. Isso inclui criar novos arquivos (como relatórios ou exportações de dados), ler documentos existentes, editar seu conteúdo e organizar arquivos em diretórios. Isso é vital para tarefas que envolvem gerar saídas ou processar dados locais.
3. Rastreamento de Web & Pesquisa Avançada: Além da navegação em uma única página, a Suna pode rastejar sistematicamente sites (seguindo links) para coletar informações abrangentes. Ela também pode se integrar a APIs de pesquisa dedicadas (como a integração opcional do Tavily) para realizar uma recuperação de informações mais sofisticada e direcionada do que o uso padrão de motores de busca, permitindo capacidades de pesquisa mais profundas.
4. Execução de Linha de Comando: Dentro de seu contêiner Docker seguro, a Suna tem a capacidade de executar comandos de shell. Esse recurso poderoso permite que ela execute scripts, utilize outras utilidades de linha de comando, interaja com recursos do sistema (dentro dos limites do contêiner) e potencialmente automatize tarefas como compilações ou implantações de software se configurada adequadamente. A segurança é primordial aqui, gerenciada pelo ambiente isolado.
5. Integração de API (via RapidAPI & Chamadas Diretas): A Suna pode fazer chamadas para Interfaces de Programação de Aplicativos (APIs) externas. Isso permite que ela se conecte a um vasto ecossistema de serviços de terceiros. A documentação destaca a integração opcional com o RapidAPI, permitindo acesso a vários provedores de dados (por exemplo, para dados do LinkedIn, informações financeiras, etc.), mas também pode ser configurada para interagir diretamente com outras APIs RESTful, ampliando enormemente seu potencial de coleta de dados e de tomada de ações.
6. Interpretação de Código: A Suna inclui a capacidade de executar trechos de código (principalmente Python) dentro de seu ambiente seguro. Isso não é apenas para executar scripts existentes, mas permite que o agente gere dinamicamente e execute código para realizar cálculos complexos, análises de dados, processamento de lógica personalizada ou transformações que vão além das capacidades de suas outras ferramentas.

O verdadeiro poder da Suna reside na capacidade da IA de selecionar e sequenciar essas ferramentas de forma apropriada com base na solicitação do usuário. Uma única instrução pode acionar um fluxo de trabalho que envolve pesquisar na web, extrair dados, processá-los com código interpretado, formatar o resultado em um arquivo e salvá-lo – tudo gerenciado pelo agente.

Arquitetura da Suna: Os Componentes Envolvidos

Entender o processo de configuração requer uma compreensão básica dos principais componentes arquitetônicos da Suna:

1. API de Backend (Python/FastAPI): A lógica central reside aqui. Ela gerencia as solicitações dos usuários, mantém o estado da conversa, orquestra o uso das ferramentas do agente e lida com a comunicação com o Modelo de Linguagem Grande (LLM) escolhido via LiteLLM (fornecendo flexibilidade com provedores como OpenAI e Anthropic).
2. Frontend (Next.js/React): Esta é a aplicação web voltada para o usuário. Ela fornece a interface de chat para interagir com a Suna, exibe resultados e inclui elementos de dashboard para monitorar a atividade do agente.
3. Ambiente Docker do Agente (via Daytona): Segurança e isolamento são críticos. Cada tarefa do agente é executada dentro de um contêiner Docker dedicado gerenciado pela Daytona. Este sandbox contém todas as ferramentas necessárias (navegador, interpretador de código, acesso ao sistema de arquivos) e evita que o agente interfira no sistema host.
4. Banco de Dados Supabase (PostgreSQL): Gerencia todas as necessidades de persistência de dados, incluindo contas de usuários e autenticação, histórico de conversas, armazenamento para arquivos gerados pelo agente, rastreamento do estado do agente e potencialmente análises.

Esses componentes trabalham juntos, comunicando-se via APIs, para entregar a experiência Suna. A configuração de auto-hospedagem envolve configurar e executar essas partes interconectadas.

Como Configurar a Suna AI

Executar a Suna por conta própria oferece controle e privacidade máximos. Os seguintes passos guiá-lo-ão pelo processo de configuração:

Fase 1: Coletando Pré-requisitos

Antes de instalar a Suna, você precisa de vários serviços externos e credenciais:

Projeto Supabase:

• Inscreva-se ou faça login em supabase.com e crie um novo projeto.
• Navegue até Configurações > API do seu projeto. Copie cuidadosamente sua URL do Projeto, chave pública anon e chave secreta service_role.
• Instale a CLI do Supabase: Siga as instruções em supabase.com/docs/guides/cli.

Banco de Dados Redis:

• Opção 1 (Nuvem - Recomendado): Use um serviço como Upstash (oferece um nível gratuito). Crie um banco de dados e registre seu Host/Endpoint, Porta, Senha e anote se SSL/TLS é necessário (geralmente sim).
• Opção 2 (Local): Instale o Redis localmente (por exemplo, brew install redis no macOS, sudo apt install redis-server no Debian/Ubuntu, ou via Docker/WSL no Windows). Anote o Host (localhost), Porta (geralmente 6379), Senha (geralmente nenhuma) e a configuração de SSL (False).

Conta Daytona & Configuração de Imagem:

• Inscreva-se em daytona.io.
• Vá para Configurações > Chaves de API e gere uma nova Chave de API. Copie-a.
• Vá para a seção Imagens. Clique em Adicionar Imagem.
• Nome da Imagem: adamcohenhillel/kortix-suna:0.0.20
• Ponto de Entrada: /usr/bin/supervisord -n -c /etc/supervisor/conf.d/supervisord.conf
• Salve essa configuração de imagem.

Chave da API LLM:

• Escolha entre OpenAI (platform.openai.com) ou Anthropic (console.anthropic.com). Obtenha uma Chave de API do seu provedor escolhido.
• Observe o Identificador do Modelo específico que você planeja usar (por exemplo, gpt-4o, anthropic/claude-3-5-sonnet-latest).

(Opcional) Chave da API Tavily: Para melhores resultados de pesquisa. Obtenha uma chave de Tavily AI.

(Opcional) Chave RapidAPI: Se você pretende usar integrações pré-construídas que necessitem dela (como raspadores da web específicos).

• Obtenha uma chave em rapidapi.com.
• Lembre-se de se inscrever nas APIs específicas (por exemplo, raspador do LinkedIn) no marketplace RapidAPI que as ferramentas da Suna podem usar. Verifique o diretório backend/agent/tools/data_providers/ para o código relevante da ferramenta e suas URLs base de API exigidas.

Fase 2: Instalação e Configuração

Agora, configure os componentes da aplicação Suna:

Clone o Repositório:

git clone https://github.com/kortix-ai/suna.git
cd suna

Configure o Backend (.env):

• cd backend
• cp .env.example .env (ou crie .env se o exemplo estiver faltando).
• Edite .env com as credenciais da Fase 1:

NEXT_PUBLIC_URL="http://localhost:3000" # Ou sua URL de frontend se diferente

# Supabase
SUPABASE_URL=YOUR_SUPABASE_URL
SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY=YOUR_SUPABASE_SERVICE_ROLE_KEY

# Redis
REDIS_HOST=YOUR_REDIS_HOST
REDIS_PORT=YOUR_REDIS_PORT
REDIS_PASSWORD=YOUR_REDIS_PASSWORD # Deixe em branco se não houver
REDIS_SSL=True # Ou False para o Redis local não SSL

# Daytona
DAYTONA_API_KEY=YOUR_DAYTONA_API_KEY
DAYTONA_SERVER_URL="https://app.daytona.io/api"
DAYTONA_TARGET="us" # Ou sua região

# --- Configuração do LLM (PREENCHA APENAS UM CONJUNTO) ---
# Exemplo Anthropic:
ANTHROPIC_API_KEY=YOUR_ANTHROPIC_API_KEY
MODEL_TO_USE="anthropic/claude-3-5-sonnet-latest" # Ou outro modelo Claude
OPENAI_API_KEY=
# Exemplo OpenAI:
# ANTHROPIC_API_KEY=
# OPENAI_API_KEY=YOUR_OPENAI_API_KEY
# MODEL_TO_USE="gpt-4o" # Ou outro modelo OpenAI
# -----------------------------------------

# Opcional
TAVILY_API_KEY=YOUR_TAVILY_API_KEY # Opcional
RAPID_API_KEY=YOUR_RAPID_API_KEY # Opcional

• Crítico: Forneça apenas chaves para um provedor de LLM (ou Anthropic ou OpenAI).

Configure o Esquema do Banco de Dados Supabase:

• Certifique-se de que você está no diretório backend.
• Faça login: supabase login
• Vincule o projeto: supabase link --project-ref YOUR_PROJECT_REF_ID (Obtenha o ID no painel do Supabase).
• Aplicar migrações: supabase db push
• Verifique o Esquema: Vá para o painel do projeto Supabase -> Configurações do Projeto -> API -> seção Esquema sob "Configuração". Certifique-se de que basejump esteja listado em "Esquemas Expostos". Adicione-o se estiver faltando e salve.

Configure o Frontend (.env.local):

• cd ../frontend
• cp .env.example .env.local (ou crie .env.local).
• Edite .env.local:

NEXT_PUBLIC_SUPABASE_URL=YOUR_SUPABASE_URL # O mesmo que no backend .env
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR_SUPABASE_ANON_KEY # O mesmo que no backend .env
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000/api" # Localização padrão do backend
NEXT_PUBLIC_URL="http://localhost:3000" # Localização padrão do frontend

Instale as Dependências:

• Frontend (Node.js/npm):

# No diretório frontend
npm install

• Backend (Python 3.11):

# No diretório backend (use um ambiente virtual!)
# python -m venv venv
# source venv/bin/activate  OU .\venv\Scripts\activate (Windows)
pip install -r requirements.txt

Fase 3: Executando a Suna

Inicie o Serviço de Backend:

• Abra um terminal.
• Navegue até caminho/para/suna/backend.
• Se estiver usando um ambiente virtual, ative-o (source venv/bin/activate).
• Execute: python api.py
• Busque a confirmação de que o servidor está em execução (provavelmente na porta 8000).

Inicie o Serviço de Frontend:

• Abra um segundo terminal.
• Navegue até caminho/para/suna/frontend.
• Execute: npm run dev
• Busque a confirmação de que o servidor está em execução (provavelmente na porta 3000).

Acesse sua Instância Suna:

• Abra um navegador e vá para http://localhost:3000.
• Use a opção de Cadastro para criar sua conta de usuário (impulsionada pela Supabase Auth).
• Faça login e comece a instruir seu agente Suna auto-hospedado.

Conclusão

A Suna AI representa um passo prático em direção a agentes de IA autônomos capazes de executar tarefas no reino digital. Sua natureza de código aberto, combinada com um poderoso conjunto de ferramentas e uma arquitetura modular, torna-a uma opção atraente para desenvolvedores e usuários que buscam um assistente de IA personalizável e auto-hospedável. Ao seguir o detalhado processo de configuração descrito acima, você pode implantar sua própria instância da Suna, concedendo-lhe uma interface de conversa para automatizar navegação, manipulação de arquivos, coleta de dados, execução de código e muito mais, tudo dentro de um ambiente que você controla. Embora configurar exija atenção cuidadosa a seus múltiplos componentes, o resultado é um agente de IA versátil pronto para agir em seu nome.