# Your first plugin

From pip install to a tool the agent can call, in about fifteen minutes.

Source: https://docs.omazy.ai/reference/sdk/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

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

## 2. Write a tool

```python
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.