Execuções Gerenciadas de Agentes

As Execuções Gerenciadas de Agentes permitem que você despache agentes de IA autônomos diretamente pelo Archyl. Atribua uma tarefa, escolha o perfil que define como eles se comportam, conecte-os a serviços externos via conectores MCP, defina um agendamento recorrente e deixe-os trabalhar no seu código com contexto arquitetural completo.

Acesse Hub de Agentes → Execuções na barra lateral para gerenciar suas execuções, Hub de Agentes → Perfis para definir como os agentes se comportam, ou Hub de Agentes → Agendamentos para automação recorrente.

Visão Geral

Uma execução gerenciada é uma única execução de agente. O agente:

1. Clona o repositório do seu projeto em um workspace novo no worker de agentes
2. Recebe seu contexto arquitetural (modelo C4, ADRs, regras de conformidade, contratos de API, stack tecnológica) junto com o briefing da sessão de trabalho: os elementos que a tarefa toca, o que as sessões anteriores aprenderam sobre eles e o veredito do preflight
3. Executa a tarefa que você definiu, chamando ferramentas e tomando decisões dentro dos limites do seu perfil
4. Publica suas alterações de código como pull request e reporta de volta com um rastreamento completo de cada ação

As execuções podem ser disparadas manualmente (avulsas) ou automaticamente via agendamentos.

Iniciando uma Execução

1. Vá até Hub de Agentes → Execuções
2. Selecione seu projeto no menu suspenso
3. Clique em Nova execução
4. Escolha um perfil
5. Escreva uma descrição da tarefa (ex.: "Verificar dependências desatualizadas e criar um resumo")
6. Opcionalmente, anexe conectores (veja abaixo)
7. Clique em Iniciar execução

O agente começa a trabalhar imediatamente. Você pode acompanhar o progresso em tempo real na página de detalhes da execução.

Perfis de Agentes

Um perfil é uma definição reutilizável de como um agente se comporta. Toda execução e todo agendamento usa um. O Archyl cria um perfil backend-fixer para sua organização no primeiro acesso; crie outros em Hub de Agentes → Perfis.

Excluir um perfil preserva o histórico das execuções que ele fez. Os agendamentos que o usavam são pausados e marcados como Perfil excluído; escolha outro perfil no agendamento para retomá-lo.

Skills

Skills são playbooks mantidos pelo Archyl, sempre alinhados às ferramentas que os agentes realmente têm. Ative-as por perfil em vez de copiar instruções para o prompt.

Um perfil com uma skill desconhecida ou um padrão de ferramentas permitidas inválido é recusado ao salvar.

O perfil padrão backend-fixer ativa Architecture memory, Conformance first e Decision records.

Página de Detalhes da Execução

Cada execução possui uma página de detalhes exibindo:

O feed de eventos exibe cartões expansíveis para cada ação:

• Chamadas de ferramentas — Exibe o nome da ferramenta, parâmetros de entrada e saída. Cada cartão mostra um rótulo de origem indicando de qual conector a ferramenta veio (ex.: github, archyl, linear).
• Mensagens — O raciocínio e as decisões do agente.
• Resultado — O desfecho, o uso de tokens, o pull request e os arquivos que o agente alterou.
• Erros — Destacados para identificação rápida.

Orientando um agente em execução

Enquanto uma execução está em andamento, digite uma mensagem na caixa de orientação para redirecionar o agente sem cancelá-lo ("pule a migração, foque no handler"). A mensagem entra na fila imediatamente e é inserida na conversa do agente no próximo passo; o feed mostra Mensagem de direcionamento entregue ao agente assim que o agente a recebe.

Quando uma execução para antes do fim

Se uma execução falha, atinge seu limite de custo ou de tempo, ou esgota as iterações, o trabalho já feito não é descartado: o Archyl o publica como um pull request em rascunho explicando por que a execução parou. Veja Pull request abaixo. Uma execução que você cancela não publica nada.

Garantias de confiabilidade

