agentskills-agentframework 0.2.2__tar.gz → 0.2.3__tar.gz

{agentskills_agentframework-0.2.2 → agentskills_agentframework-0.2.3}/PKG-INFO

@@ -1,19 +1,18 @@
 Metadata-Version: 2.4
 Name: agentskills-agentframework
-Version: 0.2.2
+Version: 0.2.3
 Summary: Microsoft Agent Framework integration for the Agent Skills format (https://agentskills.io)
 License: MIT
 Author: Pratik Panda
-Requires-Python: >=3.12,<4.0
+Requires-Python: >=3.12,<3.14
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
-Requires-Dist: agent-framework (>=1.0.0b1,<2.0)
+Requires-Dist: agent-framework (>=1.0.0rc3,<2.0)
 Requires-Dist: agentskills-core (>=0.1.0,<1.0)
 Project-URL: Homepage, https://agentskills.io
 Project-URL: Repository, https://github.com/pratikxpanda/agentskills-sdk
@@ -22,7 +21,7 @@ Description-Content-Type: text/markdown
 # agentskills-agentframework
 
 [![PyPI](https://img.shields.io/pypi/v/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
-[![Python 3.12+](https://img.shields.io/pypi/pyversions/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
+[![Python 3.12 | 3.13](https://img.shields.io/pypi/pyversions/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE)
 
 > Microsoft Agent Framework integration for the [Agent Skills SDK](../../../README.md) - turn a skill registry into Agent Framework tools.
@@ -35,13 +34,58 @@ Generates a set of [Microsoft Agent Framework](https://pypi.org/project/agent-fr
 pip install agentskills-agentframework
 ```
 
-Requires Python 3.12+. Installs `agentskills-core` and `agent-framework` as dependencies.
+Requires Python 3.12 or 3.13. Installs `agentskills-core` and `agent-framework` as dependencies.
 
-> **Note:** `agent-framework` is currently a pre-release dependency (`>=1.0.0b1`). The constraint will be updated once a stable release is published.
+> **Note:** `agent-framework` is currently a pre-release dependency (`>=1.0.0rc3`). The constraint will be updated once a stable release is published.
 
 ## Usage
 
+### Context Provider (recommended)
+
+The simplest way to integrate is via `AgentSkillsContextProvider`. It plugs into the Agent Framework lifecycle and automatically injects the skill catalog and tools on every `agent.run()` call — no manual system-prompt assembly required.
+
+```python
+from pathlib import Path
+
+from agent_framework import Agent
+from agentskills_core import SkillRegistry
+from agentskills_fs import LocalFileSystemSkillProvider
+from agentskills_agentframework import AgentSkillsContextProvider
+
+# Set up registry
+provider = LocalFileSystemSkillProvider(Path("./skills"))
+registry = SkillRegistry()
+await registry.register("incident-response", provider)
+
+# Create context provider
+skills_context_provider = AgentSkillsContextProvider(registry)
+
+# Pass it to the agent — catalog + tools are injected automatically
+agent = Agent(
+    client=client,  # any Agent Framework chat client
+    name="SREAssistant",
+    instructions="You are an SRE assistant.",
+    context_providers=[skills_context_provider],
+)
+response = await agent.run("What severity is a full DB outage?")
+```
+
+> See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/main/examples/agent-framework) for full working demos including client setup.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `skills_instruction_prompt` | Built-in template | Custom prompt template. Must contain `{skills_catalog}` and `{tools_usage_instructions}` placeholders. |
+| `skills_catalog_format` | `"xml"` | Skills catalog format — `"xml"` or `"markdown"`. |
+| `source_id` | `"agentskills"` | Unique identifier for this provider instance. |
+
+### Manual Tools
+
+For full control over system-prompt construction, use `get_tools()` directly:
+
 ```python
+from pathlib import Path
+
+from agent_framework import Agent
 from agentskills_core import SkillRegistry
 from agentskills_fs import LocalFileSystemSkillProvider
 from agentskills_agentframework import get_tools, get_tools_usage_instructions
@@ -55,10 +99,19 @@ await registry.register("incident-response", provider)
 tools = get_tools(registry)
 catalog = await registry.get_skills_catalog(format="xml")
 instructions = get_tools_usage_instructions()
-system_prompt = f"{catalog}\n\n{instructions}"
+
+# Pass to agent
+agent = Agent(
+    client=client,  # any Agent Framework chat client
+    name="SREAssistant",
+    instructions=f"{catalog}\n\n{instructions}",
+    tools=tools,
+)
 ```
 
-Pass `tools` to your Agent Framework agent and inject `system_prompt` into the `instructions`. The catalog tells the agent *what* skills exist; the usage instructions tell it *how* to use the tools.
+The catalog tells the agent *what* skills exist; the usage instructions tell it *how* to use the tools.
+
+> See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/main/examples/agent-framework) for full working demos including client setup.
 
 ## Generated Tools
 
@@ -74,6 +127,10 @@ All tools are async-compatible (`FunctionTool` with `@tool` decorator).
 
 ## API
 
+### `AgentSkillsContextProvider(registry, *, skills_instruction_prompt=None, skills_catalog_format="xml", source_id=None)`
+
+A `BaseContextProvider` that injects skill catalog + tools into the agent session automatically via `before_run()`. Skips injection when the registry has no skills.
+
 ### `get_tools(registry: SkillRegistry) -> list[FunctionTool]`
 
 Returns a list of Agent Framework function tools bound to the given registry.

agentskills_agentframework-0.2.3/README.md

@@ -0,0 +1,140 @@
+# agentskills-agentframework
+
+[![PyPI](https://img.shields.io/pypi/v/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
+[![Python 3.12 | 3.13](https://img.shields.io/pypi/pyversions/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE)
+
+> Microsoft Agent Framework integration for the [Agent Skills SDK](../../../README.md) - turn a skill registry into Agent Framework tools.
+
+Generates a set of [Microsoft Agent Framework](https://pypi.org/project/agent-framework/) `FunctionTool` instances from a `SkillRegistry`, ready to be passed to any Agent Framework agent.
+
+## Installation
+
+```bash
+pip install agentskills-agentframework
+```
+
+Requires Python 3.12 or 3.13. Installs `agentskills-core` and `agent-framework` as dependencies.
+
+> **Note:** `agent-framework` is currently a pre-release dependency (`>=1.0.0rc3`). The constraint will be updated once a stable release is published.
+
+## Usage
+
+### Context Provider (recommended)
+
+The simplest way to integrate is via `AgentSkillsContextProvider`. It plugs into the Agent Framework lifecycle and automatically injects the skill catalog and tools on every `agent.run()` call — no manual system-prompt assembly required.
+
+```python
+from pathlib import Path
+
+from agent_framework import Agent
+from agentskills_core import SkillRegistry
+from agentskills_fs import LocalFileSystemSkillProvider
+from agentskills_agentframework import AgentSkillsContextProvider
+
+# Set up registry
+provider = LocalFileSystemSkillProvider(Path("./skills"))
+registry = SkillRegistry()
+await registry.register("incident-response", provider)
+
+# Create context provider
+skills_context_provider = AgentSkillsContextProvider(registry)
+
+# Pass it to the agent — catalog + tools are injected automatically
+agent = Agent(
+    client=client,  # any Agent Framework chat client
+    name="SREAssistant",
+    instructions="You are an SRE assistant.",
+    context_providers=[skills_context_provider],
+)
+response = await agent.run("What severity is a full DB outage?")
+```
+
+> See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/main/examples/agent-framework) for full working demos including client setup.
+
+| Parameter | Default | Description |
+| --- | --- | --- |
+| `skills_instruction_prompt` | Built-in template | Custom prompt template. Must contain `{skills_catalog}` and `{tools_usage_instructions}` placeholders. |
+| `skills_catalog_format` | `"xml"` | Skills catalog format — `"xml"` or `"markdown"`. |
+| `source_id` | `"agentskills"` | Unique identifier for this provider instance. |
+
+### Manual Tools
+
+For full control over system-prompt construction, use `get_tools()` directly:
+
+```python
+from pathlib import Path
+
+from agent_framework import Agent
+from agentskills_core import SkillRegistry
+from agentskills_fs import LocalFileSystemSkillProvider
+from agentskills_agentframework import get_tools, get_tools_usage_instructions
+
+# Set up registry
+provider = LocalFileSystemSkillProvider(Path("./skills"))
+registry = SkillRegistry()
+await registry.register("incident-response", provider)
+
+# Build tools + system prompt
+tools = get_tools(registry)
+catalog = await registry.get_skills_catalog(format="xml")
+instructions = get_tools_usage_instructions()
+
+# Pass to agent
+agent = Agent(
+    client=client,  # any Agent Framework chat client
+    name="SREAssistant",
+    instructions=f"{catalog}\n\n{instructions}",
+    tools=tools,
+)
+```
+
+The catalog tells the agent *what* skills exist; the usage instructions tell it *how* to use the tools.
+
+> See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/main/examples/agent-framework) for full working demos including client setup.
+
+## Generated Tools
+
+| Tool | Parameters | Description |
+| --- | --- | --- |
+| `get_skill_metadata` | `skill_id` | Get structured metadata (name, description, etc.) |
+| `get_skill_body` | `skill_id` | Load the full markdown instructions |
+| `get_skill_reference` | `skill_id`, `name` | Read a reference document |
+| `get_skill_script` | `skill_id`, `name` | Read a script |
+| `get_skill_asset` | `skill_id`, `name` | Read an asset |
+
+All tools are async-compatible (`FunctionTool` with `@tool` decorator).
+
+## API
+
+### `AgentSkillsContextProvider(registry, *, skills_instruction_prompt=None, skills_catalog_format="xml", source_id=None)`
+
+A `BaseContextProvider` that injects skill catalog + tools into the agent session automatically via `before_run()`. Skips injection when the registry has no skills.
+
+### `get_tools(registry: SkillRegistry) -> list[FunctionTool]`
+
+Returns a list of Agent Framework function tools bound to the given registry.
+
+### `get_tools_usage_instructions() -> str`
+
+Returns a markdown string explaining the progressive-disclosure workflow - read metadata, then body, then fetch resources on demand. Designed for system-prompt injection alongside the skill catalog.
+
+## Example
+
+See [examples/agent-framework/](../../../examples/agent-framework/) for full working demos.
+
+## Error Handling
+
+| Scenario | Exception |
+| --- | --- |
+| Skill not found in registry | `SkillNotFoundError` |
+| Resource not found in skill | `ResourceNotFoundError` |
+| Provider errors (HTTP, filesystem) | `AgentSkillsError` |
+
+All exceptions inherit from `AgentSkillsError` (from `agentskills-core`).
+
+> **Note:** Binary content (scripts, assets, references) is decoded as UTF-8 with `errors="replace"`. Non-decodable bytes are replaced with the Unicode replacement character (�).
+
+## License
+
+MIT

{agentskills_agentframework-0.2.2 → agentskills_agentframework-0.2.3}/agentskills_agentframework/__init__.py

@@ -3,6 +3,9 @@
 This package bridges :mod:`agentskills_core` and `Microsoft Agent Framework
 <https://github.com/microsoft/agent-framework>`_, providing:
 
+* :class:`AgentSkillsContextProvider` -- a
+  :class:`agent_framework.BaseContextProvider` that automatically
+  injects skill awareness into an agent's session context.
 * :func:`get_tools` -- generates five
   :class:`~agent_framework.FunctionTool` instances that let an
   AI agent consume skills.
@@ -14,9 +17,11 @@ Install::
     pip install agentskills-agentframework
 """
 
+from agentskills_agentframework.context_provider import AgentSkillsContextProvider
 from agentskills_agentframework.tools import get_tools, get_tools_usage_instructions
 
 __all__ = [
+    "AgentSkillsContextProvider",
     "get_tools",
     "get_tools_usage_instructions",
 ]

agentskills_agentframework-0.2.3/agentskills_agentframework/context_provider.py

@@ -0,0 +1,170 @@
+"""Registry-backed context provider for Agent Framework agents.
+
+Provides :class:`AgentSkillsContextProvider`, which bridges a
+:class:`~agentskills_core.SkillRegistry` and the Agent Framework
+lifecycle so that skills catalogs and tools are delivered to the agent
+automatically on each ``agent.run()`` call.
+
+With the manual :func:`~agentskills_agentframework.get_tools` approach
+callers must build the system prompt themselves; the context provider
+eliminates that ceremony:
+
+    context_providers=[AgentSkillsContextProvider(registry)]
+
+On every invocation the provider:
+
+* Generates a lightweight skills catalog from the registry and appends
+  it to the session instructions.
+* Attaches five typed ``FunctionTool`` instances (the same set
+  produced by ``get_tools()``) so the agent can drill into individual
+  skills on demand.
+
+Because the registry accepts any
+:class:`~agentskills_core.SkillProvider` back-end — filesystem, HTTP,
+or custom — a single ``AgentSkillsContextProvider`` can aggregate
+skills from multiple sources.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Literal
+
+from agent_framework import BaseContextProvider, FunctionTool
+
+from agentskills_core import SkillRegistry
+
+from .tools import get_tools, get_tools_usage_instructions
+
+if TYPE_CHECKING:
+    from agent_framework import AgentSession, SessionContext, SupportsAgentRun
+
+
+_DEFAULT_SKILLS_INSTRUCTION_PROMPT = """\
+You have access to a set of skills that provide domain-specific \
+knowledge, procedures, and supporting resources. \
+Use them when a task aligns with a skill's domain.
+
+{skills_catalog}
+
+{tools_usage_instructions}\
+"""
+
+_PROMPT_VALIDATION_ERROR = (
+    "skills_instruction_prompt must contain {skills_catalog} and "
+    "{tools_usage_instructions} placeholders. "
+    "Escape literal braces by doubling them ({{ or }})."
+)
+
+
+def _validate_prompt_template(template: str) -> None:
+    """Validate that *template* contains the required placeholders."""
+    for placeholder in ("{skills_catalog}", "{tools_usage_instructions}"):
+        if placeholder not in template:
+            raise ValueError(_PROMPT_VALIDATION_ERROR)
+    try:
+        template.format(skills_catalog="", tools_usage_instructions="")
+    except (KeyError, IndexError, ValueError) as exc:
+        raise ValueError(_PROMPT_VALIDATION_ERROR) from exc
+
+
+class AgentSkillsContextProvider(BaseContextProvider):
+    """Expose a :class:`~agentskills_core.SkillRegistry` to an Agent Framework agent.
+
+    Wraps a registry of any-backend skills and hooks into the agent
+    lifecycle to supply three things at the start of every run:
+
+    * **Skills catalog** — a compact listing of registered skill
+      names and descriptions, appended to the session prompt.
+    * **Typed tool set** — five ``FunctionTool`` instances that let the
+      agent fetch metadata, full instructions, references, scripts, and
+      assets individually.
+    * **Tools usage instructions** — guidance on the progressive-disclosure
+      workflow so the agent knows how and when to invoke each tool.
+
+    The tool surface intentionally uses *typed* resource tools
+    (``get_skill_reference``, ``get_skill_script``, ``get_skill_asset``)
+    rather than a single generic reader so that the agent has clear
+    semantic signal about the kind of content it is requesting.
+
+    Args:
+        registry: The :class:`~agentskills_core.SkillRegistry` whose
+            skills should be exposed.
+
+    Keyword Args:
+        skills_instruction_prompt: Custom prompt template. Must contain
+            ``{skills_catalog}`` and ``{tools_usage_instructions}`` placeholders.
+            When ``None``, a sensible default is used.
+        skills_catalog_format: Format for the skills catalog —
+            ``"xml"`` (default) or ``"markdown"``.
+        source_id: Unique identifier for this provider instance.
+
+    Example::
+
+        from agentskills_agentframework import AgentSkillsContextProvider
+        from agentskills_core import SkillRegistry
+
+        registry = SkillRegistry()
+        await registry.register("incident-response", provider)
+
+        skills_context_provider = AgentSkillsContextProvider(registry)
+
+        agent = client.as_agent(
+            name="SREAssistant",
+            instructions="You are an SRE assistant.",
+            context_providers=[skills_context_provider],
+        )
+        response = await agent.run("What severity is a full DB outage?")
+    """
+
+    DEFAULT_SOURCE_ID: ClassVar[str] = "agentskills"
+
+    def __init__(
+        self,
+        registry: SkillRegistry,
+        *,
+        skills_instruction_prompt: str | None = None,
+        skills_catalog_format: Literal["xml", "markdown"] = "xml",
+        source_id: str | None = None,
+    ) -> None:
+        super().__init__(source_id or self.DEFAULT_SOURCE_ID)
+        self._registry = registry
+        self._skills_catalog_format = skills_catalog_format
+        self._tools: list[FunctionTool] = get_tools(registry)
+        self._tools_usage_instructions = get_tools_usage_instructions()
+
+        if skills_instruction_prompt is not None:
+            _validate_prompt_template(skills_instruction_prompt)
+        self._skills_prompt_template = (
+            skills_instruction_prompt or _DEFAULT_SKILLS_INSTRUCTION_PROMPT
+        )
+
+    async def before_run(
+        self,
+        *,
+        agent: SupportsAgentRun,
+        session: AgentSession,
+        context: SessionContext,
+        state: dict[str, Any],
+    ) -> None:
+        """Append skills catalog, tools, and usage instructions to the run context.
+
+        Does nothing when the registry is empty, so agents without any
+        registered skills pay no prompt-budget cost.
+
+        Args:
+            agent: The agent starting this run.
+            session: The active session.
+            context: Mutable run context to extend.
+            state: Provider-scoped mutable state persisted across runs.
+        """
+        if not self._registry.list_skills():
+            return
+
+        skills_catalog = await self._registry.get_skills_catalog(format=self._skills_catalog_format)
+        skills_prompt = self._skills_prompt_template.format(
+            skills_catalog=skills_catalog,
+            tools_usage_instructions=self._tools_usage_instructions,
+        )
+
+        context.extend_instructions(self.source_id, skills_prompt)
+        context.extend_tools(self.source_id, self._tools)

{agentskills_agentframework-0.2.2 → agentskills_agentframework-0.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agentskills-agentframework"
-version = "0.2.2"
+version = "0.2.3"
 description = "Microsoft Agent Framework integration for the Agent Skills format (https://agentskills.io)"
 license = "MIT"
 authors = ["Pratik Panda"]
@@ -17,11 +17,11 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
-python = ">=3.12,<4.0"
+python = ">=3.12,<3.14"
 agentskills-core = ">=0.1.0,<1.0"
-# agent-framework has no stable release yet; pin to pre-release range.
+# agent-framework >=1.0.0rc3 is required for BaseContextProvider / context_providers support.
 # TODO: Remove allow-prereleases once a stable 1.0+ is available.
-agent-framework = {version = ">=1.0.0b1,<2.0", allow-prereleases = true}
+agent-framework = {version = ">=1.0.0rc3,<2.0", allow-prereleases = true}
 
 [build-system]
 requires = ["poetry-core"]

agentskills_agentframework-0.2.2/README.md

@@ -1,82 +0,0 @@
-# agentskills-agentframework
-
-[![PyPI](https://img.shields.io/pypi/v/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
-[![Python 3.12+](https://img.shields.io/pypi/pyversions/agentskills-agentframework)](https://pypi.org/project/agentskills-agentframework/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/pratikxpanda/agentskills-sdk/blob/main/LICENSE)
-
-> Microsoft Agent Framework integration for the [Agent Skills SDK](../../../README.md) - turn a skill registry into Agent Framework tools.
-
-Generates a set of [Microsoft Agent Framework](https://pypi.org/project/agent-framework/) `FunctionTool` instances from a `SkillRegistry`, ready to be passed to any Agent Framework agent.
-
-## Installation
-
-```bash
-pip install agentskills-agentframework
-```
-
-Requires Python 3.12+. Installs `agentskills-core` and `agent-framework` as dependencies.
-
-> **Note:** `agent-framework` is currently a pre-release dependency (`>=1.0.0b1`). The constraint will be updated once a stable release is published.
-
-## Usage
-
-```python
-from agentskills_core import SkillRegistry
-from agentskills_fs import LocalFileSystemSkillProvider
-from agentskills_agentframework import get_tools, get_tools_usage_instructions
-
-# Set up registry
-provider = LocalFileSystemSkillProvider(Path("./skills"))
-registry = SkillRegistry()
-await registry.register("incident-response", provider)
-
-# Build tools + system prompt
-tools = get_tools(registry)
-catalog = await registry.get_skills_catalog(format="xml")
-instructions = get_tools_usage_instructions()
-system_prompt = f"{catalog}\n\n{instructions}"
-```
-
-Pass `tools` to your Agent Framework agent and inject `system_prompt` into the `instructions`. The catalog tells the agent *what* skills exist; the usage instructions tell it *how* to use the tools.
-
-## Generated Tools
-
-| Tool | Parameters | Description |
-| --- | --- | --- |
-| `get_skill_metadata` | `skill_id` | Get structured metadata (name, description, etc.) |
-| `get_skill_body` | `skill_id` | Load the full markdown instructions |
-| `get_skill_reference` | `skill_id`, `name` | Read a reference document |
-| `get_skill_script` | `skill_id`, `name` | Read a script |
-| `get_skill_asset` | `skill_id`, `name` | Read an asset |
-
-All tools are async-compatible (`FunctionTool` with `@tool` decorator).
-
-## API
-
-### `get_tools(registry: SkillRegistry) -> list[FunctionTool]`
-
-Returns a list of Agent Framework function tools bound to the given registry.
-
-### `get_tools_usage_instructions() -> str`
-
-Returns a markdown string explaining the progressive-disclosure workflow - read metadata, then body, then fetch resources on demand. Designed for system-prompt injection alongside the skill catalog.
-
-## Example
-
-See [examples/agent-framework/](../../../examples/agent-framework/) for full working demos.
-
-## Error Handling
-
-| Scenario | Exception |
-| --- | --- |
-| Skill not found in registry | `SkillNotFoundError` |
-| Resource not found in skill | `ResourceNotFoundError` |
-| Provider errors (HTTP, filesystem) | `AgentSkillsError` |
-
-All exceptions inherit from `AgentSkillsError` (from `agentskills-core`).
-
-> **Note:** Binary content (scripts, assets, references) is decoded as UTF-8 with `errors="replace"`. Non-decodable bytes are replaced with the Unicode replacement character (�).
-
-## License
-
-MIT