Human in the loop - Autumn AI

clarify is the only planning knob. By default (clarify: false) the agent infers reasonable defaults and executes without asking. Set clarify: true when a human is present and a missing answer would materially change the work.

Value	Agent behavior
`false`	Plan, infer defaults, and execute without asking. The default for automation.
`true`	Allow one blocking planning question before execution.

curl -sS -X POST "https://api.autumn.ai/task" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Build a list of fintech companies", "clarify": true}'

import os, requests

AUTUMN = "https://api.autumn.ai"
HEADERS = {"X-API-Key": os.environ["AUTUMN_API_KEY"]}

# clarify=true: may ask one question, e.g. geography or target count
task = requests.post(f"{AUTUMN}/task", headers=HEADERS, json={
    "prompt": "Build a list of fintech companies",
    "clarify": True,
}).json()

const task = await fetch("https://api.autumn.ai/task", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AUTUMN_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ prompt: "Build a list of fintech companies", clarify: true }),
}).then((r) => r.json());

With clarify: true, the task can stop before execution and return state: "input-required" with the question in message. Use GET /task/{task_id}?wait=50 until done is true, show the question, and answer it with POST /task/{task_id}/continue.

# answer the planning question on the same task
curl -sS -X POST "https://api.autumn.ai/task/$TASK_ID/continue" \
  -H "X-API-Key: $AUTUMN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "US only, Series A or later, 50 rows"}'

Review, then continue

A common pattern: run the first part, let a human review the rows, then continue the same task with corrections.

Python

import time

task_id = requests.post(f"{AUTUMN}/task", headers=HEADERS, json={
    "prompt": "Find Series A fintech companies in the US",
    "clarify": False,
}).json()["task_id"]

def get_status(task_id):
    while True:
        r = requests.get(
            f"{AUTUMN}/task/{task_id}",
            headers=HEADERS,
            params=dict(wait=50),
        )
        if r.status_code in (429, 503):
            time.sleep(float(r.headers.get("Retry-After", 5)))
            continue
        if not 200 <= r.status_code < 300:
            raise RuntimeError(r.json().get("message") or r.text)
        return r.json()

task = get_status(task_id)
while not task["done"]:
    task = get_status(task_id)

if task["state"] == "completed":
    rows = requests.get(f"{AUTUMN}/task/{task_id}/output", headers=HEADERS).json()["rows"]
elif task["state"] == "input-required":
    raise RuntimeError(task["message"])
elif task["state"] in {"failed", "canceled"}:
    error = task.get("error") or {}
    raise RuntimeError(
        error.get("message") or error.get("code") or task.get("message") or task["state"]
    )

# ... human reviews rows ...

requests.post(f"{AUTUMN}/task/{task_id}/continue", headers=HEADERS, json={
    "message": "Drop anything past Series A and add the CEO name column",
})

Because the task_id is durable, you can interleave agent turns and human review as many times as you need. See Follow-up tasks.

Guidance

For background automation, keep clarify: false.
Use clarify: true only when the user is present to answer.
When continuing after review, restate the current goal as a clear instruction rather than passing the user’s raw words.
POST /task/{task_id}/stop changes a running turn to state: "canceled" if a reviewer needs to intervene mid-run.