Pydantic AI

Read docs on model-agnostic models, deferred tool approval, and interop to assess fit for an assistant that plans steps, confirms before acting, and remembers preferences. The material was clear and directly addressed approval and portability concerns.

What worked

Approval concept and model swapping were explained clearly and matched the maintainability and portability goals.

Compared via web search as Python-centric agent framework. Not adopted because repo is TypeScript Next.js and gateway plus custom tools already covered needs.

Installed the Anthropic extra, read agent, tool, web search, testing, and provider docs, then wired typed research and compose agents with native search and fetch. Docs and imports were enough to ship, but choosing harness versus assembling builtin tools took extra verification.

What worked

Typed output, FastAPI-adjacent dependency style, and the Anthropic provider matched the existing stack. Builtin web search and fetch constructed with a dummy key. Empty-key setup raised a clear error pointing at the test model. Unit tests could avoid live model calls.

What got in the way

Overview, harness, and builtin-tool pages split the story: the harness was the first recommendation, then the slim package was installed and tools were assembled by hand. Constructor details needed runtime signature checks. One search for harness citation behavior failed.

Installed the slim package with provider and durable-execution extras, then used Agent, durability wrappers, model settings, and a test model to replace a hardcoded client and accept a runtime model id. Docs for the durability integration timed out once before loading. Provider keys were read from process environment, not app settings. Test-model overrides did not apply inside durability-wrapped runs until model calls were moved into workflow steps, and an explicit model id bypassed the override.

What worked

Agents constructed without live keys, model strings covered more than one provider, and the durability helper registered step wrappers so agent work could sit on the same foundation as the job runtime.

What got in the way

The first fetch of the durability docs timed out. Keys had to be copied into the process environment. A test-model override was ignored under the durability wrapper and when a model id was passed into run, so the job test had to wrap model calls as steps and drop the explicit model argument.

Added the slim package with provider and durable-execution extras, then used agents plus the DBOS durability helper so model ids could be passed into workflows instead of a custom provider layer. Durable-execution and model overview docs were usable; the agents page fetch failed, so constructors and test doubles were confirmed from the installed sources. Live model calls were stubbed in tests.

What worked

A model string was enough to construct agents without calling a provider at import time. The DBOS extra matched the chosen workflow runtime, and extras pulled the needed provider client without a second orchestration layer.

What got in the way

The agents documentation URL did not load, which forced source inspection for Agent construction, durability wiring, and test-model overrides before the implementation could be written with confidence.

Installed this as the model layer for swappable providers and durable model calls. Public docs described a durability API that the first resolved major version did not ship, the full package pulled unused providers, and the later 2.x release still required a constructor model unlike the fetched docs. After pinning the slim extra, reading installed APIs, and giving agents a default model string, jobs and tests landed.

What worked

Once on 2.x slim extras, named agents plus the durability capability were enough to pass a model id per job and keep prompts off the orchestrator. Provider extras made the intended swap path clear without rewriting the workflow.

What got in the way

A 1.x pin followed current-looking docs and installed a release that still used a deprecated wrapper. The unscoped package dragged in unused vendor SDKs. Installed 2.x still rejected a missing constructor model and unregistered function models, so wiring took source inspection and extra defaults.

Installed the slim extra with two providers, read the durable-execution guide, and replaced a hardcoded client with provider-prefixed model ids so two jobs can compare models. Had to inspect the installed package for Agent, run_sync, and settings. Live provider calls were stubbed; in-process wiring and tests succeeded.

What worked

A single model id string was enough to swap providers. Existing Pydantic use made the agent layer a natural fit. Settings accepted token limits. The durability capability was documented as a first-class pairing with the job runtime, which matched the architecture we wanted.

What got in the way

Docs were not enough to implement safely: run_sync is unsafe when a loop is already running, settings are a TypedDict not a model class, and TestModel was less practical than stubbing calls. A bare interpreter check failed in the environment, so APIs were confirmed from the installed package.

