infraestrutura-de-agentes-hospedados

Infraestrutura de Agentes Hospedados

Agentes hospedados executam em ambientes sandbox remotos, em vez de máquinas locais. Quando bem projetados, eles fornecem concorrência ilimitada, ambientes de execução consistentes e colaboração multiusuário. A percepção crítica é que a velocidade da sessão deve ser limitada apenas pelo tempo até o primeiro token do provedor de modelo, com toda a configuração de infraestrutura concluída antes do usuário iniciar sua sessão.

Quando Ativar

Ative este skill quando:

• Construir agentes de codificação em segundo plano que rodam independentemente dos dispositivos do usuário
• Projetar ambientes de execução em sandbox para cargas de trabalho de agentes
• Implementar sessões de agente multijogador com estado compartilhado
• Criar interfaces de agente para múltiplos clientes (Slack, Web, extensões Chrome)
• Escalar infraestrutura de agentes além das restrições da máquina local
• Construir sistemas onde agentes geram subagentes para trabalho paralelo

Não ative este skill para trabalho adjacente de propriedade de outros skills:

• Projetar o loop de pesquisa autônomo, portões de novidade, política de reversão ou limites de merge: harness-engineering.
• Escolher a topologia de supervisor, enxame ou passagem de bastão sem preocupações de infraestrutura hospedada: multi-agent-patterns.
• Projetar as ferramentas usadas por um agente hospedado, como ferramentas de spawn/status ou ferramentas de PR: tool-design.
• Gerenciar estado baseado em arquivos dentro de uma sessão, em vez do runtime hospedado em si: filesystem-context.

Conceitos Principais

Mova a execução do agente para ambientes sandbox remotos para eliminar os limites fundamentais da execução local: contenção de recursos, inconsistência de ambiente e restrições de usuário único. Sandboxes remotos desbloqueiam concorrência ilimitada, ambientes reproduzíveis e fluxos de trabalho colaborativos, pois cada sessão recebe seu próprio computação isolada com uma imagem de ambiente conhecidamente boa.

Projete a arquitetura em três camadas porque cada camada escala independentemente. Construa infraestrutura sandbox para execução isolada, uma camada de API para gerenciamento de estado e coordenação de clientes, e interfaces de cliente para interação do usuário em várias plataformas. Mantenha essas camadas limpas e separadas para que mudanças no sandbox não se propaguem para os clientes.

Tópicos Detalhados

Infraestrutura Sandbox

O Desafio Central Elimine a latência de inicialização do sandbox, pois os usuários percebem qualquer coisa acima de alguns segundos como quebrada. Ambientes de desenvolvimento exigem clonar repositórios, instalar dependências e executar etapas de build — faça tudo isso antes que o usuário envie um prompt.

Padrão de Registro de Imagens Pré-construa imagens de ambiente em uma cadência regular (a cada 30 minutos funciona bem) porque isso torna a sincronização com o código mais recente um delta rápido, em vez de um clone completo. Inclua em cada imagem:

• Repositório clonado em um commit conhecido
• Todas as dependências de runtime instaladas
• Comandos de configuração e build iniciais concluídos
• Arquivos em cache da execução do aplicativo e suíte de testes uma vez

Ao iniciar uma sessão, inicie um sandbox a partir da imagem mais recente. O repositório está no máximo 30 minutos desatualizado, tornando a sincronização git restante rápida.

Snapshot e Restauração Tire snapshots do sistema de arquivos em pontos-chave para permitir restauração instantânea para prompts de acompanhamento sem reexecutar a configuração:

• Após a construção inicial da imagem (snapshot base)
• Quando o agente termina de fazer alterações (snapshot da sessão)
• Antes da saída do sandbox para possível acompanhamento

Configuração Git para Agentes em Segundo Plano Configure a identidade git explicitamente em cada sandbox, pois agentes em segundo plano não estão vinculados a um usuário específico durante as construções de imagem:

• Gere tokens de instalação do GitHub App para acesso ao repositório durante o clone
• Defina user.name e user.email do git config ao commitar e enviar alterações
• Use a identidade do usuário que está solicitando para os commits, não a identidade do aplicativo

