Repository navigation
Description
Description
Currently, when using Agent.from_spec() or Agent.from_file() with custom capabilities, the user must explicitly pass custom_capability_types as a Python list of classes. This means the capabilities must be imported in code, and the spec file itself cannot be fully self‑contained – any third‑party or project‑specific capability requires a separate code change.
I propose adding an optional plugins field to AgentSpec (and therefore to the JSON/YAML spec format) that accepts a list of strings. Each string can be:
- a dotted module path (e.g.,
"my_package.capabilities") - an absolute or relative file path ending with
.py(e.g.,"/home/user/my_cap.py") - a
"module:ClassName"pair for precise loading
During Agent.from_spec(), Pydantic AI would automatically scan these paths for AbstractCapability subclasses and merge them into the final capability list (as if they were passed via custom_capability_types). This makes the spec file the single source of truth and enables a true “zero‑code” configuration experience.
Demo / how code might look
User creates a spec file my_agent.spec.json:
{
"model": "openai:gpt-4",
"plugins": [
"my_company.waf_plugins",
"/home/user/extra_caps.py"
],
"capabilities": [
{"Thinking": {"effort": "medium"}}
]
}In Python, they simply do:
agent = Agent.from_file("my_agent.spec.json")
# The capabilities from `my_company.waf_plugins` and `extra_caps.py` are automatically loaded and available.No manual imports, no custom_capability_types list – the spec file drives everything. This is particularly useful for projects that distribute re‑usable agent configurations to end users who may not be Python developers.
Proof of concept
I’ve been building a tool that heavily relies on dynamic capability loading, and I’ve implemented a helper function that does exactly this. It works reliably with .py files, regular modules, and module:Class pairs. Here’s the core (stripped of error handling for brevity):
import hashlib
import importlib.util
from pathlib import Path
from typing import Iterable
from pydantic_ai.capabilities import AbstractCapability
type CapabilityType = type[AbstractCapability]
type CapabilityList = list[CapabilityType]
def load_custom_capability(paths: Iterable[str]) -> CapabilityList:
capability_types: CapabilityList = []
seen: set[CapabilityType] = set()
for path in filter(str.strip, paths):
if path.endswith(".py"):
capability_types.extend(_load_from_file(path, seen))
elif ":" in path:
capability_types.extend(_load_from_module_class(path, seen))
else:
capability_types.extend(_load_from_module(path, seen))
return capability_types
# ... helper functions that scan modules for AbstractCapability subclasses ...Having such logic built into AgentSpec would remove a lot of boilerplate and make the whole ecosystem more approachable.
Use cases
- Re‑usable agent templates: Teams publish spec files that automatically activate custom guardrails, logging, or domain‑specific tools without requiring any Python coding by the consumer.
- Plugin systems: Applications can discover and load third‑party capabilities simply by adding entries to a config file.
- End‑user customisation: Non‑Python users can extend an agent’s behaviour by writing a simple
.pyfile and referencing it in the spec.
References
pytest’sconftest.pydiscovery and plugin loading viapipentry points is a well‑known example of configuration‑driven plugin loading.- The official documentation already encourages capabilities as the primary extension point; this proposal just makes them easier to consume from specs.
- My own dynamic loader (shown above) has been working well in production for a workflow automation tool.
Activity
linear commentedon May 1, 2026
PYAI-38
[-]AgentSpec add `plugins` field for automatic custom capability loading[/-][+][Feature Request] AgentSpec add `plugins` field for automatic custom capability loading[/+]DouweM commentedon May 5, 2026
I see the value, but:
from_spec/filecall site.plugins:)capabilities?D7x7z49 commentedon May 5, 2026
@DouweM
Thanks for the feedback. I agree with all three points you raised.
On safety. You are right that loading external code from a spec file should not happen by default. I think a simple flag on
from_specorfrom_filewould work. For exampleallow_external_capabilities=True. If the user does not pass this flag, the new field is ignored and nothing is loaded. This keeps the current safe behavior as the default.On the name.
pluginswas just a placeholder from my proof of concept. It can beextensions,imports, or anything else that feels right to the project. I have no attachment to the name.On how it works with the
capabilitiesfield. The new field is only for discovering and loading capability classes. Thecapabilitiesfield stays as it is, for configuring instances with their data and settings. For example the new field would find theThinkingclass from a module, and thecapabilitiesfield would set itsefforttomedium. Two different jobs, two fields.Now I want to explain the five groups of people around pydantic-ai. Here is how I see them.
AbstractCapabilityinterface. They publish these packages for others to use.Here is the current relationship. Group C sits in the center. Every Group C project must build its own plugin system for Group E. Group B capabilities require manual integration by Group C.
flowchart TD A[Group A<br/>pydantic-ai maintainers] B[Group B<br/>capability package authors] C1[Group C<br/>application developer 1] C2[Group C<br/>application developer 2] D1[Group D<br/>end users of app 1] D2[Group D<br/>end users of app 2] E1[Group E<br/>extension devs for app 1] E2[Group E<br/>extension devs for app 2] A -->|provides interface| B A -->|provides framework| C1 A -->|provides framework| C2 B -->|manual import by| C1 B -->|manual import by| C2 C1 -->|builds plugin system for| E1 C2 -->|builds plugin system for| E2 E1 -->|extensions only work in| C1 E2 -->|extensions only work in| C2 C1 -->|serves| D1 C2 -->|serves| D2The problem is clear. Each Group C project becomes its own island. Group E extensions are trapped inside one application. Group B capabilities need code changes in every Group C project that uses them. Group D cannot use any capability unless Group C manually integrates it first.
Here is the relationship if this feature is implemented. Pydantic-ai becomes the center. Group E disappears and merges into Group B. Group C no longer needs a custom plugin system.
flowchart TD A[Group A<br/>pydantic-ai maintainers] B[Group B<br/>capability package authors<br/>includes former Group E] C1[Group C<br/>application developer 1] C2[Group C<br/>application developer 2] D1[Group D<br/>end users of app 1] D2[Group D<br/>end users of app 2] A -->|defines spec with extension field| B A -->|provides framework| C1 A -->|provides framework| C2 B -->|publishes to| A C1 -->|pip install + spec reference| B C2 -->|pip install + spec reference| B C1 -->|serves| D1 C2 -->|serves| D2 D1 -.->|can also use spec directly| B D2 -.->|can also use spec directly| BThe change is simple but powerful. Group B publishes once and reaches every Group C project. Group C only needs
pip installand a spec file entry. Group E becomes part of Group B, writing capabilities for the whole ecosystem instead of one application. Group D can even use capabilities directly through spec files without waiting for Group C. The center is pydantic-ai, not the application developer.This field is completely optional. Developers who do not need it simply do not use it. Nothing changes for them.
The goal is simple. Pydantic-ai becomes the center of its own ecosystem, and application developers stop rebuilding the same plugin machinery over and over.
One last note. Sorry for any awkward phrasing. My English is not great so I used an LLM to help translate my thoughts. Hope that's not weird. If anything sounds off, blame the robot not me. Feel free to run this through an LLM too if it helps. I just wanted the ideas to land properly.
D7x7z49 commentedon May 5, 2026
@DouweM
I want to clarify one thing about the field I am proposing. Let me be more direct.
This field is about letting AgentSpec dynamically import capability modules. That is its only job. It is empty by default. When you add entries to it, you are telling pydantic-ai which external modules it is allowed to load.
Think of it like an access control list. The field does not blindly load anything. It only loads what the user explicitly lists. The user decides what goes in. The app developer decides whether to expose this field to their users. Pydantic-ai just provides the mechanism.
So safety is not really the key concern here. The field is an allowlist by design. If you leave it empty, nothing happens. If you put something in it, you are saying you trust that module. The responsibility sits with the person who writes the spec file. Pydantic-ai only needs to offer the option.
This field does not conflict with the existing
capabilitiesfield. It is a separate thing. Thecapabilitiesfield configures capability instances with their data and settings. The new field is about importing the modules that contain those capability classes in the first place. They work together. One imports the code. The other configures the instances.D7x7z49 commentedon May 5, 2026
One more thing. I just want to say I am really happy and honored to get a reply from you. Your work on Meltano and GitLab is inspiring. Thank you for taking the time on this.
DouweM commentedon May 6, 2026
@D7x7z49 Thanks for the writeup, makes perfect sense, and I agree we need this.
I'll assign the issue to you as champion of this feature. Do you have a plan / working implementation already? I'd like to see a PR with a concrete plan + "works for me" implementation for us to iterate on together, on a video call if you're comfortable. Can you please join our Slack and send me a DM so we can discuss next steps?
D7x7z49 commentedon May 7, 2026
@DouweM Thank you for assigning this to me and for the invitation. I’m very happy to help move this forward.
I do want to be upfront about a few constraints on my side:
That said, I believe the actual code change for this feature should be fairly small – essentially Python’s dynamic import machinery. I also feel that the
plugins(or whatever name we choose) field can act as an explicit allow‑list. For private/internal projects, that’s often enough; for more security‑sensitive environments, we can let the developer decide how to handle trust, without wrapping it too much on the framework side (but I’m open to discussing this further).I’ve joined the Slack and will DM you. I’ll start by putting together a rough plan/PR as soon as I can, but I might need a bit of patience while I get up to speed with the codebase.
Looking forward to working on this with you!
D7x7z49 commentedon May 7, 2026
How about adding an
import_capability_typesfield toAgentSpecclass 🤔like - the
custom_capability_typesparameter ofAgentclass[-][Feature Request] AgentSpec add `plugins` field for automatic custom capability loading[/-][+][Feature Request] `AgentSpec` add `plugins` field for automatic custom capability loading[/+]