Human-in-the-loop

Some agents can't finish alone: a transfer needs approval, a draft needs review, an ambiguous record needs a human to pick. im-sdk lets your agent pause the execution, ask for exactly what it needs, and continue later — as one run, not two.

from im_sdk import FORM_CONTENT_TYPE, read_resume, request_input
 
resume = read_resume()
if resume is None:
    request_input(
        {"fields": [{"name": "approved", "label": "Approve?", "type": "boolean", "required": True}]},
        content_type=FORM_CONTENT_TYPE,
        hint="Approval needed before the transfer",
    )
    # unreachable — request_input never returns
answer = resume.answer            # {"approved": True}

Run it and the execution lands in awaiting_input. Someone answers — in the Portal, in your own app, or with im-cli execution resume — and your agent runs again with the answer.

The two calls

request_input(payload, *, content_type, hint=None)

Declares "I am pausing, here is what I need", then ends the leg. It never returns: the pause stops the process, so the answer arrives on the next run of the same execution. That is why the shape above is always "resumed? use the answer : ask the question".

payload is yours — the platform stores and displays it without interpreting it, so whatever you send comes back to the human byte-for-byte. content_type tells the surface how to render it:

content_typeRendered as
application/vnd.ciu.form+json (FORM_CONTENT_TYPE)a real form — see below
application/jsonpretty-printed JSON + a free-text answer box
text/plainthe text + a free-text answer box
anything elsethe raw payload + a free-text answer box

hint is short prose for whoever is looking at the question.

Sizes: the payload may encode to at most 256 KiB, content_type to 128 characters and hint to 2000. Over any of them request_input() raises ValueError immediately — the Portal enforces the same limits, and a rejection there would park the run with no question attached to it.

read_resume()

Returns the answer this run was resumed with, or None on a first run — a fresh execution, a local run, or an older runner. None is what makes one main.py serve both legs.

resume = read_resume()
if resume is not None:
    resume.answer        # str for a free-text question, dict for a form
    resume.answered_at   # ISO timestamp, or None

answer is passed through verbatim by every hop, so narrow it yourself — nothing coerces it. It is never fabricated: an unreadable or missing answer reads as None, which keeps the run parked rather than resuming it with an empty response. Unknown fields are ignored, so an answer written before an SDK upgrade is still readable after one — which matters, because a human wait can easily straddle a release.

Asking several questions at once

Use FORM_CONTENT_TYPE and shape the payload as a form. Every surface renders it as real fields and returns an object keyed by field name:

request_input(
    {
        "title": "Review the extraction",
        "fields": [
            {"name": "correct", "label": "Is it correct?", "type": "boolean", "required": True},
            {"name": "notes", "label": "Notes", "type": "textarea"},
            {"name": "tier", "label": "Tier", "type": "select", "options": ["gold", "silver"]},
        ],
    },
    content_type=FORM_CONTENT_TYPE,
)

type is a hint: text, textarea, number, boolean, select, date. Nothing validates the shape — a form the platform can't parse simply falls back to showing the raw payload with a free-text box, which is the same rule every other content type follows.

When the model is what needs input

Usually nobody hard-codes "pause here" — the LLM reaches a point where it cannot proceed. Make that a tool call, not prose: an LLM that needs input otherwise asks in a sentence, and pattern-matching those fails silently the first time it phrases things differently.

The SDK ships the tool, so you neither write the schema nor validate what comes back:

from im_sdk import im_agent, human_input_tool, resolve_human_input
 
@im_agent("my-agent")
async def main(core, data):
    result = await core.llm.call(
        messages=[{"role": "user", "content": data["task"]}],
        alias="gpt-mini",
        tools=[human_input_tool()],
    )
 
    save_my_state(...)        # BEFORE the line below — it may never return
    resolve_human_input(result)   # parks the run if the model asked; otherwise returns None
    return result.text            # only reached when it did not ask

resolve_human_input() finds the tool call, re-validates its arguments, clamps them to what the surfaces can render, and calls request_input() for you. It does not return when the model asked — the run parks — so persist anything the next leg needs before calling it.

You do not need to tell the model about the tool in your system prompt. Providers choose tools from the tool's description, and the SDK's description is written to be the whole instruction.

What the clamps do to a model-authored form

