Skip to main content
Use the official Hatchet extension to submit external workflows and resume an agent when they finish. Deploy Hatchet workers and workflow definitions separately.

​
Install the extension

From the agent folder:
For local extension development, point the same command at a checkout:
Harnest validates and copies the package without importing its code. Use Python 3.11 or newer with the current Harnest release. Version 0.2.2 requires Harnest >=1.0.0,<2 and hatchet-sdk>=1.38,<2.

​
Submit and await a workflow

Author a domain-specific asynchronous Agent Tool and call the compiler-owned extension namespace:
Inspect a run with hatchet.status(job) or request cancellation with hatchet.cancel(job). Stopping Harnest does not stop Hatchet workers.

​
Choose an operation

See the Hatchet operation reference for methods, return values, and run states. Use run_and_wait when the tool needs a result: it verifies suspension support before submission. Use run to submit without waiting, or wait for a run you already own.

​
Configure credentials

The extension declares context.credentials and context.continuations. Resolve invocation credentials with only the operations a tool needs: The deployment must also provide HATCHET_CLIENT_TOKEN so startup recovery can inspect pending waits after a restart. Keep provider tokens in the credential resolver or process environment, not source, workflow input, continuation results, or logs. The extension disables the SDK’s implicit working-directory dotenv discovery.

​
Recovery and limits

wait stores an opaque continuation and can resume after process or replica replacement. Recovery retains pending waits across transient Hatchet outages, applies polling backoff, and uses at most 16 concurrent provider clients. Cancellation is a provider request and does not imply immediate worker shutdown. Durable waits preserve permission names and rebuild a fresh Agent Runtime Principal on resume. Principal IDs, credentials, and claims are not persisted. Inputs and workflow results must be JSON mappings. The extension rejects either payload above 1 MiB before submission or durable persistence. Job data crosses the external Hatchet boundary, so send only the fields that workflow requires. See Durable execution for recovery behavior and Authentication and credentials for scoped providers.

​
Handle failures

See the Hatchet API reference for run identities, states, and invocation methods. Invocation calls use scoped credentials; startup recovery uses the service credential. Durable submissions use stable idempotency keys. Provider failures return safe error codes without raw messages. Workflow names and provider identities must be non-empty. Payloads must be finite, acyclic JSON mappings with string keys; see the Hatchet API reference for bounds.

​
API reference

Reference: harnest.agent.