Agent State Schema

Data artifactOrchestrationOrchestration & Toolsarc:AgentStateSchema

A typed data contract declaring every field that must persist across workflow steps, with its type, semantics, and accumulation behaviour.

Responsibility. Defines exactly what information workflow state carries between steps.

Also known as: State schema, TypedDict state, FlightSearchState, SupportAgentState, State schema with reducers, TypedDict/Pydantic state, add_messages reducer, Error accumulation fields

Direct neighbourhood (hover for relationship types)

Relationships

configures structural

Conversation State Store abstract Ch3.6
Sliding-Window History Truncator Ch1.6
State-Graph Orchestrator Ch1.5B Ch2.1 +4
Working Memory Buffer abstract Ch1.5A Ch1.5B

Design guidance

MUST declare every field that must survive across workflow steps explicitly with types and semantics.
SHOULD declare accumulating fields with reducer semantics (append rather than replace) so parallel branches can add results without coordination.
SHOULD include an explicit current-step field so execution position is inspectable at any time.
SHOULD include a metadata field for timestamps, confidence scores and latency tracking.
SHOULD be reused unchanged when state moves from agent-local memory to distributed persistence.
SHOULD declare explicit, typed state with merge logic when state includes accumulated structured results beyond conversation history.
MUST declare per-field merge behaviour: overwrite by default, accumulate (append) for histories such as messages and prior attempts.
SHOULD track iteration count, prior attempts and error patterns explicitly in state rather than inferring them from conversation history.
SHOULD define merge semantics that preserve existing fields unless explicitly superseded, or scope updates to specific fields, rather than replacing entire state objects.

Classification

Patterns: Explicit state schemaReducer-annotated accumulating fieldsImmutable state updateCustom state reducersOverwrite reducer (default)Append/accumulate reducer
Technologies: Python TypedDictLangGraphTypedDictPydantic
Quality attributes: Maintainability (ISO/IEC 25010)
Risks mitigated: Lost context problemState field mismatch bugs caught at development time

Sources

Ch1.5A: T. Nguyen, "Stateful Orchestration - Introduction and Core Concepts," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 1.5A. ISBN: 9798244538229.
Ch1.5B: T. Nguyen, "Stateful Orchestration - Worked Examples," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 1.5B. ISBN: 9798244538229.
Ch1.6: T. Nguyen, "Stateful Orchestration - Pitfalls, Integration, and Synthesis," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 1.6. ISBN: 9798244538229.
Ch2.1: T. Nguyen, "Framework Landscape and Selection," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 2.1. ISBN: 9798244538229.
Ch2.2: T. Nguyen, "LangGraph," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 2.2. ISBN: 9798244538229.
Ch2.3: T. Nguyen, "LangChain Sequential Frameworks," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 2.3. ISBN: 9798244538229.
Ch2.8: T. Nguyen, "Error Handling and Resilience," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 2.8. ISBN: 9798244538229.
Ch3.6: T. Nguyen, "Trace Analysis and Execution Debugging," in Mastering Agentic AI Systems: Guide for the NVIDIA NCP-AAI Exam, 1st ed. 2026, ch. 3.6. ISBN: 9798244538229.
Ref7.07: E. Li, V. Bellotti, R. Kraus, and R. Kao, "Build a retrieval-augmented generation (RAG) agent with NVIDIA Nemotron," NVIDIA Technical Blog, Sep. 23, 2025. [Online]. Available: https://developer.nvidia.com/blog/build-a-rag-agent-with-nvidia-nemotron/