• Workers inativos são detectados. O worker de agentes dá sinal de vida a cada 10 segundos. Uma execução cujo worker está em silêncio há 3 minutos, ou que ainda está rodando 10 minutos após o limite de tempo, é marcada automaticamente como failed e sua vaga é liberada.
• Execuções travadas não prendem vagas. Uma execução que nenhum worker de agentes pegou em até 10 minutos falha, assim como uma execução que esperou a resposta de uma pessoa por mais de 1 hora e 10 minutos.
• Credenciais não sobrevivem às execuções. Cada execução recebe sua própria chave de API do Archyl de curta duração, revogada assim que a execução termina.
• O cancelamento chega ao agente. Uma execução cancelada para no próximo sinal de vida, mesmo que a solicitação direta de parada nunca tenha chegado ao worker.

Sessões de trabalho e coordenação

Cada execução é envolvida por uma sessão de trabalho do Archyl, o protocolo que o harness do Archyl oferece aos agentes de código locais. A plataforma abre e fecha a sessão; o agente nunca a gerencia.

A sessão de trabalho de uma execução

Quando uma execução começa, o Archyl abre uma sessão sobre os elementos de arquitetura que a tarefa toca. Ele cria reservas nesses elementos, calcula o veredito do gate de preflight (allow, warn ou deny) e coloca no briefing do agente as decisões, guardrails e memórias relevantes. O veredito aparece no feed de eventos como um evento Verificação.

Respeitar o trabalho de outros agentes

Respeitar o trabalho de outros agentes é uma configuração do perfil, em Coordenação, desativada por padrão. Quando está ativada, a sessão é aberta em modo exclusivo:

• Outro agente já reservou os elementos. Se outro agente tem uma reserva nos mesmos elementos, seja um agente de código como o Claude Code ou outra execução gerenciada, a execução é recusada. O motivo informa quem está trabalhando ali.
• O gate apenas alerta, por exemplo porque um guardrail de nível error se aplica. A execução fica em Aguardando aprovação sem ocupar nenhuma vaga de concorrência. A página da execução mostra os motivos, com Aprovar e iniciar e Cancelar execução.

Aprovar verifica o gate de novo: um conflito que surgiu nesse meio-tempo continua recusando a execução. Uma execução que ninguém aprova em 24 horas é cancelada.

Com a configuração desativada, a execução começa seja qual for o veredito do gate; o agente lê os motivos no próprio briefing.

Guard nas gravações de arquivos

Sempre que o agente trabalha em um repositório, vinculado ao projeto ou aberto pelo conector do GitHub, cada chamada a write_file e edit_file é conferida contra as regras de conformidade do projeto antes que a alteração seja aplicada:

Se a própria verificação falhar, a gravação passa: o Guard nunca bloqueia um agente por um erro próprio. Ele se comporta como o hook Guard dos agentes de código locais, descrito no guia do harness.

Resultado da sessão de trabalho

Antes de terminar, o agente relata o resultado: um resumo, as decisões, os próximos passos e as memórias em que se apoiou. Quando a execução termina, o Archyl:

1. Atribui os arquivos alterados à sessão, o que mostra em quais elementos reservados o trabalho de fato aconteceu
2. Fecha a sessão e guarda o resumo como memória nesses elementos
3. Registra as decisões como memória do projeto e abre um rascunho de solicitação de mudança de arquitetura para revisão. Só uma execução bem-sucedida registra decisões

A página da execução mostra um cartão Resultado da sessão de trabalho com o resumo, as decisões, os próximos passos, os elementos tocados e um link para a solicitação de mudança. Elementos que outra sessão mantém aparecem marcados como Reservado por outra sessão de trabalho.

Acompanhar uma execução ao vivo

A página de uma execução tem duas visualizações: Atividade, o feed de eventos, e Alterações, os arquivos que o agente gravou. Quando o agente precisa de você, um banner acima delas mostra o que ele está aguardando (Aguardando sua revisão do plano ou O agente tem uma pergunta) e leva você até lá.

O plano

