OpenHands: A Alternativa de IA Devin de Código Aberto

O mundo do desenvolvimento de software está passando por uma mudança sísmica, impulsionada pelos rápidos avanços em inteligência artificial. Vimos as ferramentas de IA evoluírem de simples assistentes de conclusão de código para sistemas sofisticados capazes de entender requisitos complexos e gerar aplicações funcionais. Neste cenário empolgante, um novo jogador surgiu, capturando a imaginação de desenvolvedores em todo o mundo: OpenHands. Posicionado como uma alternativa poderosa e de código aberto a desenvolvedores de IA proprietários, como o Devin AI, o OpenHands oferece uma plataforma onde agentes de IA podem realizar tarefas anteriormente exclusivas de desenvolvedores humanos.

Desenvolvido pela All-Hands-AI, o OpenHands (anteriormente conhecido como OpenDevin) não é apenas mais um assistente de codificação. Ele é concebido como uma plataforma versátil para agentes de IA projetados para abordar todo o espectro de tarefas de desenvolvimento de software. Imagine uma IA que pode não apenas escrever código, mas também modificar bases de código existentes, executar comandos de terminal, navegar na web em busca de informações (sim, até mesmo vasculhando o Stack Overflow em busca de soluções), interagir com APIs e gerenciar fluxos de trabalho de desenvolvimento complexos. Esta é a promessa do OpenHands – "Codifique Menos, Faça Mais."

O que realmente distingue o OpenHands é seu compromisso com o código aberto. Construído sob a permissiva Licença MIT, ele convida à colaboração, transparência e inovação orientada pela comunidade. Isso contrasta fortemente com modelos de código fechado, oferecendo aos desenvolvedores controle, personalização e compreensão sem precedentes sobre o funcionamento interno de seu parceiro de desenvolvimento em IA. Para equipes e indivíduos cautelosos com o bloqueio de fornecedor ou que buscam personalizar as capacidades da IA para necessidades específicas, o OpenHands apresenta uma proposta atraente.

O que o OpenHands (antigamente Open Devin) faz?

Entender as funcionalidades principais do OpenHands é fundamental para apreciar seu potencial como uma plataforma de desenvolvimento de IA. Ele confere aos agentes de IA um conjunto abrangente de capacidades:

Modificação Inteligente de Código

Os agentes do OpenHands têm a capacidade de ler, compreender e alterar código dentro do contexto de um projeto existente. Aproveitando o Modelo de Linguagem Grande (LLM) escolhido, o agente analisa a base de código, entende as interdependências entre arquivos e funções, e implementa modificações direcionadas com base em solicitações do usuário. Isso inclui tarefas como refatorar funções para maior clareza, adicionar novos endpoints de API ou atualizar dependências do projeto conforme instruído.

Execução Segura de Comandos

Um dos pilares do OpenHands é sua capacidade de executar comandos de shell (como npm install, python manage.py runserver, git commit, ls, grep e outros) dentro de um ambiente de sandbox protegido e isolado. Esta sandbox, geralmente implementada como um contêiner Docker, isola as ações do agente, prevenindo qualquer impacto não intencional no sistema host. Isso permite que o agente execute operações essenciais de desenvolvimento, como configurar ambientes de projeto, executar suítes de testes, instalar bibliotecas necessárias, rodar scripts de build e gerenciar controle de versão.

Navegação Web Integrada

O desenvolvimento de software eficaz frequentemente exige a coleta de informações externas, como consultar documentação, encontrar soluções em plataformas como Stack Overflow ou pesquisar bibliotecas. Os agentes do OpenHands estão equipados para navegar na web autonomamente, recuperando as informações necessárias para cumprir suas tarefas designadas. Essa capacidade permite que eles se mantenham atualizados com as melhores práticas e desenvolvam soluções para problemas novos sem depender exclusivamente de informações pré-alimentadas.

Interação com API

A arquitetura moderna de software frequentemente envolve integrar múltiplos serviços via APIs. Os agentes do OpenHands podem ser direcionados a interagir com essas APIs externas. Isso pode envolver buscar dados de uma fonte de terceiros, enviar atualizações para outro sistema ou orquestrar workflows que atravessam diferentes ferramentas, automatizando assim processos de desenvolvimento mais complexos.

Gerenciamento de Sistema de Arquivos

