Este passo a passo leva você de uma instalação nova do AWR até um handoff de sessão verificado: instale a CLI, inicialize um projeto, inicie uma sessão de trabalho e prove que uma sessão sucessora consegue continuar de onde a primeira parou. Tudo pode ser copiado e colado; o AWR traz o seu próprio SQLite embutido.
1. Instale o AWR
O AWR é distribuído como pacotes nativos no npm e no PyPI. Os dois canais instalam a mesma CLI em Rust (awr) e o mesmo servidor MCP (awr-mcp); não existe um SDK separado em JavaScript ou Python.
Com npm (requer Node 22.14 ou mais recente):
npm install -g @originoneai/agent-work-runtime@0.5.1
Ou com pip, dentro de um ambiente virtual (requer Python 3.9 ou mais recente):
python -m pip install agent-work-runtime==0.5.1
Verifique os dois executáveis:
awr --version
awr-mcp --version
As plataformas suportadas são macOS 15+ (arm64 e Intel x64), Linux x64 e arm64 com glibc 2.39 ou mais recente (a base do Ubuntu 24.04) e Windows x64. No Linux, verifique primeiro a sua glibc:
ldd --version | head -n 1
Em instalações via npm, mantenha as dependências opcionais habilitadas — o launcher resolve um pacote nativo por plataforma. Não há script de instalação nem downloader de rede; os wheels do pip embutem os binários. Existe um terceiro canal para autores de aplicações: um payload nativo fixado dos dois binários que um app host pode embutir, de modo que seus usuários não precisem de Node, Python ou Rust em tempo de execução.
2. Inicialize o seu projeto
A inicialização é uma operação em dois passos: uma prévia e depois um aceite explícito. Nada é escrito até você passar --accept.
AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init
Leia a prévia: ela mostra o inventário que o AWR encontrou — ledgers de tarefas em Markdown existentes, fontes YAML, objetivos — e o mapeamento de fontes que ele propõe. Arquivos existentes nunca são sobrescritos; seus documentos originais continuam sendo a autoridade. Se a prévia estiver correta, aceite-a:
awr --project "$AWR_PROJECT" init --accept
Para um projeto em branco, declare o propósito dele logo de início:
awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept
Se o seu ledger em Markdown usa palavras de status fora do padrão, mapeie-as no momento do init:
awr --project "$AWR_PROJECT" init \
--status-map pending=planned --status-map complete=completed --accept
Depois inspecione o relatório de organização:
awr --project "$AWR_PROJECT" intake inspect --json
O organization.state do relatório diz onde você está: ready significa que pelo menos uma tarefa tem um objetivo declarado na fonte, critérios de aceitação, uma próxima ação e pré-requisitos resolvidos. needs_organization significa que algo está faltando — as actions ordenadas do relatório dizem o que adicionar aos seus arquivos-fonte.
3. Inicie uma sessão de trabalho
Uma sessão é a unidade de posse de trabalho do AWR. Estes comandos usam um pequeno auxiliar de shell para que cada chamada carregue o caminho do projeto e saída em JSON:
AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001 # a task key from your intake report
AWR_AGENT=agent-primary # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }
Verifique o que está executável e então inicie uma sessão com um claim (posse de runtime do item de trabalho) e a revisão atual do projeto:
awrj ready
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
--provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
--expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")
Compile o contexto de trabalho — o objetivo, os critérios de aceitação, os fatos registrados e o histórico reunidos em um pacote delimitado:
awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
--budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"
Leia o pacote, não apenas o booleano. Em caso de BudgetExceeded, amplie o --budget; em caso de SourceStale, rode awrj source reindex e compile de novo.
4. Registre o progresso com um checkpoint
Antes de se afastar — ou antes que uma conversa longa do host seja compactada — salve um checkpoint com o hash de contexto que você realmente usou, um resumo honesto, a próxima ação exata e todos os pontos em aberto:
AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
--context-hash "$AWR_CONTEXT_HASH" \
--digest "Record the work actually done; do not invent a passing review." \
--next-action "State the exact next operator or agent action." \
--open-loop "List every unresolved loop." \
--expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"
Um checkpoint pode registrar trabalho inacabado; ele não é prova de testes passando nem de critérios de aceitação cumpridos.
5. Continue o trabalho em uma nova sessão
Para provar que a continuação funciona, encerre a primeira sessão e retome a partir dela — o mesmo caminho de takeover que um novo agente, máquina ou conversa de host usaria. Encerrar libera o claim; não marca o trabalho da fonte como concluído:
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
--expected-revision "$AWR_REV"
Agora retome. Qualquer agente — um diferente, ou o mesmo mais tarde — cria uma sessão sucessora a partir da predecessora:
AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
--agent successor --provider generic --model "$AWR_MODEL" \
--budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")
Duas verificações confirmam que o handoff funcionou:
jq -e '.context_ready'sai com código 0: o sucessor recebeu o contexto registrado da predecessora, incluindo o último checkpoint bem-sucedido.- A sessão retomada tem um novo ID — o resume cria uma nova sessão AWR em vez de modificar a antiga.
Você também pode inspecionar o estado de recuperação em modo somente leitura a qualquer momento:
awrj recovery inspect --session "$AWR_SESSION"
Trabalhando dentro do chat de um agente de codificação? Vincule a conversa do host à sessão AWR para que os checkpoints sobrevivam à compactação do host:
awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
--work "$AWR_WORK" --session "$AWR_SESSION"
O AWR não transfere a memória de processo de um host nem assume processos existentes arbitrários — a continuidade vem do que foi explicitamente registrado.
Para onde ir a seguir
- Conceitos — o que sessões, claims e checkpoints significam.
- Referência da CLI — toda a superfície de comandos usada acima.
- Fluxo de trabalho diário — este ciclo no trabalho do dia a dia.
- Solução de problemas — quando algo reporta algo inesperado.