You’re on Prefect 3.x now—agents were removed and replaced by workers. That’s why

prefect agent

no longer exists. Equivalent in Prefect 3.x: - Old (2.x):

prefect agent start -q default

- New (3.x):

prefect worker start -p <work-pool> -q default

There is no default work pool created for you in 3.x, so you’ll need to create one once, then start a worker. Quick fix (local “process” worker):

# create a work pool once
prefect work-pool create default --type process

# start a worker that polls the 'default' pool and 'default' queue
prefect worker start -p default -q default

If you’re using Docker or Kubernetes, create the pool with the matching type and start with the right extras:

# Docker example
uv run --with 'prefect[docker]' prefect work-pool create docker-pool --type docker
uv run --with 'prefect[docker]' prefect worker start -p docker-pool

# Kubernetes example
uv run --with 'prefect[kubernetes]' prefect work-pool create k8s-pool --type kubernetes
uv run --with 'prefect[kubernetes]' prefect worker start -p k8s-pool

Helpful docs: - Upgrade: agents to workers - Workers concepts - Worker CLI reference If you share what infrastructure you’re targeting (local, Docker, Kubernetes), I can give you the exact commands to use.

Great—if your Kubernetes work pools already exist, you don’t need to recreate anything. Just start a Kubernetes worker that points at those pools. Verify your pool and its type:

prefect work-pool ls
prefect work-pool inspect "<pool-name>"

Start a worker that polls your existing pool/queue:

# if you have prefect[kubernetes] installed
prefect worker start -p "<pool-name>" -q default

# or run with the kubernetes extra on-demand
uv run --with 'prefect[kubernetes]' prefect worker start -p "<pool-name>" -q default

Notes: - The worker type is inferred from the work pool, so you usually don’t need

--type

. - If you omit

-q

, the worker will poll all queues in the pool. If you want the worker to run in-cluster (recommended), deploy it via Helm:

helm repo add prefect <https://prefecthq.github.io/prefect-helm>
helm repo update
kubectl create namespace prefect
kubectl create secret generic prefect-api-key --namespace=prefect --from-literal=key=<PREFECT_API_KEY>

values.yaml (minimal):

worker:
  cloudApiConfig:
    accountId: <ACCOUNT_ID>
    workspaceId: <WORKSPACE_ID>
  config:
    workPool: <pool-name>

Install:

helm install prefect-worker prefect/prefect-worker --namespace=prefect -f values.yaml

A couple details: - In-cluster workers use in-cluster auth by default. If you run the worker outside the cluster, configure your pool with a Kubernetes cluster config (or ensure kubeconfig access) so the worker can submit jobs to the cluster. - Your existing deployments targeting that pool should run unchanged once a worker is polling it. Helpful links: - Upgrade: agents to workers - Workers concepts - Kubernetes guide - Prefect worker Helm chart Do you want the worker to run in-cluster via Helm, or from a VM/laptop outside the cluster? I can tailor the exact steps.