Antes de alterar qualquer coisa, o agente compartilha um plano: um resumo de uma frase e algumas etapas concretas, no máximo 12. O painel Plano, no topo da página da execução, transforma o plano em uma checklist. O agente marca cada etapa como Em andamento, Concluída ou Ignorada, às vezes com uma nota curta, e o painel mostra a etapa atual e o progresso (3/7).

Revisar o plano primeiro é uma configuração do perfil, em Coordenação, desativada por padrão. Quando está ativada, o agente espera uma revisão antes de alterar qualquer coisa:

1. O painel passa para Revise o plano. Você pode renomear etapas, adicionar detalhes e adicionar, remover ou reordenar etapas.
2. Aprovar plano (Aprovar plano editado depois que você o editar) deixa o agente seguir em frente. A sua versão editada é o plano que o agente segue e que a checklist acompanha.
3. Solicitar alterações envia seu feedback. O agente revisa o plano e propõe uma nova revisão para você avaliar. As revisões anteriores continuam no feed.

Enquanto nenhum plano for aprovado, o agente pode ler, mas não alterar nada: gravar arquivos e qualquer ferramenta que crie, atualize, exclua, vincule, importe, faça push ou merge (no Archyl e em qualquer conector, ex.: linear__create_issue) são recusados, assim como remember. O agente é instruído a aguardar a revisão.

Perguntas

Quando uma decisão precisa de uma pessoa, como um requisito ambíguo, um trade-off sem uma opção claramente melhor ou algo destrutivo, o agente pergunta. A pergunta aparece acima do feed, com Respostas sugeridas quando o agente oferece algumas, e uma caixa de resposta livre (Cmd/Ctrl + Enter envia). Qualquer pessoa que possa editar o projeto pode responder, e o feed registra quem respondeu.

O agente faz no máximo 5 perguntas por execução e é instruído a nunca perguntar algo que possa consultar por conta própria.

Quando o agente aguarda você

Enquanto o agente aguarda uma revisão do plano ou uma resposta, a execução mostra Aguardando você e aparece em Precisa de você na lista de execuções, junto com as execuções retidas em Aguardando aprovação.

• A espera não conta para o limite de tempo da execução: o prazo é adiado pelo tempo passado esperando. A execução mantém sua vaga de execução simultânea.
• Uma pergunta que ninguém responde em até uma hora: o agente continua pelo próprio julgamento e informa no resultado a suposição que fez.
• Um plano que ninguém revisa em até uma hora: a execução falha, sem ter alterado nada.

Onde o agente trabalha

O agente lê e altera o código no seu workspace, um clone do repositório:

• Repositório vinculado ao projeto: o Archyl o clona quando a execução começa.
• Nenhum repositório vinculado, conector do GitHub anexado: o próprio agente clona o repositório de que trata a tarefa, com as credenciais do conector, antes de tocar em qualquer arquivo. Só o servidor MCP hospedado do GitHub (api.githubcopilot.com) é suportado. O conector precisa se autenticar com um cabeçalho Authorization: Bearer, e o token dele precisa de acesso ao repositório.

Depois que um workspace é aberto, o agente altera arquivos apenas nele: enviar arquivos ou abrir pull requests pelas ferramentas de um conector é recusado. É isso que faz toda alteração passar pelo Guard, aparecer na visualização Alterações e ir para um único pull request.

Alterações

Alterações lista cada arquivo que o agente grava, no momento em que grava: Adicionado, Modificado ou Bloqueado, com as linhas adicionadas e removidas por arquivo e na execução inteira. Selecione um arquivo para ver o que cada gravação mudou.

• Quando o Guard recusa uma gravação, o arquivo fica Bloqueado: o diff mostra o que o agente tentou gravar, com a regra violada. Uma gravação que o Guard apenas sinalizou passa, com um aviso no arquivo.
• Diffs longos são cortados após 600 linhas, e arquivos com mais de 128 KB aparecem sem diff.

Comentar uma linha

Revise o diff enquanto o agente trabalha. Em Alterações, clique em um número de linha para comentar essa linha e depois em Enviar ao agente (Cmd/Ctrl + Enter). O agente recebe o arquivo, a linha e o conteúdo dela, trata o comentário e depois segue com o plano.

