> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usefused.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use a Runtime Plugin

> Discover a Runtime Plugin, consume its compiler-owned namespace, and keep access invocation-scoped.

A project-local Runtime Plugin is discovered from `plugins/<name>/plugin.yaml`. You do not add it to a central registry or manually attach it to the root agent.

After compilation, Harnest exposes the plugin module as `harnest.plugins.<name>`. Import the singleton from a discovered Agent Tool and call its bounded API:

```python tools/query_warehouse.py theme={null}
from harnest.plugins.warehouse import plugin as warehouse
from harnest.tool import tool


@tool
async def query_warehouse(statement: str) -> list[dict]:
    """Query the configured warehouse through its Runtime Plugin."""

    return await warehouse.query(statement)
```

The call runs inside a managed invocation, so `warehouse.context` resolves the typed `WarehouseContext` created for that request. Retaining it after the invocation ends fails closed.

## Resolve the typed context explicitly

Trusted application code can ask Harnest for the same invocation-scoped view:

```python lib/warehouse_service.py theme={null}
from harnest import context
from harnest.plugins.warehouse import WarehouseContext


async def run_query(statement: str) -> list[dict]:
    """Resolve the warehouse capability without exposing its SDK client."""

    warehouse = context.plugins("warehouse", WarehouseContext)
    return await warehouse.query(statement)
```

Keep application clients and connection pools private on the singleton. Expose domain operations through the typed context instead of returning the raw SDK object.

## Find published plugins

Search public PyPI for compatible `harnest-plugin-*` packages:

```bash theme={null}
harnest plugins search warehouse
```

Search verifies package naming, one `harnest.plugins` entry point, the bundled `plugin.yaml` and `plugin.py`, release identity, and the published wheel digest without importing package code. `official` means Fused controls and explicitly recognizes that package name; `community` means only that the wheel satisfies the structural contract. Neither label is a security review.

<Warning>
  Search does not install a plugin. The current compiler discovers Runtime Plugins from the project-local `plugins/<name>/` folder. Merely adding or installing a PyPI package does not register its entry point as a project plugin. Obtain and review the publisher's source bundle, place it under the local `plugins/` directory, then run `harnest env sync` before compiling.
</Warning>

<CardGroup cols={2}>
  <Card title="Create your own plugin" icon="puzzle-piece" href="/harnest/build/runtime-plugins/create">
    Define the local manifest, singleton, typed context, and dependencies.
  </Card>

  <Card title="Use plugin lifecycle" icon="arrows-rotate" href="/harnest/build/runtime-plugins/lifecycle">
    Add only the hooks and factories declared by the manifest.
  </Card>
</CardGroup>
