DOCSEARCHbyAlgolia
Submit Docs

Pydantic Deep Agents

repository·main·Indexed 21 days ago

https://github.com/vstorm-co/pydantic-deepagents

A batteries-included agent harness for Python built on Pydantic AI, featuring tool-calling, sandboxed execution, multi-agent teams, and 'Live Run Forking'. The project provides a Python framework for building deep agents and a self-hosted terminal AI assistant. It includes specialized implementations such as DeepResearch, an autonomous research agent, and an ACP server for integration with the Zed editor.

Tokens
192.7K
Snippets
457
Records
855
Agent score
72%

What's inside pydantic-deep

  1. Overview of Pydantic Deep Agents capabilities

    main

    Pydantic Deep Agents provides several out-of-the-box capabilities for autonomous AI assistants:

    CapabilityDescription
    PlanningA built-in todo list for breaking work down and tracking progress
    FilesystemRead, write, and edit files, with grep and glob
    Sub-agentsDelegate focused tasks to isolated specialists
    SkillsModular capability packages, loaded on demand
    BackendsStorage and execution environments: StateBackend, LocalBackend, DockerSandbox, CompositeBackend
    Context managementAutomatic summarization to prevent context window overflow

  2. Overview of Agent Capabilities

    main

    Pydantic Deep Agents allows you to build agents with a progressive capability lifecycle. As you build, you can add the following features to your agent:

    • File I/O: Read and write files.
    • Shell Access: Run shell commands.
    • Planning: Enable the agent to plan its work.
    • Custom Tools: Call your own defined tools.
    • Delegation: Delegate tasks to sub-agents.
    • Streaming: Stream the agent's thinking process.
    • Human-in-the-loop: Ask for user permission before performing risky actions.
    • Persistence: Remember information between sessions.

  3. Core Features of pydantic-deep

    main

    The framework provides several high-level capabilities for autonomous agents:

    • Planning: Task tracking with subtasks, dependencies, and cycle detection.
    • Filesystem: Full file operations (ls, read_file, write_file, edit_file, glob, grep, execute) with Docker sandbox support and a permission system.
    • Subagents: Synchronous/asynchronous delegation, background tasks, and cancellation support.
    • Summarization: LLM-based summaries or zero-cost sliding window options.
    • Cost Tracking: Automatic enforcement of token and USD budgets.
    • Hooks: Lifecycle hooks to run shell commands on tool events.
    • Checkpointing: Ability to save, rewind, and fork conversation state.
    • Skills: Domain-specific skills loaded from SKILL.md files.
    • Context Files: Auto-discovery and injection of AGENTS.md and SOUL.md.
    • Memory: Persistent MEMORY.md across sessions.
    • Teams: Multi-agent coordination with shared TODOs and task claiming.
    • Web: Built-in WebSearch and WebFetch capabilities.

  4. Understand the Pydantic Deep Demo Agent Workspace Structure

    main

    When using the Pydantic Deep Demo Agent, the environment is organized into specific directories for managing files, user inputs, and specialized logic. Use these directories to ensure the agent can correctly locate and persist its work.

    Directory Map

    • /workspace/: The primary directory for all agent-generated output, including scripts, charts, and reports.
    • /uploads/: Contains files provided by the user (e.g., CSV, PDF, images, text) for the agent to process.
    • /skills/: Contains definitions for specialized capabilities like data-analysis, code-review, and test-generator.

  5. Technical Debt and API Design Report

    main

    This document provides a detailed audit of the pydantic-deep codebase, focusing on code quality, consistency, and API design. It identifies systemic issues such as improper type usage (e.g., using Any or dict[str, Any] instead of Pydantic models or Protocols), duplication of primitives, and the presence of 'god-objects' like DeepAgentDeps.

    Key areas of concern include:

    • Type Safety: Excessive use of Any and manual dictionary hydration instead of using ModelMessagesTypeAdapter or BaseModel.
    • Architecture: Oversized objects (DeepAgentDeps), incoherent boundaries between capabilities and toolsets, and duplicated logic for eviction and token estimation.
    • Maintenance: Dead code in EvictionProcessor and the need to relocate forking-specific types from the cross-cutting types.py to toolsets/forking/.

  6. Identify the available user interfaces

    main

    You can use pydantic-deepagents through four primary interfaces depending on your workflow:

    1. CLI App: A terminal-based AI assistant featuring interactive chat, streaming responses, slash commands, and session persistence.
    2. ACP Server: An integration for code editors (primarily Zed) using the Agent Client Protocol (ACP) via FastAPI.
    3. DeepResearch Web App: A browser-based interface for research agents, featuring real-time progress visualization, research tree visualization, and plan management via WebSockets.
    4. Python API: Direct programmatic access for building custom integrations and automated workflows.

  7. Use the CLI Terminal AI Assistant

    main

    The apps/cli package provides a Terminal User Interface (TUI) for interacting with Pydantic Deep Agents. It supports advanced features like multimodal input (images), parallel tool execution, and subagent management.

    Key capabilities include:

    • Multimodal Input: Paste images from the clipboard or reference files using @filename.
    • Tool Execution: View command outputs and file diffs directly in the terminal.
    • Subagent Management: Monitor active and idle subagents in a dedicated sidebar.
    • Session Control: Use ESC to cancel running tasks (note: ensure your backend supports process tree killing for reliable cancellation).

  8. Understanding the pydantic-deep architecture and quality status

    main

    The pydantic-deep framework is a factory for composing deep-agent capabilities and toolsets, heavily inspired by pydantic-ai. While functionally strong, the codebase is currently undergoing structural shifts to address technical debt in typing, primitive duplication, and API surface explosion.

    Key Architectural Concepts:

    • Capabilities vs. Toolsets: Capabilities (e.g., MemoryCapability, ContextFilesCapability) often manage instruction injection, while Toolsets (e.g., MemoryToolset) provide the actual functional tools.
    • DeepAgentDeps: The central dependency object used by capabilities to access framework features like the fork_coordinator or backend.
    • Forking: A major subsystem (comprising ~21.5% of the framework) that provides overlay, diff, and merge capabilities for agentic workflows. It includes advanced features like LLM-judging and subprocess testing, which are gated behind specific strategies.

  9. Explore Advanced Power Features in Pydantic Deep Agents

    main

    The Advanced User Guide provides specialized features that can be added to a standard agent. Most of these features are opt-in and can be enabled by passing a flag to create_deep_agent() or adding an item to the capabilities list, allowing you to add functionality without rewriting your existing agent logic.

    Advanced features are categorized into several functional areas:

    Lifecycle & Control

    • Capabilities & lifecycle: The foundational hook points for all other features.
    • Hooks: Execute custom code or shell commands before and after tool calls.
    • Stuck-loop detection: Detect and break cycles where an agent repeats itself.
    • Periodic reminders: Re-inject context on a schedule to keep the agent on track.

    Context & Cost

    • Context management: Manage long runs via eviction, summarization, and compaction to stay within token budgets.
    • Cost tracking & budgets: Track token spend in USD and enforce budget limits.

    Running & Steering

    • Goal loop: Maintain execution until a specific goal is met.
    • Monitor: Observe and react to agent runs in real time.
    • Message queue & steering: Send new instructions to an agent while it is currently running.
    • Live run forking: Branch a running agent to explore multiple paths in parallel.
    • Plan mode: Require the agent to draft and confirm a plan before execution.

    Scaling Out

    • Agent teams: Coordinate multiple agents using a shared todo list and message bus.
    • Multi-user / multi-tenant: Run isolated agents for multiple users safely.
    • Fallback models: Automatically switch to a different model if the primary one fails.

    Output & Tooling

    • Output styles: Customize the format of agent responses.
    • Browser: Provide a real browser for web navigation and interaction.
    • Document parsing: Convert PDFs and other documents into readable text.
    • Agent Spec: Define agents declaratively using a specification rather than imperative code.

  10. Overview of pydantic-deepagents extension layers

    main

    The project provides three distinct extension layers to enhance agent capabilities:

    1. Toolsets: FunctionToolset or AbstractToolset instances registered on the agent that provide callable tools and optional system prompt instructions.
    2. Capabilities: Lifecycle hooks and instruction injection mechanisms.
    3. Processors: A pipeline for transforming message history.

    Understanding these layers allows you to extend how agents interact with the environment, manage their own state, and communicate with other agents.

  11. What is the Pydantic Deep Agents Agent Harness?

    main

    Pydantic Deep Agents is an agent harness that provides the infrastructure required to turn an LLM into a functional autonomous agent. While the model provides intelligence, the harness provides the following capabilities:

    • Live run forking: Split a run into N isolated branches to try different approaches, using an AI judge or test results to pick a winner.
    • Tool-calling: Built-in support for file operations (read/write/edit), shell execution, glob, grep, web search, web fetch, and browser automation.
    • Multi-agent / swarm: Spawn subagents for parallel workstreams with shared TODO lists and a peer-to-peer message bus.
    • Persistent memory: Uses MEMORY.md to persist state across sessions, auto-injected into system prompts.
    • Unlimited context: Uses auto-summarization (LLM-based or sliding window) to prevent hitting token limits.
    • Sandboxed execution: Docker-based sandboxing with named workspaces where installed packages persist.
    • Plan Mode: A dedicated planner subagent that structures work and asks clarifying questions before execution.
    • Checkpoints: Ability to save conversation state, rewind, or fork sessions.
    • Skills system: Domain-specific knowledge loaded from SKILL.md files.
    • Document parsing: Local parsing of PDFs, DOCX, XLSX, PPTX, and images (via LiteParse).
    • MCP Support: Connect to Model Context Protocol servers (GitHub, Figma, etc.).
    • Lifecycle hooks: PRE/POST_TOOL_USE hooks for security and auditing.
    • Structured output: Type-safe Pydantic model responses.
    • Fallback models: Automatic hopping to a secondary model on API errors.
    • Stuck loop detection: Detects repeated or alternating tool call patterns.
    • Cost tracking: Real-time token and USD tracking with BudgetExceededError enforcement.

  12. What is a Deep Agent and how does it work?

    main

    Unlike a 'shallow' agent that responds in a single turn, a Deep Agent is designed to work until a job is completed. It follows a continuous loop of:

    1. Plan: Breaking complex tasks into smaller, manageable steps.
    2. Execute: Performing actions using provided toolsets.
    3. Iterate: Checking results and adjusting its approach based on feedback.
    4. Delegate: Spawning sub-agents to handle specialized sub-tasks.

    You do not manually orchestrate this loop; you provide the goal and the tools, and the agent decides when to plan, delegate, or finish.