• O comentário aparece abaixo da linha, Na fila até o agente lê-lo e depois Entregue. Ele também aparece em Atividade, e cada arquivo mostra quantos comentários tem.
• Você pode comentar linhas adicionadas, inalteradas e removidas. Gravações bloqueadas pelo Guard não aceitam comentários.
• Os comentários são aceitos enquanto o agente trabalha ou aguarda você. Um comentário ainda Na fila quando a execução termina aparece como Não entregue.

Em uma execução encerrada, um comentário vira uma nota para a próxima: Guardar para continuar o mantém no seu navegador, e a barra acima dos arquivos (3 comentários para uma continuação) continua a execução com eles (Continuar com eles).

Pull request

Quando a execução termina, o Archyl faz commit das alterações do workspace em uma branch chamada archyl/agent- seguido dos 8 primeiros caracteres do ID da execução, e abre um pull request contra a branch de onde o clone partiu. O link aparece no topo de Alterações (Abrir pull request) e no resultado.

No GitLab, o rascunho é um merge request Draft:. No Bitbucket, a branch é enviada sem pull request. Uma execução que não alterou nenhum arquivo não publica nada.

Pull requests são abertos no github.com, gitlab.com e bitbucket.org. O Archyl só envia suas credenciais do Git para esses hosts: um repositório em um servidor Git auto-hospedado (GitHub Enterprise, um GitLab privado, Azure DevOps, Gitea) é clonado sem credenciais, então um repositório privado não pode ser clonado, e nenhum pull request é aberto.

Continuar uma execução

Uma execução encerrada, qualquer que seja o resultado, oferece dois botões:

• Continuar inicia uma nova execução que retoma o trabalho desta. Escreva o que o agente deve fazer a seguir: seus comentários para continuar preenchem as instruções, um por linha (caminho:linha — comentário). O perfil padrão é o da execução, e você pode escolher conectores.
• Executar novamente abre a janela de início com a mesma tarefa e o mesmo perfil, para começar do zero.

Uma continuação sabe o que foi pedido à execução anterior e o que ela fez. Ela parte da branch que essa execução publicou, faz commit nela e adiciona suas alterações ao mesmo pull request em vez de abrir outro. Se a execução anterior enviou sua branch sem abrir um pull request, a continuação abre um, contra a branch que uma nova execução usaria como alvo. Se a execução anterior abriu um repositório pelo conector do GitHub, a continuação o abre de novo nessa branch.

• Se a branch não existe mais (por exemplo, mesclada e excluída), a continuação parte da branch de onde uma nova execução partiria, a branch vinculada ao projeto ou a branch padrão do repositório, e abre um novo pull request. O feed avisa.
• Um pull request em rascunho continua em rascunho: marque-o como pronto para revisão quando o trabalho estiver concluído.
• O Archyl só continua em branches criadas pelos agentes dele, nunca nas suas.

A página da nova execução leva à execução que ela continua (Continua a execução), e a execução anterior leva às continuações dela (Continuada em). Uma execução ainda em andamento não pode ser continuada: comente as linhas dela.

Conectores MCP

Os conectores permitem que você anexe serviços externos às execuções do seu agente. Qualquer serviço que exponha um servidor MCP (Model Context Protocol) pode ser conectado.

Serviços Suportados

Criando um Conector

1. Vá até Hub de Agentes → Conectores
2. Clique em Novo conector
3. Insira um nome (ex.: "github")
4. Cole a URL do servidor MCP
5. Adicione cabeçalhos de autenticação, se necessário
6. Clique em Criar conector — o Archyl verifica o servidor e exibe as ferramentas disponíveis

Namespace de Ferramentas

Quando um conector é anexado a uma execução, suas ferramentas recebem o nome do conector como prefixo:

As ferramentas do servidor MCP nativo do Archyl não possuem prefixo (ex.: get_agent_context, list_conformance_rules).

