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_type | Rendered as |
|---|---|
application/vnd.ciu.form+json (FORM_CONTENT_TYPE) | a real form — see below |
application/json | pretty-printed JSON + a free-text answer box |
text/plain | the text + a free-text answer box |
| anything else | the 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 Noneanswer 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 askresolve_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 sent | You get |
|---|---|
an unrecognised type | text — a wrong control is answerable, a dropped field is not |
select with no options | text |
| more than 6 fields | the first 6 |
more than 3 required fields | the first 3 stay required |
| a 500-character label or title | truncated to 120 |
| arguments that don't validate at all | a 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 unusableKeeping 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 pushagent_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 transcriptTwo 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 NoneAnswering a paused run
| Where | How |
|---|---|
| Portal | Open the execution — a panel shows the question and takes the answer |
| CLI | im-cli run prompts inline on a terminal; otherwise im-cli execution resume <uuid> |
| Your app | The 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.