Ninguém confia em um novo colega de equipe por causa do currículo. A confiança vem da estrutura: uma responsabilidade bem delimitada, trabalho que acontece onde a equipe pode ver e revisão antes que qualquer coisa seja entregue. Remova qualquer um desses elementos e até um colega brilhante se torna um risco. O mesmo vale para agentes de IA como membros da equipe. A pergunta nunca é “o modelo é inteligente o suficiente”. É “eu sei o que essa coisa pode tocar, consigo ver o que ela fez e alguma coisa é entregue sem que uma pessoa diga sim”.
O Sharkly responde a isso com configuração, não com promessas. Um Agente no Sharkly é uma configuração de trabalho salva, e não um prompt avulso: suas instruções, Runtime, Skills, repositórios, ambiente e configurações de execução definem como ele lida com o trabalho. Um prompt desaparece quando o terminal fecha. Uma configuração é inspecionável, compartilhável e estável em todas as execuções.
Se você quiser primeiro a visão geral da plataforma, comece por o que é o Sharkly e volte depois.
Resumo rápido
Um Agente no Sharkly é uma configuração de trabalho salva e reutilizável para um ator de IA: instruções de operação, uma vinculação de Computer e Runtime, Skills anexadas, repositórios Git, variáveis de ambiente e configurações de execução como concorrência, timeouts e modo de diretório de trabalho. Você confia nele do mesmo jeito que confia em um colega: pela estrutura, não pela fé. Seu escopo é explícito na configuração, seus estados de execução e trace são visíveis, e seus resultados retornam para a Tarefa, onde uma pessoa revisa e aceita. Agentes pesquisam, executam, testam e reportam. Pessoas definem a direção, concedem autoridade e aceitam o resultado.
O que um Agente é (e o que não é)
Um Agente é um ator de IA configurado para lidar com trabalho no Sharkly. Ele pode receber Tarefas atribuídas, escrever comentários, atualizar o estado da Tarefa pelo fluxo de trabalho disponível e produzir um trace de execução. Como a configuração é salva, uma equipe pode manter Agentes separados para alterações de código, revisão, testes, documentação ou triagem operacional sem reescrever as mesmas instruções para cada Tarefa.
Duas fronteiras importam desde o início.
Um Agente não é o host de execução. Seu trabalho roda por meio de um Runtime selecionado em um Computer conectado. O Agente define como o trabalho deve ser conduzido; o Computer fornece o host; o Runtime executa a sessão propriamente dita; a Tarefa continua sendo o registro compartilhado. Cada papel tem uma única função, e é por isso que um só Computer pode atender vários Agentes.
Um Agente não escolhe o próprio modelo. Ele segue o modelo padrão do Runtime, sem seletor de modelo nem controle de profundidade de raciocínio no Agente. Para usar outro modelo, altere-o na configuração de ferramentas do Runtime ou do Computer, por exemplo no próprio Claude Code ou no Codex.
A confiança é uma propriedade do sistema, não do modelo
Este é o argumento em que este artigo se apoia: um agente é confiável quando seu trabalho tem escopo definido, é visível e pode ser revisado. Não quando o modelo é impressionante.
Escopo definido significa que a autoridade do Agente está registrada antes de ele rodar: quais repositórios ele pode tocar, em qual Computer ele executa, o que suas instruções permitem, quantas Tarefas ele pode executar ao mesmo tempo e quanto tempo uma execução pode durar. Visível significa que estados de execução, eventos de trace e resultados retornam para a Tarefa, onde qualquer pessoa pode inspecioná-los, em vez de desaparecerem em um terminal privado. Revisável significa que uma pessoa fica no fim do ciclo: um Agente pode deixar uma Tarefa aguardando uma resposta humana ou aguardando revisão humana, e esses sinais chegam à Caixa de entrada da pessoa responsável.
Esse é o contrato humano-agente na prática. A automação para onde o julgamento da equipe é necessário. Se você ainda está avaliando o próprio fluxo de trabalho, nosso guia sobre codificação agêntica aborda a mudança de escrever prompts para atribuir trabalho.
A superfície de configuração do Agente
Um Agente pode incluir nome, descrição, avatar e responsável; instruções de operação; visibilidade e posicionamento em Espaços; uma conexão de Computer e um provedor de Runtime; Skills atribuídas; repositórios Git específicos do Agente; variáveis de ambiente comuns e secretas; argumentos adicionais de Runtime; configurações de Diretório de Trabalho da Tarefa; e um limite máximo de Tarefas em execução paralela, além de um timeout por Tarefa. Cada peça é uma alavanca de confiança.
As Instruções são incluídas em cada execução. Use-as para comportamentos que devem valer em todas as Tarefas: escopo e papel, como inspecionar uma Tarefa antes de agir, quando pedir intervenção humana, verificações esperadas e formato de relatório. A documentação traça uma distinção útil entre três coisas: requisitos específicos da Tarefa vão na descrição ou nos comentários da Tarefa, um procedimento reutilizável que vários Agentes podem compartilhar vai em uma Skill, e as instruções do próprio Agente carregam sua identidade estável. “Leia a descrição da Tarefa e os comentários recentes antes de editar. Mantenha as alterações limitadas ao comportamento solicitado. Rode as verificações relevantes mais próximas e reporte falhas sem escondê-las” pertence ao Agente, porque isso deve ser verdade na segunda-feira e continuar verdadeiro em março. A descrição atende a outro leitor: ela diz às Pessoas o que atribuir, enquanto as instruções dizem ao Agente como trabalhar.
A Visibilidade é Pessoal, disponível apenas para o responsável atual, ou Espaço, disponível para as Pessoas que conseguem acessar o Espaço do Agente. Ela também controla quem pode atribuir o Agente, iniciar um Agent Chat com ele ou acioná-lo por meio de um comentário ou menção. Comece como Pessoal enquanto ajusta; mude para Espaço quando a configuração valer a pena compartilhar. Essa promoção é o momento em que a prática de trabalho de um desenvolvedor se torna infraestrutura da equipe.
Computer e Runtime se combinam no alvo de execução. Um Computer estar online significa apenas que seu serviço local está enviando heartbeats; não significa que o Runtime selecionado consegue executar uma Tarefa. Se o Computer estiver offline, novas execuções normalmente esperam que ele se reconecte; se o Runtime selecionado não existir mais, escolha outro elegível. A história completa de configuração está em Computers no Sharkly.
As Skills empacotam instruções reutilizáveis e arquivos de apoio: regras de revisão, checklists de entrega, um processo da equipe. Skills de Runtime local continuam disponíveis automaticamente naquele Computer; Skills compartilhadas de Espaço precisam ser atribuídas explicitamente. Um alerta que vale repetir: evite vincular muitas Skills sobrepostas, porque instruções conflitantes tornam a execução menos previsível. Veja Skills no Sharkly para um mergulho mais profundo.
Os Repositórios são a alavanca de escopo mais limpa que você tem. Anexe-os ao Agente quando ele precisar de um escopo de código mais restrito do que o padrão do Espaço; sem vinculações, o Sharkly recorre aos repositórios configurados para o Espaço da Tarefa. Um Agente de documentação vinculado ao repositório de docs não tem caminho para o seu serviço de pagamentos.
Ambiente e configurações de execução limitam o que uma execução pode consumir. Variáveis de ambiente comuns e secretas, mais argumentos adicionais de Runtime, permitem que uma execução carregue configuração sem que ninguém cole credenciais em uma Tarefa. Nunca coloque tokens de repositório, chaves privadas ou tokens de instalação na descrição de uma Tarefa, em comentários, nas instruções de um Agente ou em uma Skill. As Configurações de Execução da Tarefa controlam Tarefas paralelas, duração máxima da execução e o modo de diretório de trabalho:
| Modo temporário | Modo especificado | |
|---|---|---|
| O que uma execução recebe | Um diretório isolado por Tarefa; execuções com repositório podem preparar um worktree novo | Um diretório local absoluto configurado, vindo do pool de diretórios do Agente |
| Concorrência | Execução paralela mais segura; o padrão é 50% do limite do Computer | Uma execução por diretório por vez; o padrão corresponde ao número de diretórios |
| Disponibilidade | Qualquer Computer conectado | Somente Computers locais |
| Ideal para | A maior parte do trabalho com repositórios, e sempre que várias Tarefas puderem modificar o mesmo código em paralelo | Repositórios muito grandes, caches locais caros ou Tarefas vinculadas a serviços locais |
Defina um valor de concorrência manual maior que o número de diretórios e o produto avisa que pode haver colisão de escritas. A mecânica de isolamento é o tema de como o Sharkly executa Agentes em paralelo sem conflitos de merge.
Conversas vs Tarefas: duas superfícies, uma regra
O Agent Chat é uma conversa independente para fazer uma pergunta, investigar um tema ou moldar um plano antes que algo precise de uma Tarefa rastreada. O Chat oferece três modos: Explore, para investigação somente leitura; Plan, para propostas que você revisa e confirma antes de o Sharkly criar a tarefa e as subtarefas planejadas; e Execute, para ação direta pela CLI configurada do Agente. Cada sessão pertence à pessoa que a criou.
Uma Tarefa é onde o trabalho vai quando precisa de responsável, status, histórico de execução ou revisão. O par de decisão: use o Chat para explorar, planejar ou agir antes que o trabalho precise de uma Tarefa rastreada; use a Tarefa quando o trabalho precisar de um Responsável, status, critérios de aceitação ou um registro durável.
Uma fronteira evita que as equipes percam contexto. Enviar uma mensagem no Agent Chat não cria um comentário na tarefa, e mensagens no chat de Agente de uma tarefa não aparecem em Atividade como comentários. Se a equipe precisa ver uma conclusão, copie-a para a descrição da tarefa ou para um comentário. A confiança depende do registro compartilhado, e o registro compartilhado é a Tarefa.
O que os estados de status dizem
A visibilidade aqui é um conjunto específico de estados que você consegue ler, não um slogan de dashboard.
Uma execução de Tarefa passa por enfileirada, despachada, aguardando diretório local, em execução, concluída, com falha e cancelada. Os estados de execução são separados do status do fluxo de trabalho da Tarefa: uma execução pode falhar enquanto a Tarefa permanece aberta para uma nova tentativa. O log de execução registra por que uma execução foi enfileirada, quando ela começou e terminou, chamadas de ferramentas e eventos do Runtime, a origem do acionamento e detalhes de falhas.
A disponibilidade do Agente é um terceiro sinal, separado. Um Agente online ainda pode ter trabalho enfileirado porque a concorrência ou a capacidade de diretórios está esgotada. E o Backlog funciona como área de estacionamento: uma Tarefa atribuída a um Agente espera enquanto está no Backlog, e movê-la para um status pronto para trabalho é o que inicia a execução. Atribuir um Agente nunca dispara trabalho de surpresa.
Seu primeiro Agente: um passo a passo em que você pode confiar
A forma mais rápida de construir confiança é o menor ciclo útil, segundo a documentação do Sharkly: conecte um Computer, crie um Agente e atribua uma Tarefa de baixo risco.
- Conecte um Computer. Abra Configurações, depois Computers, e escolha Conectar Computer. Espere até que ele apareça como conectado, com pelo menos um Runtime disponível.
- Crie o Agente com um papel restrito. Nome: Code Reader. Descrição: lê um repositório, explica a implementação atual e reporta riscos sem alterar arquivos. Visibilidade: Pessoal.
- Escreva instruções que reforcem o escopo: “Leia a Tarefa completa e os comentários relevantes antes de agir. Mantenha o escopo na solicitação. Na primeira Tarefa, não edite arquivos. Reporte o que você inspecionou, as evidências de cada conclusão e tudo o que permanecer incerto.”
- Vincule o código. Anexe um repositório Git ou configure um diretório local especificado que já o contenha. Skills podem esperar.
- Crie uma Tarefa pequena, só de texto: revise o caminho de erro de autenticação, identifique três casos de falha visíveis ao usuário, cite o arquivo relevante para cada um e não altere nada.
- Atribua e inicie, usando um status pronto para trabalho em vez de Backlog. Acompanhe o estado da execução passar de enfileirada para em execução e depois leia o resultado na Tarefa.
- Revise de verdade. Verifique se o Agente inspecionou o código pretendido, permaneceu dentro do limite de não editar, apresentou evidências e registrou incertezas em vez de adivinhar.
Esse último passo é o ponto central. Uma primeira Tarefa somente leitura permite que o Agente conquiste autoridade antes de ter alguma. Quando o ciclo funcionar, amplie o escopo de forma deliberada. A mecânica completa de atribuição está em como atribuir sua primeira Tarefa a um Agente de codificação com IA.
E se um Agente deixar de merecer essa confiança, a revogação é limpa. Arquivá-lo o remove de atribuições e menções e cancela seu trabalho em execução, enquanto suas Tarefas anteriores, comentários e histórico de execução permanecem disponíveis. Um colega que você pode desligar sem perder o registro do trabalho dele é um colega que você pode se permitir integrar.
Perguntas frequentes
O que exatamente é um Agente no Sharkly?
Um Agente é um ator de IA configurado para lidar com trabalho no Sharkly: uma configuração salva de instruções, uma vinculação de Computer e Runtime, Skills, repositórios, variáveis de ambiente e configurações de execução. Ele pode receber Tarefas atribuídas, escrever comentários, atualizar o estado da Tarefa e produzir um trace de execução. Como a configuração é salva, a prática de trabalho de uma pessoa se torna reutilizável quando o Agente é compartilhado com um Espaço.
Qual modelo um Agente do Sharkly usa?
O Agente segue o modelo padrão do Runtime selecionado, como Claude Code ou Codex, e não exibe nem promete um nome de modelo específico. Não há seletor de modelo nem controle de profundidade de raciocínio no Agente. Para trocar de modelo, atualize a configuração de ferramentas do Runtime ou do Computer.
Qual é a diferença entre conversar com um Agente e atribuir uma Tarefa a ele?
O Agent Chat é uma conversa independente para explorar, planejar ou agir antes que o trabalho precise de um registro rastreado. Uma Tarefa é a unidade compartilhada de trabalho, com Responsável, status, histórico de execução e revisão. Mensagens de chat não se tornam comentários de tarefa, então conclusões visíveis para a equipe devem ficar na Tarefa.
Como limitar o que um Agente pode fazer?
O escopo é definido na configuração: as instruções definem o papel e as regras de cautela, as vinculações de repositório limitam qual código o Agente vê, e as Configurações de Execução da Tarefa limitam Tarefas paralelas e a duração da execução. O modo de diretório de trabalho temporário adiciona isolamento ao dar a cada Tarefa seu próprio diretório. A aceitação final continua sendo de uma pessoa.
Por que minha Tarefa atribuída não inicia?
Verifique três coisas. Uma Tarefa no Backlog espera por definição; mova-a para um status pronto para trabalho. Um Computer online significa apenas que os heartbeats estão chegando, então confirme que o Runtime selecionado aparece como disponível. E um Agente online ainda pode enfileirar trabalho quando sua concorrência ou seus diretórios especificados estão cheios.