Esse sistema de namespace evita colisões entre nomes de ferramentas, torna o feed de eventos fácil de acompanhar e permite que as ferramentas permitidas de um perfil cubram um conector inteiro com um único padrão, como github__*.

Agendamentos

Os agendamentos permitem definir execuções recorrentes de agentes usando expressões cron padrão.

Criando um Agendamento

1. Vá até Hub de Agentes → Agendamentos
2. Clique em Novo agendamento
3. Escolha um perfil e escreva a descrição da tarefa
4. Selecione uma expressão cron (presets disponíveis ou insira uma personalizada)
5. Anexe conectores, se necessário
6. Clique em Criar agendamento

Gerenciamento de Agendamentos

Cada agendamento exibe:

• Expressão cron — Quando o agente executa
• Próxima execução — Quando a próxima execução está agendada
• Última execução — Quando o agente executou pela última vez
• Status — Ativo ou pausado, ou Perfil excluído quando seu perfil foi excluído

Você pode:

• Pausar um agendamento sem excluí-lo
• Retomar um agendamento pausado
• Executar agora — Executar imediatamente fora da cadência normal
• Editar o texto da tarefa, a expressão cron ou os conectores anexados
• Excluir o agendamento

Um agendamento cujo perfil foi excluído continua pausado: retomá-lo ou usar Executar agora é recusado até você editar o agendamento e escolher outro perfil.

Exemplos de Agendamentos

Contexto Arquitetural

Toda execução gerenciada recebe automaticamente acesso ao servidor MCP do seu projeto no Archyl. O agente pode:

• Consultar o modelo C4 para entender os limites do sistema
• Ler ADRs para compreender decisões arquiteturais passadas
• Verificar regras de conformidade para saber quais padrões seguir
• Navegar por contratos de API para entender interfaces de serviços
• Consultar atribuições de tecnologia para escolher as ferramentas corretas
• Recuperar e memorizar fatos sobre elementos por meio da memória de arquitetura

Esse contexto é injetado antes de o agente começar a trabalhar — ele não precisa descobrir sua arquitetura do zero. Além disso, cada execução é envolvida em uma sessão de trabalho do harness, de modo que seu resultado vira memória dos elementos que ela tocou.

Provedor de IA

As execuções usam o modelo gerenciado pelo Archyl, a menos que sua organização tenha ativado Use o seu próprio fornecedor de IA. Com o BYO ativado, as execuções rodam no seu provedor com as suas credenciais: Anthropic, AWS Bedrock, OpenAI ou um endpoint compatível com OpenAI que implemente a Responses API. O Google Gemini ainda não consegue executar agentes gerenciados: as execuções são recusadas com uma mensagem explícita, em vez de passarem silenciosamente a usar o modelo do Archyl.

Cotas e Concorrência

As Execuções Gerenciadas de Agentes estão disponíveis nos planos Scale e Custom. O uso é rastreado por organização com cotas mensais, exibidas no topo das páginas Execuções e Agendamentos. Continuar uma execução e aprovar uma execução retida também contam como execuções. Organizações com BYO AI ativado não são contabilizadas na cota, tanto em execuções manuais quanto agendadas.

Cada execução ativa (pending, running ou waiting_for_input) ocupa uma das vagas de execução simultânea da sua organização. A vaga é liberada no momento em que a execução termina, qualquer que seja o motivo.

Boas Práticas

• Seja específico nas descrições de tarefas — "Verificar pacotes Go com CVEs conhecidos e listá-los com severidade" funciona melhor do que "verificar dependências"
• Dê a cada tarefa o seu próprio perfil — Um revisor somente leitura com allowedTools limitado a list_*, get_* e read_file não consegue modificar nada por acidente.
• Anexe apenas os conectores necessários — Cada conector adiciona ferramentas ao contexto do agente. Menos ferramentas significa uma execução mais focada.
• Comece com execuções manuais — Teste a descrição da sua tarefa com uma execução avulsa antes de criar um agendamento.
• Use regras de conformidade em conjunto — Defina guardrails primeiro e depois ative a skill Conformance first para que as execuções as validem automaticamente.