Os agentes necessitam da capacidade de interagir com arquivos de projeto. O OpenHands concede a eles as permissões para criar, ler, escrever e deletar arquivos e diretórios dentro de seu espaço de trabalho designado (tipicamente um volume mapeado do sistema local para a sandbox do agente). Isso permite que eles estruturem projetos de forma lógica, adicionem novos módulos ou componentes, gerenciem arquivos de configuração e armazenem resultados de saída.

Essas diversas capacidades, orquestradas por um backend LLM escolhido pelo usuário, capacitam os agentes do OpenHands a lidarem autonomamente com tarefas complexas de desenvolvimento em múltiplas etapas, avançando significativamente além da geração básica de código rumo a um suporte genuíno de engenharia de software impulsionado por IA.

Como instalar o OpenHands no Mac, Linux, Windows

Usar o Docker é o método recomendado e mais robusto para executar o OpenHands localmente. Ele garante consistência ambiental e fornece o isolamento necessário para as operações do agente. Abaixo está um guia detalhado para instalar o OpenHands em diferentes sistemas operacionais.

Requisitos do Sistema

Certifique-se de que seu sistema atenda aos seguintes pré-requisitos:

• Sistema Operacional:
• macOS (com suporte ao Docker Desktop)
• Linux (Ubuntu 22.04 testado, outras distribuições modernas provavelmente compatíveis)
• Windows (com suporte ao WSL 2 e Docker Desktop)
• Hardware: Um sistema com um processador moderno e pelo menos 4GB de RAM é aconselhável. Tarefas que envolvem operações complexas ou execuções de LLMs locais maiores se beneficiarão significativamente de recursos aumentados de RAM e CPU/GPU.

Passos de Instalação dos Pré-requisitos

Siga estes passos cuidadosamente para configurar os pré-requisitos necessários.

Passo 1: Instalar Docker Desktop

Baixe e instale o Docker Desktop adaptado para seu sistema operacional diretamente do site oficial do Docker (https://www.docker.com/products/docker-desktop/). Siga o assistente de instalação fornecido pelo Docker. Após a instalação, confirme se o daemon do Docker está ativo; seu ícone deve ser visível na bandeja do sistema ou na barra de menu.

Passo 2: Configurar o Docker com Base no SO

Configurações específicas são necessárias dependendo do seu sistema operacional.

Configuração para macOS

1. Inicie o Docker Desktop.
2. Acesse Configurações (geralmente através do ícone de engrenagem).
3. Navegue até a seção Avançado.
4. Verifique se a opção Permitir que o socket Docker padrão seja usado está marcada (ativada). Essa permissão é essencial para que o contêiner do OpenHands gerencie outros contêineres Docker (como a sandbox).

Configuração para Linux

1. Instale o Docker Desktop para Linux seguindo a documentação oficial do Docker.
2. Certifique-se de que o serviço Docker está em execução após a instalação.
   (Observação: Embora testado no Ubuntu 22.04, a compatibilidade com outras distribuições Linux é esperada, mas não garantida.)

Configuração para Windows

1. Instalar WSL (Windows Subsystem for Linux): Se o WSL 2 ainda não estiver instalado, abra o PowerShell como Administrador e execute wsl --install. Este comando instala o WSL e uma distribuição Linux padrão (geralmente Ubuntu). Uma reinicialização do sistema pode ser necessária.
2. Verifique a Versão do WSL: Abra uma janela padrão do PowerShell ou do Prompt de Comando e digite wsl --version. Confirme se a saída indica a versão 2 ou superior do WSL. Se a versão 1 for mostrada, atualize o WSL ou configure a versão 2 como padrão usando wsl --set-default-version 2.
3. Instalar o Docker Desktop para Windows: Prossiga com a instalação do Docker Desktop se ainda não o fez.
4. Configurar a Integração do Docker Desktop com o WSL: Inicie o Docker Desktop, vá para Configurações. Sob Geral, certifique-se de que Usar o mecanismo baseado em WSL 2 esteja ativado. Sob Recursos > Integração com WSL, confirme que Ativar a integração com minha distribuição padrão do WSL esteja ativado. Aplique as alterações e reinicie o Docker, se solicitado.
5. Nota Crítica: Para usuários do Windows, todos os comandos subsequentes docker relacionados ao OpenHands devem ser executados dentro do ambiente do terminal WSL (por exemplo, terminal Ubuntu), não diretamente do PowerShell ou Prompt de Comando.

Iniciando a Aplicação OpenHands

Com os pré-requisitos atendidos, agora você pode iniciar a aplicação OpenHands.

Passo 1: Abra Seu Terminal

• Em macOS ou Linux, abra seu aplicativo Terminal padrão.
• Em Windows, inicie o terminal da distribuição WSL instalada (por exemplo, Ubuntu).

Passo 2: Puxar Imagem de Runtime (Opcional)

O OpenHands utiliza uma imagem Docker separada para o ambiente de execução sandbox do agente. Puxar essa imagem com antecedência pode, às vezes, acelerar a inicialização. Use a tag recomendada na documentação oficial:

docker pull docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik

(Verifique sempre a última tag recomendada no repositório do OpenHands no GitHub ou na documentação oficial, pois as tags podem mudar.)

Passo 3: Execute o Contêiner OpenHands

Execute o seguinte comando abrangente em seu terminal (use o terminal WSL no Windows):

docker run -it --rm --pull=always \
    -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands-state:/.openhands-state \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.all-hands.dev/all-hands-ai/openhands:0.34

Passo 4: Acesse a Interface do Usuário Web

Uma vez que o comando docker run é executado, monitore a saída do log em seu terminal. Quando a sequência de inicialização da aplicação for concluída, abra seu navegador da web preferido e navegue até http://localhost:3000.

Com esses passos concluídos, o OpenHands está instalado com sucesso e em execução localmente. O próximo passo imediato envolve configurar um Modelo de Linguagem Grande para impulsionar o agente.

Começando com Open Hands

Com o OpenHands operacional, a próxima etapa vital é conectá-lo a um LLM, que serve como o motor cognitivo do agente. Após a configuração do LLM, você pode começar a atribuir tarefas de desenvolvimento. Esta seção detalha a configuração inicial e fornece exemplos ilustrativos de interação.

Configuração Inicial do LLM

Este é um primeiro passo obrigatório ao iniciar a interface do usuário.

• Primeira Inicialização: Ao acessar http://localhost:3000 pela primeira vez, um modal de configurações aparecerá automaticamente.
• Campos Obrigatórios: É necessário selecionar um Fornecedor de LLM (por exemplo, OpenAI, Anthropic, Google, OpenRouter, opções locais como Ollama), escolher um Modelo de LLM específico oferecido por esse fornecedor e inserir sua respectiva Chave de API.
• Acessando Configurações Depois: Se o modal inicial for fechado ou se você precisar modificar a configuração posteriormente, clique no ícone de engrenagem (⚙️) presente na interface do usuário (geralmente localizado próximo à área de entrada de chat ou em uma barra lateral).

(Instruções detalhadas para configurar fornecedores específicos de LLM são fornecidas na seção subsequente.)

Sua Primeira Interação: Tarefa "Hello World"

Inicie a interação com uma tarefa fundamental para observar o processo do agente.

Passo 1: Solicitar ao Agente

Digite a seguinte instrução no campo de entrada de chat e pressione Enter:

Escreva um script bash hello.sh que imprime "hello world!"

Passo 2: Observar a Fase de Planejamento

O OpenHands retransmite a solicitação para o LLM configurado, que então formula um plano estratégico. Normalmente, o agente delineará suas ações pretendidas na interface, como:

1. Criar um novo arquivo chamado hello.sh.
2. Inserir o comando bash echo "hello world!" neste arquivo.
3. Conceder permissões de execução ao script usando chmod +x hello.sh.
4. Executar o script via ./hello.sh para confirmar que a saída corresponde às expectativas.

Passo 3: Observar a Fase de Execução

O agente prossegue para executar os passos planejados dentro de seu ambiente de runtime Docker isolado. O log da interface mostrará os comandos em execução e refletirá as modificações no sistema de arquivos conforme ocorrem.

Passo 4: Verificar o Resultado

Após a conclusão bem-sucedida, o agente deve relatar o resultado da execução, incluindo a saída esperada: "hello world!".

Passo 5: Refinamento Iterativo

Agora, vamos modificar o script com uma instrução de acompanhamento:

Modifique hello.sh para que aceite um nome como o primeiro argumento, mas por padrão use "world"

Passo 6: Observar o Processo de Modificação

O agente novamente formulará e executará um plano:

1. Leia o conteúdo existente de hello.sh.
2. Atualize o código do script para incorporar o tratamento de argumentos, potencialmente usando expansão de parâmetros bash como echo "hello ${1:-world}!".
3. Opcionalmente, execute testes com e sem argumentos (por exemplo, ./hello.sh e ./hello.sh Developer) para validar as alterações.

Passo 7: Tarefa de Conversão de Linguagem

Demonstre a flexibilidade do agente solicitando uma mudança de linguagem:

Por favor, converta hello.sh em um script Ruby e execute-o

Passo 8: Observar a Adaptação ao Ambiente

Se o ambiente de sandbox não tiver o interpretador Ruby necessário, o agente pode planejar e executar comandos de instalação primeiro (por exemplo, apt-get update && apt-get install -y ruby). Subsequentemente, ele traduzirá a lógica para o código Ruby (por exemplo, puts "hello #{ARGV[0] || 'world'}!"), salvá-lo-ás em hello.rb, torná-lo executável e executar o novo script.

Este exemplo introdutório destaca o fluxo de trabalho central do agente: compreender instruções, planejar etapas de execução, interagir com o sistema de arquivos e shell dentro de uma sandbox e adaptar-se com base em solicitações iterativas.

Construindo do Zero: Exemplo de Aplicação TODO

Os agentes frequentemente demonstram um desempenho robusto em projetos "greenfield", onde podem estabelecer a estrutura sem precisar de um contexto extenso de uma base de código complexa existente.

Passo 1: Fornecendo o Prompt Inicial do Projeto

Seja preciso em relação aos recursos desejados e ao stack tecnológico:

Construa um aplicativo TODO somente frontend em React. Todo estado deve ser armazenado em localStorage. Implemente a funcionalidade básica para adicionar novas tarefas e exibir a lista atual de tarefas.

Passo 2: Monitorar o Planejamento e a Construção

O agente pode elaborar estratégias da seguinte forma:

1. Utilize create-react-app (se disponível/instruído) ou escafandre manualmente arquivos básicos de HTML, CSS e JavaScript/JSX.
2. Desenvolva componentes React para o formulário de entrada de tarefas e a exibição da lista de tarefas.
3. Implemente o gerenciamento de estado da aplicação usando hooks do React como useState e useEffect.
4. Integre localStorage.setItem() e localStorage.getItem() para persistência de dados entre sessões.
5. Escreva a estrutura HTML necessária e aplique estilo básico com CSS.

Passo 3: Solicitar Melhoria de Recurso

Uma vez que a aplicação fundamental está operacional, solicite recursos adicionais:

Permita adicionar uma data de vencimento opcional a cada tarefa. Exiba essa data de vencimento ao lado da descrição da tarefa na lista.

Passo 4: Observar o Desenvolvimento Iterativo

O agente modificará os componentes React existentes para incluir um elemento de entrada de data, atualizará a estrutura de estado da aplicação para acomodar as informações de data de vencimento e ajustará a lógica de renderização para exibir as datas adequadamente na lista de tarefas.

Passo 5: Implementar Controle de Versão (Melhor Prática)

Salve regularmente o progresso do agente usando controle de versão, assim como você faria em um desenvolvimento manual. Você pode até mesmo instruir o agente a lidar com commits:

Comite as alterações atuais com a mensagem "feat: Adicionar funcionalidade de data de vencimento às tarefas" e envie o commit para um novo branch chamado "feature/due-dates" no repositório remoto de origem.

(Observação: A execução bem-sucedida de comandos Git, especialmente o envio para remotos, requer que o Git esteja instalado e potencialmente configurado com credenciais de autenticação dentro do ambiente de trabalho/sandbox do agente.)

Adicionando Novo Código a Projetos Existentes

O OpenHands é capaz de integrar novos códigos e recursos a bases de código estabelecidas.

Exemplo 1: Adicionando um Ação do GitHub

• Prompt:

Adicione um fluxo de trabalho de Ação do GitHub a este repositório que analise o código JavaScript usando ESLint sempre que o código for enviado para o branch principal.

• Comportamento do Agente: O agente pode primeiro inspecionar a estrutura do projeto (por exemplo, ls .github/workflows) para ver se já existem fluxos de trabalho. Em seguida, ele determinaria o lintador apropriado (ou usaria o especificado), criaria um novo arquivo YAML (por exemplo, .github/workflows/lint.yml) e preenchê-lo-ás com a configuração correta para uma Ação do GitHub acionada em envios para main, executando o ESLint.

Exemplo 2: Adicionando uma Rota de Backend (O Contexto é Importante)

• Prompt:

Modifique o arquivo da aplicação Express.js localizado em './backend/api/routes.js'. Adicione um novo endpoint GET em '/api/tasks' que recupere e retorne todas as tarefas chamando a função assíncrona 'getAllTasks' encontrada em './db/queries.js'.

• Comportamento do Agente: Fornecer o caminho específico do arquivo (./backend/api/routes.js) e informações contextuais relevantes (como a existência e localização de getAllTasks em ./db/queries.js) melhora dramaticamente a eficiência e precisão do agente. Ele mirará no arquivo especificado e inserirá o código necessário do manipulador de rota, incluindo a importação da função requerida.

Refatoração de Código

Aproveite o OpenHands para esforços direcionados de refatoração de código.

Exemplo 1: Renomeando Variáveis para Clareza

• Prompt: No arquivo './utils/calculation.py', renomeie todas as variáveis de uma letra dentro da função 'process_data' para serem mais descritivas quanto ao seu propósito.

Exemplo 2: Dividindo Funções Grandes

• Prompt: Refatore a função 'process_and_upload_data' em 'data_handler.java'. Divida sua lógica em duas funções distintas: 'process_data' e 'upload_data', mantendo a funcionalidade original.

Exemplo 3: Melhorando a Estrutura do Arquivo

• Prompt: Separe as definições de rotas principais em './api/routes.js' em arquivos distintos com base nos recursos (por exemplo, 'userRoutes.js', 'productRoutes.js'). Atualize o arquivo principal do servidor ('server.js') para importar e usar esses arquivos de rotas modulares.

Corrigindo Bugs

Enquanto a correção de bugs pode ser intrincada, o OpenHands pode ajudar, especialmente quando o problema está bem definido.

Exemplo 1: Corrigindo Lógica Específica

• Prompt: A expressão regular usada para validação de e-mails no manipulador do endpoint '/subscribe' dentro de 'server/handlers.js' rejeita incorretamente nomes de domínio válidos '.co.uk'. Por favor, corrija o padrão regex.

Exemplo 2: Modificando Comportamento

• Prompt: A função 'search_items' implementada em 'search.php' atualmente realiza uma busca sensível a maiúsculas. Modifique esta função para garantir que a busca seja insensível a maiúsculas.

Exemplo 3: Empregando uma Abordagem Dirigida por Testes

1. Prompt para Criação de Teste: A função 'calculate_discount' em 'pricing.js' falha quando a quantidade de entrada é zero. Escreva um novo caso de teste usando Jest no arquivo 'pricing.test.js' que reproduza especificamente esse bug.
2. Observe a Execução do Teste: O agente gera o código do teste, executa a suíte de testes (por exemplo, via npm test) e relata a falha esperada.
3. Prompt para Correção do Código: Agora, modifique a função 'calculate_discount' em 'pricing.js' para lidar corretamente com o caso de quantidade zero, assegurando que o teste anteriormente escrito passe.
4. Observe a Correção e Validação: O agente ajusta a lógica da função (talvez adicionando uma verificação condicional para a quantidade zero) e re-executa a suíte de testes, relatando o resultado bem-sucedido.

Estratégia de Uso Central: Comece com solicitações simples e específicas. Forneça contexto necessário, como caminhos de arquivos e nomes de funções. Quebre objetivos complexos em passos menores e iterativos. Comite mudanças frequentemente usando controle de versão.

Como Configurar o OpenHands com LLMs (OpenAI, OpenRouter, Google Gemini, Local)

Estabelecer a conexão entre o OpenHands e um LLM capaz é fundamental. Essa configuração é gerenciada através da interface do usuário web do OpenHands.

Acessando Configurações de LLM

• Durante a Configuração Inicial: Um modal de configuração aparece automaticamente ao carregar a interface do usuário pela primeira vez em http://localhost:3000.
• Para Mudanças Subsequentes: Clique no ícone de engrenagem (⚙️) dentro da interface do usuário, normalmente situado próximo à entrada de chat ou em um painel de configurações.

Procedimento Geral de Configuração de LLM

1. Selecione o Fornecedor de LLM: Escolha o serviço desejado (por exemplo, "OpenAI", "Anthropic", "Google", "OpenRouter", "Ollama") no menu suspenso disponível.
2. Digite a Chave de API: Cole cuidadosamente a chave de API associada ao seu fornecedor escolhido no campo de entrada designado. As chaves de API devem ser tratadas com a mesma segurança que as senhas.
3. Especifique o Modelo de LLM: Selecione o modelo específico que você pretende usar do fornecedor escolhido (por exemplo, gpt-4o, claude-3-5-sonnet-20240620, gemini-1.5-pro-latest). Os modelos disponíveis podem ser populados dinamicamente com base no fornecedor selecionado, ou você pode precisar inserir o nome do modelo manualmente.
4. Explore Opções Avançadas (Opcional): Ative as configurações avançadas para revelar mais possibilidades de configuração:

• Modelo Personalizado: Se seu modelo preferido não estiver listado, você pode frequentemente inserir seu identificador preciso aqui (consulte a documentação do fornecedor para o ID do modelo correto).
• URL Base: Essa configuração é crítica ao conectar-se a LLMs hospedados localmente ou usar serviços proxy. Ela define o URL do endpoint API que o OpenHands deve direcionar para solicitações.

5. Salve a Configuração: Aplique e salve suas configurações escolhidas.

Passos de Configuração Específicos do Fornecedor

Siga estes passos detalhados para provedores populares de LLM:

Configuração OpenAI

1. Visite https://platform.openai.com/.
2. Faça login ou crie uma nova conta.
3. Navegue até a seção Chaves de API e gere uma nova chave secreta. Copie essa chave imediatamente, pois ela pode não ser exibida novamente.
4. Certifique-se de que as informações de cobrança estejam configuradas corretamente nas configurações de Billing para habilitar o uso da API.
5. Dentro das configurações da UI do OpenHands:

• Defina o Fornecedor como OpenAI.
• Cole sua chave de API gerada no campo de Chave de API.
• Selecione ou digite o modelo desejado do OpenAI (por exemplo, gpt-4o, gpt-4-turbo).

Configuração Anthropic (Claude)

1. Vá para https://console.anthropic.com/.
2. Faça login ou crie uma conta.
3. Acesse Configurações da Conta > Chaves de API e crie uma nova chave de API. Copie a chave gerada.
4. Configure a cobrança em Planos & Cobrança. Considere definir limites de uso para gerenciar custos efetivamente.
5. Nas configurações da UI do OpenHands:

• Defina o Fornecedor como Anthropic.
• Cole sua chave de API copiada.
• Selecione ou insira o modelo específico do Claude (por exemplo, claude-3-5-sonnet-20240620, claude-3-opus-20240229).

Configuração Google Gemini

1. Obtenha uma chave de API através de:

• Google AI Studio: (https://aistudio.google.com/app/apikey) - Adequado para experimentação individual.
• Google Cloud Vertex AI: (https://cloud.google.com/vertex-ai) - Recomendado para aplicações empresariais ou integradas à nuvem.

2. Se usando o Google Cloud, certifique-se de que as APIs necessárias do Vertex AI estejam habilitadas e que a cobrança esteja configurada para seu projeto.

3. Nas configurações da UI do OpenHands:

• Defina o Fornecedor como Google.
• Cole sua chave de API obtida.
• Selecione ou insira o modelo desejado do Gemini (por exemplo, gemini-1.5-pro-latest, gemini-1.5-flash-latest).

Configuração OpenRouter

1. Navegue até https://openrouter.ai/.
2. Faça login ou crie uma conta.
3. Vá para a seção Chaves e gere uma nova chave de API. Copie-a.
4. Adicione créditos à sua conta através da seção Cobrança para habilitar o uso.
5. Nas configurações da UI do OpenHands:

• Defina o Fornecedor como OpenRouter.
• Cole sua chave de API do OpenRouter gerada.
• Selecione ou digite o identificador exato do modelo usado pelo OpenRouter (por exemplo, anthropic/claude-3.5-sonnet, google/gemini-pro-1.5, mistralai/mistral-7b-instruct). Consulte a documentação dos Modelos do OpenRouter para obter uma lista dos identificadores disponíveis.

Configuração de LLMs Locais (exemplo, via Ollama)

1. Instale o Ollama: Siga o guia de instalação em https://ollama.com/.
2. Baixe o Modelo: Use a CLI do Ollama para baixar um modelo desejado, por exemplo, ollama pull llama3 (ou outros modelos como codellama, mistral).
3. Executar o Servidor Ollama: Certifique-se de que o servidor em segundo plano do Ollama esteja em execução (ele geralmente inicia automaticamente após a instalação).
4. Nas configurações da UI do OpenHands:

• Defina o Fornecedor como Ollama (ou potencialmente LiteLLM se o estiver usando como intermediário).
• Chave de API: Geralmente não requerida para configurações padrão do Ollama; você pode deixá-la em branco ou inserir NA ou ollama.
• Ative Opções Avançadas.
• Defina a URL Base: Isso é essencial. Como o OpenHands é executado dentro do Docker, localhost aponta para o próprio contêiner, não para a máquina host onde o Ollama está em execução. Use o nome DNS especial http://host.docker.internal:11434. host.docker.internal resolve-se para o IP da sua máquina host a partir do contêiner, e 11434 é a porta padrão para o servidor da API do Ollama.
• Especifique o Modelo: Selecione ou digite o nome exato do modelo do Ollama que você baixou (por exemplo, llama3, codellama) no campo Modelo ou Modelo Personalizado.

Como Configurar o Runtime do Docker do OpenHands

O termo "runtime" no OpenHands designa o ambiente isolado de contêiner Docker no qual o agente executa comandos e interage com o sistema de arquivos. A configuração envolve principalmente especificar qual imagem de runtime usar ao iniciar o contêiner principal da aplicação OpenHands.

Propósito do Ambiente Runtime

• Isolamento e Segurança: O contêiner de runtime opera separadamente do contêiner principal da aplicação OpenHands. Essa segregação cria uma sandbox segura, impedindo que ações realizadas pelo agente (como instalação de software ou execução de código) impactem diretamente a aplicação principal ou o sistema host.
• Ambiente de Execução: A imagem de runtime normalmente inclui ferramentas básicas essenciais (como um shell e utilitários de linha de comando comuns). Dependendo da imagem específica escolhida, ela pode também vir pré-instalada com ferramentas de desenvolvimento como Python, Node.js ou Git. Além disso, o agente geralmente tem a capacidade de instalar ferramentas adicionais necessárias dentro deste ambiente de sandbox usando gerenciadores de pacotes (apt, npm, pip, etc.).

Configuração via Comando docker run

O método principal para configurar o runtime é através da flag -e (variável de ambiente) dentro do comando docker run usado para lançar a aplicação OpenHands:

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.34-nikolaik

Essa variável de ambiente instrui a aplicação OpenHands sobre a tag específica da imagem Docker que ela deve usar sempre que precisar provisionar um novo contêiner sandbox para lidar com a execução das tarefas do agente.

Modificando ou Atualizando o Runtime

• Trocando Versões de Runtime: Se uma nova versão da imagem de runtime se tornar disponível (por exemplo, 0.35-newfeature), você deve primeiro parar o contêiner OpenHands atualmente em execução (por exemplo, docker stop openhands-app). Em seguida, reinicie-o usando o comando docker run, atualizando a tag da imagem especificada na flag -e SANDBOX_RUNTIME_CONTAINER_IMAGE:

docker run ... -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.35-newfeature ... docker.all-hands.dev/all-hands-ai/openhands:<corresponding_app_version>

(Observação: Geralmente é aconselhável atualizar a tag da imagem da aplicação openhands principal em paralelo para garantir compatibilidade entre a aplicação e o ambiente de runtime.)

• Usando Builds de Desenvolvimento: Para testar os recursos mais recentes, potencialmente instáveis, você pode utilizar a tag main para a imagem de runtime:

-e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:main

• Aproveitando a Versionamento Semântico: A documentação sugere que as tags de versão podem suportar convenções de versionamento semântico (por exemplo, :0.9 potencialmente resolvendo para a última 0.9.x versão patch). Isso pode oferecer uma maneira de receber atualizações menores automaticamente se o repositório de imagens o suportar.

Em essência, gerenciar o runtime do Docker envolve principalmente selecionar e especificar a tag apropriada da imagem de runtime dentro do seu comando docker run, equilibrando os requisitos de estabilidade com a necessidade de recursos ou atualizações específicas.

Melhores Prompts do OpenHands

A eficácia do agente OpenHands é profundamente influenciada pela qualidade dos prompts fornecidos. Elaborar prompts que sejam claros, específicos e adequadamente dimensionados é essencial para alcançar resultados precisos e úteis.

Características de Prompts Eficazes

Boas prompts geralmente exibem as seguintes qualidades:

• Concreto: