agently-sdk


Nameagently-sdk JSON
Version 0.4.0 PyPI version JSON
download
home_pageNone
SummaryOfficial SDK for developing extensions for the Agently framework
upload_time2025-03-01 08:09:47
maintainerNone
docs_urlNone
authorNone
requires_python>=3.11
licenseMIT
keywords agently sdk ai agent plugin
VCS
bugtrack_url
requirements build twine pytest pytest-cov black isort mypy semantic-kernel pydantic
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # Agently SDK

[![PyPI version](https://badge.fury.io/py/agently-sdk.svg)](https://badge.fury.io/py/agently-sdk)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official SDK for developing extensions for the [Agently](https://github.com/onwardplatforms/agently) framework. Currently focused on plugin development, with more capabilities planned for future releases.

## Installation

```bash
pip install agently-sdk
```

## Quick Start

Create a simple plugin:

```python
from agently_sdk.plugins import Plugin, PluginVariable, kernel_function

class HelloPlugin(Plugin):
    name = "hello"
    description = "A simple hello world plugin"
    
    default_name = PluginVariable(
        name="default_name",
        description="Default name to use in greetings",
        default="World"
    )
    
    @kernel_function
    def greet(self, name=None) -> str:
        """Greet the user."""
        return f"Hello, {name or self.default_name}!"
```

## Plugin Development

### Plugin Class

The `Plugin` class is the base class for all Agently plugins. It provides the structure and interface for creating plugins that can be used by Agently agents.

| Attribute     | Type  | Required | Description                                     |
| ------------- | ----- | -------- | ----------------------------------------------- |
| `name`        | `str` | Yes      | The name of the plugin, used for identification |
| `description` | `str` | Yes      | A brief description of what the plugin does     |

#### Methods

| Method                   | Description                                                                 |
| ------------------------ | --------------------------------------------------------------------------- |
| `get_kernel_functions()` | Returns a dictionary of all methods decorated with `@kernel_function`       |
| `get_plugin_variables()` | Returns a dictionary of all `PluginVariable` instances defined in the class |

### PluginVariable

The `PluginVariable` class represents a configurable variable for a plugin. It allows plugins to be configured with different values when they are loaded by Agently.

| Parameter     | Type                    | Required | Default | Description                                    |
| ------------- | ----------------------- | -------- | ------- | ---------------------------------------------- |
| `name`        | `str`                   | Yes      | -       | The name of the variable                       |
| `description` | `str`                   | Yes      | -       | A description of what the variable is used for |
| `default`     | `Any`                   | No       | `None`  | The default value if none is provided          |
| `required`    | `bool`                  | No       | `False` | Whether this variable must be provided         |
| `validator`   | `Callable[[Any], bool]` | No       | `None`  | Optional function that validates the value     |
| `choices`     | `List[Any]`             | No       | `None`  | Optional list of valid choices for the value   |
| `type`        | `Type`                  | No       | `None`  | Optional type constraint for the value         |

#### Methods

| Method            | Description                                           |
| ----------------- | ----------------------------------------------------- |
| `validate(value)` | Validates a value against this variable's constraints |
| `to_dict()`       | Converts this variable to a dictionary representation |

### Kernel Function Decorator

Agently SDK provides two decorators for marking methods as callable by agents:

1. `@agently_function` - The recommended decorator for Agently plugins
2. `@kernel_function` - An alias for `@agently_function` provided for backward compatibility

Both decorators wrap the `kernel_function` decorator from `semantic_kernel.functions` while maintaining compatibility with our existing code. If the Semantic Kernel package is not available, they fall back to a compatible implementation.

```python
from agently_sdk.plugins import Plugin, PluginVariable, agently_function

class MyPlugin(Plugin):
    name = "my_plugin"
    description = "A sample plugin"
    
    @agently_function
    def my_function(self, param1: str, param2: int = 0) -> str:
        """
        Function docstring that describes what this function does.
        
        Args:
            param1: Description of param1
            param2: Description of param2
            
        Returns:
            Description of the return value
        """
        # Implementation
        return result
```

## Best Practices

### Plugin Design

1. **Clear Purpose**: Each plugin should have a clear, focused purpose
2. **Descriptive Names**: Use descriptive names for plugins, variables, and functions
3. **Comprehensive Documentation**: Include detailed docstrings for all functions
4. **Input Validation**: Validate all inputs to ensure robust behavior
5. **Error Handling**: Handle errors gracefully and provide informative error messages

### Variable Configuration

1. **Default Values**: Provide sensible default values for variables when possible
2. **Validation**: Use validators to ensure variables meet requirements
3. **Type Constraints**: Specify value types to catch type errors early
4. **Descriptive Names**: Use clear, descriptive names for variables

## License

MIT 

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "agently-sdk",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "agently, sdk, ai, agent, plugin",
    "author": null,
    "author_email": "Onward Platforms <info@onwardplatforms.com>",
    "download_url": "https://files.pythonhosted.org/packages/37/b4/8827991ef8f8e7b3f2a72594f0c5078df53b000e7c83a449664ad61ef1c5/agently_sdk-0.4.0.tar.gz",
    "platform": null,
    "description": "# Agently SDK\n\n[![PyPI version](https://badge.fury.io/py/agently-sdk.svg)](https://badge.fury.io/py/agently-sdk)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThe official SDK for developing extensions for the [Agently](https://github.com/onwardplatforms/agently) framework. Currently focused on plugin development, with more capabilities planned for future releases.\n\n## Installation\n\n```bash\npip install agently-sdk\n```\n\n## Quick Start\n\nCreate a simple plugin:\n\n```python\nfrom agently_sdk.plugins import Plugin, PluginVariable, kernel_function\n\nclass HelloPlugin(Plugin):\n    name = \"hello\"\n    description = \"A simple hello world plugin\"\n    \n    default_name = PluginVariable(\n        name=\"default_name\",\n        description=\"Default name to use in greetings\",\n        default=\"World\"\n    )\n    \n    @kernel_function\n    def greet(self, name=None) -> str:\n        \"\"\"Greet the user.\"\"\"\n        return f\"Hello, {name or self.default_name}!\"\n```\n\n## Plugin Development\n\n### Plugin Class\n\nThe `Plugin` class is the base class for all Agently plugins. It provides the structure and interface for creating plugins that can be used by Agently agents.\n\n| Attribute     | Type  | Required | Description                                     |\n| ------------- | ----- | -------- | ----------------------------------------------- |\n| `name`        | `str` | Yes      | The name of the plugin, used for identification |\n| `description` | `str` | Yes      | A brief description of what the plugin does     |\n\n#### Methods\n\n| Method                   | Description                                                                 |\n| ------------------------ | --------------------------------------------------------------------------- |\n| `get_kernel_functions()` | Returns a dictionary of all methods decorated with `@kernel_function`       |\n| `get_plugin_variables()` | Returns a dictionary of all `PluginVariable` instances defined in the class |\n\n### PluginVariable\n\nThe `PluginVariable` class represents a configurable variable for a plugin. It allows plugins to be configured with different values when they are loaded by Agently.\n\n| Parameter     | Type                    | Required | Default | Description                                    |\n| ------------- | ----------------------- | -------- | ------- | ---------------------------------------------- |\n| `name`        | `str`                   | Yes      | -       | The name of the variable                       |\n| `description` | `str`                   | Yes      | -       | A description of what the variable is used for |\n| `default`     | `Any`                   | No       | `None`  | The default value if none is provided          |\n| `required`    | `bool`                  | No       | `False` | Whether this variable must be provided         |\n| `validator`   | `Callable[[Any], bool]` | No       | `None`  | Optional function that validates the value     |\n| `choices`     | `List[Any]`             | No       | `None`  | Optional list of valid choices for the value   |\n| `type`        | `Type`                  | No       | `None`  | Optional type constraint for the value         |\n\n#### Methods\n\n| Method            | Description                                           |\n| ----------------- | ----------------------------------------------------- |\n| `validate(value)` | Validates a value against this variable's constraints |\n| `to_dict()`       | Converts this variable to a dictionary representation |\n\n### Kernel Function Decorator\n\nAgently SDK provides two decorators for marking methods as callable by agents:\n\n1. `@agently_function` - The recommended decorator for Agently plugins\n2. `@kernel_function` - An alias for `@agently_function` provided for backward compatibility\n\nBoth decorators wrap the `kernel_function` decorator from `semantic_kernel.functions` while maintaining compatibility with our existing code. If the Semantic Kernel package is not available, they fall back to a compatible implementation.\n\n```python\nfrom agently_sdk.plugins import Plugin, PluginVariable, agently_function\n\nclass MyPlugin(Plugin):\n    name = \"my_plugin\"\n    description = \"A sample plugin\"\n    \n    @agently_function\n    def my_function(self, param1: str, param2: int = 0) -> str:\n        \"\"\"\n        Function docstring that describes what this function does.\n        \n        Args:\n            param1: Description of param1\n            param2: Description of param2\n            \n        Returns:\n            Description of the return value\n        \"\"\"\n        # Implementation\n        return result\n```\n\n## Best Practices\n\n### Plugin Design\n\n1. **Clear Purpose**: Each plugin should have a clear, focused purpose\n2. **Descriptive Names**: Use descriptive names for plugins, variables, and functions\n3. **Comprehensive Documentation**: Include detailed docstrings for all functions\n4. **Input Validation**: Validate all inputs to ensure robust behavior\n5. **Error Handling**: Handle errors gracefully and provide informative error messages\n\n### Variable Configuration\n\n1. **Default Values**: Provide sensible default values for variables when possible\n2. **Validation**: Use validators to ensure variables meet requirements\n3. **Type Constraints**: Specify value types to catch type errors early\n4. **Descriptive Names**: Use clear, descriptive names for variables\n\n## License\n\nMIT \n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "Official SDK for developing extensions for the Agently framework",
    "version": "0.4.0",
    "project_urls": {
        "Bug Tracker": "https://github.com/onwardplatforms/agently-sdk/issues",
        "Documentation": "https://github.com/onwardplatforms/agently-sdk",
        "Homepage": "https://github.com/onwardplatforms/agently-sdk"
    },
    "split_keywords": [
        "agently",
        " sdk",
        " ai",
        " agent",
        " plugin"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "78045c7f3fc16b3759e879b9ece058bbf73b6a7950ea05ff3922b7576e9d4ce0",
                "md5": "36d523bba94871de1232ec41de043f95",
                "sha256": "372fbedb204db07aa4aa7d35f68a08b8b53d4e306f7efb74f8ccc3d88ee5cb36"
            },
            "downloads": -1,
            "filename": "agently_sdk-0.4.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "36d523bba94871de1232ec41de043f95",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 12594,
            "upload_time": "2025-03-01T08:09:45",
            "upload_time_iso_8601": "2025-03-01T08:09:45.535235Z",
            "url": "https://files.pythonhosted.org/packages/78/04/5c7f3fc16b3759e879b9ece058bbf73b6a7950ea05ff3922b7576e9d4ce0/agently_sdk-0.4.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "37b48827991ef8f8e7b3f2a72594f0c5078df53b000e7c83a449664ad61ef1c5",
                "md5": "f2a5be2a3c1d2820551596f48cbaf98e",
                "sha256": "ecf414c8515c206cb4c17c7ef06309e495cec9f3a1afc32bbb789dab965bb2b7"
            },
            "downloads": -1,
            "filename": "agently_sdk-0.4.0.tar.gz",
            "has_sig": false,
            "md5_digest": "f2a5be2a3c1d2820551596f48cbaf98e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 15551,
            "upload_time": "2025-03-01T08:09:47",
            "upload_time_iso_8601": "2025-03-01T08:09:47.132687Z",
            "url": "https://files.pythonhosted.org/packages/37/b4/8827991ef8f8e7b3f2a72594f0c5078df53b000e7c83a449664ad61ef1c5/agently_sdk-0.4.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-03-01 08:09:47",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "onwardplatforms",
    "github_project": "agently-sdk",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "build",
            "specs": []
        },
        {
            "name": "twine",
            "specs": []
        },
        {
            "name": "pytest",
            "specs": []
        },
        {
            "name": "pytest-cov",
            "specs": []
        },
        {
            "name": "black",
            "specs": []
        },
        {
            "name": "isort",
            "specs": []
        },
        {
            "name": "mypy",
            "specs": []
        },
        {
            "name": "semantic-kernel",
            "specs": []
        },
        {
            "name": "pydantic",
            "specs": []
        }
    ],
    "lcname": "agently-sdk"
}
        
Elapsed time: 0.41022s