---
title: Quickstart | Handinger
description: Install an SDK, create your first worker, and run a task in a few minutes.
---

This guide takes you from zero to a running task in about five minutes. You will:

1. Install the SDK.
2. Authenticate with an API key.
3. Create a reusable worker template.
4. Run a task against it.
5. Add a follow-up turn to the same task.

Need a key first? See the [authentication guide](/guides/authentication/index.md) for how to mint and store one.

## 1. Install the SDK

- [ TypeScript](#tab-panel-3)
- [ Python](#tab-panel-4)

Terminal window

```
npm install @ramensoft/handinger
# or: pnpm add @ramensoft/handinger
# or: yarn add @ramensoft/handinger
```

Terminal window

```
pip install handinger
# or: uv pip install handinger
```

## 2. Set your API key

The SDKs read `HANDINGER_API_KEY` from the environment by default. Add it to your shell, `.env`, or secret manager:

Terminal window

```
export HANDINGER_API_KEY="hdg_live_…"
```

If your runtime does not expose env vars (a Cloudflare Worker, a serverless function with explicit bindings, etc.), pass the key to the client constructor instead — see the [authentication guide](/guides/authentication#use-the-key/index.md).

## 3. Create a worker

A **worker** is a reusable agent template: its instructions, output schema, and integrations are persisted, then reused on every task. Create one once and run it many times.

- [ TypeScript](#tab-panel-5)
- [ Python](#tab-panel-6)
- [ cURL](#tab-panel-7)

```
import Handinger from '@ramensoft/handinger';


const handinger = new Handinger();


const worker = await handinger.workers.create({
  title: 'Scientific claim debunker',
  prompt:
    'Verify or debunk scientific claims by searching peer-reviewed databases like PubMed and arXiv. Summarize the consensus and cite the strongest evidence on each side.',
});


console.log(worker.id); // → "wrk_vk81XUHKHG-qr4"
```

```
from handinger import Handinger


client = Handinger()


worker = client.workers.create(
    title="Scientific claim debunker",
    prompt=(
        "Verify or debunk scientific claims by searching peer-reviewed databases "
        "like PubMed and arXiv. Summarize the consensus and cite the strongest "
        "evidence on each side."
    ),
)


print(worker.id)  # → "wrk_vk81XUHKHG-qr4"
```

Terminal window

```
WORKER_ID=$(curl -s https://handinger.com/api/workers \
  -H "Authorization: Bearer $HANDINGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Scientific claim debunker",
    "prompt": "Verify or debunk scientific claims by searching peer-reviewed databases like PubMed and arXiv. Summarize the consensus and cite the strongest evidence on each side."
  }' | jq -r '.id')


echo "$WORKER_ID"  # → wrk_vk81XUHKHG-qr4
```

Pass `prompt` for one-shot bootstrapping — Handinger expands it into a structured system prompt and (when appropriate) a JSON output schema. Pass `instructions` directly when you already know the exact prompt you want.

## 4. Run a task

A **task** is one run of a worker. The response is a `Worker` object reflecting the final state: `output_text` plus structured output, sources, and files.

- [ TypeScript](#tab-panel-8)
- [ Python](#tab-panel-9)
- [ cURL](#tab-panel-10)

```
const result = await handinger.tasks.create({
  workerId: worker.id,
  input: 'Humans only use 10% of their brain.',
});


console.log(result.output_text);
// → "This claim is debunked. Functional brain imaging shows essentially every
//    region activates over the course of a typical day — the '10%' figure has
//    no neuroscience basis."
console.log(result.structured_output);
// → { verdict: 'debunked', summary: '…', citations: ['…'] }
```

```
result = client.tasks.create(
    worker_id=worker.id,
    input="Humans only use 10% of their brain.",
)


print(result.output_text)
# → "This claim is debunked. Functional brain imaging shows essentially every
#    region activates over the course of a typical day — the '10%' figure has
#    no neuroscience basis."
print(result.structured_output)
# → {"verdict": "debunked", "summary": "…", "citations": ["…"]}
```

Terminal window

```
RESPONSE=$(curl -s https://handinger.com/api/tasks \
  -H "Authorization: Bearer $HANDINGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"workerId\": \"$WORKER_ID\",
    \"input\": \"Humans only use 10% of their brain.\"
  }")


TASK_ID=$(echo "$RESPONSE" | jq -r '.id')
echo "$RESPONSE" | jq '{ output_text, structured_output }'
```

The call blocks until the worker finishes (typically a few seconds for a simple prompt). For long-running tasks, see [streaming](/guides/tasks#streaming-the-response/index.md).

## 5. Continue the conversation

To add a follow-up turn instead of starting a fresh task, reuse the task id from the previous response. The worker keeps full conversation history, including any uploaded files and tool calls.

- [ TypeScript](#tab-panel-11)
- [ Python](#tab-panel-12)
- [ cURL](#tab-panel-13)

```
const followUp = await handinger.tasks.create({
  workerId: worker.id,
  taskId: result.id, // <-- reuse the prior task id
  input: 'How strong is the scientific consensus?',
});


console.log(followUp.output_text);
```

```
follow_up = client.tasks.create(
    worker_id=worker.id,
    task_id=result.id,  # reuse the prior task id
    input="How strong is the scientific consensus?",
)


print(follow_up.output_text)
```

Terminal window

```
curl -s https://handinger.com/api/tasks \
  -H "Authorization: Bearer $HANDINGER_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"workerId\": \"$WORKER_ID\",
    \"taskId\": \"$TASK_ID\",
    \"input\": \"How strong is the scientific consensus?\"
  }" | jq -r '.output_text'
```

## Where to go next

1. Customize the worker

   Tighten the worker’s behaviour with explicit instructions and an output schema — see the [workers guide](/guides/workers/index.md).

2. Run real conversations

   Stream output, attach files, and handle errors in the [tasks guide](/guides/tasks/index.md).

3. Browse the API reference

   Every endpoint, parameter, and response is documented in the [API reference](/api/index.md).