Projetando fluxos de trabalho de agentes: de conversas avulsas à automação de várias etapas · Lição 4 de 6

Lição 4: Gerenciamento de estado e passagem de contexto

Objetivos de aprendizado:

Distinguir o estado do fluxo de trabalho do contexto do agente

Dominar três padrões de gerenciamento de estado

Entender checkpoint e recuperação

Pré-requisitos: Lição 3: Decompondo uma tarefa complexa em um fluxo de trabalho | Próxima: Lição 5 >>

Por que o gerenciamento de estado é o coração de um fluxo de trabalho

Você projeta um fluxo de trabalho perfeito: 10 passos, dependências limpas. No passo 8, o servidor reinicia. O fluxo de trabalho quebra.

Rodar tudo de novo? Aí o trabalho dos 7 primeiros passos — talvez 30 minutos dele — vai para o lixo.

Esse é o preço de não ter gerenciamento de estado.

O gerenciamento de estado resolve três problemas:¹

Passagem de dados entre passos: como o passo 3 recebe os resultados dos passos 1 e 2?
Acompanhamento do progresso: quanto o fluxo de trabalho já avançou? Quanto falta?
Recuperação de falhas: depois de uma queda, retomar de onde parou em vez de começar do zero.

Sem gerenciamento de estado, um agente só consegue passar informação pelo histórico da conversa. O histórico da conversa transborda, se perde e é esquecido pelo agente.

Com gerenciamento de estado, o fluxo de trabalho tem uma “memória” clara: persistente, consultável, recuperável.²

Estado vs. contexto vs. memória

Essas três palavras são fáceis de confundir, então vamos fixá-las primeiro:¹

Estado

Todas as informações sobre a tarefa atual: em que passo você está, o resultado de cada passo, o que fazer em seguida
É um instantâneo: tudo o que o fluxo de trabalho sabe neste momento
Armazenado em: variáveis de script, um banco de dados, arquivos

Contexto

A informação passada para uma única chamada de agente
É entrada: o que este agente precisa saber para fazer seu trabalho
Extraído seletivamente do estado: nem todo o estado vai para o agente, apenas a parte relevante

Memória

Lições aprendidas no passado: o que já foi feito, que problemas apareceram, quais foram as soluções
É histórico: conhecimento de longo prazo que atravessa tarefas e sessões
Fora do escopo desta lição (memória de longo prazo é um tema difícil por si só)

Um exemplo:

JAVASCRIPT

// Estado: tudo o que o fluxo de trabalho sabe
const workflowState = {
  phase: 'testing',
  filesProcessed: 47,
  totalFiles: 100,
  issues: [/* todos os problemas encontrados nos passos anteriores */],
  currentBatch: [/* arquivos sendo processados neste momento */]
};

// Contexto: as informações para este agente (extraídas do estado)
const agentContext = {
  file: workflowState.currentBatch[0],
  previousIssues: workflowState.issues.filter(i => i.severity === 'high')
};

// Chamada do agente
const result = await agent({
  task: 'testar arquivo',
  context: agentContext  // apenas a informação relevante, não o estado inteiro
});

// Atualiza o estado
workflowState.filesProcessed++;
workflowState.issues.push(...result.newIssues);

O princípio central: o estado é global, o contexto é local.³

Padrão de estado 1: variáveis de script (estado em memória)

Quando usar: fluxos de trabalho curtos (< 10 minutos) que não precisam atravessar processos ou máquinas.

Vantagem: simples, rápido, sem dependências externas.

Desvantagem: o estado se perde quando o processo quebra, sem forma de recuperar.

Padrão básico

JAVASCRIPT

async function simpleWorkflow(files) {
  // O estado são apenas variáveis JavaScript comuns
  let processed = 0;
  let results = [];
  let errors = [];
  
  for (const file of files) {
    try {
      const result = await processFile(file);
      results.push(result);
      processed++;
      console.log(`Progresso: ${processed}/${files.length}`);
    } catch (error) {
      errors.push({ file, error });
    }
  }
  
  return { results, errors, total: files.length };
}

