Your first plugin

The shortest useful plugin is one tool and a manifest. Everything else is optional and can wait until you need it.

1. Install

pip install omazy-plugin-sdk

2. Write a tool

from omazy_plugin_sdk import tool

@tool
def check_stock(sku: str, ctx) -> dict:
    """Check whether a SKU is in stock and how many units remain."""
    response = ctx.http.get(f"https://inventory.example.com/stock/{sku}")
    response.raise_for_status()
    return response.json()

Three things are doing real work here, and none of them are obvious:

The type hints become the tool’s parameter schema. sku: str is what tells the model to pass a string rather than an object it invented.

The docstring is the tool’s description. The model chooses between your tools by reading these, so write them for a capable colleague who has never seen your system. “Check stock” is worse than the version above, because it does not say what comes back.

The return value must be serialisable. Return a dict, not your ORM object.

3. Describe it

The manifest says what the plugin is, what it needs, and what it contributes. It is also where you declare settings, so the console can render an install form without you writing any UI.

4. Run it locally

Run the plugin server and point a development workspace at it. You get the same call path a published plugin gets, so anything that works here works installed.

5. Test the boring failures first

New plugins usually break in the same four places, in the same order:

1. The upstream API is slow and the tool times out.
2. The upstream API returns an error and the tool raises instead of explaining.
3. The model calls the tool with a plausible but wrong argument.
4. The tool works and returns something the model cannot summarise.

Number two is the one worth fixing early. A tool that raises gives the agent nothing to say. A tool that returns {"error": "no such SKU"} lets the agent tell the customer something true. Failing informatively beats failing loudly.

What not to do

Do not store credentials in your plugin. Ask ctx. An install-scoped credential disappears when the plugin is uninstalled, and a hard-coded one does not, which is the difference between an uninstall and a rumour of one.