Migrating Deep Agents To Pydantic AI Harness

PydanticOfficialPublished by Pydantic

Skill
Workflow
Software development
MIT
No issues found

From the author

Migrate Python LangChain Deep Agents applications to Pydantic AI and Pydantic AI Harness. Use when the source uses the upstream `deepagents` package or demonstrably reproduces its middleware, backends, skills, memory, subagents, or sandbox contracts. Use `migrating-langchain-to-pydantic-ai` for plain LangChain, LangGraph, or LCEL migrations and `pydantic-ai-harness` for greenfield Harness usage.

— the description by Pydantic

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured methodology for transitioning existing Deep Agents applications to the Pydantic AI ecosystem. It emphasizes preserving observed application contracts and runtime behavior rather than performing a direct code-to-code translation of framework primitives. The process involves establishing the source contract, mapping features to Pydantic AI and Harness capabilities, and verifying the migration through rigorous parity testing.

What it does

Maps Deep Agents middleware, backends, and skills to Pydantic AI primitives and Harness capabilities.
Provides a step-by-step procedure for tracing request lifecycles from source to target.
Guides the construction of Pydantic AI Agents using typed dependencies and RunContext.
Outlines strategies for preserving application-level state, orchestration, and side-effect recovery.
Defines validation protocols to ensure parity in request, error, and event shapes.
Offers guidance on handling complex features like subagents, sandboxes, and durable execution.

When to use it

When migrating an application that uses the upstream deepagents package.
When you need to move from Deep Agents to Pydantic AI while maintaining existing business logic and contracts.
When you need to verify that the new Pydantic AI implementation matches the original application's behavior.
When you need to integrate Harness capabilities into an existing agent-based architecture.

Advantages

Ensures functional parity by focusing on contract preservation rather than framework-specific syntax.
Reduces regression risks through a structured, slice-based migration approach.
Provides clear mapping paths for complex components like sandboxes, skills, and middleware.
Maintains application-level control over infrastructure and state management.

Usage examples

“How do I migrate my Deep Agents file-system tools to Pydantic AI Harness?”: The agent will guide you to use the FileSystem capability, mapping Deep Agents file paths to Harness path schemas and ensuring permissions are handled via wrapper toolsets.
“What is the recommended approach for migrating custom middleware from Deep Agents?”: The agent will help you identify whether the middleware should be implemented as a Pydantic AI Hook, a wrapper toolset, or a focused Harness capability based on its specific function.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/pydantic/migrating-deep-agents-to-pydantic-ai-harness/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip migrating-deep-agents-to-pydantic-ai-harness.zip -d .agents/skills

Documentation by Pydantic

Migrate Deep Agents to Pydantic AI Harness

Preserve the application's observed contracts, not the shape of create_deep_agent. Compose Pydantic AI primitives and Harness capabilities; keep infrastructure with the application that already owns it.

Establish the source contract

Resolve the deepagents import origin before applying these mappings. Route a local module or project-owned create_deep_agent to the ordinary LangChain migration only when its implementation has ordinary LangChain or LangGraph semantics; vendored implementations that reproduce Deep Agents contracts remain in scope. Read repository instructions, manifests, lockfiles, tests, runtime entrypoints, and the resolved source. Record exact Deep Agents, LangChain, LangGraph, Pydantic AI, and Harness versions. If the locked source is unavailable, reproduce its environment without changing the target lockfile. If that is not possible, mark affected behavior unverified and do not claim parity.
Trace one representative request through prompt and model profile, tools and integrations, middleware and permissions, backend and execution, skills and memory, delegation, state, checkpoints and approvals, retries and limits, events, side effects, and the public boundary. Inspect every caller of that boundary.
Run the cheapest deterministic baseline. Record evidence separately from the outcome: source-inspected, probe-observed, or regression-tested.
Load only the mapping needed for the detected source features:
- Core Migration for construction, models and profiles, prompts, tools and MCP, middleware, state, outputs, caching, or tracing.
- Context and Execution for coding-agent defaults, planning, files, permissions, backends, sandboxes, interpreters, media, skills, memory, retrieval, or context limits.
- Orchestration and Recovery for synchronous, dynamic, or background subagents; grading loops; approvals; checkpoints; fault tolerance; durable execution; or streaming.
- Hosts and Protocols only when migrating Deep Agents Code, a frontend, ACP, A2A, or a deployment boundary.

Build the Pydantic AI target

Start with one reusable Agent. Pydantic AI owns the model/provider boundary, normalized messages, agent loop, typed dependencies and outputs, tools and toolsets, run APIs, usage limits, and generic hooks.
Put authenticated identity, service clients, and configuration in deps_type and RunContext; expose only model-chosen inputs through typed tools. Choose instructions versus system_prompt from the required history behavior, and consume result.output rather than leaking framework messages through the application boundary.
Add Harness capabilities one at a time for observed optional behavior. A capability composes instructions, toolsets, hooks, and model settings onto the agent; it does not replace application infrastructure or Pydantic AI runtime semantics.
Select run_sync, run, run_stream, run_stream_events, iter, deferred results, and message history from the caller's actual lifecycle. Preserve the old wire shape with a boundary adapter while callers migrate.
Before coding, inspect the locked pydantic_ai and pydantic_ai_harness public exports, docs, and source signatures for the selected provider, Agent, tools/toolsets, capabilities, run and deferred APIs, and persistence integration. Import capabilities from their owning public submodules, reject deprecation warnings, and run an import-and-construction smoke test in the exact target environment. Record the interpreter and resolved pydantic_ai and pydantic_ai_harness module paths with the result. Add only the required extras; do not pass LangChain objects through or copy remembered examples.
Keep queues, tenancy, artifact storage, remote sandbox lifecycle, durable domain state, deployment, and external side-effect recovery in application services.
Classify orchestration as model-controlled delegation, a fixed application workflow, or a background worker before selecting SubAgents or DynamicWorkflow; keep fixed sequencing and worker queues in application code.
If public Pydantic AI primitives cannot implement required generic runtime semantics correctly, propose the core primitive instead of recreating the runtime in Harness.

When there is no direct equivalent, do not stop at "unsupported." State the source contract and impact, then recommend either an existing composition, a narrow adapter or application service, a new Harness capability built from public primitives, or a Pydantic AI core change. Recommend one option and name its residual risk; ask before choosing when the options materially change behavior, architecture, public API, or scope.

Migrate and verify

Port one vertical slice behind the existing application boundary: typed dependencies, one tool family, output, and one representative request.
Preserve source request, result, error, event, and continuation shapes with a small adapter while callers migrate.
Run the original suite together with focused characterization, parity, and evaluation checks before expanding to the next capability. Exercise the supported Agent boundary in the same interpreter and installed checkout the target will use; do not accept results from another environment. Read Tested Composition only when a local coding-agent composition is useful.
Read Validation and Cutover before publishing examples or claiming cutover; for a simple slice, use only the applicable checks.
Cut over only when each in-scope contract is regression-tested, intentionally changed with agreement, or explicitly not applicable. Report anything else as unverified.

Match validation to observed contracts. Focused characterization and parity tests are sufficient for a stateless slice; persistence, approvals, concurrency, streaming, and external side effects require the ledger and applicable restart and idempotency checks.

Files

ATTRIBUTION.mdAdded by AutoGineer905 B
LICENSELicence file added by AutoGineer1.1 KiB
SKILL.md6.5 KiB
agents/openai.yaml258 B
references/CONTEXT-AND-EXECUTION.md7.3 KiB
references/CORE-MIGRATION.md4.1 KiB
references/HOSTS-AND-PROTOCOLS.md2.4 KiB
references/ORCHESTRATION-AND-RECOVERY.md6.0 KiB
references/TESTED-COMPOSITION.md2.3 KiB
references/VALIDATION.md4.9 KiB

references/ORCHESTRATION-AND-RECOVERY.md

Orchestration and Recovery

Read only when the source uses subagents, grading loops, approvals, checkpoints, retries, durable execution, or streaming.

Import SubAgent and SubAgents from pydantic_ai_harness.subagents. Harness can load its Markdown agent format from configured folders, but it does not consume a Deep Agents YAML roster. Parse and validate retained application configuration into explicit Agent and SubAgent objects, or intentionally convert it: YAML system_prompt becomes Agent.instructions or the Markdown body, description remains the description, and tools become explicit toolsets or a tool_resolver. Set the child model explicitly or through AgentOverride; a model key in Harness Markdown is parsed but not applied.