Estratégia de Pool Aquecido Mantenha um pool de sandboxes pré-aquecidos para repositórios de alto volume, pois inicializações a frio são a principal fonte de frustração do usuário:

• Mantenha sandboxes prontos antes dos usuários iniciarem sessões
• Expire e recrie entradas do pool conforme novas construções de imagem são concluídas
• Comece a aquecer um sandbox assim que um usuário começar a digitar (aquecimento preditivo)

Seleção de Framework de Agente

Arquitetura Servidor-Primeiro Estruture o framework do agente como um servidor primeiro, com TUI e aplicativos de desktop como clientes leves, porque isso evita duplicar a lógica do agente em várias superfícies:

• Vários clientes personalizados compartilham um backend de agente
• Comportamento consistente em todas as superfícies de interação
• Sistemas de plugins estendem a funcionalidade sem alterações no cliente
• Arquiteturas orientadas a eventos entregam atualizações em tempo real para qualquer cliente conectado

Código como Fonte da Verdade Selecione frameworks onde o agente possa ler seu próprio código-fonte para entender o comportamento. Priorize isso, pois ter o código como fonte da verdade evita que o agente alucine sobre suas próprias capacidades — um modo de falha subestimado no desenvolvimento de IA.

Requisitos do Sistema de Plugins Exija um sistema de plugins que suporte interceptação em tempo de execução, pois isso permite controles de segurança e observabilidade sem modificar a lógica central do agente:

• Ouça eventos de execução de ferramentas (por exemplo, tool.execute.before)
• Bloqueie ou modifique chamadas de ferramentas condicionalmente
• Injete contexto ou estado em tempo de execução

Otimizações de Velocidade

Aquecimento Preditivo Comece a aquecer o sandbox assim que um usuário começar a digitar seu prompt, não quando ele o enviar, porque o intervalo de digitação (5-30 segundos) é suficiente para concluir a maior parte da configuração:

• Clone as alterações mais recentes em paralelo com a digitação do usuário
• Execute a configuração inicial antes do usuário pressionar Enter
• Para inicialização rápida, o sandbox pode estar pronto antes do usuário terminar de digitar

Leitura Paralela de Arquivos Permita que o agente comece a ler arquivos imediatamente, mesmo se a sincronização do branch base mais recente não estiver completa, porque em repositórios grandes, os prompts recebidos raramente tocam em arquivos alterados recentemente:

• O agente pode pesquisar imediatamente sem esperar pela sincronização git
• Bloqueie edições de arquivos (não leituras) até que a sincronização seja concluída
• Essa separação é segura porque a defasagem de dados de leitura de 30 minutos raramente importa para pesquisa

Maximize o Trabalho em Tempo de Build Mova tudo que for possível para a etapa de construção da imagem, porque a duração do tempo de build é invisível para os usuários:

• Instalação completa de dependências
• Configuração do esquema do banco de dados
• Execução inicial do aplicativo e suíte de testes (preenche caches)

Agentes Auto-geradores

Sessões Geradas por Agentes Construa ferramentas que permitam aos agentes gerar novas sessões, pois modelos de fronteira são capazes de decompor trabalho e coordenar subtarefas:

• Tarefas de pesquisa em diferentes repositórios
• Execução paralela de subtarefas para grandes alterações
• Vários PRs menores a partir de uma tarefa principal

Exponha três primitivas: iniciar uma nova sessão com parâmetros especificados, ler o status de qualquer sessão (capacidade de check-in) e continuar o trabalho principal enquanto sub-sessões são executadas em paralelo.

Engenharia de Prompt para Auto-geração Engenharia de prompts que orientem quando os agentes devem gerar sub-sessões em vez de fazer o trabalho em linha:

• Tarefas de pesquisa que exigem exploração entre repositórios
• Dividir alterações monolíticas em PRs menores
• Exploração paralela de diferentes abordagens

Camada de API

