# SDK

The Python plugin SDK. Build a plugin that adds tools, prompts, automations and webhooks to an Omazy workspace.

Source: https://docs.omazy.ai/reference/sdk/

The SDK is for building **plugins**: Python packages that extend what an agent
can do beyond answering from what it has read.

An agent without plugins knows things. An agent with plugins can also do things.
That is the whole distinction, and it is a larger one than it sounds, because
"can I check my order status" and "can you check my order status" are separated
by exactly one integration.

```sh
pip install omazy-plugin-sdk
```

## A plugin is a Python module

No framework to inherit from and no directory ceremony to memorise. You write
functions, decorate the ones you want exposed, and ship a manifest describing
what the plugin is and what it needs.

```python
from omazy_plugin_sdk import tool

@tool
def order_status(order_id: str, ctx) -> dict:
    """Look up the current status of an order."""
    return ctx.http.get(f"/orders/{order_id}").json()
```

The docstring is not decoration. It is what the model reads to decide whether
this tool is the right one to call, which makes it the most load-bearing comment
you will ever write.

## The eleven component types

A plugin can contribute any of these. Most plugins use two or three.

| Component | Contributes |
|---|---|
| **Tool** | A function the agent can call mid-conversation. |
| **Resource** | Data exposed over MCP. |
| **System prompt fragment** | Instructions merged into the agent's brief. |
| **Automation template** | A ready-made automation the workspace can enable. |
| **Webhook handler** | An endpoint for inbound calls from another system. |
| **Scheduled sync** | Work that runs on a timer. |
| **Lifecycle hooks** | Install, upgrade and uninstall behaviour. |
| **Action** | An operation a person can trigger from the console. |
| **Settings schema** | The configuration form shown at install time. |

## What `ctx` gives you

Every decorated function receives a context object. It is how a plugin reaches
the outside world without knowing anything about how the platform is deployed:
an HTTP client with credentials already attached, the current workspace and app,
storage, logging, and metering.

Take the credentials point seriously. A plugin should never carry its own copy
of a secret. Ask `ctx` and you get one scoped to the install, which means
uninstalling actually revokes access rather than merely hiding the button.

## Metering

If your plugin does something that costs money, meter it. The SDK gives you a
meter to record units of work, which is what allows a workspace to see what a
plugin actually costs rather than discovering it later in an invoice.

## Coming in this section

Writing your first plugin, the manifest specification, testing locally,
publishing, and the threat model you should read before you handle anyone else's
data.