Context and Execution
Read only when the source uses coding-agent defaults, planning, files, backends, sandboxes, skills, memory, or context management. Confirm imports and extras against the locked Harness version.
Use the owning public modules. In particular, import Skills from pydantic_ai_harness.skills and RepoContext from pydantic_ai_harness.repo_context; do not use compatibility modules left behind by a rename.
| Deep Agents feature | Harness candidate | Important difference |
|---|---|---|
| coding-agent defaults | Coder() plus a workspace capability (LocalWorkspace('.') or a sandbox) |
Compare its documented composition first. Coder fails at run start without a workspace. It is an opinionated local coding harness, not a semantic guarantee of Deep Agents parity. Use individual capabilities when a component must change. |
| todo planning | Planning |
Deep Agents before 0.7, or an explicitly configured TodoListMiddleware, exposes write_todos; current 0.7.x defaults do not. Add Planning only when that behavior exists or is an accepted addition. Harness has its own schema, tools, reminder injection, events, and stores. |
| local workspace files | FileSystem |
It works in the run's workspace, bounded by root_dir (the working directory by default); it is not Deep Agents' virtual BackendProtocol. Compare the installed tool schemas and source limits: for example, Deep Agents file tools use file_path, while Harness uses path, and backend file-size limits need a separate guard. |
| filesystem permissions | a wrapper toolset or capability, deferred approval, and backing-service authorization | Preserve operation classes, first-match rule order, unmatched-call behavior, allow/deny/interrupt results, route-relative paths, and child overrides. Deep Agents interrupt rules require a checkpointer; persist and restore the target approval continuation too. The rules cover built-in file tools, not arbitrary tools, direct backend access, or sandbox commands. |
| host or local shell execution | Shell |
It runs commands in the run's workspace: host subprocesses with LocalWorkspace. Its command filtering cannot preserve a sandbox backend's OS isolation; use a sandbox workspace for that. |
| remote isolated execution | ModalSandbox or another sandbox capability |
Match lease, filesystem, network, credential, reconnect, timeout, and cleanup contracts. |
| interpreter and programmatic tool calling | CodeMode, DynamicWorkflow, or an application interpreter |
Deep Agents QuickJS eval defaults to thread persistence; the other modes are turn and call. task() is enabled with subagents, while tools.* requires an allowlist. Harness uses Monty and different tool schemas. Match state lifetime, structured results, resource limits, and authority; interpreter bridges can bypass ordinary tool-approval paths unless guarded explicitly. |
| multimodal input, file reads, or tool results | Pydantic AI user-content and ToolReturn; pydantic_ai_harness.media stores and walkers for persistence offload |
Keep model-facing content in Pydantic AI types. With StepPersistence, configure media_store on its FileStepStore, SqliteStepStore, MongoStepStore, or PostgresStepStore; for another serializer, use externalize_media and restore_media directly. Preserve order, MIME support, provider filtering, references, serialization, and restoration. |
| Agent Skills | Skills |
Pass the parent skill-library directory, whose immediate children are <name>/SKILL.md packages. Harness reads it from the run's workspace (or workspace=) at each run start, and offers each skill as a deferred capability the model loads with load_capability. For a static slice, normalize flat catalogs into this shape and use Skills; do not replace it with eager prompt concatenation. Preserve writable catalogs, tool names and results, bundled files, scripts, standard-root discovery, and behavioral frontmatter with a focused service only when those contracts matter. |
| repository instructions and asset inventory | RepoContext |
It starts at the workspace's working directory. Configure home_dir, filenames, autoload_instructions, expose_inventory_tool, inventory_tool_name, asset_roots, nested_traversal, and nested_inject from observed discovery and injection behavior. Compose it with FileSystem when file traversal should inject nested context. It does not replace skill activation or writable memory. |
| writable long-term memory | Memory |
Check namespace, store, injection role and bound, search, concurrency, retention, and deletion. Deep Agents memory=[...] injects backend-relative files; use explicit instructions for static content, RepoContext only for repository-owned context, or an adapter/application store for arbitrary files. If callers use file tools at paths such as /memory/..., preserve those names and paths with a filesystem/tool adapter, or intentionally change callers and prompts. Memory has different tools and namespace semantics. |
| retrieval or RAG | existing retrieval services exposed as typed tools; a focused Harness search capability only when it matches | Retrieval is application data access, not Deep Agents memory or a filesystem backend. Preserve ingestion, chunking, filters, tenancy, ranking, metadata, citations, result bounds, latency, and failure shapes. |
| context summarization | compaction capabilities, often TieredCompaction |
Harness rewrites Pydantic AI message history. Match thresholds, summary prompt and role, tool-pair validity, receipts, usage, and recovery. |
| oversized tool-result offload | ToolOutputLimits with matching bands/store, or the retained backend artifact path |
Use ToolOutputLimits(store=...) only when its overflow-store contract matches. Otherwise retain or adapt the backend artifact path. Deep Agents human-message eviction needs separate handling. Verify thresholds, lossless versus lossy behavior, receipts, read-back, failure fallback, store lifetime, and serialization. |
For pluggable or composite 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.
Primary sources: Deep Agents changelog, backends, permissions, sandboxes, interpreters, multimodality, skills, memory, and Pydantic AI Harness.