Designing Agent Workflows: From One-Off Conversations to Multi-Step Automation · Lesson 4 of 6

Lesson 4: State Management and Passing Context

Learning goals:

Distinguish workflow state from agent context

Master three state-management patterns

Understand checkpointing and recovery

Prerequisites: Lesson 3: Decomposing a Complex Task into a Workflow | Next: Lesson 5 >>

Why state management is the heart of a workflow

You design a perfect workflow: 10 steps, clean dependencies. On step 8, the server restarts. The workflow crashes.

Rerun it? Then the work from the first 7 steps — maybe 30 minutes of it — is thrown away.

That's the price of having no state management.

State management solves three problems:¹

Passing data between steps: how does step 3 get the results of steps 1 and 2?
Progress tracking: how far along is the workflow? How much is left?
Failure recovery: after a crash, resume from where it stopped instead of starting over.

Without state management, an agent can only pass information through conversation history. Conversation history overflows, gets lost, and gets forgotten by the agent.

With state management, the workflow has a clear "memory": persistent, queryable, recoverable.²

State vs. context vs. memory

These three words are easy to mix up, so let's pin them down first:¹

State

All the information about the current task: which step you're on, the result of each step, what to do next
It's a snapshot: everything the workflow knows at this moment
Stored in: script variables, a database, files

Context

The information passed into a single agent call
It's input: what this agent needs to know to do its job
Selectively pulled from state: not all state goes to the agent, only the relevant part

Memory

Lessons learned from the past: what was done before, what problems came up, what the solutions were
It's history: long-term knowledge across tasks and sessions
Out of scope for this lesson (long-term memory is its own hard topic)

An example:

JAVASCRIPT

// State: everything the workflow knows
const workflowState = {
  phase: 'testing',
  filesProcessed: 47,
  totalFiles: 100,
  issues: [/* all issues found in earlier steps */],
  currentBatch: [/* files being processed right now */]
};

// Context: the info for this agent (pulled from state)
const agentContext = {
  file: workflowState.currentBatch[0],
  previousIssues: workflowState.issues.filter(i => i.severity === 'high')
};

// Agent call
const result = await agent({
  task: 'test file',
  context: agentContext  // only relevant info, not the whole state
});

// Update state
workflowState.filesProcessed++;
workflowState.issues.push(...result.newIssues);

The key principle: state is global, context is local.³

State pattern 1: script variables (in-memory state)

When to use it: short workflows (< 10 minutes) that don't need to cross processes or machines.

Upside: simple, fast, no external dependencies.

Downside: state is lost when the process crashes, with no way to recover.

Basic pattern

JAVASCRIPT

async function simpleWorkflow(files) {
  // State is just ordinary JavaScript variables
  let processed = 0;
  let results = [];
  let errors = [];
  
  for (const file of files) {
    try {
      const result = await processFile(file);
      results.push(result);
      processed++;
      console.log(`Progress: ${processed}/${files.length}`);
    } catch (error) {
      errors.push({ file, error });
    }
  }
  
  return { results, errors, total: files.length };
}

Where does the state live? In the function's local variables (processed, results, errors).

What if the process crashes? All state is lost, and you start over from the beginning.

Better: a structured state object

JAVASCRIPT

async function betterWorkflow(files) {
  // Organize state in an object — clearer
  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;
}

Why it helps: the state has a clear structure, it's easy to pass to other functions, and it's easy to serialize (if you need to persist it).

State pattern 2: checkpointing

When to use it: medium-length workflows (10-60 minutes) where you need to save progress after expensive operations.

Upside: after a crash, you can resume from the most recent checkpoint and avoid redoing work.

Downside: you have to design checkpoint locations and recovery logic.¹

Choosing checkpoint locations

JAVASCRIPT

