Skip to main content
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:
The package root exposes feature namespaces only. Classes, decorators, functions, errors, and types stay in the feature module that owns them. Find signatures, fields, and methods in the Python API reference. Each public module has its own page, including Tasks and Cron.

Domain imports

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. The implementation path harnest.context_agent has been removed. Use from harnest import context for context.agent operations and from harnest.context import AgentSession, AgentResponse for their contracts. Modules prefixed with _ are private implementation details. The harnest.task_storage implementation path has also been removed. Import TaskRecord, TaskStore, and TaskStoreConflictError from harnest.task. Run harnest upgrade AGENT_DIR --apply to rewrite supported imports in an existing project. Imports or uses of private storage helpers require manual review.

IDE autocomplete and hover help

Synchronize the managed environment to enable typed completion and hover documentation:
Explicit sync updates python.defaultInterpreterPath in .vscode/settings.json to the environment it synchronized. For the default runtime profile on macOS or Linux:
Windows uses Scripts/python.exe; development and eval profiles select the eval directory. Sync replaces stale interpreter settings while preserving comments and unrelated preferences, even when a user-owned .venv prevents creating the convenience link. Open the agent folder as your VS Code workspace folder so these settings apply. After a dependency change during development reload, run harnest env sync . again to refresh an editor setting that points to the old interpreter. A Harnest-managed .venv link follows the replacement automatically for the selected profile. VS Code can retain a previously selected interpreter separately from this setting. If it still uses another interpreter, run Python: Select Interpreter and choose the exact path printed by sync. See the VS Code settings reference. Other IDEs can use the same interpreter. Codex desktop, Codex CLI, and Antigravity 2.0 are separate agent applications. For Python commands in these agents, use .venv/bin/python directly; their terminal commands do not inherit the VS Code Python interpreter setting. Harnest preserves any .venv it does not own and prints the managed interpreter for manual selection. Keep .venv out of version control. Harnest includes static declarations for its lazy domain namespaces and invocation context. Editors can discover methods and signatures on harnest.context, context.agent, context.session, context.mcp, context.skills, and the other context capabilities without running an agent. Context values still resolve for each active invocation; do not access them at module import time. Core functions and methods carry parameter and return annotations. Static consumer checks cover public classes, inherited methods, properties, and protocol methods across Harnest’s domains. Task, context-provider, and lifecycle decorators preserve the authored callable’s parameters and result type, so an editor can flag invalid direct calls:
The direct call above retains its str argument and result types. Deferred task arguments are validated at runtime; .defer() accepts scheduling options and returns a TaskHandle. Dynamic payloads and resource lookups without an expected class may still use Any. For application-defined resources, pass the expected class to preserve its completion and return type:
Here, your application supplies and registers CustomerDirectory. context.storage("name", ExpectedType) and context.extensions("name", ExpectedContext) also preserve the supplied type. Lookups without an expected type return Any; Harnest cannot infer a company’s resource type from a runtime string. Runtime type validation remains in place. 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 reuses a stable environment path, so the .venv link continues to resolve the current interpreter. Synchronization also migrates Harnest-owned links away from older fingerprinted environments.

Scoped operations

Sandbox execution and cleanup share a namespace:
control.current() returns the active scope. See sandbox failure recovery and cleanup for cancellation and deadline guarantees. Query lifecycle coverage with the same domain pattern:

Public API stability

Public module exports, annotations, and docstrings are checked by the release gate. Re-exports preserve object identity, including exception classes. 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 HTTP documents have independent format versions.