agent-plugins 0.1.1__tar.gz → 0.2.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/.agent-plugin/plugin.json +1 -0
- agent_plugins-0.2.1/.agent-plugin/skills/agent-plugins/SKILL.md +250 -0
- agent_plugins-0.2.1/PKG-INFO +124 -0
- agent_plugins-0.2.1/README.md +103 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/pyproject.toml +3 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/pyproject.toml.orig +3 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/__init__.py +6 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/backend.py +3 -3
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/plan.py +73 -10
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/sdist.py +4 -2
- agent_plugins-0.2.1/src/agent_plugins/_build/wheel.py +239 -0
- agent_plugins-0.2.1/src/agent_plugins/_build/wheel_archive.py +292 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_cli.py +61 -2
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_discovery.py +9 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_files.py +69 -13
- agent_plugins-0.2.1/src/agent_plugins/_mcp.py +198 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_plugin.py +63 -7
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/__init__.py +2 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/json.py +14 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/lazy.py +2 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/manifest.py +10 -1
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/mcp.py +48 -5
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/models.py +15 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/skill.py +13 -4
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/mcp.py +14 -4
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_skill.py +17 -4
- agent_plugins-0.1.1/.agent-plugin/skills/agent-plugins/SKILL.md +0 -195
- agent_plugins-0.1.1/PKG-INFO +0 -224
- agent_plugins-0.1.1/README.md +0 -205
- agent_plugins-0.1.1/src/agent_plugins/_build/wheel.py +0 -187
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/.agent-plugin/skills/agent-plugins/agents/openai.yaml +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/LICENSE +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/__main__.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_build/__init__.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_errors.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_marker.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/errors.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/__init__.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_schema/v1/manifest.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/_tree.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/__init__.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/hatchling.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/build/uv_build.py +0 -0
- {agent_plugins-0.1.1 → agent_plugins-0.2.1}/src/agent_plugins/py.typed +0 -0
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agent-plugins
|
|
3
|
+
description: Ship and inspect Agent Skills, MCP server configuration, and client extension files with a Python distribution. Use when adding an Agent Plugin to a Python project, attaching a prebuilt wheel, loading the exact project or installed selection, selecting a named skill, reading checked skill resources, resolving a stdio MCP launch, or verifying package artifacts.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Agent Plugins
|
|
7
|
+
|
|
8
|
+
Use `agent-plugins` when a Python distribution should carry the instructions and MCP
|
|
9
|
+
configuration that match its installed code version.
|
|
10
|
+
|
|
11
|
+
An [Agent Plugin](https://agent-plugins.org/) is an open, vendor-neutral
|
|
12
|
+
portable directory format for reusable agent components. Its fixed locations
|
|
13
|
+
let compatible clients find [Agent Skills](https://agentskills.io/specification)
|
|
14
|
+
and [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification)
|
|
15
|
+
server configuration in the same package. Distribution, permissions, and user
|
|
16
|
+
experience remain with each client.
|
|
17
|
+
|
|
18
|
+
## Build the plugin directory
|
|
19
|
+
|
|
20
|
+
Keep one Agent Plugin directory in the codebase:
|
|
21
|
+
|
|
22
|
+
```text
|
|
23
|
+
my-plugin/
|
|
24
|
+
├── plugin.json
|
|
25
|
+
├── skills/
|
|
26
|
+
│ └── use-my-package/
|
|
27
|
+
│ ├── SKILL.md
|
|
28
|
+
│ ├── scripts/
|
|
29
|
+
│ └── references/
|
|
30
|
+
├── mcp.json
|
|
31
|
+
└── com.example.client/
|
|
32
|
+
└── hooks/
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
- `plugin.json` identifies the plugin and its Agent Plugins schema.
|
|
36
|
+
- `skills/` contains Agent Skills and their nested files.
|
|
37
|
+
- `mcp.json` describes stdio, Streamable HTTP, or legacy HTTP+SSE servers.
|
|
38
|
+
- Reverse-domain directories contain client extension files.
|
|
39
|
+
|
|
40
|
+
Create a minimal `plugin.json` at the plugin root:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
45
|
+
"name": "my-project"
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Find the Python project's `pyproject.toml` and set
|
|
50
|
+
`[tool.agent-plugins].root` to the authored plugin root. Prefer a path relative
|
|
51
|
+
to `pyproject.toml`. For uv_build:
|
|
52
|
+
|
|
53
|
+
```toml
|
|
54
|
+
[build-system]
|
|
55
|
+
requires = ["agent-plugins", "uv_build"]
|
|
56
|
+
build-backend = "agent_plugins.build.uv_build"
|
|
57
|
+
|
|
58
|
+
[tool.agent-plugins]
|
|
59
|
+
root = "../.."
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
For Hatchling:
|
|
63
|
+
|
|
64
|
+
```toml
|
|
65
|
+
[build-system]
|
|
66
|
+
requires = ["agent-plugins", "hatchling"]
|
|
67
|
+
build-backend = "agent_plugins.build.hatchling"
|
|
68
|
+
|
|
69
|
+
[tool.agent-plugins]
|
|
70
|
+
root = "../.."
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The build selects `plugin.json`, the complete `skills/` tree, and `mcp.json`
|
|
74
|
+
when present. Select other root-relative files explicitly:
|
|
75
|
+
|
|
76
|
+
```toml
|
|
77
|
+
[tool.agent-plugins]
|
|
78
|
+
root = "../.."
|
|
79
|
+
include = ["bin/**", "com.example.client/**"]
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Every include pattern must stay within the plugin root and match at least one
|
|
83
|
+
filesystem entry. A matched directory contributes its regular files.
|
|
84
|
+
|
|
85
|
+
Use `attach_wheel()` when another build system already produced the wheel. It rewrites the input after the complete attached artifact succeeds. Pass `output_dir` to preserve the source.
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
import agent_plugins as ap
|
|
89
|
+
|
|
90
|
+
result = ap.attach_wheel(
|
|
91
|
+
"dist/my_package-1.0.0-py3-none-any.whl",
|
|
92
|
+
project="packages/python",
|
|
93
|
+
)
|
|
94
|
+
print(result.output)
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
The CLI exposes the same operation:
|
|
98
|
+
|
|
99
|
+
```console
|
|
100
|
+
agent-plugins attach-wheel dist/my_package-1.0.0-py3-none-any.whl \
|
|
101
|
+
--project packages/python
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Reuse a previously computed plan by passing it directly:
|
|
105
|
+
|
|
106
|
+
```python
|
|
107
|
+
from pathlib import Path
|
|
108
|
+
|
|
109
|
+
plan = ap.build_plan("packages/python")
|
|
110
|
+
Path("dist/attached").mkdir(parents=True, exist_ok=True)
|
|
111
|
+
result = ap.attach_wheel(
|
|
112
|
+
"dist/my_package-1.0.0-py3-none-any.whl",
|
|
113
|
+
plan=plan,
|
|
114
|
+
output_dir="dist/attached",
|
|
115
|
+
)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
The output directory receives the same filename. Inspect `result.replaced_existing_plugin` and `result.removed_signatures`. The CLI writes removed-signature warnings to stderr.
|
|
119
|
+
|
|
120
|
+
`agent_plugins.build.BuildBackend` provides the wheel, source distribution, and
|
|
121
|
+
editable hooks used by the bundled adapters. A custom delegate must also expose
|
|
122
|
+
the three corresponding `get_requires_for_build_*` hooks.
|
|
123
|
+
|
|
124
|
+
## Choose build-time or runtime access
|
|
125
|
+
|
|
126
|
+
Keeping `agent-plugins` in `[build-system].requires` makes it available during
|
|
127
|
+
the build. Add the package to `[project].dependencies` when installed Python
|
|
128
|
+
code needs to locate or inspect Agent Plugins:
|
|
129
|
+
|
|
130
|
+
```toml
|
|
131
|
+
[project]
|
|
132
|
+
dependencies = ["agent-plugins"]
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Load the exact project selection before building. After installing a build from that selection, locate it with the Python distribution name used by pip:
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
import agent_plugins as ap
|
|
139
|
+
|
|
140
|
+
source = ap.Plugin.from_project("packages/python")
|
|
141
|
+
plugin = ap.locate("my-package")
|
|
142
|
+
skill = source.skill("use-my-package")
|
|
143
|
+
|
|
144
|
+
print(source.path)
|
|
145
|
+
print(plugin.path)
|
|
146
|
+
print(plugin.manifest.path)
|
|
147
|
+
print(plugin.manifest.name)
|
|
148
|
+
print(skill.source)
|
|
149
|
+
print(skill.file("SKILL.md"))
|
|
150
|
+
|
|
151
|
+
if mcp := plugin.mcp:
|
|
152
|
+
for name, server in mcp.servers.items():
|
|
153
|
+
print(name, server)
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`Plugin.from_project()` uses the build plan, so its files match the source
|
|
157
|
+
paths selected for packaging. `plugin.path` is the absolute installed plugin
|
|
158
|
+
root. Each item in
|
|
159
|
+
`plugin.skills` is an `ap.Skill` rooted at one immediate directory under
|
|
160
|
+
`skills/`. Use `plugin.skill(name)` for exact structural lookup. Use
|
|
161
|
+
`Path(skill)` or `skill.path` for that directory. Use `skill.file()` for a
|
|
162
|
+
selected instruction, reference, script, or asset:
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
print(skill.file("SKILL.md"))
|
|
166
|
+
print(skill.file("references/api.md"))
|
|
167
|
+
print(skill.tree(max_depth=2))
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`skill.source` returns the complete `SKILL.md` text. Use `skill.frontmatter`
|
|
171
|
+
for the raw source text between the `---` delimiters and `skill.body` for the
|
|
172
|
+
Markdown after the frontmatter. The package checks UTF-8 text and delimiter
|
|
173
|
+
structure. It does not parse the frontmatter as YAML. The first access to any
|
|
174
|
+
source property reads and splits `SKILL.md`, then caches all three strings. Path
|
|
175
|
+
and tree access leave the document unread so an agent can choose which files
|
|
176
|
+
and content to load.
|
|
177
|
+
|
|
178
|
+
`plugin.manifest` is an `ap.Manifest`. `plugin.mcp` is an `ap.MCPConfig` when
|
|
179
|
+
`mcp.json` exists. Each object exposes `.path` immediately. Accessing a parsed
|
|
180
|
+
field such as `manifest.name` or `mcp.servers` reads, validates, and caches its
|
|
181
|
+
document. MCP access validates the manifest first.
|
|
182
|
+
|
|
183
|
+
MCP servers are frozen `ap.StdioServer`, `ap.StreamableHTTPServer`, or
|
|
184
|
+
`ap.SSEServer` values in a read-only mapping. `manifest.issues` records
|
|
185
|
+
non-fatal manifest violations. `mcp.issues` records invalid server entries
|
|
186
|
+
skipped during loading. Document-level failures raise `ap.ValidationError` on
|
|
187
|
+
parsed value access.
|
|
188
|
+
|
|
189
|
+
Resolve a validated stdio server after the client creates its plugin data directory:
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
from pathlib import Path
|
|
193
|
+
import os
|
|
194
|
+
|
|
195
|
+
data_dir = Path(".agent-data/my-package").resolve()
|
|
196
|
+
data_dir.mkdir(parents=True, exist_ok=True)
|
|
197
|
+
|
|
198
|
+
mcp = plugin.mcp
|
|
199
|
+
if mcp is not None:
|
|
200
|
+
launch = mcp.resolve_stdio(
|
|
201
|
+
"my-package",
|
|
202
|
+
data_dir=data_dir,
|
|
203
|
+
base_env={"PATH": os.environ.get("PATH", "")},
|
|
204
|
+
)
|
|
205
|
+
print(launch.command, launch.args, launch.cwd)
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
The client owns data retention, process creation, permissions, logging, and the MCP lifecycle. `resolve_stdio()` returns immutable subprocess inputs and performs one-pass Agent Plugins placeholder expansion.
|
|
209
|
+
|
|
210
|
+
Display the plugin to inspect its selected directory tree:
|
|
211
|
+
|
|
212
|
+
```python
|
|
213
|
+
print(plugin)
|
|
214
|
+
print(plugin.tree(max_depth=2))
|
|
215
|
+
print(plugin.tree(max_depth=None, max_files=None))
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
`Path(plugin)`, `Path(skill)`, and `Path(plugin.manifest)` use the native path
|
|
219
|
+
protocol. When `plugin.mcp` is present, `Path(plugin.mcp)` does too.
|
|
220
|
+
`ap.installed()` returns each discovered plugin keyed by Python distribution
|
|
221
|
+
name. Discovery is fail-fast when a marked distribution has unusable metadata
|
|
222
|
+
or selected files.
|
|
223
|
+
|
|
224
|
+
## Verify the package
|
|
225
|
+
|
|
226
|
+
Inspect the selected paths before building:
|
|
227
|
+
|
|
228
|
+
```console
|
|
229
|
+
agent-plugins plan path/to/python-project
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Then verify the package through its installation boundaries:
|
|
233
|
+
|
|
234
|
+
1. Build a wheel and source distribution through an adapter, or attach the Agent Plugin after an external wheel build.
|
|
235
|
+
2. Build a wheel from the source distribution.
|
|
236
|
+
3. Install the wheel in a clean environment.
|
|
237
|
+
4. Install the Python project as editable.
|
|
238
|
+
5. Compare `Plugin.from_project()` with `ap.locate()` by plugin-relative file inventory and public component values.
|
|
239
|
+
6. Access `plugin.manifest.name` and `plugin.mcp.servers` when MCP exists to run
|
|
240
|
+
the supported Agent Plugins JSON validation.
|
|
241
|
+
7. Confirm each `skill.path`, `skill.file("SKILL.md")`, and `skill.files` points to
|
|
242
|
+
the packaged skill tree.
|
|
243
|
+
8. Access `skill.source`, `skill.frontmatter`, and `skill.body` to verify UTF-8 text and the
|
|
244
|
+
packaged `SKILL.md` delimiter structure.
|
|
245
|
+
9. Run an Agent Skills validator to check frontmatter fields and other Agent
|
|
246
|
+
Skills rules.
|
|
247
|
+
|
|
248
|
+
Handle `ap.AgentPluginError` when a requested Python distribution or usable plugin
|
|
249
|
+
root is absent. Handle `ap.ValidationError` when an installed plugin document
|
|
250
|
+
or `SKILL.md` structure is invalid.
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-plugins
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: Ship Agent Plugins with Python packages and inspect their installed files
|
|
5
|
+
Author: Péter Ferenc Gyarmati
|
|
6
|
+
Author-email: Péter Ferenc Gyarmati <dev.petergy@gmail.com>
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
License-File: LICENSE
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Typing :: Typed
|
|
15
|
+
Requires-Dist: tomli==2.3.1 ; python_full_version < '3.11'
|
|
16
|
+
Requires-Python: >=3.10, <3.15
|
|
17
|
+
Project-URL: Documentation, https://peter-gy.github.io/agent-plugins/
|
|
18
|
+
Project-URL: Issues, https://github.com/peter-gy/agent-plugins/issues
|
|
19
|
+
Project-URL: Source, https://github.com/peter-gy/agent-plugins
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
<p align="center">
|
|
23
|
+
<picture>
|
|
24
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
|
|
25
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
|
|
26
|
+
<img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
|
|
27
|
+
</picture>
|
|
28
|
+
</p>
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
Ship Agent Plugins with Python packages.
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
<p align="center">
|
|
35
|
+
<a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
|
|
36
|
+
<a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
|
|
37
|
+
<a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
|
|
38
|
+
</p>
|
|
39
|
+
|
|
40
|
+
<p align="center">
|
|
41
|
+
<a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
|
|
42
|
+
<a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
|
|
43
|
+
<a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
|
|
44
|
+
<a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
|
|
45
|
+
</p>
|
|
46
|
+
|
|
47
|
+
`agent-plugins` ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.
|
|
48
|
+
|
|
49
|
+
The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.
|
|
50
|
+
|
|
51
|
+
## Package your plugin
|
|
52
|
+
|
|
53
|
+
Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
|
|
54
|
+
|
|
55
|
+
```toml
|
|
56
|
+
[build-system]
|
|
57
|
+
requires = ["agent-plugins", "uv_build"]
|
|
58
|
+
build-backend = "agent_plugins.build.uv_build"
|
|
59
|
+
|
|
60
|
+
[tool.agent-plugins]
|
|
61
|
+
root = "."
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
Build with the [uv package manager](https://docs.astral.sh/uv/):
|
|
65
|
+
|
|
66
|
+
```console
|
|
67
|
+
uv build
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
|
|
71
|
+
|
|
72
|
+
```console
|
|
73
|
+
agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
|
|
77
|
+
|
|
78
|
+
## Inspect an installed plugin
|
|
79
|
+
|
|
80
|
+
Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
|
|
81
|
+
|
|
82
|
+
```console
|
|
83
|
+
pip install agent-plugins
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
```python
|
|
87
|
+
import agent_plugins as ap
|
|
88
|
+
|
|
89
|
+
plugin = ap.locate("agent-plugins")
|
|
90
|
+
skill = plugin.skill("agent-plugins")
|
|
91
|
+
|
|
92
|
+
print(skill.source)
|
|
93
|
+
print(skill.file("SKILL.md"))
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
|
|
97
|
+
|
|
98
|
+
## Documentation
|
|
99
|
+
|
|
100
|
+
- [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
|
|
101
|
+
- [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
|
|
102
|
+
- [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
|
|
103
|
+
- [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
|
|
104
|
+
|
|
105
|
+
<details>
|
|
106
|
+
<summary>Packaging lifecycle</summary>
|
|
107
|
+
|
|
108
|
+
<p align="center">
|
|
109
|
+
<picture>
|
|
110
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
|
|
111
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
|
|
112
|
+
<img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
|
|
113
|
+
</picture>
|
|
114
|
+
</p>
|
|
115
|
+
|
|
116
|
+
</details>
|
|
117
|
+
|
|
118
|
+
## Development
|
|
119
|
+
|
|
120
|
+
See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
|
|
121
|
+
|
|
122
|
+
## License
|
|
123
|
+
|
|
124
|
+
[Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).
|
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-dark.svg">
|
|
4
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg">
|
|
5
|
+
<img alt="agent-plugins" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-lockup-horizontal-light.svg" width="430">
|
|
6
|
+
</picture>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
Ship Agent Plugins with Python packages.
|
|
11
|
+
</p>
|
|
12
|
+
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://peter-gy.github.io/agent-plugins/"><strong>Documentation</strong></a> ·
|
|
15
|
+
<a href="https://pypi.org/project/agent-plugins/"><strong>PyPI</strong></a> ·
|
|
16
|
+
<a href="https://agent-plugins.org/"><strong>Agent Plugins format</strong></a>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
<a href="https://pypi.org/project/agent-plugins/"><img alt="PyPI version" src="https://img.shields.io/pypi/v/agent-plugins"></a>
|
|
21
|
+
<a href="https://pypi.org/project/agent-plugins/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/agent-plugins"></a>
|
|
22
|
+
<a href="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml"><img alt="CI status" src="https://github.com/peter-gy/agent-plugins/actions/workflows/ci.yml/badge.svg"></a>
|
|
23
|
+
<a href="https://github.com/peter-gy/agent-plugins/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/pypi/l/agent-plugins"></a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
`agent-plugins` ships a Python library and its agent integrations in one package. An agent with Python execution can read its packaged instructions, then use the library in the same environment. Library code, skills, tool configuration, and resources share one release.
|
|
27
|
+
|
|
28
|
+
The [Agent Plugins format](https://agent-plugins.org/) defines the directory: a manifest, [Agent Skills](https://agentskills.io/specification) for instructions and resources, [Model Context Protocol (MCP)](https://modelcontextprotocol.io/specification) server configuration for tools, and client extensions. This library packages that directory and makes it discoverable through Python metadata. Agent clients choose which components to activate.
|
|
29
|
+
|
|
30
|
+
## Package your plugin
|
|
31
|
+
|
|
32
|
+
Keep `plugin.json` and `skills/` beside your code. For a project using the [uv build backend](https://docs.astral.sh/uv/concepts/build-backend/), configure `pyproject.toml`:
|
|
33
|
+
|
|
34
|
+
```toml
|
|
35
|
+
[build-system]
|
|
36
|
+
requires = ["agent-plugins", "uv_build"]
|
|
37
|
+
build-backend = "agent_plugins.build.uv_build"
|
|
38
|
+
|
|
39
|
+
[tool.agent-plugins]
|
|
40
|
+
root = "."
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Build with the [uv package manager](https://docs.astral.sh/uv/):
|
|
44
|
+
|
|
45
|
+
```console
|
|
46
|
+
uv build
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The [quickstart](https://peter-gy.github.io/agent-plugins/guide/getting-started) creates a complete project, builds it, and locates the installed plugin. Use the [Hatchling adapter](https://peter-gy.github.io/agent-plugins/guide/build-backends#hatchling) for Hatchling projects, or [attach a prebuilt wheel](https://peter-gy.github.io/agent-plugins/guide/attach-wheel) when another tool owns the build:
|
|
50
|
+
|
|
51
|
+
```console
|
|
52
|
+
agent-plugins attach-wheel dist/my_project-0.1.0-py3-none-any.whl --project .
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Attachment updates the wheel in place. Pass `--output-dir` to preserve the input.
|
|
56
|
+
|
|
57
|
+
## Inspect an installed plugin
|
|
58
|
+
|
|
59
|
+
Install `agent-plugins` in the environment you want to inspect. The package includes its own Agent Skill:
|
|
60
|
+
|
|
61
|
+
```console
|
|
62
|
+
pip install agent-plugins
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import agent_plugins as ap
|
|
67
|
+
|
|
68
|
+
plugin = ap.locate("agent-plugins")
|
|
69
|
+
skill = plugin.skill("agent-plugins")
|
|
70
|
+
|
|
71
|
+
print(skill.source)
|
|
72
|
+
print(skill.file("SKILL.md"))
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Pass your library's distribution name to `locate()` to inspect its plugin. Use [`Plugin.from_project()`](https://peter-gy.github.io/agent-plugins/guide/inspect-project) to inspect the selected source files before building.
|
|
76
|
+
|
|
77
|
+
## Documentation
|
|
78
|
+
|
|
79
|
+
- [Get started](https://peter-gy.github.io/agent-plugins/guide/getting-started): package, install, and locate a plugin.
|
|
80
|
+
- [How packaging works](https://peter-gy.github.io/agent-plugins/guide/artifact-lifecycle): wheels, source distributions, and editable installs.
|
|
81
|
+
- [Integrate](https://peter-gy.github.io/agent-plugins/guide/inspect-installed): read skills, inspect files, and resolve MCP configuration.
|
|
82
|
+
- [Python API](https://peter-gy.github.io/agent-plugins/reference/python-api) · [CLI](https://peter-gy.github.io/agent-plugins/reference/cli) · [Configuration](https://peter-gy.github.io/agent-plugins/reference/pyproject)
|
|
83
|
+
|
|
84
|
+
<details>
|
|
85
|
+
<summary>Packaging lifecycle</summary>
|
|
86
|
+
|
|
87
|
+
<p align="center">
|
|
88
|
+
<picture>
|
|
89
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-dark.svg">
|
|
90
|
+
<source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg">
|
|
91
|
+
<img alt="Core model: an authored Python project builds into one wheel that installs the library beside its version-matched Agent Plugin, which locate() returns as a plugin handle" src="https://raw.githubusercontent.com/peter-gy/agent-plugins/main/docs/public/brand/agent-plugins-core-model-light.svg" width="300">
|
|
92
|
+
</picture>
|
|
93
|
+
</p>
|
|
94
|
+
|
|
95
|
+
</details>
|
|
96
|
+
|
|
97
|
+
## Development
|
|
98
|
+
|
|
99
|
+
See [development_docs/](https://github.com/peter-gy/agent-plugins/tree/main/development_docs) for setup, architecture, checks, and releases. Serve the documentation locally with `pnpm --dir docs dev`.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
[Apache-2.0](https://github.com/peter-gy/agent-plugins/blob/main/LICENSE).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "agent-plugins"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.2.1"
|
|
4
4
|
description = "Ship Agent Plugins with Python packages and inspect their installed files"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "Apache-2.0"
|
|
@@ -21,6 +21,8 @@ name = "Péter Ferenc Gyarmati"
|
|
|
21
21
|
email = "dev.petergy@gmail.com"
|
|
22
22
|
|
|
23
23
|
[project.urls]
|
|
24
|
+
Documentation = "https://peter-gy.github.io/agent-plugins/"
|
|
25
|
+
Issues = "https://github.com/peter-gy/agent-plugins/issues"
|
|
24
26
|
Source = "https://github.com/peter-gy/agent-plugins"
|
|
25
27
|
|
|
26
28
|
[project.scripts]
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "agent-plugins"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.2.1"
|
|
4
4
|
description = "Ship Agent Plugins with Python packages and inspect their installed files"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "Apache-2.0"
|
|
@@ -22,6 +22,8 @@ classifiers = [
|
|
|
22
22
|
]
|
|
23
23
|
|
|
24
24
|
[project.urls]
|
|
25
|
+
Documentation = "https://peter-gy.github.io/agent-plugins/"
|
|
26
|
+
Issues = "https://github.com/peter-gy/agent-plugins/issues"
|
|
25
27
|
Source = "https://github.com/peter-gy/agent-plugins"
|
|
26
28
|
|
|
27
29
|
[project.scripts]
|
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
"""
|
|
1
|
+
"""Package and inspect Agent Plugins through Python distributions."""
|
|
2
2
|
|
|
3
3
|
from ._build.plan import BuildPlan, FileMapping, build_plan
|
|
4
|
+
from ._build.wheel import WheelAttachment, attach_wheel
|
|
4
5
|
from ._discovery import installed, locate
|
|
5
6
|
from ._errors import AgentPluginError
|
|
6
7
|
from ._plugin import Plugin
|
|
@@ -9,6 +10,7 @@ from ._schema import (
|
|
|
9
10
|
Manifest,
|
|
10
11
|
MCPConfig,
|
|
11
12
|
MCPServer,
|
|
13
|
+
ResolvedStdioServer,
|
|
12
14
|
SSEServer,
|
|
13
15
|
StdioServer,
|
|
14
16
|
StreamableHTTPServer,
|
|
@@ -26,12 +28,15 @@ __all__ = [
|
|
|
26
28
|
"MCPServer",
|
|
27
29
|
"Manifest",
|
|
28
30
|
"Plugin",
|
|
31
|
+
"ResolvedStdioServer",
|
|
29
32
|
"SSEServer",
|
|
30
33
|
"Skill",
|
|
31
34
|
"StdioServer",
|
|
32
35
|
"StreamableHTTPServer",
|
|
33
36
|
"ValidationError",
|
|
34
37
|
"ValidationIssue",
|
|
38
|
+
"WheelAttachment",
|
|
39
|
+
"attach_wheel",
|
|
35
40
|
"build_plan",
|
|
36
41
|
"installed",
|
|
37
42
|
"locate",
|
|
@@ -10,7 +10,7 @@ from typing import Protocol, cast
|
|
|
10
10
|
|
|
11
11
|
from .plan import build_plan
|
|
12
12
|
from .sdist import write_sdist_plugin
|
|
13
|
-
from .wheel import
|
|
13
|
+
from .wheel import _attach_editable_wheel, attach_wheel
|
|
14
14
|
|
|
15
15
|
ConfigSettings = dict[str, object] | None
|
|
16
16
|
|
|
@@ -66,7 +66,7 @@ class BuildBackend:
|
|
|
66
66
|
filename = self._delegate.build_wheel(
|
|
67
67
|
wheel_directory, config_settings, metadata_directory
|
|
68
68
|
)
|
|
69
|
-
|
|
69
|
+
attach_wheel(Path(wheel_directory) / filename, plan=plan)
|
|
70
70
|
return filename
|
|
71
71
|
|
|
72
72
|
def build_sdist(
|
|
@@ -91,7 +91,7 @@ class BuildBackend:
|
|
|
91
91
|
filename = self._delegate.build_editable(
|
|
92
92
|
wheel_directory, config_settings, metadata_directory
|
|
93
93
|
)
|
|
94
|
-
|
|
94
|
+
_attach_editable_wheel(Path(wheel_directory) / filename, plan)
|
|
95
95
|
return filename
|
|
96
96
|
|
|
97
97
|
def get_requires_for_build_wheel(
|