|
| 1 | +--- |
| 2 | +name: migrate-deep-agents-to-pydantic-ai |
| 3 | +description: Converts and audits Python LangChain Deep Agents applications, create_deep_agent projects, and Deep Agents Code or deploy layouts using Pydantic AI plus pydantic-ai-harness capabilities. Use when migrating, reviewing, or validating a Deep Agents project, or a LangGraph harness that specifically uses Deep Agents-style middleware, backends, HarnessProfile behavior, AGENTS.md or skills, subagents, sandboxes, planning, memory, streaming, approvals, or persistence. |
| 4 | +--- |
| 5 | + |
| 6 | +# Migrate Deep Agents to Pydantic AI |
| 7 | + |
| 8 | +Translate behavior and operational guarantees, not constructor arguments. Keep application orchestration outside the agent where it already owns queues, sandboxes, tenancy, deployment, or external side effects. |
| 9 | + |
| 10 | +## Assume Semantic Deltas |
| 11 | + |
| 12 | +- Treat every mapping, including `direct`, as a hypothesis rather than a claim of identical behavior. |
| 13 | +- Read [the semantic delta and spike guide](references/SEMANTIC-DELTAS.md) before choosing the target architecture. |
| 14 | +- Show users every known or plausible change in prompts, tools, state, files, child results, errors, events, approvals, persistence, budgets, and side effects. |
| 15 | +- Spike each high-risk or uncertain mapping on the installed source and target versions. Discard the research probe; rewrite only lasting application contracts as project regression tests. |
| 16 | +- Keep target shape, parity disposition, and evidence status separate. A `direct` target can still have `unknown` parity and `unproved` evidence. Retain the old path or add an adapter instead of implying parity. |
| 17 | + |
| 18 | +## Workflow |
| 19 | + |
| 20 | +1. **Freeze the contract.** Record entry points, outputs, tools, filesystem and shell boundaries, subagent topology/state handoff, context policy, persistence, approvals, streaming, budgets, deployment surfaces, the resolved HarnessProfile, and the fully assembled effective prompt. Do not remove Deep Agents yet. |
| 21 | +2. **Inventory the project.** Resolve `SKILL_DIR` to the absolute directory containing this `SKILL.md`, run the bundled scanner from any working directory, and verify its findings manually. Read [the migration map](references/MIGRATION-MAP.md) for every detected feature. |
| 22 | + |
| 23 | + ```bash |
| 24 | + SKILL_DIR="<absolute path to this skill>" |
| 25 | + python3 "$SKILL_DIR/scripts/inventory_deepagents.py" <project-root> |
| 26 | + ``` |
| 27 | +3. **Inspect installed APIs.** Check the project's locked versions and importable symbols. Treat Harness APIs as version-sensitive; prefer the installed package, its bundled README files, and official docs over remembered imports. |
| 28 | +4. **Build the delta ledger.** Create one row per independently testable invariant; split broad features such as subagents or persistence into state, result, routing, failure, concurrency, and recovery rows. Record target candidate, plausible delta, spike evidence, user impact, and rollback. Keep three fields independent: target shape (`direct`, `composed`, `custom`, `retain externally`, or `unknown`), parity disposition (`exact`, `compatible`, `intentional change`, or `unknown`), and evidence status (`unproved`, `source-inspected`, `spike-observed`, `regression-locked`, or `production-observed`). |
| 29 | +5. **Choose the target shape.** Use a plain `Agent` for one agent loop, `SubAgents` for occasional delegation, `DynamicWorkflow` for scripted fan-out/chaining, `pydantic_graph` for an application state machine, and a durable runtime for crash-safe orchestration. |
| 30 | +6. **Build one vertical slice.** Port typed deps, one tool family, output type, and one representative request. Keep adapters around existing LangChain tools only as a temporary seam. |
| 31 | +7. **Add harness behavior deliberately.** Compose only the capabilities the contract needs. Read only the matching recipe sections routed below. |
| 32 | +8. **Close real gaps with executable workarounds.** Read [the validated workaround guide](references/WORKAROUNDS.md) for every `composed`, `custom`, or `retain externally` target shape. Copy or adapt the bundled capability, toolset, facade, or application-boundary assets; run the same source-contract assertion against the target. Do not stop at documenting a missing equivalent. |
| 33 | +9. **Migrate by risk.** Port read-only tools before writes, local runs before persistence, synchronous delegation before background work, and deterministic hooks before deployment integrations. |
| 34 | +10. **Verify parity.** Follow [the validation guide](references/VALIDATION.md). Compare outputs, tool traces, budgets, failure modes, approval pauses, resume behavior, and side effects—not just whether the new agent answers. |
| 35 | +11. **Cut over reversibly.** Keep the old path behind a flag until representative evals pass; then remove framework-specific adapters and dependencies. |
| 36 | + |
| 37 | +## Translation Rules |
| 38 | + |
| 39 | +- Prefer typed dependencies (`deps_type` + `RunContext`) over global clients or graph context dictionaries. |
| 40 | +- Prefer Pydantic output models over prompt-only response formats. |
| 41 | +- Prefer toolsets for related tools, capabilities for reusable tools plus instructions or hooks, and `Hooks` for narrow interception. |
| 42 | +- Treat static repository instructions, writable memory, message history, and durable checkpoints as four different concerns. |
| 43 | +- Enforce permissions in tools, toolsets, sandboxes, and application credentials. Prompt instructions are not a security boundary. |
| 44 | +- Bound every recursive or fan-out path with request, token, call-count, timeout, and external-side-effect limits as appropriate. |
| 45 | +- Preserve model-visible tool errors for recoverable mistakes; propagate infrastructure and invariant failures unless the contract explicitly contains them. |
| 46 | +- Do not treat Harness `Shell` command filters as isolation. Use an OS/container/remote sandbox when untrusted model-written commands require a hard boundary. |
| 47 | +- When an asset tool requires approval, include `DeferredToolRequests` in the agent output or install a tested deferred-call handler; persist messages and pending application state before returning control. |
| 48 | +- If Code Mode is present, use an explicit safe-tool selector such as `CodeMode(tools={'code_mode': True})`; never use `tools='all'` with guarded asset tools. |
| 49 | +- Do not describe `StepPersistence` as a full LangGraph checkpoint. It records events and provider-valid message snapshots; use durable execution or application state for stronger resume guarantees. |
| 50 | + |
| 51 | +## Project Patterns |
| 52 | + |
| 53 | +Read only the matching project playbook: [Open SWE](references/PROJECT-PATTERNS.md#open-swe), [Deep Research](references/PROJECT-PATTERNS.md#deep-research), [Content Builder](references/PROJECT-PATTERNS.md#content-builder), [Text-to-SQL](references/PROJECT-PATTERNS.md#text-to-sql), [deploy coding](references/PROJECT-PATTERNS.md#deploy-coding-agent), or [deploy GTM](references/PROJECT-PATTERNS.md#deploy-gtm-agent). Use it as a decomposition example, not a copy-paste template. |
| 54 | + |
| 55 | +## Reference Routing |
| 56 | + |
| 57 | +- Always use [the minimal agent](references/RECIPES.md#a-minimal-agent) and [typed dependencies](references/RECIPES.md#typed-tools-and-dependencies) when implementing. |
| 58 | +- Read [the composed long-horizon agent](references/RECIPES.md#a-composed-long-horizon-agent) only when inventory justifies planning, repository context, filesystem, shell, overflow, or compaction. |
| 59 | +- Read [delegation](references/RECIPES.md#subagents) or [dynamic workflows](references/RECIPES.md#dynamic-workflows) only when inventory finds child agents or fan-out. |
| 60 | +- Read [context and memory](references/RECIPES.md#context-memory-and-history) or [filesystem, shell, and Code Mode](references/RECIPES.md#filesystem-shell-and-code-mode) only for those detected surfaces. |
| 61 | +- Read [approvals](references/RECIPES.md#approvals-and-policy), [streaming](references/RECIPES.md#streaming-and-mid-run-messages), [persistence](references/RECIPES.md#persistence), or [LangChain adapters](references/RECIPES.md#transitional-langchain-tools) only when required. |
| 62 | +- Read [skill capabilities](references/EXTENDING-THE-HARNESS.md#turn-one-skill-into-a-deferred-capability), [skill catalogs](references/EXTENDING-THE-HARNESS.md#load-a-directory-of-existing-skills), [background jobs](references/EXTENDING-THE-HARNESS.md#build-background-subagents), [remote sandboxes](references/EXTENDING-THE-HARNESS.md#wrap-a-remote-sandbox), [middleware](references/EXTENDING-THE-HARNESS.md#translate-middleware), or [ordered policy](references/EXTENDING-THE-HARNESS.md#implement-ordered-policy) only for a matching gap. |
| 63 | +- For planning, virtual state files, source-shaped invocation, child JSON/state merge, native approval, background jobs, remote sandboxes, or skill catalogs, start from the tested modules in `assets/parity_workarounds/` rather than rewriting them from memory. |
| 64 | + |
| 65 | +## Deliverables |
| 66 | + |
| 67 | +Produce: |
| 68 | + |
| 69 | +- an inventory and behavior contract; |
| 70 | +- a semantic delta ledger with spike evidence for every high-risk or uncertain mapping; |
| 71 | +- a mapping with target shape, parity disposition, and evidence status for every feature; |
| 72 | +- a staged migration plan; |
| 73 | +- migrated code and deterministic tests when implementation is requested; |
| 74 | +- a named executable workaround and target parity test for every non-`direct` mapping; |
| 75 | +- an explicit gap and risk register; |
| 76 | +- evidence from parity tests and traces. |
0 commit comments