{"id":34107257,"url":"https://github.com/vstorm-co/pydantic-deepagents","last_synced_at":"2026-03-12T04:02:32.525Z","repository":{"id":326699680,"uuid":"1106580780","full_name":"vstorm-co/pydantic-deepagents","owner":"vstorm-co","description":"Python Deep Agent framework built on top of Pydantic-AI, designed to help you quickly build production-grade autonomous AI agents with planning, filesystem operations, subagent delegation, skills, and structured outputs—in just 10 lines of code.","archived":false,"fork":false,"pushed_at":"2026-03-06T00:43:41.000Z","size":18630,"stargazers_count":411,"open_issues_count":1,"forks_count":40,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-03-06T05:00:02.231Z","etag":null,"topics":["agent-framework","anthropic","artificial-intelligence","business-intelligence","chatgpt","clawdbot","enterprise","framework","gemini","llms","mcp","moltbot","multiagent","open-source","openai","pydantic","pydantic-ai","python"],"latest_commit_sha":null,"homepage":"https://vstorm-co.github.io/pydantic-deepagents/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vstorm-co.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-29T14:36:36.000Z","updated_at":"2026-03-06T02:02:21.000Z","dependencies_parsed_at":"2025-12-15T11:01:31.743Z","dependency_job_id":null,"html_url":"https://github.com/vstorm-co/pydantic-deepagents","commit_stats":null,"previous_names":["vstorm-co/pydantic-deep","vstorm-co/pydantic-deepagents"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/vstorm-co/pydantic-deepagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-deepagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-deepagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-deepagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-deepagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vstorm-co","download_url":"https://codeload.github.com/vstorm-co/pydantic-deepagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vstorm-co%2Fpydantic-deepagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30415039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T00:40:14.898Z","status":"online","status_checked_at":"2026-03-12T02:00:07.260Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","anthropic","artificial-intelligence","business-intelligence","chatgpt","clawdbot","enterprise","framework","gemini","llms","mcp","moltbot","multiagent","open-source","openai","pydantic","pydantic-ai","python"],"created_at":"2025-12-14T18:05:26.725Z","updated_at":"2026-03-12T04:02:32.481Z","avatar_url":"https://github.com/vstorm-co.png","language":"Python","funding_links":[],"categories":["MCP Servers","Openai","Frameworks \u0026 Libraries"],"sub_categories":["Agent Platforms"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/baner.png\" alt=\"pydantic-deep\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ePydantic Deep Agents\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eFrom framework to terminal — autonomous AI agents that plan, code, and ship\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://vstorm-co.github.io/pydantic-deepagents/\"\u003eDocs\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://pypi.org/project/pydantic-deep/\"\u003ePyPI\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#cli--terminal-ai-assistant\"\u003eCLI\u003c/a\u003e \u0026middot;\n  \u003ca href=\"#deepresearch--reference-app\"\u003eDeepResearch\u003c/a\u003e \u0026middot;\n  \u003ca href=\"https://vstorm-co.github.io/pydantic-deepagents/examples/\"\u003eExamples\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/pydantic-deep/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/pydantic-deep.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10+-blue.svg\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://opensource.org/licenses/MIT\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-yellow.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://coveralls.io/github/vstorm-co/pydantic-deepagents?branch=main\"\u003e\u003cimg src=\"https://coveralls.io/repos/github/vstorm-co/pydantic-deepagents/badge.svg?branch=main\" alt=\"Coverage Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/vstorm-co/pydantic-deepagents/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/vstorm-co/pydantic-deepagents/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pydantic/pydantic-ai\"\u003e\u003cimg src=\"https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic\u0026logoColor=white\" alt=\"Pydantic AI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003e🔄 Unlimited Context\u003c/b\u003e\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003e🤖 Subagent Delegation\u003c/b\u003e\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003e🧠 Persistent Memory\u003c/b\u003e\n  \u0026nbsp;\u0026bull;\u0026nbsp;\n  \u003cb\u003e🛡️ Lifecycle Hooks\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\n### Same Architecture as the Best\n\npydantic-deep implements the **deep agent pattern** — the same architecture powering:\n\n| | Product | What They Built |\n|:-:|---------|-----------------|\n| 🤖 | [**Claude Code**](https://claude.ai/code) | Anthropic's AI coding assistant |\n| 🦾 | [**Manus AI**](https://manus.ai) | Autonomous task execution |\n| 👨‍💻 | [**Devin**](https://devin.ai) | AI software engineer |\n\n**Now you can build the same thing** — or just use the CLI.\n\n\u003e **Inspired by:** [LangChain's Deep Agents](https://github.com/langchain-ai/deepagents) research on autonomous agent architectures.\n\n---\n\n**pydantic-deep** is three things:\n\n1. **A Python framework** for building Claude Code-style agents with planning, filesystem access, subagents, memory, and unlimited context\n2. **A CLI** that gives you a terminal AI assistant out of the box\n3. **DeepResearch** — a full-featured research agent with web UI, web search, diagrams, and sandboxed code execution\n\n---\n\n## CLI — Terminal AI Assistant\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/cli_demo.gif\" alt=\"pydantic-deep CLI demo\" width=\"700\"\u003e\n\u003c/p\u003e\n\n```bash\npip install pydantic-deep[cli]\npydantic-deep chat\n```\n\nThat's it. You get an interactive AI agent in your terminal with:\n\n- File read/write/edit, shell execution, glob, grep\n- Task planning and subagent delegation\n- Persistent memory across sessions\n- Context compression for unlimited conversations\n- Git-aware project context\n- Built-in commands: `/commit`, `/pr`, `/review`, `/test`, `/fix`, `/explain`\n- Customizable skills, hooks, and output styles\n\n```bash\n# Interactive mode\npydantic-deep chat\n\n# Run a single task\npydantic-deep run \"Fix the failing tests in src/\"\n\n# Docker sandbox for isolated execution\npydantic-deep run \"Build a web scraper\" --sandbox\n\n# Pick a model\npydantic-deep chat --model anthropic:claude-sonnet-4-20250514\n\n# Manage config\npydantic-deep config set model openai:gpt-4.1\n```\n\n\u003e See [CLI docs](docs/cli/index.md) for the full reference.\n\n---\n\n## Framework — Build Your Own Agent\n\n```bash\npip install pydantic-deep\n```\n\n```python\nfrom pydantic_ai_backends import StateBackend\nfrom pydantic_deep import create_deep_agent, create_default_deps\n\nagent = create_deep_agent()\ndeps = create_default_deps(StateBackend())\n\nresult = await agent.run(\"Create a todo list for building a REST API\", deps=deps)\n```\n\nOne function call gives you an agent with planning, filesystem tools, subagents, skills, context management, and cost tracking. Everything is toggleable:\n\n```python\nagent = create_deep_agent(\n    model=\"openai:gpt-4.1\",\n    include_todo=True,          # Task planning\n    include_filesystem=True,    # File read/write/edit/execute\n    include_subagents=True,     # Delegate to subagents\n    include_skills=True,        # Domain-specific skills from SKILL.md files\n    include_memory=True,        # Persistent MEMORY.md across sessions\n    include_plan=True,          # Structured planning before execution\n    include_teams=True,         # Multi-agent teams with shared TODOs\n    include_web=True,           # Web search and URL fetching\n    context_manager=True,       # Auto-summarization for unlimited context\n    cost_tracking=True,         # Token/USD budget enforcement\n    include_checkpoints=True,   # Save, rewind, and fork conversations\n)\n```\n\n### Structured Output\n\n```python\nfrom pydantic import BaseModel\n\nclass CodeReview(BaseModel):\n    summary: str\n    issues: list[str]\n    score: int\n\nagent = create_deep_agent(output_type=CodeReview)\nresult = await agent.run(\"Review the auth module\", deps=deps)\nprint(result.output.score)  # Type-safe!\n```\n\n### Context Management\n\n```python\nfrom pydantic_deep import create_summarization_processor\n\nprocessor = create_summarization_processor(\n    trigger=(\"tokens\", 100000),\n    keep=(\"messages\", 20),\n)\nagent = create_deep_agent(history_processors=[processor])\n```\n\n### Hooks (Claude Code-Style)\n\n```python\nfrom pydantic_deep import Hook, HookEvent\n\nagent = create_deep_agent(\n    hooks=[\n        Hook(\n            event=HookEvent.PRE_TOOL_USE,\n            command=\"echo 'Tool called: $TOOL_NAME' \u003e\u003e /tmp/audit.log\",\n        ),\n    ],\n)\n```\n\n### Cost Tracking\n\n```python\nagent = create_deep_agent(\n    cost_tracking=True,\n    cost_budget_usd=5.0,\n    on_cost_update=lambda info: print(f\"Cost: ${info.total_usd:.4f}\"),\n)\n```\n\n### Custom Subagents\n\n```python\nagent = create_deep_agent(\n    subagents=[\n        {\n            \"name\": \"code-reviewer\",\n            \"description\": \"Reviews code for quality issues\",\n            \"instructions\": \"You are a senior code reviewer...\",\n            \"preferred_mode\": \"sync\",\n        },\n    ],\n)\n```\n\n\u003e See the full [API reference](https://vstorm-co.github.io/pydantic-deepagents/api/toolsets/) for all options.\n\n---\n\n## DeepResearch — Reference App\n\nA full-featured research agent with web UI, built entirely on pydantic-deep.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\u003ca href=\"apps/deepresearch/\"\u003e\u003cimg src=\"assets/planner_asks_question.png\" alt=\"Planner subagent asks clarifying questions\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003ePlan Mode\u003c/b\u003e — planner asks clarifying questions\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\u003ca href=\"apps/deepresearch/\"\u003e\u003cimg src=\"assets/spawn_subagents_deepresearch.png\" alt=\"Parallel subagent research\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eParallel Subagents\u003c/b\u003e — 5 agents researching simultaneously\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\"\u003e\n\u003ca href=\"apps/deepresearch/\"\u003e\u003cimg src=\"assets/excalidraw_in_deepresearch.png\" alt=\"Excalidraw canvas\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eExcalidraw Canvas\u003c/b\u003e — live diagrams synced with agent\u003c/p\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\"\u003e\n\u003ca href=\"apps/deepresearch/\"\u003e\u003cimg src=\"assets/display_files_deepresearch.png\" alt=\"File browser\"\u003e\u003c/a\u003e\n\u003cp align=\"center\"\u003e\u003cb\u003eFile Browser\u003c/b\u003e — workspace files with inline preview\u003c/p\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nWeb search (Tavily, Brave, Jina), sandboxed code execution, Excalidraw diagrams, subagents, plan mode, report export, and more.\n\n```bash\ncd apps/deepresearch\nuv sync\ncp .env.example .env  # Add your API keys\nuv run deepresearch    # Open http://localhost:8080\n```\n\n\u003e See [apps/deepresearch/README.md](apps/deepresearch/README.md) for full setup.\n\n---\n\n## Architecture\n\npydantic-deep implements the **deep agent pattern** — the same architecture powering Claude Code, Devin, and Manus AI. Every component is modular and works standalone:\n\n| Component | Package | What It Does |\n|-----------|---------|--------------|\n| **Backends** | [pydantic-ai-backend](https://github.com/vstorm-co/pydantic-ai-backend) | File storage, Docker/Daytona sandbox |\n| **Planning** | [pydantic-ai-todo](https://github.com/vstorm-co/pydantic-ai-todo) | Task tracking with dependencies |\n| **Subagents** | [subagents-pydantic-ai](https://github.com/vstorm-co/subagents-pydantic-ai) | Sync/async delegation, cancellation |\n| **Summarization** | [summarization-pydantic-ai](https://github.com/vstorm-co/summarization-pydantic-ai) | LLM summaries or sliding window |\n| **Middleware** | [pydantic-ai-middleware](https://github.com/vstorm-co/pydantic-ai-middleware) | Lifecycle hooks, permissions |\n\n```\n                              pydantic-deep\n┌─────────────────────────────────────────────────────────────────────┐\n│                                                                     │\n│   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐   │\n│   │ Planning │ │Filesystem│ │ Subagents│ │  Skills  │ │  Teams  │   │\n│   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬────┘   │\n│        │            │            │            │            │        │\n│        └────────────┴─────┬──────┴────────────┴────────────┘        │\n│                           │                                         │\n│                           ▼                                         │\n│  Summarization ──► ┌──────────────────┐ ◄── Middleware              │\n│  Checkpointing ──► │    Deep Agent    │ ◄── Hooks                   │\n│  Cost Tracking ──► │   (pydantic-ai)  │ ◄── Memory                  │\n│                    └────────┬─────────┘                             │\n│                             │                                       │\n│           ┌─────────────────┼─────────────────┐                     │\n│           ▼                 ▼                 ▼                     │\n│    ┌────────────┐    ┌────────────┐    ┌────────────┐               │\n│    │   State    │    │   Local    │    │   Docker   │               │\n│    │  Backend   │    │  Backend   │    │  Sandbox   │               │\n│    └────────────┘    └────────────┘    └────────────┘               │\n│                                                                     │\n└─────────────────────────────────────────────────────────────────────┘\n```\n\n---\n\n## All Features\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClick to expand full feature list\u003c/b\u003e\u003c/summary\u003e\n\n### Core Toolsets\n\n- **Planning** — Task tracking with subtasks, dependencies, cycle detection. PostgreSQL storage. Event system.\n- **Filesystem** — `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep`, `execute`. Docker sandbox. Permission system.\n- **Subagents** — Sync/async delegation. Background task management. Soft/hard cancellation.\n- **Summarization** — LLM-based summaries or zero-cost sliding window. Trigger on tokens, messages, or fraction.\n- **Middleware** — 7 lifecycle hooks. Composable chains. Permission handling.\n\n### Advanced\n\n- **Checkpointing** — Save state at intervals. Rewind or fork sessions. In-memory and file-based stores.\n- **Agent Teams** — Shared TODO lists with claiming and dependency tracking. Peer-to-peer message bus.\n- **Hooks** — Claude Code-style lifecycle hooks. Shell commands on tool events. Audit logging, safety gates.\n- **Persistent Memory** — `MEMORY.md` that persists across sessions. Auto-injected into system prompt.\n- **Context Files** — Auto-discover and inject `AGENT.md` into the system prompt.\n- **Output Styles** — Built-in (concise, explanatory, formal, conversational) or custom from files.\n- **Plan Mode** — Dedicated planner subagent for structured planning before execution.\n- **Cost Tracking** — Token/USD budgets with automatic enforcement and real-time callbacks.\n- **Eviction Processor** — Evict large tool outputs to files. Keep context lean while preserving data.\n- **Patch Tool Calls** — On resume, patch stale tool call results for clean history.\n- **Custom Tool Descriptions** — Override any tool's description via `descriptions` parameter.\n- **Custom Commands** — `/commit`, `/pr`, `/review`, `/test`, `/fix`, `/explain`. Three-scope discovery: built-in, user, project.\n- **Web Tools** — Web search (Tavily) and URL fetching with automatic markdown conversion.\n- **Structured Output** — Type-safe responses with Pydantic models via `output_type`.\n- **Human-in-the-Loop** — Confirmation workflows for sensitive operations.\n- **Streaming** — Full streaming support for real-time responses.\n- **Image Support** — Multi-modal analysis with image inputs.\n\n\u003c/details\u003e\n\n---\n\n## Contributing\n\n```bash\ngit clone https://github.com/vstorm-co/pydantic-deepagents.git\ncd pydantic-deepagents\nmake install\nmake test  # 100% coverage required\nmake all   # lint + typecheck + test\n```\n\n---\n\n## Star History\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.star-history.com/#vstorm-co/pydantic-deepagents\u0026type=date\"\u003e\n    \u003cimg src=\"https://api.star-history.com/svg?repos=vstorm-co/pydantic-deepagents\u0026type=date\" alt=\"Star History\" width=\"600\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n### Need help implementing this in your company?\n\n\u003cp\u003eWe're \u003ca href=\"https://vstorm.co\"\u003e\u003cb\u003eVstorm\u003c/b\u003e\u003c/a\u003e — an Applied Agentic AI Engineering Consultancy\u003cbr\u003ewith 30+ production AI agent implementations.\u003c/p\u003e\n\n\u003ca href=\"https://vstorm.co/contact-us/\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Talk%20to%20us%20%E2%86%92-0066FF?style=for-the-badge\u0026logoColor=white\" alt=\"Talk to us\"\u003e\n\u003c/a\u003e\n\n\u003cbr\u003e\u003cbr\u003e\n\nMade with \u0026#10084;\u0026#65039; by \u003ca href=\"https://vstorm.co\"\u003e\u003cb\u003eVstorm\u003c/b\u003e\u003c/a\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fpydantic-deepagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvstorm-co%2Fpydantic-deepagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvstorm-co%2Fpydantic-deepagents/lists"}