Transformando tarefas pontuais de agentes em workflows reutilizáveis

Para tornar reutilizável uma tarefa de várias etapas executada por um agente de IA, salve as etapas como definições de modelo tipadas e um arquivo de workflow declarativo no seu repositório. Assim, a próxima sessão executa o processo salvo em vez de reconstruí-lo a partir de um prompt.

Você provavelmente já passou por isto: um agente faz uma verificação de release impecável (testes, build, smoke test, tudo na ordem certa), a sessão é encerrada e o processo vai embora junto com ela. No dia seguinte, você descreve tudo de novo e recebe uma versão ligeiramente diferente.

Este artigo mostra como preservar esse processo com o Swamp. Ele aborda o que se torna reutilizável e o que não se torna, apresenta um pequeno workflow de verificação de release e explica como o mesmo workflow roda no Claude Code, Cursor, OpenCode ou Codex.

Por que uma boa execução do agente desaparece

Uma sessão de agente mantém seu processo de trabalho apenas no contexto da conversa, então o processo termina quando a sessão termina. Os comandos executados, a ordem escolhida e as verificações adicionadas não ficam salvos em nenhum lugar que a próxima sessão possa executar. O que sobra é a transcrição do chat e os arquivos que porventura foram alterados.

A solução é transformar o processo do agente em arquivos no repositório que são de fato executados. Quando as etapas passam a viver no repositório, você para de reexplicar a tarefa a cada sessão, e o tempo do agente vai para as mudanças em vez de ser gasto reconstruindo o procedimento.

Workflows reutilizáveis de agentes de IA com o Swamp: o que persiste e o que não persiste

O Swamp é uma ferramenta de linha de comando que armazena a automação funcional de um agente como modelos tipados, definições em YAML, workflows, dados versionados e referências a vaults em um diretório .swamp/ dentro de um repositório Git. O README do Swamp cita seis conceitos centrais: modelos, que descrevem sistemas externos como tipos; definições, que são arquivos YAML que configuram um uso específico de um tipo de modelo; workflows; dados; vaults; e tags.

O Swamp torna o processo repetível, não o raciocínio. Depois que as etapas de um agente são salvas como definições de modelo e um arquivo de workflow, as execuções seguintes rodam essas etapas salvas. No entanto, quando o agente cria ou edita esses arquivos, o resultado pode variar de uma sessão para outra.

O Swamp e o MCP têm funções diferentes. O MCP conecta um agente a ferramentas, como explica o guia do desenvolvedor para o ecossistema MCP. O Swamp armazena e executa a automação que o agente constrói com essas ferramentas, e é possível usar os dois em conjunto. O Swamp roda na sua própria máquina, e as credenciais que ele usa vêm do ambiente do shell que o inicia.

Configurando o Swamp para o seu harness

Instale o binário com o script oficial e, em seguida, inicialize o repositório para o seu harness. O script de instalação oficial suporta macOS e Linux, e também são publicados binários de release para Windows.

curl -fsSL https://swamp-club.com/install.sh | sh

swamp repo init                    # Claude Code (default)
swamp repo init --tool cursor      # or: opencode, codex

O Claude Code lê as skills do Swamp em .claude/skills/ e as instruções em CLAUDE.md. O Cursor usa .cursor/skills/ e .cursor/rules/swamp.mdc. O OpenCode e o Codex usam ambos .agents/skills/ e AGENTS.md.

O Swamp traz as skills embutidas no próprio binário e as grava no disco quando você executa o init, e é assim que o agente as encontra sem nenhuma configuração extra. Autocompletar para o shell está disponível via swamp completions <shell>.

Um workflow de verificação de release, de ponta a ponta

Um workflow do Swamp é um arquivo YAML que organiza jobs como um DAG, e cada etapa chama um método em uma definição de modelo. Como explica How Swamp Works, cada job aguarda os jobs dos quais depende, e etapas no mesmo job rodam lado a lado, a menos que uma dependa de outra.

Normalmente, você pediria ao agente para criar as definições run-tests, build-artifact e smoke-test. Mesmo assim, leia o workflow resultante, porque é esse o arquivo que você está aprovando. A estrutura abaixo segue a referência de workflows. Os placeholders <method> foram mantidos de propósito: substitua-os pelos nomes de métodos que suas definições realmente expõem.

id: <keep the generated id>
name: release-check
tags:
  purpose: release
jobs:
  - name: checks
    description: Run tests and build in parallel
    steps:
      - name: tests
        task:
          type: model_method
          modelIdOrName: run-tests
          methodName: <method>
      - name: build
        task:
          type: model_method
          modelIdOrName: build-artifact
          methodName: <method>
  - name: smoke
    dependsOn:
      - job: checks
        condition:
          type: succeeded
    steps:
      - name: smoke
        task:
          type: model_method
          modelIdOrName: smoke-test
          methodName: <method>
version: 1

No workflow release-check, os testes e o build rodam ao mesmo tempo. condition.type: succeeded segura o job de smoke até que ambos passem. Valide o arquivo com swamp workflow validate release-check e, em seguida, execute-o:

swamp workflow run release-check
swamp workflow run release-check --tag env=staging
swamp data query 'attributes.ok == false'   # example query from the Swamp manual

swamp workflow run aguarda até que a execução termine (com sucesso, falha ou cancelamento) ou pause em um gate manual_approval. Uma execução bem-sucedida retorna código de saída 0 e qualquer outro desfecho retorna um código diferente de zero, então o CI pode usar isso como gate. A flag --tag sobrescreve tags em tempo de execução. Cada execução salva suas saídas como dados versionados que não podem ser alterados depois, e você pode encontrá-los novamente por tag, de modo que uma sessão posterior consegue ler o que aconteceu em vez de reconstruir tudo a partir do histórico do chat. A expressão do data query vem do exemplo em How Swamp Works e precisa ser adaptada aos campos do seu modelo.

Uma etapa de smoke aprovada só prova que o endpoint respondeu. Ela não prova que a página foi renderizada nem que os usuários conseguiram concluir um fluxo. Reproduzir sessões no build de staging é a forma de tornar visíveis regressões de front-end desse tipo.

Levando o mesmo workflow entre harnesses

Quando uma equipe leva um workflow do Swamp de um harness para outro, o que ela compartilha são os arquivos de modelos, definições e workflows. O diretório de skills de cada harness fica no .gitignore e é gravado pelo próprio Swamp, e swamp repo upgrade --tool <name> permite que um desenvolvedor troque de harness ou use vários lado a lado. O README observa que cada ferramenta recebe sua própria pasta de skills, mantida fora do Git.

Suponha que o repositório tenha sido inicializado para o Claude Code e que um colega use o Cursor. O harness do agente muda, mas o arquivo de workflow continua o mesmo:

# same checkout, teammate on Cursor
swamp repo upgrade --tool cursor
swamp workflow run release-check

swamp workflow run não depende de qual agente o invocou. O papel do agente é escrever e editar definições, e essa parte muda conforme o harness. O OpenCode e o Codex compartilham .agents/skills/ e AGENTS.md, então as duas ferramentas leem as skills do mesmo local.

Por padrão, o Swamp mantém os dados de execução, como dados de modelos, execuções de workflows, saídas e logs de auditoria, em .swamp/. Equipes que precisam do mesmo estado em várias máquinas podem trocar para outro backend de datastore, como um caminho em sistema de arquivos compartilhado ou o S3. O checkout também vai com você: em uma máquina remota configurada para codificação agêntica, o mesmo workflow roda, desde que aquele shell tenha as credenciais de que os modelos precisam. Use --repo-dir ou SWAMP_REPO_DIR para apontar o Swamp para um repositório fora do diretório atual.

Maturidade e limitações do Swamp

O Swamp é uma ferramenta em estágio inicial. Ele é mantido ativamente nos repositórios swamp-club e publica releases contínuas identificadas por data. Esteja preparado para mudanças.

• Contribuições fechadas. Apenas a equipe do Elder Swamp Club escreve código para o Swamp. Pull requests vindos de forks são fechados automaticamente, então bugs e ideias de funcionalidades devem ser enviados via swamp issue bug ou swamp issue feature, e os mantenedores implementam os que aceitarem.
• Telemetria. O Swamp coleta telemetria de uso, a menos que você a desative. É possível desativá-la para um único comando com --no-telemetry, para um shell com SWAMP_NO_TELEMETRY=1, para um repositório com telemetryDisabled: true no .swamp.yaml, ou para todas as execuções na sua máquina com swamp config set telemetry.collection disabled, que grava a configuração em ~/.config/swamp/telemetry.yaml.
• Escopo. Um script de uma linha ou um cron job não precisa de modelos, DAG e dados versionados. O Swamp compensa quando uma tarefa envolve vários sistemas, precisa de histórico ou é compartilhada por uma equipe.
• Extensões executam código. Revise extensões de terceiros antes de confiar nelas.
• Licença. AGPL-3.0 com a Swamp Extension and Definition Exception.

Um executor determinístico repete um workflow ruim com a mesma fidelidade com que repete um bom. Asserções e revisão humana continuam sendo necessárias.

Conclusão

O Swamp preserva o procedimento, não o raciocínio do agente. Definições e workflows salvos garantem as mesmas etapas e os mesmos gates em todas as execuções, e o agente continua livre (e variável) sempre que os escreve ou altera. Um bom próximo passo é escolher um processo que seu agente já executa bem, como uma verificação de release ou uma rodada de revisão, e pedir a ele que salve esse processo como um workflow do Swamp. Revise o YAML, faça o commit e execute-o a partir de um segundo harness para confirmar que ele também funciona lá.

Perguntas frequentes

Como executo um workflow do Swamp no CI do GitHub Actions?

Use swamp-club/setup-swamp, a GitHub Action oficial. Ela instala o Swamp com o script de instalação oficial e também pode fazer login no swamp.club se você informar um input api-key. Defina repo-init como true para executar swamp repo init após a instalação. Uma etapa posterior chama swamp workflow run com o nome do workflow. Se a execução falhar, o comando retorna um código de saída diferente de zero e o job falha. A action ainda está em uma release inicial v0.1.

Onde devo armazenar os segredos de um workflow do Swamp?

Coloque-os em um vault do Swamp e faça referência a eles pelo nome nas definições e nos workflows. O Swamp busca o valor real no momento em que uma etapa é executada. Isso mantém o segredo fora dos seus arquivos YAML e dos seus dados em .swamp, e nada é guardado para a próxima execução. O provedor de criptografia local embutido não exige configuração adicional. Outros provedores de vault armazenam segredos em serviços externos, como AWS Secrets Manager, Azure Key Vault ou 1Password.

Um workflow do Swamp precisa de um agente de IA para ser executado?

Não. swamp workflow run é um comando de CLI comum, então um desenvolvedor, um job de CI ou um script pode executar um workflow salvo sem nenhum agente. Você só precisa do agente para criar ou editar modelos, definições e workflows. Para execuções que ninguém inicia manualmente, o swamp serve pode executar um workflow a partir de um gatilho cron. Ele também pode executar um workflow quando chega um webhook assinado do GitHub, Jira, Linear, Stripe, Slack ou de um endpoint genérico.

O Swamp pode ser instalado no Windows?

Sim. As releases do Swamp na página de releases do GitHub swamp-club/swamp incluem um arquivo swamp-windows-x86_64.zip que contém o swamp.exe, junto com os builds para macOS e Linux. O comando curl de uma linha envia o script de instalação para o sh, então ele não funciona no Windows. Usuários de Windows baixam o arquivo da release, extraem o swamp.exe e o colocam em um diretório que esteja no PATH.