CDX-201c · Module 2

Shared Context & State Management

3 min read

In multi-agent workflows, context sharing is the primary coordination challenge. Each agent has its own context window, its own conversation history, and its own understanding of the task. There is no shared memory between agents by default. Context must be explicitly passed through hand-offs, shared files, or structured state objects.

Three patterns for context sharing dominate production workflows. File-based context: agents communicate through files in the repository (a plan.md file, a decisions.json log, or structured comments in the code). Hand-off context: structured messages passed between agents through the Agents SDK. Shared AGENTS.md: all agents inherit the same AGENTS.md, which provides baseline project context. The choice depends on the volume and structure of shared state — small, structured state fits hand-offs; large, evolving state fits files.

from agents import Agent, Runner

# File-based context sharing
planner = Agent(
    name="planner",
    model="o3",
    instructions="""
    1. Analyze the task and write a detailed plan
    2. Save the plan to .codex/plan.md
    3. Save key decisions to .codex/decisions.json
    These files will be read by downstream agents.
    """,
)

implementer = Agent(
    name="implementer",
    model="codex-1",
    instructions="""
    1. Read .codex/plan.md for the implementation plan
    2. Read .codex/decisions.json for architectural decisions
    3. Implement according to the plan
    4. Update .codex/progress.json as you complete each step
    """,
)

Do This

  • Use file-based context for large, structured state that multiple agents need to read
  • Use hand-off messages for small, one-time context between sequential agents
  • Keep shared context minimal — every token of context consumes window space in every agent
  • Create a .codex/ directory for pipeline state files — keep them separate from source code

Avoid This

  • Assume agents can read each other's conversation history — they cannot
  • Pass entire file contents in hand-off messages — reference the file path instead
  • Let context grow unbounded — set explicit limits on plan length and decision log size
  • Forget to clean up pipeline state files after the workflow completes