Use a Runtime Plugin

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:

tools/query_warehouse.py

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:

lib/warehouse_service.py

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:

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.

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.

Create your own plugin

Define the local manifest, singleton, typed context, and dependencies.

Use plugin lifecycle

Add only the hooks and factories declared by the manifest.

Overview

Get started

Guides

Use a Runtime Plugin

Resolve the typed context explicitly

Find published plugins

Create your own plugin

Use plugin lifecycle

​Resolve the typed context explicitly

​Find published plugins

Create your own plugin

Use plugin lifecycle

Resolve the typed context explicitly

Find published plugins