Some AI workflows are easier to implement as state machines than as agent conversations. Pydantic Graph is an asynchronous graph/state-machine library in the Pydantic ecosystem, and its docs note that it does not require the full PydanticAI agent library. The practical advantage is explicit transitions: the program knows whether it is waiting for data, validation, review or completion. That makes failure and replay behavior easier to specify.
What the architecture changes
Graph nodes and typed state express permitted transitions. Rather than ask the model what stage comes next, application logic can return the appropriate next node based on validation results. An extraction model may emit a document summary, but a parser decides whether required fields exist. A state object tracks document hash, reviewer decision and target revision. Keep ephemeral model messages out of business-critical state unless they are needed for audit. Typed state does not imply persistence across process crashes; storage and resume policies must be designed.
A concrete, controlled workflow
For a contract intake flow, start in RECEIVED, advance to CLASSIFIED when a deterministic file check passes, proceed to EXTRACTED after the model proposes fields, and move to REVIEW_REQUIRED whenever extraction confidence or source coverage is insufficient. A reviewer records changes and approval, leading to COMMIT_PENDING. Before committing, compare the original revision with the current target and enforce idempotency. A completed record enters VERIFIED only after an authoritative read-back. A rejected document goes to a terminal REJECTED state without a write.
Permissions and human oversight
Do not let a generated state name trigger a privileged transition. Server-controlled code owns the transition table and validates actor roles. Bind approvals to immutable payload hashes and put secret-bearing dependencies in the runtime, not serialized graph state. If execution can call third-party tools, make timeouts and retry permissions part of each node specification. Keep approval deadlines and cancellation explicit so a dormant graph cannot resume under stale authorization.
Failure modes and limits
Typed transitions do not guarantee that a model’s extracted fields are true, nor that external systems execute atomically. A crash after sending an API request but before saving the result can still duplicate a mutation unless the external request is idempotent or reconciled. State explosion can make graph designs harder to maintain than a short sequence of functions. The official documentation recommends choosing graph structure only when it provides value, not as a default for every agent.
When to choose it or an alternative
Use Pydantic Graph for Python applications with meaningful branching, review and state. Use straightforward Python control flow when there are only one or two steps. Use durable orchestration platforms such as Prefect or Temporal when jobs must survive process failures with operational scheduling, observability and distributed execution. Compare the real persistence and compensation requirements before deciding a graph runtime is sufficient.
How to evaluate before deploying
Test every transition, including malformed extraction, reviewer rejection, approval expiry, duplicate callback, commit timeout and inconsistent read-back. Assert that no path reaches the write node without valid authorization. Property-based tests can generate illegal state combinations and confirm they fail closed. Capture state snapshots in development but verify that production traces mask confidential fields. Report persistence guarantees only after a crash-recovery test in the target hosting environment.
Version, pricing and regional availability
Editorial scope: product documentation and documented conceptual behavior checked on 25 October 2026. Exact deployed package version, contract tier, price, quota and applicable geographic region have not been established for this record; they remain unknown rather than assumed. Where a dated release or announcement is discussed, it does not by itself prove that an individual account or region had access. Recheck moving documentation and source applicability before publication.