Onde o estado vive? Nas variáveis locais da função (processed, results, errors).

E se o processo quebrar? Todo o estado se perde, e você recomeça do início.

Melhor: um objeto de estado estruturado

JAVASCRIPT

async function betterWorkflow(files) {
  // Organize o estado em um objeto — fica mais claro
  const state = {
    input: { files, total: files.length },
    progress: { current: 0, phase: 'processing' },
    output: { results: [], errors: [] },
    metadata: { startTime: Date.now() }
  };
  
  for (const file of state.input.files) {
    try {
      const result = await processFile(file);
      state.output.results.push(result);
      state.progress.current++;
    } catch (error) {
      state.output.errors.push({ file, error });
    }
  }
  
  state.progress.phase = 'completed';
  state.metadata.endTime = Date.now();
  state.metadata.duration = state.metadata.endTime - state.metadata.startTime;
  
  return state;
}

Por que isso ajuda: o estado tem uma estrutura clara, é fácil de passar para outras funções e é fácil de serializar (caso você precise persistir).

Padrão de estado 2: checkpoint

Quando usar: fluxos de trabalho de duração média (10-60 minutos) em que você precisa salvar o progresso depois de operações caras.

Vantagem: depois de uma queda, você pode retomar do checkpoint mais recente e evitar refazer trabalho.

Desvantagem: você precisa projetar os locais dos checkpoints e a lógica de recuperação.¹

Escolhendo os locais dos checkpoints

JAVASCRIPT

async function workflowWithCheckpoints(tasks) {
  const checkpointFile = '.workflow-state.json';
  
  // Tenta restaurar o estado anterior
  let state = await loadCheckpoint(checkpointFile) || {
    completed: [],
    pending: tasks,
    phase: 'processing'
  };
  
  console.log(`Retomando: ${state.completed.length}/${tasks.length} concluídas`);
  
  while (state.pending.length > 0) {
    const task = state.pending.shift();
    
    // Executa a tarefa
    const result = await executeTask(task);
    state.completed.push({ task, result });
    
    // Checkpoint: salva a cada 10 tarefas
    if (state.completed.length % 10 === 0) {
      await saveCheckpoint(checkpointFile, state);
      console.log(`Checkpoint: ${state.completed.length} tarefas concluídas`);
    }
  }
  
  state.phase = 'completed';
  await saveCheckpoint(checkpointFile, state);
  
  return state;
}

async function saveCheckpoint(file, state) {
  await fs.writeFile(file, JSON.stringify(state, null, 2));
}

async function loadCheckpoint(file) {
  try {
    const data = await fs.readFile(file, 'utf-8');
    return JSON.parse(data);
  } catch {
    return null;  // o arquivo não existe, começa do zero
  }
}

Estratégias de checkpoint:

Checkpoints periódicos: salvar a cada N tarefas ou a cada M minutos
Checkpoints por fase: salvar depois que cada fase importante termina (por exemplo, “fase de análise concluída”)
Antes de operações críticas: salvar antes de uma operação irreversível (por exemplo, um deploy, uma exclusão)

Padrão de estado 3: armazenamento externo (estado persistente)

Quando usar: fluxos de trabalho de longa duração (> 1 hora), trabalho que precisa se coordenar entre máquinas ou trabalho que precisa de aprovação humana.

Vantagem: o estado é persistente; a queda de um processo ou o reinício de uma máquina não importam, e pausar/retomar é suportado.

Desvantagem: exige uma dependência externa (um banco de dados, Redis) e acrescenta complexidade.⁴

Implementação básica

JAVASCRIPT

// Interface do repositório de estado
class WorkflowStateStore {
  constructor(db) {
    this.db = db;
  }
  
  async save(workflowId, state) {
    await this.db.set(`workflow:${workflowId}`, JSON.stringify(state));
  }
  