async function workflowWithCheckpoints(tasks) {
  const checkpointFile = '.workflow-state.json';
  
  // Try to restore prior state
  let state = await loadCheckpoint(checkpointFile) || {
    completed: [],
    pending: tasks,
    phase: 'processing'
  };
  
  console.log(`Resuming: ${state.completed.length}/${tasks.length} done`);
  
  while (state.pending.length > 0) {
    const task = state.pending.shift();
    
    // Run the task
    const result = await executeTask(task);
    state.completed.push({ task, result });
    
    // Checkpoint: save after every 10 tasks
    if (state.completed.length % 10 === 0) {
      await saveCheckpoint(checkpointFile, state);
      console.log(`Checkpoint: ${state.completed.length} tasks done`);
    }
  }
  
  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;  // file doesn't exist, start from scratch
  }
}

Checkpoint strategies:

Periodic checkpoints: save every N tasks or every M minutes
Phase checkpoints: save after each major phase completes (e.g. "analysis phase done")
Before critical operations: save before an irreversible operation (e.g. a deploy, a delete)

State pattern 3: external storage (persistent state)

When to use it: long-running workflows (> 1 hour), work that needs to coordinate across machines, or work that needs human approval.

Upside: state is persistent; a process crash or machine restart doesn't matter, and pause/resume is supported.

Downside: it needs an external dependency (a database, Redis) and adds complexity.⁴

Basic implementation

JAVASCRIPT

