Create and run Tasks

Use Tasks for work that should run independently of a model call, such as generating a report, processing an upload, or calling a slow service with retries. An Agent Tool decides when to queue the work. The task itself is not model-visible. Use an ordinary function call when the caller can do the work immediately and does not need queueing or recovery. See the harnest.task API reference for parameters, return types, and methods.

Call	Behavior
`await build_report(...)`	Runs an async task body as an ordinary local Python call
`await build_report.defer(...)`	Commits queue work and returns `TaskHandle`
`await handle.result()`	Returns a terminal result or suspends a durable tool

Configure Lifecycle storage

Before queueing work, register a task storage provider in the agent’s root lifecycle/ folder. Adding a @task function does not configure storage. Harnest discovers these Python factories automatically; there is no task-storage setting to add to config.yaml. For the durable tool example below, create or update lifecycle/storage.py:

lifecycle/storage.py

import os

from harnest import lifecycle
from harnest_postgres import PostgresStore

@lifecycle.storage.sessions
@lifecycle.storage.checkpoints
@lifecycle.storage.tasks
def storage() -> PostgresStore:
    """Share durable storage for conversations, suspended tools, and queued work."""
    return PostgresStore(os.environ["DATABASE_URL"])

Set DATABASE_URL to your running PostgreSQL database before starting the agent. harnest_postgres ships with the managed Harnest runtime. Harnest calls the factory and owns starting and closing its provider. Replace any existing factories for the roles shown above; do not register a second provider for the same role. If you already have session and checkpoint providers that you want to keep, register only @lifecycle.storage.tasks on this new factory.

Work you need	Lifecycle configuration
Queue and run Tasks	`@lifecycle.storage.tasks`
Suspend a durable tool while it awaits a Task	Task storage plus a Harnest-owned `@lifecycle.storage.checkpoints` provider; use persistent storage for recovery after restart
Run fixed or dynamic Cron schedules	Add `@lifecycle.storage.cron` to the same factory as task storage so both roles share one provider instance

For local experiments, a task factory can return harnest.task.MemoryTaskStore() instead. It loses queued work on process exit and does not provide session or checkpoint storage; register it only for task and optional cron roles. Use persistent storage for production. See Task and cron storage for Redis, custom providers, and complete storage setup.

Define and call a task

From the agent root, create a compilable task starter:

harnest add task build-report

Use --project <agent-root> when running the command from elsewhere. The generated file is suitable when no other module imports the task; use the shared-library pattern below when tools also import it. When a tool needs the task callable, define it once in lib/ and re-export it from tasks/. The following three files work together:

Define the shared task

lib/report_tasks.py

from harnest.task import task

@task(queue="reports", max_retries=3)
async def build_report(account_id: str) -> dict:
    """Build one account report."""

    return {"account_id": account_id, "status": "ready"}

Make the task discoverable

tasks/build_report.py

from harnest.lib.report_tasks import build_report

Queue work from an Agent Tool

tools/request_report.py

from harnest.lib.report_tasks import build_report
from harnest.agent import tool

@tool(durable=True)
async def request_report(account_id: str) -> dict:
    """Queue a report and return it when ready."""

    handle = await build_report.defer(account_id=account_id)
    return await handle.result()

If nothing imports the task, you can define it directly in tasks/<name>.py. The file must export exactly one same-named @task callable. Tasks can be synchronous or asynchronous. Give each task a docstring and accept JSON-safe arguments; its result must also be JSON-safe. See the task parameter contracts for signature restrictions.

Decide whether to wait

For fire-and-forget work, defer the task and return its ID to the caller. Wait for its result when the agent needs the output to continue. An unfinished result requires an async @tool(durable=True) and a Harnest-owned checkpointer. The returned TaskHandle lets managed code inspect status, cancel work, and access its result. It belongs to the active compiled runtime; there is no public API to reconstruct or list handles by ID.

Make retries safe

Workers can retry a task. Make side effects idempotent, such as recording a report under a stable business key before notifying another service. An idempotency key deduplicates submission; it does not make every external effect happen exactly once. Inside a durable tool, Harnest derives a replay-stable submission key when you omit one. Use defer(schedule_in=...) for a one-time delay. For recurring work, use Cron schedules.

Runtime requirements

Requirement	Behavior
Queue backend	Harnest workers with an explicit `lifecycle.storage.tasks` provider; no fallback
Installation	`harnest_postgres` and `harnest_redis` are bundled with Harnest; declare custom adapter dependencies in your project
Database	PostgreSQL, Redis, or a custom provider selected by your Lifecycle factory
Payloads and results	JSON-safe values only
Credentials	Resolved at execution; never serialized into task state
Runtime principal	Permission names and invocation identity are persisted separately; the principal object and credentials are not
Defer boundary	Available only while the compiled Harnest runtime is active

With Lifecycle storage configured and DATABASE_URL set, run from your agent folder. Replicas can share the same persistent provider:

harnest env sync .
harnest test .
harnest serve .

Queued execution requires configured storage and an active compiled runtime. Calling .defer() outside it raises TaskUnavailableError. Call the task body directly for database-free unit tests.

Start a fresh agent session

A task can invoke the compiled root agent without an HTTP call through context.agent.create_session() and AgentSession.invoke(). Pass a stable session key when retries should derive the same child session and invocation identities. To continue an existing conversation, use context.agent.open_session(session_id) inside the task. It opens only sessions owned by the task’s user, including the session that queued the task. Choose the destination explicitly; defer() does not select one. For example, a one-time reminder can carry the current session ID into a delayed task:

# In a tool that queues the reminder:
handle = await send_reminder.defer(
    session_id=context.session_id,
    text="Take a break",
    schedule_in=60,
)

# In the compiled @task function:
session = await context.agent.open_session(session_id)
await session.invoke(f"Remind the user: {text}")

The later agent turn is saved in that session’s transcript. A client that needs an immediate alert must watch that session or deliver the resulting message through its own chat transport. If the session was deleted before the task runs, opening it fails instead of creating a replacement. Deferred tasks inherit user identity and public metadata. Fixed schedules use the automation identity; dynamic schedules use their creator with fresh context and empty grants. When .defer() runs under an Agent Runtime Principal, Harnest stores only its permission names and reconstructs a fresh principal for each worker attempt. Agent calls made by the Task inherit that restriction unless trusted task code passes a narrower principal. A Task deferred without an active principal preserves compatibility behavior. Durable external waits return a typed in_progress response. Human approvals and client tools fail closed because their continuation is process-local after the task returns.

An unfinished handle.result() requires an async @tool(durable=True) and a Harnest-owned checkpointer. Harnest resumes framework execution; it does not restore a Python stack.

See Durable execution for cross-replica resume behavior.

Test Task behavior

Call the decorated function directly to unit-test its business logic without a database. Exercise .defer(), retries, cancellation, and durable resume through a compiled smoke test with your chosen persistent provider so the real queue and checkpoint boundaries run together. Custom providers can use the shared conformance suite.

Overview

Get started

Harnest Studio

Guides

API reference

Create and run Tasks

Configure Lifecycle storage

Define and call a task

Decide whether to wait

Make retries safe

Runtime requirements

Start a fresh agent session

Test Task behavior

​Configure Lifecycle storage

​Define and call a task

​Decide whether to wait

​Make retries safe

​Runtime requirements

​Start a fresh agent session

​Test Task behavior

Configure Lifecycle storage

Define and call a task

Decide whether to wait

Make retries safe

Runtime requirements

Start a fresh agent session

Test Task behavior