Trabalhando com projetos

Um projeto divide um agente por assunto. Este capítulo é para o membro que percebeu que toda conversa com o seu agente compartilha os mesmos arquivos, as mesmas instruções e as mesmas anotações acumuladas, e quer um assunto mantido à parte do resto.

O que é um projeto

O seu agente tem um workspace: um diretório no host que guarda os arquivos dele, a memória dele e os transcripts de tudo que você já disse a ele. Um projeto é um segundo workspace ao lado do primeiro, do mesmo agente e do mesmo você, com uma cópia própria dos três.

No disco, o workspace de um projeto é workspace-<id>, irmão de workspace/ e nunca filho dele. Os dois harnesses o organizam do mesmo jeito, que é a razão inteira de o layout ter mudado para esta forma — Agentes, workspaces e projetos cobre o que há dentro.

O app enuncia a ideia em uma frase na tela de projetos: um projeto guarda arquivos, memória e instruções próprios, e herda o modelo, as skills e as credenciais deste agente.

Por que você criaria um

Porque “esta conversa é sobre a análise do ensaio de sementes, mantenha os arquivos e as instruções dela longe do meu outro trabalho” é, de outro modo, indizível. Tudo que você envia cai numa pilha só; toda anotação fixa que você escreve vale para tudo; e uma instrução que é certa para um assunto é ruído em toda outra conversa.

Um projeto responde às três de uma vez. O que ele não é: um jeito de dar acesso a outra pessoa. Um projeto pertence a uma tupla (tenant, subscription, agente, usuário), exatamente como o workspace ao lado do qual ele fica, e não há compartilhamento entre membros nem delegação entre projetos.

O que muda dentro de um projeto

A linha das tarefas agendadas tem uma ressalva de harness: só o ganglion realmente arquiva um agendamento dentro do projeto em que ele foi criado. O picoclaw mantém um único repositório de agendamentos por container, o que é uma limitação daquele harness e não uma decisão — veja Tarefas agendadas.

Duas outras linhas são as que as pessoas entendem errado.

O grafo de conhecimento não é por projeto. O painel de memória e o grafo de conhecimento são duas memórias diferentes com dois nomes diferentes. As anotações que você escreve no painel de memória pertencem ao projeto em que você está; o grafo que o agente constrói para si mesmo tem você como escopo e atravessa os seus projetos — um servidor de grafo só, alcançado com o projeto nomeado num cabeçalho, em vez de um grafo separado por projeto. Veja Skills e memória.

Os arquivos compartilhados por um administrador ficam no workspace principal. Arquivos e conteúdo que um operador publica para um tenant ou uma subscription descem só até o workspace do próprio agente; eles não são copiados para os workspaces de projeto. Já as skills compartilhadas, o modelo e as suas credenciais são herdados.

Um projeto também herda a identidade do seu agente, em vez de substituí-la. As instruções que você digita são somadas ao que o agente já sabe sobre si mesmo, e o app diz isso onde você as digita: “Diga o que é este projeto e como ele deve se comportar aqui.”

No harness ganglion a separação é imposta pelo kernel, não por convenção: um turno dentro de um projeto roda com o confinamento de sistema de arquivos enraizado no diretório daquele projeto, então a ferramenta de shell não alcança o workspace principal nem nenhum outro projeto. Foi isso que o layout de irmãos comprou — um projeto dentro do workspace principal nunca poderia ter passado de uma convenção.

Criando um

Abra Projetos na barra lateral. Diferente dos outros cinco destinos, este substitui o que está no centro da tela em vez de abrir um painel ao lado — um projeto é um lugar em que você entra, não um painel que você consulta.

Aperte Novo projeto e preencha dois campos:

• Nome — por exemplo, “Ensaio de sementes 2026”. O identificador é derivado do nome pelo orquestrador; você nunca digita um.
• Instruções — opcional, e a coisa em que vale gastar um minuto. O texto de exemplo é um bom modelo: “Sempre cite o protocolo do ensaio e responda começando pelo número da parcela.”

Salvar cria o workspace. A tela então conta a você a única consequência que, de outro modo, você descobriria como uma primeira resposta lenta: o agente reinicia na sua próxima mensagem. Um projeto muda o que o container do agente tem montado, então o container é reconstruído antes do próximo turno.

Cada projeto é um cartão nessa tela, mostrando o nome, as instruções e a data em que foi criado. O projeto em que você está agora é marcado como Atual, em vez de ser escondido ou movido para a frente — pedir para ver a lista não é a mesma coisa que sair de onde você está.

Trabalhando dentro de um

Entrar num projeto muda o escopo de quase tudo na tela. O caminho no topo o nomeia. A lista de conversas mostra “Conversas deste projeto” em vez de “Conversas gerais”. A tela inicial diz “Pergunte qualquer coisa neste projeto para começar” em vez de nomear o agente. Os painéis Arquivos, memória e Tarefas agendadas se dirigem todos ao workspace do projeto, não ao do agente.

Uma regra pega as pessoas de surpresa: uma conversa permanece no projeto em que começou. O seletor de projeto é oferecido quando você começa uma conversa e travado depois disso, porque o transcript de uma conversa vive fisicamente no workspace daquele projeto. O app diz isso com todas as letras — “Uma conversa permanece no projeto em que começou.”

Para mover trabalho entre projetos, passe o arquivo você mesmo pelo painel Arquivos. O agente não consegue copiá-lo de um para o outro; de dentro de um projeto, o outro não está lá.

Editando e excluindo

O lápis num cartão edita o nome e as instruções. Só o que você mudou é enviado, então renomear um projeto não apaga as instruções dele.

Excluir é a ação destrutiva, e a confirmação diz exatamente o que vai embora: “Os arquivos, a memória e todas as conversas dele são removidos. Não dá para desfazer.” Como criar, também reinicia o agente na sua próxima mensagem.

Excluir um projeto não exclui as tarefas agendadas que foram arquivadas nele. Elas continuam disparando, e o orquestrador de propósito volta a mostrá-las na lista de tarefas do próprio agente depois disso — uma tarefa que você não vê é uma tarefa que você não consegue parar. Exclua as tarefas de um projeto antes de excluir o projeto. Veja Tarefas agendadas.

Quais agentes têm projetos

Os dois harnesses que este livro cobre servem projetos: o picoclaw os constrói com a própria maquinaria de agentes e despacho, e o ganglion toma o projeto como um cabeçalho da requisição e trabalha a partir do workspace irmão correspondente. Veja Harnesses para o que é um harness e como um deles é escolhido.

O que não os tem é um orquestrador mais antigo que o recurso. Diante de um desses, o app web informa que o agente não suporta projetos, e tanto a linha da barra lateral quanto a tela são omitidas por completo, em vez de mostradas e mortas.

Para onde ir agora

Tarefas agendadas é a única superfície com escopo de projeto que tem uma restrição própria. Agentes, workspaces e projetos descreve como o workspace de um projeto aparece no disco, e Skills e memória explica as duas memórias que um projeto separa e não separa.