Deep Agents Mapping

Use this reference when the slice calls create_deep_agent, or a vendored equivalent, or depends on Deep Agents middleware, backends, profiles, skills, memory, subagents, permissions, sandboxes, or hosts. Deep Agents is an opinionated harness over the LangChain agent loop and the LangGraph runtime; Pydantic AI Harness is the matching capability library over the Pydantic AI agent loop. Map behavior to behavior, then confirm every candidate against the locked source and target versions. Rows that concern the plain agent loop, tools, structured output, state, or streaming are in Concept Mapping; this file covers what the harness adds on top.

Contents

• What the harness bundles
• Construction, models, and middleware
• Context and execution
• Orchestration and recovery
• Hosts and protocols
• A tested Harness composition
• Migration traps

What the harness bundles

Translating constructor arguments one by one misses the harness. Snapshot the resolved agent instead: the effective prompt, the model-visible tool list, the middleware order on the main agent and on every subagent, the state schema, and the runtime configuration. In current deepagents releases the defaults are:

• Tools: ls, read_file, write_file, edit_file, glob, and grep; execute only when the resolved backend supports shell execution; task when inline subagents or the general-purpose child are enabled. write_todos exists only before 0.7 or with an explicitly configured todo middleware.
• Prompt: the caller's system_prompt, then the harness profile's base_system_prompt, then its system_prompt_suffix, with skills, memory, and filesystem middleware injecting more text per request.
• Middleware order: skills, filesystem, subagents, summarization, patch-tool-calls, async subagents; then caller middleware; then profile extra_middleware, tool exclusion, provider prompt caching, memory, and human-in-the-loop. Profiles can exclude entries by class or name.
• Profiles: HarnessProfile shapes prompt layers, tool descriptions and exclusions, excluded middleware, and the general-purpose child; ProviderProfile shapes model construction. A Pydantic AI model profile configures provider behavior only; it never configures the Harness composition, so profile-driven differences must be reproduced explicitly.
• Subagent stacks: each declarative child gets its own filesystem, skills, memory, and exclusion middleware; a compiled child is whatever the caller built; an AsyncSubAgent is a remote LangGraph deployment. A behavior seen only during delegated work may come from any of these.

Record which of these the application actually exercises. An unused default is not-applicable, not a migration task.

Construction, models, and middleware

Adapt LangChain @tool and StructuredTool objects to typed Pydantic functions or toolsets. Preserve their names, schemas, return values, and errors rather than passing framework objects through unchanged; the transitional wrappers in Concept Mapping apply here too.

For MCP, use pydantic_ai.capabilities.MCP when provider-native or client-side selection is needed; use pydantic_ai.mcp.MCPToolset for client-side MCP connections. Preserve transport, authentication, tool filtering, structured content, connection and session lifetime, elicitation, sampling, retries, and tracing at the integration boundary.

Context and execution

Import each capability from its owning public module, for example Skills from pydantic_ai_harness.skills and RepoContext from pydantic_ai_harness.repo_context; do not use compatibility modules left behind by a rename.

For pluggable or composite backends (StateBackend, StoreBackend, FilesystemBackend, CompositeBackend, sandbox backends), expose the existing storage or sandbox service through a focused toolset or capability. Preserve runtime-injected backend factories, route prefixes, path, tenancy, transaction, sandbox ownership, and lifecycle contracts instead of forcing them through local FileSystem. Preserve each route's storage lifetime and ownership: do not replace an ephemeral StateBackend route with persistent filesystem or store state.

Enforce authorization and isolation at the backing service. Treat prompt instructions, globs, path checks, and shell allowlists as defense in depth.

Orchestration and recovery

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.

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.
• Streaming: verify lineage, ordering, backpressure, redaction, child and tool events, error termination, and final-output timing.

Hosts and protocols

Migrate the underlying agent separately, then preserve the external contract with an adapter.

If the target lacks a protocol feature, retain the existing adapter or propose a focused adapter built on public Pydantic AI run, message, event, and deferred-tool primitives. Do not bury a wire-level behavior change inside the agent migration.

A tested Harness composition

Use this smoke test when a local coding-agent composition is plausible; Coder(workspace) is shorter when its documented defaults match the source. Run it in the exact target environment: it proves that imports and public constructor signatures resolve against the locked versions, not that behavior matches the source application.

# ruff: noqa: I001
import asyncio
from collections.abc import AsyncIterator
from pathlib import Path
from tempfile import TemporaryDirectory

from pydantic_ai import Agent
from pydantic_ai.messages import ModelMessage
from pydantic_ai.models.function import AgentInfo, FunctionModel
from pydantic_ai.models.test import TestModel

from pydantic_ai_harness.compaction import SlidingWindowCompaction
from pydantic_ai_harness.filesystem import FileSystem
from pydantic_ai_harness.planning import Planning
from pydantic_ai_harness.repo_context import RepoContext
from pydantic_ai_harness.skills import Skills
from pydantic_ai_harness.subagents import SubAgent, SubAgents


async def stream(_messages: list[ModelMessage], _info: AgentInfo) -> AsyncIterator[str]:
    yield 'Workspace ready.'


worker = Agent(TestModel(call_tools=[]), name='researcher', description='Research a bounded question.')

with TemporaryDirectory() as workspace:
    root = Path(workspace)
    skill = root / 'skills' / 'inspect-workspace'
    skill.mkdir(parents=True)
    (skill / 'SKILL.md').write_text(
        '---\nname: inspect-workspace\ndescription: Inspect a workspace.\n---\nUse read-only tools.',
        encoding='utf-8',
    )
    migrated = Agent(
        FunctionModel(stream_function=stream),
        output_type=str,
        instructions='Work only inside the configured workspace.',
        capabilities=[
            Planning(),
            FileSystem(root, read_only=True),
            RepoContext(workspace_dir=root),
            Skills(root / 'skills'),
            SubAgents(agents=[SubAgent(worker, max_calls=1)], agent_folders=None),
            SlidingWindowCompaction(max_messages=20, keep_messages=10),
        ],
    )
    result = asyncio.run(migrated.run('Describe the available workspace tools.'))
    assert isinstance(result.output, str)
    assert result.all_messages()

Use TestModel(call_tools=[]) for construction-only checks and a FunctionModel with scripted tool calls when a test claims tool behavior. Event-aware capabilities such as RepoContext can make Agent.run() use the streamed model path, so provide stream_function and execute the complete composition once rather than inferring the path from the model stub.

Migration traps

• Treating a deepagents import as out of scope, or as a reason to hand the migration to another skill, instead of mapping the bundled features it actually uses.
• Translating create_deep_agent(...) arguments without snapshotting the profile-resolved prompt, tools, and middleware.
• Passing a LangChain BaseChatModel or LangChain tools through unchanged.
• Replacing a sandbox backend with local Shell or FileSystem, or treating path checks and allowlists as the isolation boundary.
• Turning /memory/... file paths into Harness Memory without preserving the tool names, paths, and injection role callers depend on.
• Replacing a LangGraph checkpointer with StepPersistence or message_history alone.
• Assuming write_todos, the general-purpose child, or summarization exists on the source without checking the installed version and profile.
• Reproducing AsyncSubAgent with synchronous SubAgents or DynamicWorkflow.

Primary sources: Deep Agents architecture, create_deep_agent source, profiles, backends, permissions, sandboxes, subagents, async subagents, human-in-the-loop, Deep Agents Code, Pydantic AI Harness, Pydantic AI capabilities, deferred tools, and durable execution.