Skip to content
Open
Show file tree
Hide file tree
Changes from 5 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/multi-agent-applications.md
Original file line number Diff line number Diff line change
Expand Up @@ -327,3 +327,9 @@ See the [graph](graph.md) documentation on when and how to use graphs.
The following examples demonstrate how to use dependencies in Pydantic AI:

- [Flight booking](examples/flight-booking.md)

## Community Frameworks

For more advanced multi-agent scenarios with built-in toolsets, consider:

- [Pydantic-Deep](https://github.com/vstorm-co/pydantic-deepagents) — A deep agent framework built on Pydantic AI with ready-to-use toolsets for task planning (`TodoToolset`), filesystem operations (`FilesystemToolset`), and subagent delegation (`SubAgentToolset`). See the [toolsets documentation](toolsets.md#pydantic-deep) for usage examples.
39 changes: 39 additions & 0 deletions docs/toolsets.md
Original file line number Diff line number Diff line change
Expand Up @@ -708,3 +708,42 @@ toolset = ACIToolset(

agent = Agent('openai:gpt-5', toolsets=[toolset])
```

### Pydantic-Deep {#pydantic-deep}

[Pydantic-Deep](https://github.com/vstorm-co/pydantic-deepagents) implements the [Deep Agents](https://blog.langchain.com/deep-agents/) architecture pattern for Pydantic AI. Deep agents are production-grade agents with planning, file system operations, task delegation, and sandboxed code execution — patterns documented from production systems like Claude Code and Manus.

Available toolsets:

- `TodoToolset`: Task planning and progress tracking for agent self-organization
- `FilesystemToolset`: File operations (ls, read, write, edit, glob, grep, execute)
- `SubAgentToolset`: Spawn and delegate tasks to specialized subagents
- `SkillsToolset`: Load and use [agent skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) from markdown files
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assuming (some of) these can be used stand-alone, without the rest of the Deep Agent framework, would it be possible to extract these into separate packages, that we can consider for upstreaming once they've matured a bit?

If they are usable standalone, even if they're still in the same package, I also wouldn't mind subheadings so that it's easier for a user to find "Todo Toolset" or "File system Toolset" in the sidebar ToC if they just want that bit.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe it makes sense to have the explanation of your framework in the multi-agent-... page, and then here have a separate section for each of the stand-alone-usable toolsets, that can say "Part of ..." linking to the Deep Agent doc.

Those sections should be more generic, less marketing copy, just saying things like "File system access is useful because blablabla. Check out these implementations by the community:", as they may have multiple links, e.g. also https://pypi.org/project/pydantic-ai-filesystem-sandbox/.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion. I've analyzed the toolsets for extractability:

Easy to extract:

  • TodoToolset
  • SkillsToolset

Would require more work:

  • FilesystemToolset - tightly coupled to the BackendProtocol abstraction layer
  • SubAgentToolset - dynamically imports other toolsets and is coupled to DeepAgentDeps

I'll look into extracting TodoToolset and SkillsToolset as separate packages first. Need to think through the API design and whether to keep them compatible with pydantic-deep or make them fully independent. Will follow up once I have a plan.

In the meantime, I can add subheadings for each toolset in the docs for better discoverability in the sidebar.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd like to have headings under "Third-Party Toolsets" (after MCP Servers, before Langchain) for each type of common toolset that has one or more community implementations and then in that section list each option, i.e. "Task Management"/Todos", "Filesystem" (https://pypi.org/project/pydantic-ai-filesystem-sandbox/ + yours once it's available), "Memory", "Code Execution" (could list https://github.com/pydantic/mcp-run-python), etc.

The ones that Pydantic-Deep covers can then have an item saying something to the effect of "The third-party Pydantic-Deep deep agent framework includes a FilesystemToolset among others"

That way it'll be easier to discover for users, not being nested under the not-necessarily-related-seeming Deep Agents heading, and leaves room for more future community alternatives.

The copy on the Multi-Agent page can then be the main place where that concept is introduced + Pydantic-Deep is mentioned more clearly, as I don't think a "Deep Agents/Pydantic-Deep" heading necessarily makes sense on the Toolsets page. I also wouldn't be opposed to a new page like https://starlette.dev/third-party-packages/ listing Third Party packages explicitly; that's also where https://github.com/jagreehal/pydantic-ai-guardrails could go for example.


The framework also includes multiple backends (in-memory, filesystem, Docker sandbox), automatic conversation summarization, and human-in-the-loop approval workflows.

You will need to install the `pydantic-deep` package.

```python {test="skip" lint="skip"}
from pydantic_ai import Agent
from pydantic_deep import create_deep_agent, create_default_deps, DeepAgentDeps
from pydantic_deep.backends import StateBackend
from pydantic_deep.toolsets import TodoToolset, FilesystemToolset

# Option 1: Use the pre-configured deep agent
backend = StateBackend()
deps = create_default_deps(backend)
agent = create_deep_agent()
result = await agent.run("Help me organize my tasks", deps=deps)

# Option 2: Use individual toolsets with your own agent
backend = StateBackend()
deps = DeepAgentDeps(backend=backend)
agent = Agent(
'openai:gpt-4.1',
toolsets=[TodoToolset(), FilesystemToolset()],
)
result = await agent.run("Your prompt", deps=deps)
```

See the [full demo application](https://github.com/vstorm-co/pydantic-deepagents/tree/main/examples/full_app) for a complete example with a chat interface, file uploads, skills, and streaming responses.