Hatchet Python SDK

The Hatchet Python SDK is the official client for Hatchet, a distributed and fault-tolerant orchestration platform for background tasks, AI agents, and durable workflows. It lets you define workflows and tasks as decorated Python functions, run workers that pull work from the Hatchet engine, and trigger runs from events, schedules, or cron expressions.

Built on Pydantic and gRPC, the SDK provides a fully typed, async-first API surface with feature clients for runs, workers, workflows, scheduling, rate limits, metrics, logs, and webhooks. It works against both self-hosted Hatchet deployments and Hatchet Cloud.

What You Get

• A typed Hatchet client with decorators for declaring tasks, standalone functions, and multi-step workflows
• Worker runtime that registers and executes your workflows against the Hatchet engine
• Feature clients for runs, workflows, workers, scheduling, cron, rate limits, metrics, logs, filters, and webhooks
• Event-driven and scheduled triggering with durable execution and automatic retries
• Optional OpenTelemetry instrumentation for tracing and observability

Common Use Cases

• Offloading slow or unreliable background jobs from web request handlers
• Orchestrating multi-step, dependency-aware AI agent and data pipelines
• Running scheduled and recurring jobs with cron and one-off scheduling
• Fan-out/fan-in and concurrency-limited processing at scale

Under The Hood

Architecture The SDK centers on a Hatchet facade (hatchet_sdk/hatchet.py) that wires together a low-level Client and a set of feature clients (runs, workflows, workers, cron, scheduled, rate limits, metrics, logs, filters, webhooks). Workflows and tasks are declared with decorators that build Workflow/Standalone runnables; a Worker registers these and long-polls the Hatchet engine over gRPC, executing them inside a context that carries cancellation, logging, and durable-execution state. Tech Stack Python 3.10+, Pydantic v2 and pydantic-settings for typed config and payloads, grpcio/grpcio-tools/protobuf for engine communication, aiohttp and tenacity for async transport and retries, prometheus-client for metrics, with an optional OpenTelemetry extra for tracing. Code Quality The package ships py.typed, is organized into cohesive modules (clients, features, runnables, types, utils), and is validated by an extensive suite of ~90 test files plus mypy/ruff/black lint configuration, indicating strong type discipline and test coverage. API Design The public API is decorator-driven and ergonomic — @hatchet.task/@hatchet.workflow mirror familiar task-queue conventions, generics preserve input/output types end to end, and feature clients group operations logically, though the surface is broad and leans on the external docs site for full usage examples.