  async load(workflowId) {
    const data = await this.db.get(`workflow:${workflowId}`);
    return data ? JSON.parse(data) : null;
  }
  
  async delete(workflowId) {
    await this.db.del(`workflow:${workflowId}`);
  }
}

// Um fluxo de trabalho apoiado em armazenamento externo
async function persistentWorkflow(workflowId, tasks) {
  const store = new WorkflowStateStore(redis);
  
  // Carrega o estado (se existir)
  let state = await store.load(workflowId) || {
    id: workflowId,
    phase: 'init',
    completed: [],
    pending: tasks,
    createdAt: Date.now(),
    updatedAt: Date.now()
  };
  
  console.log(`Fluxo de trabalho ${workflowId}: fase ${state.phase}, 
               progresso ${state.completed.length}/${tasks.length}`);
  
  // Fase 1: processa as tarefas
  if (state.phase === 'init' || state.phase === 'processing') {
    state.phase = 'processing';
    
    while (state.pending.length > 0) {
      const task = state.pending.shift();
      const result = await executeTask(task);
      state.completed.push({ task, result });
      state.updatedAt = Date.now();
      
      // Salva o estado depois de cada tarefa
      await store.save(workflowId, state);
    }
    
    state.phase = 'awaiting_approval';
    await store.save(workflowId, state);
  }
  
  // Fase 2: espera a aprovação humana (pode retomar em outro processo/máquina)
  if (state.phase === 'awaiting_approval') {
    console.log('Aguardando aprovação...');
    // Podemos retornar aqui e deixar outro processo (ou algumas horas depois) continuar
    return { workflowId, status: 'awaiting_approval' };
  }
  
  // Fase 3: executa a operação final (depois da aprovação)
  if (state.phase === 'approved') {
    state.phase = 'finalizing';
    await store.save(workflowId, state);
    
    await executeFinalAction(state.completed);
    
    state.phase = 'completed';
    state.completedAt = Date.now();
    await store.save(workflowId, state);
  }
  
  return state;
}

// Fluxo de trabalho de aprovação
async function approveWorkflow(workflowId) {
  const store = new WorkflowStateStore(redis);
  const state = await store.load(workflowId);
  
  if (!state) throw new Error('o fluxo de trabalho não existe');
  if (state.phase !== 'awaiting_approval') {
    throw new Error(`não é possível aprovar: a fase atual é ${state.phase}`);
  }
  
  state.phase = 'approved';
  state.approvedAt = Date.now();
  await store.save(workflowId, state);
  
  // Continua executando o fluxo de trabalho
  return await persistentWorkflow(workflowId, []);
}

O padrão central: uma máquina de estados²

As fases do fluxo de trabalho são os estados de uma máquina de estados:

init → processing → awaiting_approval → approved → finalizing → completed                         ↓                     rejected → cancelled

init → processing → awaiting_approval → approved → finalizing → completed                         ↓                     rejected → cancelled

Cada transição de fase é salva no armazenamento externo, e é isso que permite ao fluxo de trabalho retomar a partir de qualquer fase.

Boas práticas para passar contexto

Princípio 1: passe apenas o necessário

JAVASCRIPT

// ❌ Ruim: entregar todo o estado ao agente
const result = await agent({
  task: 'analisar este arquivo',
  context: workflowState  // resultados da análise de 100 arquivos, configuração, logs...
});

// ✓ Bom: dar apenas a informação relevante
const result = await agent({
  task: 'analisar este arquivo',
  context: {
    file: currentFile,
    guidelines: workflowState.config.analysisGuidelines,
    similarIssues: workflowState.results
      .filter(r => r.file.type === currentFile.type)
      .slice(0, 3)  // no máximo 3 casos parecidos
  }
});

Por quê? Quanto maior o contexto, mais fácil é o agente se distrair; a qualidade do raciocínio cai e o custo sobe.³

Princípio 2: estruture o contexto

JAVASCRIPT