Isolamento de Estado por Sessão Isole o estado por sessão (SQLite por sessão funciona bem) porque a interferência entre sessões é um modo de falha sutil e difícil de depurar:

• Banco de dados dedicado por sessão
• Nenhuma sessão pode impactar o desempenho de outra
• A arquitetura lida com centenas de sessões simultâneas

Streaming em Tempo Real Transmita todo o trabalho do agente em tempo real, pois o feedback de alta frequência é crítico para a confiança do usuário:

• Streaming de tokens dos provedores de modelo
• Atualizações de status de execução de ferramentas
• Notificações de alterações em arquivos

Use conexões WebSocket com APIs de hibernação para reduzir custos de computação durante períodos ociosos, mantendo conexões abertas.

Sincronização Entre Clientes Construa um sistema de estado único que sincronize em todos os clientes (interfaces de chat, bots do Slack, extensões Chrome, interfaces web, instâncias VS Code) porque os usuários trocam de superfície com frequência e esperam continuidade. Todas as alterações sincronizam com o estado da sessão, permitindo a troca contínua de cliente.

Suporte Multijogador

Por que Multijogador Importa Projete para multijogador desde o dia um, porque é quase gratuito de adicionar com uma arquitetura de sincronização adequada, e desbloqueia fluxos de trabalho de alto valor:

• Ensinar não-engenheiros a usar IA de forma eficaz
• Sessões de QA ao vivo com vários membros da equipe
• Revisão de PR em tempo real com alterações imediatas
• Sessões de depuração colaborativas

Requisitos de Implementação Construa o modelo de dados para que as sessões não sejam vinculadas a autores únicos, porque o multijogador falha silenciosamente se a autoria for codificada:

• Passe informações de autoria para cada prompt
• Atribua alterações de código ao usuário que solicitou
• Compartilhe links de sessão para colaboração instantânea

Autenticação e Autorização

Commits Baseados em Usuário Use autenticação do GitHub para abrir PRs em nome do usuário (não do aplicativo) porque isso preserva a trilha de auditoria e impede que os usuários aprovem suas próprias alterações geradas por IA:

• Obtenha tokens de usuário para criação de PR
• PRs aparecem como sendo de autoria do humano, não do bot

Fluxo Sandbox-para-API Siga esta sequência porque ela mantém as permissões do sandbox mínimas, enquanto permite que a API lide com operações sensíveis:

1. O sandbox envia alterações (atualizando a configuração de usuário do git)
2. O sandbox envia um evento para a API com o nome do branch e ID da sessão
3. A API usa o token do GitHub do usuário para criar PR
4. Webhooks do GitHub notificam a API sobre eventos de PR

Implementações de Cliente

Integração com Slack Priorize o Slack como o primeiro canal de distribuição para adoção interna, pois cria um ciclo de viralidade à medida que os membros da equipe veem outros usando-o:

• Sem sintaxe necessária, interface de chat natural
• Construa um classificador (modelo rápido com descrições de repositórios) para determinar em qual repositório trabalhar
• Inclua dicas para repositórios comuns; permita "desconhecido" para casos ambíguos

Interface Web Construa uma interface web com estes recursos, pois ela serve como a principal superfície para usuários avançados:

• Streaming em tempo real do trabalho do agente em desktop e mobile
• Instância VS Code hospedada executando dentro do sandbox
• Visualização de desktop transmitida para verificação visual
• Capturas de tela antes/depois para PRs
• Página de estatísticas: sessões que resultaram em PRs mesclados (métrica primária), uso ao longo do tempo, contagem ao vivo de "humanos solicitando"

Extensão Chrome Construa uma extensão Chrome para usuários não-engenheiros, porque a extração de DOM e React internals oferece maior precisão do que capturas de tela brutas a um custo de token menor:

• Interface de chat em barra lateral com ferramenta de captura de tela
• Extraia DOM/React internals em vez de imagens brutas
• Distribua via política de dispositivo gerenciado (ignora a Chrome Web Store)

Orientação Prática

Lista de Verificação de Design de Agente Hospedado

Antes de construir o sistema, decida estas propriedades de infraestrutura explicitamente:

1. Ciclo de vida do sandbox: como as sessões iniciam, snapshot, restauram, expiram e terminam.
2. Política de imagem e pool aquecido: com que frequência as imagens são reconstruídas, quais caches são pré-computados e quando os sandboxes aquecidos expiram.
3. Sincronização de leitura/escrita: se os agentes podem ler antes da sincronização do repositório ser concluída e quais eventos desbloqueiam as escritas.
4. Isolamento de estado por sessão: qual armazenamento pertence a uma sessão, o que é compartilhado e como a interferência entre sessões é evitada.
5. Autenticação e identidade de commit: quais operações usam tokens de aplicativo, quais usam tokens de usuário e como os commits são atribuídos.
6. Extração de saída: como branches, PRs, arquivos, logs, capturas de tela e resumos de sessão saem do sandbox.
7. Orçamento e desmontagem: tempo máximo de execução, limites de custo, política de inatividade e comportamento de limpeza forçada.

Tratamento de Mensagens de Acompanhamento

Escolha entre enfileirar e inserir mensagens de acompanhamento enviadas durante a execução. Prefira enfileiramento porque é mais simples de gerenciar e permite que os usuários enviem pensamentos sobre os próximos passos enquanto o agente trabalha. Construa um mecanismo para parar o agente no meio da execução quando necessário, porque sem ele os usuários se sentem presos.

Métricas que Importam

Acompanhe estas métricas porque elas indicam valor real, em vez de uso por vaidade:

• Sessões que resultam em PRs mesclados (métrica principal de sucesso)
• Tempo do início da sessão até a primeira resposta do modelo
• Taxa de aprovação de PR e número de revisões
• Porcentagem de código escrito por agente em todos os repositórios

Estratégia de Adoção

Impulsione a adoção interna por meio da visibilidade, em vez de mandatos, porque o uso forçado gera ressentimento:

• Trabalhe em espaços públicos (canais do Slack) para visibilidade
• Deixe o produto criar ciclos de viralidade
• Não force o uso sobre ferramentas existentes
• Construa para as necessidades das pessoas, não para requisitos hipotéticos

Exemplos

Exemplo 1: Ciclo de vida de sessão de codificação em segundo plano

prompt do usuário
-> API aloca sandbox aquecido da imagem atual
-> sandbox sincroniza o delta do branch mais recente
-> leituras permitidas imediatamente, escritas bloqueadas até a sincronização ser concluída
-> agente edita e testa dentro do workspace isolado
-> sandbox tira snapshot do sistema de arquivos final
-> branch é enviado
-> API cria PR usando token do usuário
-> resumo da sessão, logs e URL do PR são retornados aos clientes

Esta sequência mantém o trabalho de configuração fora do caminho visível ao usuário, preservando a auditabilidade e a propriedade das alterações de código pelo usuário.

Exemplo 2: Decisão de limite

Se a tarefa for "fazer o loop do agente rodar por dias com rubricas bloqueadas e aprovação de PR", use harness-engineering. Se a tarefa for "executar esse loop em sandboxes remotos com pools aquecidos, snapshots de sessão, clientes de streaming e PRs de autoria do usuário", use este skill.

Diretrizes

1. Pré-construa imagens de ambiente em cadência regular (30 minutos é um bom padrão)
2. Comece a aquecer sandboxes quando os usuários começarem a digitar, não quando eles enviarem
3. Permita leituras de arquivos antes da sincronização git ser concluída; bloqueie apenas escritas
4. Estruture o framework do agente como servidor-primeiro, com clientes como wrappers leves
5. Isole o estado por sessão para evitar interferência entre sessões
6. Atribua commits ao usuário que solicitou, não ao aplicativo
7. Acompanhe PRs mesclados como métrica principal de sucesso
8. Construa para multijogador desde o início; é quase gratuito com arquitetura de sincronização adequada

Pegadinhas

1. Latência de inicialização a frio: A primeira inicialização do sandbox leva de 30 a 60 segundos e os usuários percebem isso como quebrado. Use um pool aquecido.