// State store interface
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}`);
  }
}

// A workflow backed by external storage
async function persistentWorkflow(workflowId, tasks) {
  const store = new WorkflowStateStore(redis);
  
  // Load state (if it exists)
  let state = await store.load(workflowId) || {
    id: workflowId,
    phase: 'init',
    completed: [],
    pending: tasks,
    createdAt: Date.now(),
    updatedAt: Date.now()
  };
  
  console.log(`Workflow ${workflowId}: phase ${state.phase}, 
               progress ${state.completed.length}/${tasks.length}`);
  
  // Phase 1: process tasks
  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();
      
      // Save state after each task
      await store.save(workflowId, state);
    }
    
    state.phase = 'awaiting_approval';
    await store.save(workflowId, state);
  }
  
  // Phase 2: wait for human approval (may resume in another process/machine)
  if (state.phase === 'awaiting_approval') {
    console.log('Awaiting approval...');
    // We can return here and let another process (or a few hours later) continue
    return { workflowId, status: 'awaiting_approval' };
  }
  
  // Phase 3: run the final operation (after approval)
  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;
}

// Approval workflow
async function approveWorkflow(workflowId) {
  const store = new WorkflowStateStore(redis);
  const state = await store.load(workflowId);
  
  if (!state) throw new Error('workflow does not exist');
  if (state.phase !== 'awaiting_approval') {
    throw new Error(`cannot approve: current phase is ${state.phase}`);
  }
  
  state.phase = 'approved';
  state.approvedAt = Date.now();
  await store.save(workflowId, state);
  
  // Continue running the workflow
  return await persistentWorkflow(workflowId, []);
}

The key pattern: a state machine²

The workflow's phases are the states of a state machine:

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

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

Every phase transition is saved to external storage, which is what lets the workflow resume from any phase.

Best practices for passing context

Principle 1: pass only what's needed

JAVASCRIPT

// ❌ Bad: hand the agent all the state
const result = await agent({
  task: 'analyze this file',
  context: workflowState  // analysis results for 100 files, config, logs...
});

// ✓ Good: give only the relevant info
const result = await agent({
  task: 'analyze this file',
  context: {
    file: currentFile,
    guidelines: workflowState.config.analysisGuidelines,
    similarIssues: workflowState.results
      .filter(r => r.file.type === currentFile.type)
      .slice(0, 3)  // at most 3 similar cases
  }
});

Why? The bigger the context, the easier it is for the agent to get distracted; reasoning quality drops and cost rises.³

Principle 2: structure the context

JAVASCRIPT

// ❌ Bad: unstructured text
const context = `
Analyzed 47 files earlier and found 23 issues.
The current file is src/utils.js, 350 lines.
Config requires checking for SQL injection and XSS.
`;

// ✓ Good: a structured object
const context = {
  progress: { filesAnalyzed: 47, issuesFound: 23 },
  currentFile: { path: 'src/utils.js', lines: 350 },
  checkTypes: ['sql_injection', 'xss']
};

Why? Structured context is easier for the agent to understand, and easier for you to debug.

Principle 3: accumulating context vs. resetting context

Accumulating context: each step's result is added to the context, so it keeps growing.

JAVASCRIPT

let context = { task: 'refactor codebase' };

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

// In the end context holds every file's result, which can get huge

Resetting context: each step clears the context and keeps only what's needed.

JAVASCRIPT

const allResults = [];

for (const file of files) {
  const context = {
    file,
    guidelines: config.guidelines,
    exampleIssues: allResults.slice(-3)  // only the last 3
  };
  
  const result = await agent({ task: 'analyze', context });
  allResults.push(result);  // lives in workflow state, not in context
}

Which to pick: use resetting context most of the time to avoid context explosion. Use accumulating context only when later steps genuinely need every earlier result (like a final summary step).⁵

Observability of state

A good workflow should be able to answer these questions:

Which phase is it in right now?
How much is done? How much is left?
How many errors has it hit?
When is it expected to finish?

Implementing progress tracking

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}] 
                 step ${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
    };
  }
}

// Usage
async function myWorkflow() {
  const wf = new ObservableWorkflow('data migration', 4);
  
  const data = await wf.executeStep('read source data', async () => {
    return await readSourceData();
  });
  
  const transformed = await wf.executeStep('transform format', async () => {
    return await transformData(data);
  });
  
  await wf.executeStep('write to target database', async () => {
    return await writeToTarget(transformed);
  });
  
  await wf.executeStep('verify', async () => {
    return await validateMigration();
  });
  
  console.log('Final status:', wf.getStatus());
}

Next lesson: Lesson 5: Error Handling and Retry Strategies — learn how to make a workflow recover gracefully on failure instead of crashing outright

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 ↩

Exercises

For the three workflows below, choose the right state-management pattern (script variables, checkpointing, external storage) and explain why:

Level 1: Choose a state-management pattern

Workflow A: batch-compress 20 images, 5 seconds each, 100 seconds total

Workflow B: train a machine learning model, 50 epochs at 10 minutes each, 500 minutes total (8 hours)

Workflow C: review 100 PRs, each needing human approval before merge, and the whole process may run for several days

Done criteria · checked locally

Correct pattern choices (A: script variables, B: checkpointing, C: external storage)sound reasoning (accounting for duration, recoverability, and whether human involvement is needed)

Design the state object for a "multi-service deployment" workflow. The workflow needs to: (1) build Docker images for 5 services (2) push them to an image registry (3) deploy to a test environment one by one (4) run integration tests (5) if tests pass, deploy to production.

Level 2: Design a state structure

Requirements:

Design a JSON object that represents the workflow state
Include: current phase, per-service status, error info, timestamps
Explain where checkpoints should be saved

Done criteria · checked locally

Sound state structure (includes a phase marker, a service list with each service's status, an error array, and timing info)each service's status carries enough info (e.g. build status, image ID, deploy status)correctly identifies checkpoint locations (at least after phases 2 and 4, and before production deploy)

Lesson 4: State Management and Passing Context

Why state management is the heart of a workflow

State vs. context vs. memory

State pattern 1: script variables (in-memory state)

Basic pattern

Better: a structured state object

State pattern 2: checkpointing

Choosing checkpoint locations

State pattern 3: external storage (persistent state)

Basic implementation

Best practices for passing context

Principle 1: pass only what's needed

Principle 2: structure the context

Principle 3: accumulating context vs. resetting context

Observability of state

Implementing progress tracking

Footnotes

Exercises

For the three workflows below, choose the right state-management pattern (script variables, checkpointing, external storage) and explain why:

Design the state object for a "multi-service deployment" workflow. The workflow needs to: (1) build Docker images for 5 services (2) push them to an image registry (3) deploy to a test environment one by one (4) run integration tests (5) if tests pass, deploy to production.