Building Planning Systems

Quando construí pela primeira vez a camada de orquestração de tarefas do meu framework de orquestração Python, fiz o que parecia natural: passei cada etapa ao modelo com contexto suficiente apenas para aquela etapa fazer sentido por si só. A etapa 1 pesquisaria o problema. A etapa 2 elaboraria uma solução. A etapa 3 escreveria o relatório final.

O modelo era capaz. Cada etapa produzia saída razoável. Mas o relatório final contradizia o esboço, que contradizia a pesquisa. As três etapas estavam navegando por estimativa — cada uma partindo de um mapa interno diferente da tarefa.

A correção não foi um modelo mais inteligente ou um prompt mais elaborado. Foi um plano compartilhado.

Pense em um plano como um mapa compartilhado antes de um grupo de caminhantes partir. Todos estudam a mesma rota, os mesmos pontos de verificação e as mesmas anotações sobre o terreno. Sem o mapa, três caminhantes tomam três caminhos diferentes e acabam em três cumes diferentes. Com ele, cada caminhante constrói sobre o que o anterior explorou. Um plano é um mapa compartilhado — sem ele, cada etapa navega por estimativa.

No agente de orquestração de tarefas que rodo no meu Mac Mini para trabalho com clientes, toda tarefa agora começa com uma chamada de planejamento: o modelo lê a especificação da tarefa e retorna uma lista numerada de etapas. Essa lista vai para um dicionário de contexto compartilhado. Cada etapa subsequente o lê. O problema de contradição desapareceu completamente.

A chamada de planejamento é simples. Peço ao modelo que divida uma tarefa em etapas numeradas e retorne cada etapa em sua própria linha. Esse é o sistema de planejamento completo.

Aqui está o primeiro bloco executável — copie-o, defina ANTHROPIC_API_KEY e execute:

Executar isso retorna algo como:

O modelo raciocina sobre a tarefa e produz um plano sequenciado. Esse é o sistema de planejamento. Sem fórmulas STRIPS. Sem busca A*. Sem redes hierárquicas de tarefas. Apenas um modelo, um prompt claro e uma lista numerada de etapas.

O plano chega como texto livre. O próximo passo é analisá-lo em uma lista Python para que cada etapa seja endereçável por índice, depois armazenar tudo em um dicionário de contexto que viaja com a tarefa por toda a sua vida útil.

Uma vez analisadas, as etapas vão para um dicionário de contexto junto com tudo mais que a tarefa precisa:

Este dicionário é a única fonte de verdade para toda a execução da tarefa. Cada etapa lê dele antes de agir e escreve seu registro de conclusão de volta nele depois. Nenhuma etapa jamais parte de uma lousa em branco.

Ponto de Verificação do Módulo

Antes de continuar, considere: o que aconteceria se você pulasse o contexto compartilhado e passasse apenas a descrição da etapa atual ao modelo em cada chamada?

O modelo produziria saída que é localmente razoável, mas globalmente incoerente. A etapa 3 pode desfazer o que a etapa 2 configurou porque a etapa 3 nunca a viu. Este é exatamente o modo de falha descrito no início — cada etapa navegando por estimativa a partir de seu próprio mapa interno.

O dicionário de contexto é o que torna o plano um mapa compartilhado, não apenas uma lista de sugestões que cada etapa pode silenciosamente ignorar.

Cada etapa recebe o contexto completo: a tarefa original, o plano ordenado e um resumo de cada etapa que já foi concluída. O modelo não pode acidentalmente desfazer trabalho anterior porque sempre vê o que foi realizado.

Após cada etapa, registre sua conclusão antes de avançar:

O loop de planejamento completo reúne todas essas peças:

Este é o sistema de planejamento completo que rodo no harness do SDLC no meu Mac Mini. Não é STRIPS. Não é A*. É um modelo que gera um plano, um analisador que o estrutura e um loop que executa etapas sequencialmente enquanto mantém cada etapa informada sobre as anteriores.

Prompt Reflexivo

O que aconteceria se você executasse essas etapas em paralelo em vez de sequencialmente?

A etapa 3 — "Aplicar o manifesto Kubernetes atualizado" — depende da etapa 2 ter construído e enviado a imagem Docker. Executar ambas ao mesmo tempo significaria que a etapa 3 aplica um manifesto que aponta para uma imagem que ainda não existe. A implantação falharia.

Esta é a razão mais profunda pela qual o sistema de planejamento e o modelo de execução linear andam juntos. O plano estabelece dependências implicitamente por meio da ordenação. O loop sequencial respeita essas dependências automaticamente. Paralelizar as etapas exigiria que você modelasse explicitamente cada dependência entre elas — o que é o caminho de volta para STRIPS e A*, a complexidade que essa abordagem é projetada para evitar.

O loop de planejamento aqui ainda pede ao modelo que descreva o que faria em cada etapa. No próximo módulo, estendo esse padrão para uma camada de orquestração de ferramentas adequada: em vez de pedir ao modelo que narre uma etapa, dou a ele um pequeno conjunto de ferramentas verificadas — ler arquivo, escrever arquivo, executar comando — e o deixo escolher a correta. O sistema de planejamento que você construiu aqui torna-se a entrada para essa camada de orquestração.

O planejamento e as camadas de ferramentas juntos formam a espinha dorsal do agente de orquestração de tarefas. O módulo 06 então explica por que manter esse agente linear e de thread único — em vez de dividi-lo em sub-agentes paralelos — é o que o torna confiável em produção.