Inkdown
Start writing

Study

70 filesยท12 subfolders

Shared Workspace

Study
AI eng

11_RUN_STATE

Shared from "Study" on Inkdown

Run State - Comprehensive Deep Dive

Overview

RunState is the serialization mechanism that enables pausing, resuming, and inspecting agent runs. Think of RunState as a "save point" or "checkpoint" in a video game - it captures the complete state of an agent run at any moment, allowing you to pause execution, save that state, and resume it later. This is essential for human-in-the-loop workflows, long-running tasks, and debugging.

Core Concepts

What is RunState?

RunState is a complete snapshot of an agent run that includes:

  • Current agent - Which agent is currently active
  • Conversation history - All messages and tool calls so far
  • Model responses - History of model responses
  • Tool use tracker - Which tools have been used
  • Guardrail results - Results of guardrail checks
  • Session state - Session-related information
  • Sandbox state - Sandbox execution state (if applicable)
basic-ques
core
Revision w/ Whiteboard
CN Basics - 1
CN Basics - 2
DNS
Event loop
programming-language-concepts.md
zero-language-explanation.md
DB
Quick
databases-deep-dive.md
01-introduction.md
02-relational-databases.md
03-database-design.md
04-indexing.md
05-transactions-acid.md
06-nosql-databases.md
07-query-optimization.md
08-replication-ha.md
09-sharding-partitioning.md
10-caching-strategies.md
11-cap-theorem.md
12-connection-pooling.md
13-backup-recovery.md
14-monitoring.md
15-database-selection.md
README.md
JS
core topics
Event loop
Merlin Backend
01-Orchestration.md
02-DeepResearch.md
03-Search.md
04-Scraping.md
05-Streaming.md
06-MultiProviderLLM.md
07-MemoryAndContext.md
08-ErrorHandling.md
09-RateLimiting.md
10-TaskQueue.md
11-SecurityAndAuth.md
Orchestration-2nd-draft
Mobile
Build Alternative
Bundling
metro-bundler-deep-dive.md
OpenAI Agents Python
00_OVERVIEW.md
01_AGENT_SYSTEM.md
02_RUNNER_SYSTEM.md
03_TOOL_SYSTEM.md
04_ITEMS_SYSTEM.md
05_GUARDRAILS.md
06_HANDOFFS.md
07_MEMORY_SESSIONS.md
08_MODEL_PROVIDERS.md
09_SANDBOX_SYSTEM.md
10_TRACING.md
11_RUN_STATE.md
12_CONTEXT.md
13_LIFECYCLE_HOOKS.md
14_CONFIGURATION.md
15_ERROR_HANDLING.md
16_STREAMING.md
17_EXTENSIONS.md
18_MCP_INTEGRATION.md
19_BEST_PRACTICES.md
20_ARCHITECTURE_PATTERNS.md
opencode-study
context-handling
core
Python
Alembic
Basics
sqlalchemy - fastapi
SQLAlchemy overview
tweets
system_design_for_agentic_apps.md
Agent Loop
  • Interruptions - Pending human approvals
  • Error details - Any errors that occurred
  • Context - User-provided context object
  • Trace state - Tracing information
    • Why RunState Matters
    1. Human-in-the-Loop - Pause for human approval and resume
    2. Long-Running Tasks - Handle tasks that span hours or days
    3. Debugging - Inspect state at any point
    4. Reproducibility - Replay exact execution paths
    5. Error Recovery - Resume from failures
    6. State Inspection - Understand what the agent is doing

    RunState Structure

    RunState Class
    Python

    Schema Versioning

    CURRENT_SCHEMA_VERSION

    The SDK uses schema versioning to handle changes in RunState format:

    Python
    SCHEMA_VERSION_SUMMARIES

    Each schema version has a summary:

    Python
    Schema Compatibility

    The SDK checks schema compatibility:

    Python

    RunState Serialization

    to_json()

    Serialize RunState to JSON:

    Python

    What gets serialized:

    • Agent metadata (name, instructions, etc.)
    • All run items
    • Model responses
    • Tool use tracker
    • Guardrail results
    • Trace state
    • Sandbox state (if applicable)
    • Context (if serializer provided)
    • Run configuration
    from_json()

    Deserialize RunState from JSON:

    Python

    What gets deserialized:

    • All serialized fields
    • Agent is reconstructed from metadata
    • Context is deserialized (if deserializer provided)
    Context Serialization

    Custom context requires serializers:

    Python

    RunState and Human-in-the-Loop

    Pausing for Approval

    RunState enables approval workflows:

    Python
    Interruption Handling

    RunState captures interruptions:

    Python

    RunState and Resumption

    Resuming from State

    Resume a run from a saved state:

    Python
    Resumption Behavior

    When resuming:

    • The current agent is restored
    • Conversation history is preserved
    • Tool use tracker is restored
    • Pending approvals are handled
    • Session state is maintained
    • Sandbox state is restored (if applicable)
    Resumption with New Input

    You can provide new input when resuming:

    Python

    RunState and Sessions

    Session-Aware RunState

    RunState includes session information:

    Python
    Session Resumption

    Resume with session context:

    Python

    RunState and Sandbox

    Sandbox State in RunState

    Sandbox state is included:

    Python
    Sandbox Resumption

    Resume with sandbox state:

    Python

    RunState and Errors

    Error Details

    RunState captures error details:

    Python
    Error Recovery

    Recover from errors using RunState:

    Python

    RunState Inspection

    Inspecting Conversation History
    Python
    Inspecting Tool Usage
    Python
    Inspecting Guardrail Results
    Python
    Inspecting Model Responses
    Python

    RunState and Tracing

    Trace State

    RunState includes trace state:

    Python
    Resuming with Trace

    Trace is continued when resuming:

    Python

    RunState Best Practices

    1. Serialize Context Properly

    Always provide serializers for custom context:

    Python
    2. Handle Schema Versions

    Be aware of schema version changes:

    Python
    3. Clean Up Old States

    Implement cleanup for old states:

    Python
    4. Validate State Before Resumption

    Validate state before resuming:

    Python
    5. Encrypt Sensitive States

    Encrypt sensitive state data:

    Python

    Common RunState Patterns

    1. Approval Workflow
    Python
    2. Long-Running Task
    Python
    3. Error Recovery
    Python
    4. Debugging
    Python
    5. State Sharing

    Share state across processes:

    Python

    RunState and Version Migration

    Migrating Between Versions

    When the schema changes, implement migration:

    Python
    Backward Compatibility

    Maintain backward compatibility:

    Python

    RunState Performance

    State Size

    RunState can be large for long conversations:

    Python
    Optimizing State Size

    Reduce state size:

    Python
    State Compression

    Compress state for storage:

    Python

    Summary

    RunState enables pausing and resuming agent runs. Key takeaways:

    1. RunState is a complete snapshot of an agent run
    2. Serialization enables state persistence
    3. Schema versioning handles format changes
    4. Context serialization requires custom serializers
    5. Human-in-the-loop via approval workflows
    6. Resumption continues from saved state
    7. Session integration maintains conversation context
    8. Sandbox state preserves execution environment
    9. Error details capture failure information
    10. Inspection enables debugging
    11. Tool use tracker monitors tool usage
    12. Guardrail results capture validation outcomes
    13. Model responses track LLM interactions
    14. Trace state preserves tracing information
    15. Validation before resumption
    16. Encryption for sensitive data
    17. Cleanup prevents storage bloat
    18. Migration handles schema changes
    19. Compression reduces storage size
    20. Performance considerations for large states

    RunState is essential for building robust, resumable, and debuggable agent workflows.