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

# Python imports

> Import authoring contracts from their Harnest domain.

Import each capability from its public domain module. The examples in this documentation use these paths so you can find related types and operations in one place:

```python theme={null}
from harnest.agent import Agent, AgentRuntimePrincipal, client_tool, tool
from harnest.auth import AuthPrincipal, AuthenticationError
from harnest import context, cron, lifecycle
from harnest.sandbox import Sandbox, control
```

The package root exposes feature namespaces only. Classes, decorators, functions, errors, and types stay in the feature module that owns them.

## Domain imports

| Capability               | Public module                    | Examples                                                                                     |
| ------------------------ | -------------------------------- | -------------------------------------------------------------------------------------------- |
| Agents and graphs        | `harnest.agent`, `harnest.graph` | `Agent`, `tool`, `client_tool`, `AgentRuntimePrincipal`, `Graph`, `Edge`                     |
| Authentication           | `harnest.auth`                   | `AuthPrincipal`, `Authenticator`, `AuthenticationError`, `principal_for`                     |
| HTTP endpoints and hooks | `harnest.http`                   | `AgentInvoker`, `AgentResponse`, `HTTPCallRequest`, `HTTPLifecycleContext`                   |
| Server configuration     | `harnest.server`                 | `ServerConfig`, `ServerLimits`, `load_server_config`                                         |
| Agent tools              | `harnest.agent`                  | `tool`, `client_tool`, `ClientToolError`, `ToolCallRequest`, `ToolLifecycleContext`          |
| MCP                      | `harnest.mcp`                    | `MCPClient`, `MCPContext`, `MCPToolCallRequest`, `MCPToolCallError`                          |
| Models                   | `harnest.model`                  | `LiteLLMModel`, `LiteLLMContext`, `ModelCallRequest`, `ModelLifecycleError`                  |
| Lifecycle                | `from harnest import lifecycle`  | `agent`, `model`, `tool`, `mcp`, `http`, `storage`, `resource`, `coverage`                   |
| Invocation context       | `from harnest import context`    | `provider`, `resource`, `SessionContext`, `StorageContext`, `ScopedAssets`, `AgentSession`   |
| Recurring Tasks          | `from harnest import cron`       | `Cron`, `CronJob`, `create`, `get`, `list`, `update`, `pause`, `resume`, `cancel`, `delete`  |
| Sandbox providers        | `harnest.sandbox`                | `Sandbox`, `SandboxNetworkPolicy`, `SandboxProviderCapabilities`, `SandboxResult`, `control` |
| Runtime adapters         | `harnest.runtime`                | `ResponseRequest`, `InvocationRequest`, `RuntimeDriver`, `RuntimeEvent`                      |
| Assets                   | `harnest.assets`                 | `AssetStorage`, `AssetScope`, `Stored`                                                       |
| Storage                  | `harnest.store`                  | `MemoryStore`, `PostgresStore`, `RedisStore`, `CustomStorage`, `StorageRegistry`             |
| Long-term memory         | `harnest.memory`                 | `MemoryStore`, `MemoryRecord`, `MemoryScope`, `MemoryPage`                                   |

Agent-owned approval contracts live in `harnest.agent.approval`. Other existing
domain modules include `harnest.content`, `harnest.credentials`,
`harnest.continuation`, `harnest.extensions`, `harnest.skills`, `harnest.task`,
`harnest.logging`, and `harnest.tracing`.

`AgentResponse` from `harnest.http` represents an HTTP route response. `AgentResponse` from `harnest.context` represents a local agent invocation response; select the contract for your integration.

## IDE autocomplete and hover help

Harnest ships as a typed Python package with inline signatures, API docstrings,
and a PEP 561 `py.typed` marker. Because each agent uses an isolated managed
environment, synchronize it before opening the project in your editor.

```bash theme={null}
harnest env sync .
```

From the agent folder, the command creates or atomically updates `.venv` as a link to the
current managed environment. VS Code, PyCharm, and other Python IDEs normally
detect that conventional project path automatically. The editor can then
resolve `harnest` and show completion, parameter and return types, and hover
documentation without a separate SDK installation or manual interpreter setup.

Harnest never replaces a `.venv` directory, file, or link that it does not own.
If the path already belongs to you, synchronization still succeeds and prints
`IDE environment unchanged:` with the exact managed Python executable to select
manually. Add `.venv` to version-control ignores when working in a project that
was not created by `harnest init`.

The managed wheel also includes editor-only definitions for
`harnest.extensions.docker` and `harnest.extensions.hatchet`. Those imports get
completion and hover help while the actual modules remain available at runtime
only when their corresponding official extension is installed in the project.

Run `env sync` after dependency changes. Harnest retargets its `.venv` link when
the content-addressed runtime changes, so an automatically detected interpreter
continues to resolve the current environment.

## Scoped operations

Sandbox execution and cleanup share a namespace:

```python theme={null}
from harnest.sandbox import control

with control.execute(timeout_seconds=30) as execution:
    execution.check()
    # Perform provider work with execution.remaining() as the I/O budget.

with control.cleanup(timeout_seconds=5) as cleanup:
    cleanup.check()
    # Release owned resources using cleanup.remaining() as the I/O budget.
```

`control.current()` returns the active scope. See [sandbox failure recovery and cleanup](/docs/harnest/build/sandboxing#failure-recovery-and-cleanup) for cancellation and deadline guarantees.

Query lifecycle coverage with the same domain pattern:

```python theme={null}
from harnest import lifecycle

coverage = lifecycle.coverage("langgraph", "managed")
```

## Public API stability

The modules in the table above are Harnest's supported Python authoring
surface. Their declared exports are snapshot-tested so an accidental removal or
move fails the release gate. Public callable annotations and hover docstrings
are checked by the same gate. Re-exports preserve object identity, including
exception classes used by existing handlers.

During `0.x`, Harnest may make a breaking public Python API change only in a
minor release. Public names and signatures are otherwise backward compatible;
deprecated APIs remain available for at least one minor release before removal,
except when retaining them would preserve a security defect. Patch releases do
not intentionally break these contracts.

Serialized plans, locks, manifests, and request/response documents use their own
schema or format versions. A Python re-export does not change those formats, and
a schema migration does not imply that exception identity or Python signatures
may change silently.