Quickstart

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 for how to mint and store one.

1. Install the SDK

TypeScript

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

Python

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:

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.

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

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"

Python

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"

cURL

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

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: ['…'] }

Python

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": ["…"]}

cURL

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.

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

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);

Python

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)

cURL

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.

2. Run real conversations

   Stream output, attach files, and handle errors in the tasks guide.

3. Browse the API reference

   Every endpoint, parameter, and response is documented in the API reference.