Deep Agents feature	Pydantic AI and Harness candidate	Important difference
synchronous named children	`SubAgents`	Inspect the automatic general-purpose child and disablement, isolated versus forked context, declarative versus compiled children, tools, skills, permissions, approvals, state, structured results, and streaming inheritance. Harness does not transfer mutable parent capability state implicitly; use explicit dependencies or state transfer, `shared_capabilities`, or an application repository, then test child write visibility.
model-written fan-out or chaining	`DynamicWorkflow`	This is a redesign, not an API port: Deep Agents generates JavaScript for QuickJS and calls `task(...)`; Harness generates Python for Monty and calls child agents from `run_workflow`. Verify structured results, interpreter and thread state, nesting, and tool boundaries. Neither is a durable background task service.
`AsyncSubAgent` background work	an application queue/worker and narrow agent tools	Preserve graph ID, transport and authentication, start/check/update/cancel/list operations, task/thread/run identity, pending state, stale reads, steering, cancellation, and result durability. Harness synchronous delegation and generated workflows are not background-task services.
`RubricMiddleware` grading loop	an explicit evaluator/revision loop or focused capability	Preserve the invocation rubric, grader model and tools, revision feedback, iteration limit, terminal verdict, callbacks, and progress events. `TrajectoryJudge` provides cadence-based mid-run steering, so use it only when that different lifecycle is accepted.
approval or `interrupt_on`	Pydantic AI `DeferredToolRequests`, `DeferredToolResults`, `ToolApproved`, and `ToolDenied`	Include `DeferredToolRequests` in `output_type`. When returned, persist `result.all_messages()`, resolve the request with `build_results(...)`, then call `run(message_history=..., deferred_tool_results=...)`. Use `HandleDeferredToolCalls` only for an in-process handler whose lifecycle is sufficient. The LangGraph `Command(resume=...)` protocol is not reproduced.
provider-valid run snapshots	`StepPersistence`	It records step events, continuable snapshots, lineage, and tool effects; it is not arbitrary LangGraph graph-state checkpointing.
durable model and tool execution	`TemporalDurability`, `DBOSDurability`, `PrefectDurability`, `AWSLambdaDurability`, `AbsurdDurability`, `PGTaskDurability`, or another matching integration	Select by the deployment contract and install its extra. Wire the integration's workflow or handler boundary, not only its capability; verify crash and redeploy recovery, replay, timers, signals, and side-effect idempotency in that runtime.
retries, fallbacks, and call limits	Pydantic AI tool/output retries, provider or model transport retries, `pydantic_ai.models.fallback.FallbackModel`, `UsageLimits`, and application or durable-workflow policy	Classify expected versus unexpected errors and retry scope. Match backoff, fallback order, tool-error visibility, counters, terminal propagation, and side-effect idempotency.
LangGraph and Deep Agents event streaming	Pydantic AI streaming APIs plus Harness event handlers	Translate the application's selected modes and projections. Namespaced graphs and Deep Agents subagent handles with child identity, status, messages, tool calls, nested work, and output are not preserved automatically.

Explicit designs for gaps

Forked child context or compiled LangGraph children: pass selected context explicitly, rebuild the child with Pydantic AI primitives, or retain it behind a typed tool boundary during migration.
Background subagents: keep the queue and worker in the host. Give the agent narrow start, list, inspect, steer, and cancel tools with tenant checks, idempotency keys, bounded retries, and durable results.
Approvals: test approve, deny, changed arguments, stale decisions, authorization changes, crash before and after execution, replay, and side-effect idempotency.
Checkpoints: separate message continuation, capability state, plans, files, approvals, domain state, and side effects. Do not replace a LangGraph checkpointer keyed by thread_id with StepPersistence without designing thread identity, message_history continuation, and ownership of the remaining state. Use StepPersistence only for its documented snapshot contract.
Streaming: verify lineage, ordering, backpressure, redaction, child and tool events, error termination, and final-output timing.

Primary sources: Deep Agents subagents, async subagents, grading rubrics, human-in-the-loop, fault tolerance, event streaming, Pydantic AI deferred tools, and durable execution.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by

Pydantic

Publisher

Pydantic (Official)

Source

pydantic/skills · skills/migrating-deep-agents-to-pydantic-ai-harness · commit 98f591c

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Also distributed in

pydantic/skills

AutoGineer is not affiliated with or endorsed by Pydantic or Pydantic.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download migrating-deep-agents-to-pydantic-ai-harness.zip