The provider validates against the tool schema, but a schema cannot express every rule, and a model will happily produce a form no human can answer. So the arguments are clamped:

The model sentYou get
an unrecognised typetext — a wrong control is answerable, a dropped field is not
select with no optionstext
more than 6 fieldsthe first 6
more than 3 required fieldsthe first 3 stay required
a 500-character label or titletruncated to 120
arguments that don't validate at alla plain-text question instead, so the run still parks

That last row matters: the model has already decided it cannot continue, so discarding its question would leave a run that fails for no visible reason.

Not using core.llm directly?

The same contract is available in pieces, so LangChain, LangGraph, a raw provider SDK or an MCP server all stay aligned with what the platform renders:

from im_sdk import HumanInputRequest, human_input_tool_schema, sanitize_form
 
human_input_tool_schema()   # plain JSON Schema dict — bind_tools, raw OpenAI, MCP
HumanInputRequest           # pydantic model — StructuredTool(args_schema=…), LangGraph
sanitize_form(raw_args)     # the clamps, for arguments you obtained yourself → None if unusable

Keeping state across the pause

Your agent restarts from scratch on the resumed leg, so anything it needs to continue must be on disk in the right place. Use agent_root():

from im_sdk import agent_root
 
db = agent_root() / "checkpoints.sqlite"     # survives every push

agent_root() returns AGENT_ROOT_PATH — slot<uid>/<agent_uuid>, stable across pushes and publish/rollback. Outside the runner (a local run, a test) it falls back to the working directory and warns — a RuntimeWarning on stderr, plus a trace log when one is being collected — because that fallback is not durable and silently getting it is the single most common way to lose suspended state.

Clean up on the finishing leg

Nothing garbage-collects the agent root: no size cap, no TTL, no pruning job, and the volume is shared with every other agent on the container. Only your agent knows a thread will never be resumed, so only your agent can free it:

# after the run produces its answer — never on the parked path
await saver.adelete_thread(thread_id)      # LangGraph checkpointer
state_path().unlink(missing_ok=True)       # a plain transcript

Two caveats worth planning for. A cancelled pause leaves an orphan — the run ends with no leg 2 coming to clean up — so if your agent parks often, sweep stale threads by age at startup. And concurrent executions of one agent share the root, so set PRAGMA journal_mode=WAL on any SQLite file and expect database is locked.

AGENT_ROOT_PATH is per agent and survives pushes, publishes and rollbacks. A few things to know: concurrent runs of the same agent share it (SQLite locking is yours to handle), nothing cleans it up, and the platform does not back it up.

Exit behaviour

A pause is not a failure. request_input() raises AwaitingInput, which is deliberately not a ImError; @im_agent catches it and exits 0, which is what parks the execution instead of failing it.

Hand-rolling your own main()? You must handle it, or an uncaught exception exits non-zero and your run reports as failed with the question stranded:

from im_sdk import AwaitingInput, ImError
 
def main() -> None:
    try:
        print(json.dumps(asyncio.run(run())))
    except AwaitingInput as pause:
        print(json.dumps({"status": "awaiting_input", "interrupt": pause.payload}))
    except ImError as exc:
        print(f"in·manas error: {exc}", file=sys.stderr)
        raise SystemExit(1) from None

Answering a paused run

WhereHow
PortalOpen the execution — a panel shows the question and takes the answer
CLIim-cli run prompts inline on a terminal; otherwise im-cli execution resume <uuid>
Your appThe execution.awaiting_input webhook carries the question; answer via the resume endpoint

The question is stored server-side, so you can close your terminal and answer hours later. im-cli execution list --status awaiting_input finds every run that is waiting.

Runnable examples

apps/core-sdk/examples/hil-interrupt-agent/ is a complete LangGraph agent that interrupts, parks, and resumes its thread from a checkpoint DB under AGENT_ROOT_PATH — including proof that the state survives being resumed by a different pushed version.

apps/core-sdk/examples/hil-llm-agent/ is the case where the model raises the question: it calls ask_human, the arguments are clamped to a renderable form, and the run parks. Orchestrated with LangChain through a small ChatIm adapter over core.llm, so bind_tools() works while routing stays server-side. It also shows the two things a real agent needs and a snippet cannot: budgeting how often to interrupt a human, and returning the answer as a ToolMessage paired with the call that asked for it.