// ❌ Ruim: texto sem estrutura
const context = `
Analisou 47 arquivos antes e encontrou 23 problemas.
O arquivo atual é src/utils.js, 350 linhas.
A configuração exige verificar injeção de SQL e XSS.
`;

// ✓ Bom: um objeto estruturado
const context = {
  progress: { filesAnalyzed: 47, issuesFound: 23 },
  currentFile: { path: 'src/utils.js', lines: 350 },
  checkTypes: ['sql_injection', 'xss']
};

Por quê? Contexto estruturado é mais fácil de o agente entender e mais fácil de você depurar.

Princípio 3: contexto acumulado vs. contexto reiniciado

Contexto acumulado: o resultado de cada passo é adicionado ao contexto, que só cresce.

JAVASCRIPT

let context = { task: 'refatorar a base de código' };

for (const file of files) {
  const result = await agent({ task: 'analisar', context });
  context.results = context.results || [];
  context.results.push(result);  // acumula
}

// No fim, o contexto guarda o resultado de cada arquivo, o que pode ficar enorme

Contexto reiniciado: cada passo limpa o contexto e mantém apenas o necessário.

JAVASCRIPT

const allResults = [];

for (const file of files) {
  const context = {
    file,
    guidelines: config.guidelines,
    exampleIssues: allResults.slice(-3)  // apenas os 3 últimos
  };
  
  const result = await agent({ task: 'analisar', context });
  allResults.push(result);  // vive no estado do fluxo de trabalho, não no contexto
}

Qual escolher: use contexto reiniciado na maior parte do tempo, para evitar a explosão do contexto. Use contexto acumulado apenas quando passos posteriores realmente precisarem de todos os resultados anteriores (como um passo final de resumo).⁵

Observabilidade do estado

Um bom fluxo de trabalho deve conseguir responder a estas perguntas:

Em que fase ele está agora?
Quanto já foi feito? Quanto falta?
Quantos erros ele encontrou?
Quando é esperado que termine?

Implementando o acompanhamento de progresso

JAVASCRIPT

class ObservableWorkflow {
  constructor(name, totalSteps) {
    this.state = {
      name,
      totalSteps,
      currentStep: 0,
      phase: 'init',
      startTime: Date.now(),
      errors: [],
      results: []
    };
  }
  
  async executeStep(stepName, fn) {
    this.state.currentStep++;
    this.state.phase = stepName;
    
    console.log(`[${this.state.name}] 
                 passo ${this.state.currentStep}/${this.state.totalSteps}: 
                 ${stepName}`);
    
    const stepStart = Date.now();
    
    try {
      const result = await fn();
      this.state.results.push({ stepName, result, duration: Date.now() - stepStart });
      return result;
    } catch (error) {
      this.state.errors.push({ stepName, error: error.message });
      throw error;
    }
  }
  
  getStatus() {
    const progress = (this.state.currentStep / this.state.totalSteps) * 100;
    const elapsed = Date.now() - this.state.startTime;
    const avgStepTime = elapsed / this.state.currentStep;
    const remainingSteps = this.state.totalSteps - this.state.currentStep;
    const estimatedRemaining = avgStepTime * remainingSteps;
    
    return {
      progress: `${progress.toFixed(1)}%`,
      currentPhase: this.state.phase,
      elapsed: `${(elapsed / 1000).toFixed(1)}s`,
      estimatedRemaining: `${(estimatedRemaining / 1000).toFixed(1)}s`,
      errors: this.state.errors.length
    };
  }
}

// Uso
async function myWorkflow() {
  const wf = new ObservableWorkflow('migração de dados', 4);
  
  const data = await wf.executeStep('ler dados de origem', async () => {
    return await readSourceData();
  });
  
  const transformed = await wf.executeStep('transformar formato', async () => {
    return await transformData(data);
  });
  
  await wf.executeStep('escrever no banco de dados de destino', async () => {
    return await writeToTarget(transformed);
  });
  
  await wf.executeStep('verificar', async () => {
    return await validateMigration();
  });
  
  console.log('Status final:', wf.getStatus());
}