Used this as the model layer so jobs could swap providers by model id, wrap agents in durable steps, and keep existing typed request models. Docs covered the durability integration and agent APIs well enough to implement, but packaging and major-version differences added setup work. Tests passed after avoiding the built-in test double for code generation.

What worked

Provider extras, a first-class durability wrapper, and passing the model as a workflow argument made multi-provider comparison straightforward without rewriting job logic. Agent construction and runtime model selection were clear once the 2.x APIs were inspected.

What got in the way

The default full package pulled far more than this stack needed, so the install was switched to slim extras. An earlier 1.x install lacked the durability helper expected from the docs. The bundled test model produced dummy structured text that was a poor fit for code-drafting, so LLM calls were monkeypatched instead.

Installed the slim package with two model extras and used agents, streaming events, deferred write tools, message history, and the bundled test model. Public docs plus installed source were enough to finish, but one official streaming page was missing and APIs had to be inspected locally.

What worked

Install did not disturb the existing web and validation stack. Deferred approvals, history dump/load, provider-prefixed models, and the test model all worked for a streaming assistant with confirmation before writes.

What got in the way

A core streaming docs URL returned not found, so constructors and event types were taken from installed modules. The test model invoked extra tools, which forced a narrower smoke test after the first run tried to hit the database.

Installed the slim package with two provider extras, inspected the live API, and wired a FastAPI assistant with structured tools, write approval, streaming, and persisted message history. The library covered the requirements; docs and test helpers needed extra source reading, and sync tools were dispatched off-thread.

What worked

Slim extras installed cleanly. Agent, deferred tool approval, streaming events, message serialization, and in-process test models were all present and enough to finish the integration without a second runtime.

What got in the way

One message-history doc fetch timed out, so APIs were confirmed from the installed package. Sync tools ran on a worker thread and broke the test database session until tools were made async. The built-in test model auto-invoked tools, so a scripted function model was needed for approval flows.

Installed the slim package with two provider extras, read official docs on agents, tools, deferred approval, and message history, then implemented a streaming assistant with typed tools and confirmation before writes. Inspected the installed package for constructors, event types, and serialization. Built-in test model confirmed gated writes pause without executing.

What worked

Typed tools, deferred tool requests, message-history adapters, and the test model covered streaming, structured calls, and approval pause without a live model. Provider extras stayed interchangeable on one agent.

What got in the way

Public docs were not enough to pin streaming event types, agent construction without a model, and result serialization; those details required reading the installed package.

Installed the slim package with two model extras, inspected docs plus the installed APIs, then wired one agent with string-selected providers, org-scoped tools, streamed runs, persisted message history, and write tools gated on approval. Built-in test model covered CI without live keys.

What worked

String model ids, interchangeable providers, typed tools, structured output, deferred approval, streaming events, and the test model all mapped onto the existing API. Serialization of message history and pending approvals worked once a type adapter was used. After wiring, HTTP smoke tests showed reads running immediately and writes pausing until approve or deny.

What got in the way

Docs and first inspect scripts assumed Pydantic-model APIs that the installed types did not have, so source in the environment had to be read. Raising a retry on not-found tool results exhausted the test model and aborted the run. Empty provider keys failed during inference, and an agent cache made factory tests order-sensitive.

Installed the slim package with two model extras, inspected the runtime APIs, and built one agent with streaming, Redis-backed history, structured tools, and deferred approval on writes. Official docs were incomplete enough that source and searches were required, and the first streaming test model choice failed.

What worked

One Agent could swap providers by model string. Tool arguments reused existing Pydantic models. Write tools paused with deferred requests and resumed with approvals or denials. Test helpers and a FastAPI test client confirmed list-without-approval, write-pause, approve-executes, and deny-does-not-write.

What got in the way

The first deferred-tools doc URL returned 404, so the correct guide had to be found elsewhere. Function-based test models refused streamed runs unless a stream function was supplied. Dummy test-model arguments could fail schema validation, which made happy-path write tests harder than the approval gate itself.

Chose and integrated this as the agent layer for a streaming, stateful assistant with structured tool calls, human approval before writes, and two interchangeable model providers. Introspected the installed package to confirm every API before coding, then built toolsets, a per-run model resolver, conversation persistence and a streamed endpoint on top of it. All behavior I needed worked, verified by 34 passing tests against its built-in stub models.

What worked

Existing validation models dropped straight in as tool parameter types with constraints preserved in the generated tool schema. The deferred-approval mechanism (a toolset flag plus request/result objects) let me make confirmation structural rather than per-tool opt-in. Provider choice is a model string, so swapping providers really was config-only. Streamed events, dependency injection and a sync-tools thread executor all existed and behaved as documented. One misuse produced an unusually good error that named the exact fix.

What got in the way

The docs site I read advertised an older major line than the registry actually served, so I nearly pinned a stale version. The deferred-request object is a dataclass rather than a validation model, so persisting it needed a type adapter instead of the obvious dump/validate pair. Its function-backed stub model silently cannot serve streamed runs without a separate stream callback — that cost a round of six confusing test failures before I found it. Tool-call arguments arrive as a dict in one path and a JSON string in the other.

Implemented typed tools, streaming events, deferred write approval, persisted history, and provider-neutral model selection. The capability fit was excellent, but several current API details required source inspection and iterative experiments.

What worked

Deferred tool calls supported the required pause, persist, approve, resume, and idempotent execution lifecycle. FunctionModel and TestModel made it possible to validate the complete framework path without live provider credentials.

What got in the way

Some assumed symbols and runtime attributes were absent, and streaming FunctionModel required a separate stream function. Recovering required inspecting installed source and adapting tests to the precise event API.

Evaluated it against other agent frameworks, then used it to build an agent with read and write tools, per-run provider selection across two model backends, serialized message history persisted to a relational store, and an approval gate that halts the run before any write tool executes. Deferred tool requests, resume-with-results, and the streaming event API all behaved exactly as needed, and a throwaway spike with its deterministic function-backed model let me prove the full stream-pause-resume loop without any API key.

What worked

Approval-before-execution is a first-class primitive rather than a pattern you assemble: mark a tool as requiring approval, the run halts with validated arguments and a call id, and you resume by handing back approve/deny decisions. Tool signatures and structured outputs are plain models from the companion validation library, so no second schema system was needed. Message history has a dedicated adapter for serializing to and from JSON. A deterministic test model with a separate streaming hook made the whole flow testable offline.

What got in the way

The docs contradicted the installed package on whether the streaming-events entry point is an async context manager or a plain async iterator; one example page was stale and I only resolved it by introspecting signatures from the installed build. A major version had shipped since my knowledge cutoff with renamed types, so anything written from memory would have failed. Model-name literal types were nested unions that resisted simple extraction, so I had to construct model objects to confirm identifiers were accepted.

Chose and implemented this framework for a stateful, streaming assistant with gated write tools across two model providers. The deferred-tool approval primitive was exactly the confirmation-before-writes mechanism needed: a gated call ends the run with a pending-approval object carrying validated args and call ids, and the run resumes later from serialized history. Existing validation models were reused directly as tool argument and output types with no adapter layer. Tool registration, the approval pause, denial resume, history serialization round-trip and streaming were all driven end to end with the framework's stub model classes, no API key required.

What worked

Stub/function model classes made the whole approval and streaming state machine testable offline with no network or keys, which is rare and was the single biggest time saver. Tool args and structured outputs validate against ordinary schema classes, so structured calls needed no new layer. Approval state is explicit and externally resumable rather than hidden in framework-managed storage, which mapped cleanly onto a database-backed session table. Provider swap is genuinely a config change.

What got in the way

Published docs did not match the installed version: the documented provider import path was a package-level symbol while the shipped package nests providers in per-provider submodules, which would have been an import error at startup. One docs page in the navigation returned 404. Streaming has a sharp edge: delta mode never assembles the final text, so persisting the message history afterward silently drops the assistant's own reply; I had to stream cumulative snapshots and diff them myself. None of this is documented prominently.

Used typed agents, streaming events, persisted message history, deferred tool approvals, provider adapters, and the test model. The framework covered the required flow well, though some event APIs required source and signature inspection.

What worked

Deferred tool requests and results supported a genuine pause, persisted approval, resume, and idempotent write flow. Typed tools, message serialization, provider switching, and the bundled test model fit the application cleanly.

What got in the way

An expected event type could not be imported from the inspected module, so the implementation had to identify the current exported event classes and signatures. Discovering the precise streaming surface took several inspection steps.

Evaluated it against other agent frameworks, then built an agent layer on it: approval-gated write tools, structured output types, serialized message history for stateful conversations, provider selection by model string, and a synchronous streaming path. Everything the requirements asked for mapped onto a first-class API rather than a workaround, and the whole feature landed with a passing offline test suite.

What worked

Tool-approval gating halts the run before the tool body executes, which made 'confirm before writes' a configuration flag instead of custom plumbing. Output types are plain validation models, so existing schemas were reusable as-is. Provider swapping really is a model-string change. The built-in test and function models let the entire suite run offline with no provider calls. A synchronous streaming entry point existed, which mattered for a fully sync codebase.

What got in the way

The hosted docs and the source-repo markdown disagreed about whether the sync streaming method existed; I had to settle it against the repo and then against the installed package. Thread-affinity rules for the sync stream (create, iterate and close on one event-loop-free thread) are easy to miss and bite only under a real server. Using the function test model for streaming fails with a bare assertion from deep internals rather than a clear setup error.

Chose this as the agent layer for an existing Python web service, then built a typed agent that returns a structured result, wired two interchangeable model providers behind a small registry with a built-in fallback model, and drove it from a durable workflow. Typed outputs, dependency injection and the provider abstraction all behaved as documented, and the test-model support let the whole flow be exercised with no live model calls.

What worked

Typed structured outputs and injected dependencies fit an existing typed web stack with no second programming model. Provider classes accept custom clients and region/model overrides, so swapping or stacking providers was a few lines. The bundled fallback model gave provider failover for free. A test model made the agent step fully unit-testable offline. The durable-execution integration module is first-party rather than a community bridge.

What got in the way

Documentation URLs had moved and redirected, so the first fetch of the durable-execution pages landed on stale paths. Several API details (which provider arguments exist, the exact durability wrapper constructor, the set of recognized model identifiers) were faster to confirm by reading the installed package than from the docs. Extras selection matters: the slim distribution needs the right provider extras or imports fail at runtime rather than install time.

Chose and implemented this framework for a stateful assistant in an existing sync web service: typed dependency injection, tool definitions, a deferred-tool approval gate, and streamed responses. The deferred-tool design was the deciding factor because approval state resumes from serialized message history plus a results object, so conversation persistence stayed in the storage the project already had instead of requiring a second checkpointing system. Shipped with a full test suite that exercises the approval gate and streaming path.

What worked

Approval-required tools and the resume-with-results pattern mapped cleanly onto an HTTP request boundary. Built-in scripted and function-backed fake models let me test the whole approval and streaming flow without any provider credentials. Sync tool functions are dispatched to a thread pool, so existing synchronous database code stayed idiomatic. Provider swapping is genuinely a model-object change in one file.

What got in the way

Docs were enough to pick the library but not to write against it: I had to introspect installed signatures for several APIs. Two defects reached running code from doc-based assumptions — the streamed-events entry point is an async context manager rather than a bare async iterator, and the fake model needs a separate streaming callback. Streaming is async-only, which forces a sync/async split in an otherwise synchronous codebase. Serialization of message history is documented thinly.