Use a Harnest Extension

Harnest discovers extensions from extensions/<name>/extension.yaml. From the agent folder, install a verified public PyPI wheel by its short slug or full distribution name:

harnest extensions install warehouse
# Equivalent: harnest extensions install harnest-extension-warehouse
harnest env sync .

To review and test an unpublished extension, install its local source tree instead:

harnest extensions install ../harnest-extension-warehouse
harnest env sync .

The installer validates the package without importing its code. PyPI installs require a universal py3-none-any wheel; local installs use the source tree. Packages are copied intact to extensions/<manifest-name>, and only declared contributes directories are compiled. Use --force to replace an installed extension. Review its code and capabilities, then run harnest env sync . to refresh dependencies. Published wheels can declare Harnest or framework dependencies, but the installed project uses Harnest’s pinned versions. Other extension dependencies join the root environment. Local extensions must not redeclare compiler-owned packages. After compilation, Harnest exposes the extension module as harnest.extensions.<name>. Import the singleton from a discovered Agent Tool and call its bounded API:

tools/query_warehouse.py

from harnest.extensions.warehouse import extension as warehouse
from harnest.agent import tool

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

    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.extensions.warehouse import WarehouseContext

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

    warehouse = context.extensions("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 extensions

Search public PyPI for compatible harnest-extension-* packages:

harnest extensions search warehouse

Search checks package identity, entry point, manifest, and wheel digest without importing code. official identifies Fused-maintained packages; community means the package meets the structural contract. Neither label is a security review.

Search does not install an extension, and pip install alone does not register one with an agent project. Use harnest extensions install <slug-or-project> to verify and materialize a published wheel, then run harnest env sync before compiling.

Create your own extension

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

Use extension lifecycle

Add only the hooks and factories declared by the manifest.

API reference

Reference: harnest.agent.

Overview

Get started

Harnest Studio

Guides

API reference

Use a Harnest Extension

Resolve the typed context explicitly

Find published extensions

Create your own extension

Use extension lifecycle

API reference

​Resolve the typed context explicitly

​Find published extensions

Create your own extension

Use extension lifecycle

​API reference

Resolve the typed context explicitly

Find published extensions

API reference