Próxima lição: Lição 5: Tratamento de erros e estratégias de retentativa — aprenda a fazer um fluxo de trabalho se recuperar com elegância em caso de falha, em vez de quebrar por completo

MachineLearningMastery: 5 Architectural Patterns for Persistent Memory and State in AI Agents — https://machinelearningmastery.com/5-architectural-patterns-for-persistent-memory-and-state-in-ai-agents/ ↩ ↩² ↩³
MindStudio: Workflow State vs. Session State — https://www.mindstudio.ai/blog/workflow-state-vs-session-state-ai-agents ↩ ↩²
Chrono Innovation: Architecture for Scalable Agentic AI Workflows — https://www.chronoinnovation.com/resources/agentic-ai-workflows-architecture/ ↩ ↩²
Appamass: State Management Patterns for Reliable AI Agent Workflows — https://appamass.com/en/blog/state-management-patterns-for-reliable-ai-agent-workflows-5yemlru6ui6cacast3l5 ↩
Ranjan Kumar: Building Agents That Remember — https://ranjankumar.in/building-agents-that-remember-state-management-in-multi-agent-ai-systems ↩

Exercícios

Para os três fluxos de trabalho abaixo, escolha o padrão correto de gerenciamento de estado (variáveis de script, checkpoint, armazenamento externo) e explique por quê:

Nível 1: Escolha um padrão de gerenciamento de estado

Fluxo de trabalho A: comprimir em lote 20 imagens, 5 segundos cada, 100 segundos no total

Fluxo de trabalho B: treinar um modelo de machine learning, 50 épocas de 10 minutos cada, 500 minutos no total (8 horas)

Fluxo de trabalho C: revisar 100 PRs, cada um precisando de aprovação humana antes do merge, e o processo todo pode levar vários dias

Critérios de conclusão · marcado localmente

Escolhas corretas de padrão (A: variáveis de script, B: checkpoint, C: armazenamento externo)raciocínio sólido (levando em conta duração, recuperabilidade e se é necessária participação humana)

Projete o objeto de estado para um fluxo de trabalho de “deploy de múltiplos serviços”. O fluxo de trabalho precisa: (1) construir imagens Docker para 5 serviços (2) enviá-las para um registro de imagens (3) fazer deploy no ambiente de teste um a um (4) rodar testes de integração (5) se os testes passarem, fazer deploy em produção.

Nível 2: Projete uma estrutura de estado

Requisitos:

Projete um objeto JSON que represente o estado do fluxo de trabalho
Inclua: fase atual, status por serviço, informações de erro, timestamps
Explique onde os checkpoints devem ser salvos

Critérios de conclusão · marcado localmente

Estrutura de estado sólida (inclui um marcador de fase, uma lista de serviços com o status de cada um, um array de erros e informações de tempo)o status de cada serviço carrega informação suficiente (por exemplo, status da build, ID da imagem, status do deploy)identifica corretamente os locais dos checkpoints (pelo menos depois das fases 2 e 4, e antes do deploy em produção)

Lição 4: Gerenciamento de estado e passagem de contexto

Por que o gerenciamento de estado é o coração de um fluxo de trabalho

Estado vs. contexto vs. memória

Padrão de estado 1: variáveis de script (estado em memória)

Padrão básico

Melhor: um objeto de estado estruturado

Padrão de estado 2: checkpoint

Escolhendo os locais dos checkpoints

Padrão de estado 3: armazenamento externo (estado persistente)

Implementação básica

Boas práticas para passar contexto

Princípio 1: passe apenas o necessário

Princípio 2: estruture o contexto

Princípio 3: contexto acumulado vs. contexto reiniciado

Observabilidade do estado

Implementando o acompanhamento de progresso

Footnotes

Exercícios

Para os três fluxos de trabalho abaixo, escolha o padrão correto de gerenciamento de estado (variáveis de script, checkpoint, armazenamento externo) e explique por quê: