Skip to content

Your First Plugin

This tutorial creates a minimal plugin that adds a greeting agent.

1. Create package structure

Under plugins/src/cadence_example_plugins/ add a folder greeter_agent/:

plugins/src/cadence_example_plugins/greeter_agent/
├─ __init__.py
├─ plugin.py
├─ agent.py
└─ tools.py

__init__.py:

from cadence_sdk import register_plugin
from .plugin import GreeterPlugin


# Register on import
def _register():
    register_plugin(GreeterPlugin)


_register()

2. Define tools

tools.py:

from cadence_sdk import tool


@tool
def greet(name: str) -> str:
    """Return a friendly greeting for a given name."""
    return f"Hello, {name}! 👋"


greeter_tools = [greet]

3. Implement agent

agent.py:

from typing import List
from cadence_sdk import BaseAgent
from cadence_sdk.base.metadata import PluginMetadata


class GreeterAgent(BaseAgent):
    def __init__(self, metadata: PluginMetadata):
        # Enable parallel tool calls for better performance
        super().__init__(metadata, parallel_tool_calls=True)

    def get_tools(self) -> List:
        from .tools import greeter_tools
        return greeter_tools

    def get_system_prompt(self) -> str:
        return "You are a friendly greeter agent. Use the `greet` tool to greet users by name."

4. Implement plugin class

plugin.py:

from cadence_sdk import BasePlugin, PluginMetadata, BaseAgent


class GreeterPlugin(BasePlugin):
    @staticmethod
    def get_metadata() -> PluginMetadata:
        return PluginMetadata(
            name="greeter_agent",
            version="0.1.0",
            description="Greets users by name",
            capabilities=["greeting"],
            llm_requirements={
                "provider": "openai",
                "model": "gpt-4.1",
                "temperature": 0,
                "max_tokens": 256,
            },
            agent_type="specialized",
            dependencies=["cadence_sdk>=1.3.0,<2.0.0"],
        )

    @staticmethod
    def create_agent() -> BaseAgent:
        from .agent import GreeterAgent

        return GreeterAgent(GreeterPlugin.get_metadata())

5. Point Cadence to your plugins directory

Ensure .env contains:

CADENCE_PLUGINS_DIR=./plugins/src/cadence_example_plugins

6. Run Cadence and verify

python -m cadence start all
# In another terminal
curl http://127.0.0.1:8000/plugins/plugins

You should see greeter_agent in the list.

7. Try it

curl -X POST http://127.0.0.1:8000/conversation/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Use greeter_agent to greet Alice", "tone": "natural"}'

Tips

  • Keep create_agent() static
  • Keep tools simple and well documented
  • Add health_check() if your plugin uses external services
  • Consider enabling parallel_tool_calls=True in your agent constructor for better performance when tools can run concurrently

Looking to distribute your plugin without file system access? See Plugin Upload Feature to package as name-version.zip and install via UI/API.