Question: Relationship between AgentPool and Pydantic-AI - Design Philosophy

[Leoyzen]

As a contributor to AgentPool, I'd like to clarify the design philosophy regarding AgentPool's relationship with pydantic-ai to better understand how to approach certain contributions and feature proposals.

Context

Based on the codebase analysis, I observe that:

1. AgentPool has its own abstraction layer: MessageNode, BaseAgent, Tool, Team - which unifies multiple protocols (native/pydantic-ai, ACP, AG-UI, Claude Code, Codex)
2. Pydantic-ai is used as an execution backend: For native agents, AgentPool lazily creates pydantic-ai's Agent instance via get_agentlet(), converting its own Tool abstractions to pydantic-ai's Tool using to_pydantic_ai()
3. AgentPool adds orchestration features: Session management, protocol bridging, multi-agent teams, hooks, connections - which go beyond pydantic-ai's scope

Questions

1. Should pydantic-ai be treated as a "first-class citizen" in AgentPool?

• Should AgentPool increasingly leverage pydantic-ai's abstractions (e.g., Agent class, RunContext, toolsets, multi-agent patterns) where they align?
• Or should AgentPool maintain independent abstractions to support heterogeneous agent types?
  2. Is AgentPool intended as a "second-level wrapper/orchestration framework" on top of pydantic-ai?
• Should we view AgentPool's role as: pydantic-ai handles agent execution, AgentPool handles orchestration (protocol bridging, multi-agent coordination, deployment)?
• This aligns with the README's description: "AgentPool acts as a protocol bridge"
  3. For features that pydantic-ai provides, should AgentPool:
• (A) Wrap and expose them (current pass-through pattern in RFC-0002/0003)
• (B) Re-implement them in AgentPool's own abstractions
• (C) Mix - use pydantic-ai for native agents, maintain own abstractions for cross-protocol features
  4. Specific scenarios I'm considering:
• Multi-agent workflows: Should we use pydantic-ai's agent delegation pattern or AgentPool's Team abstraction?
• Tool management: Should we leverage pydantic-ai's toolsets more heavily or continue with AgentPool's ToolManager?
• Configuration: Should we expose more pydantic-ai agent options directly in YAML, or keep them behind abstractions?

Motivation

Understanding this design philosophy would help contributors:

• Make better decisions about whether a feature belongs in AgentPool or should be delegated to pydantic-ai
• Avoid duplicating effort on things pydantic-ai already provides
• Maintain consistency with the project's architectural vision
• Write more aligned code and PRs

Research Notes

I've researched both the AgentPool codebase and pydantic-ai's design philosophy:
From AgentPool:

• Tools use to_pydantic_ai() conversion with fallback to schemez
• BaseAgent extends MessageNode, not pydantic-ai's Agent
  From pydantic-ai:
• Designed as "FastAPI for GenAI" - a core framework meant to be extended
• Provides toolsets, custom agents, history processors as extension points
• Multiple frameworks already build on top: pydantic-deep, pydantic-ai-todo, etc.
• Has multi-agent patterns (delegation, graphs) but orchestration is left to frameworks

References

• Pydantic-AI Multi-Agent Applications
• Pydantic-AI Toolsets

[phil65]

So right now, AgentPool basically uses some main abstractions from Pydantic-AI (mainly the events as well as the message history) and tries to make all the agent types adhere to these. An event stream for lets say a claude code agent with tool calls etc should look "the same" from the outside than one from the pydantic-ai agent. that way any adapter (ACP/OpenCode server) only need to handle only event stream "type".
Perhaps I could make this clearer in code by re-exporting these types, I think thats a good point.
That structure a) has historical reasons and b) I think that pydantic-ai made some sane choices in that regard, so I didnt feel to reinvent everything here (at least for now).
Apart from these core abstractions, all other pydantic-ai stuff should stay "pydantic-ai" stuff, so pydantic-ai is just one of many backends.
When it comes to tools: AgentPool has its own set of tools which can be used for any agent (works easily with pydantic-ai, others need an MCP bridge), but users are also free to use the "native" ones provided by each backend (which might have limitations though, because only our own tools consistently access files / execute commands through the agent's execution environment. A claude code write tool only works locally)
Does this help clear things up?

[Leoyzen]

I need to use functionality similar to pydantic-ai-skills (skill system / tool grouping) in my project.

Core Questions

1. What's AgentPool's stance on pydantic-ai ecosystem extensions?
   • Should AgentPool natively support pydantic-ai extensions (skills, toolsets, memory, etc.)?
   • Or keep minimal abstractions and let users integrate at the application layer?
2. For pydantic-ai-only features, what's the recommended integration approach?
   • If AgentPool provides abstractions that other backends (Claude Code, Codex) don't support, could this cause confusion?
   • Should these be passed through via backend_options rather than top-level abstractions?
3. How to balance "configuration-driven" with "ecosystem compatibility"?
   • One of AgentPool's strengths is YAML configuration + automatic ACP/OpenCode integration
   • But pydantic-ai's rich ecosystem may not all be configurable
   • Where do you draw the line?

Expected Response

Hoping for clarification on:

• Should this type of feature be contributed to AgentPool core?
• If yes, in what form (top-level config vs backend-specific options)?
• If no, what's the recommended best practice?

[phil65]

yeah backend_options would be one option, but thats quite a larger refactor. I guess as a start, you could add builtin_toolsets to the native-agent-config which then resolves to pydantic-ais native ones (or to pydantic-ai-skills toolset). then just add builtin_toolsets to the Agent ctor as well as Agent.from_config, and pass them to the pydnatic-ai agent in get_agentlet.