Skip to content

[Feature Request] AgentSpec add plugins field for automatic custom capability loading #5266

Open

Description

@D7x7z49

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 .py file and referencing it in the spec.

References

  • pytest’s conftest.py discovery and plugin loading via pip entry 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

  1. added
    featureNew feature request, or PR implementing a feature (enhancement)
    on May 1, 2026
  2. linear commented on May 1, 2026

    @linear
  3. changed the title [-]AgentSpec add `plugins` field for automatic custom capability loading[/-] [+][Feature Request] AgentSpec add `plugins` field for automatic custom capability loading[/+] on May 1, 2026
  4. DouweM commented on May 5, 2026

    @DouweM
    Contributor

    I see the value, but:

    • Loading an agent from a spec should be safe (i.e. not allow arbitrary code execution) by default, i.e. this would need to be opted into on the from_spec/file call site.
    • I don't like the name plugins :)
    • Are you suggesting the capabilities in those files are auto-loaded? Or does the user still need to reference them in capabilities?
  5. D7x7z49 commented on May 5, 2026

    @D7x7z49
    Author

    @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_spec or from_file would work. For example allow_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. plugins was just a placeholder from my proof of concept. It can be extensions, imports, or anything else that feels right to the project. I have no attachment to the name.

    On how it works with the capabilities field. The new field is only for discovering and loading capability classes. The capabilities field stays as it is, for configuring instances with their data and settings. For example the new field would find the Thinking class from a module, and the capabilities field would set its effort to medium. Two different jobs, two fields.


    Now I want to explain the five groups of people around pydantic-ai. Here is how I see them.

    • Group A, pydantic-ai maintainers. The team that builds and maintains pydantic-ai itself. They define the capability interface and the spec format.
    • Group B, capability package authors. Developers who create capability packages that follow pydantic-ai's AbstractCapability interface. They publish these packages for others to use.
    • Group C, application developers. Developers like me who use pydantic-ai to build an agent application. We write spec files and application logic.
    • Group D, end users. Users of the application built by Group C. They may not write Python code. They use spec files and configuration to customize the agent.
    • Group E, application extension developers. Developers who write extensions for a specific Group C application. They work within one project's custom plugin system.

    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| D2
    
    Loading

    The 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| B
    
    Loading

    The change is simple but powerful. Group B publishes once and reaches every Group C project. Group C only needs pip install and 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.

  6. D7x7z49 commented on May 5, 2026

    @D7x7z49
    Author

    @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 capabilities field. It is a separate thing. The capabilities field 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.

  7. D7x7z49 commented on May 5, 2026

    @D7x7z49
    Author

    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.

  8. DouweM commented on May 6, 2026

    @DouweM
    Contributor

    @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?

  9. D7x7z49 commented on May 7, 2026

    @D7x7z49
    Author

    @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:

    • I’m currently working on other projects, so the time I can dedicate will be somewhat limited.
    • I haven’t yet dug deeply into the Pydantic AI codebase, so I’ll need some time to get familiar with the internals.
    • English is not my native language, and I’m unable to join a voice/video call. I rely on translators and LLMs to help me write and read. Text-based async communication (here or on Slack) works perfectly for me.

    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!

  10. D7x7z49 commented on May 7, 2026

    @D7x7z49
    Author

    How about adding an import_capability_types field to AgentSpec class 🤔
    like - the custom_capability_types parameter of Agent class

  11. changed the title [-][Feature Request] AgentSpec add `plugins` field for automatic custom capability loading[/-] [+][Feature Request] `AgentSpec` add `plugins` field for automatic custom capability loading[/+] on May 8, 2026
  12. self-assigned this
    on May 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

featureNew feature request, or PR implementing a feature (enhancement)

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions