Human Questions (Pending Tool Calls)

The resumable extraction agent can pause mid-extraction and ask a human a question when it needs information it cannot infer on its own. Each question is stored as a pending tool call (with tool_name == "ask_human"). Answering it unblocks the agent: dependent extraction runs are scheduled to resume with the supplied answer.

These methods cover the same endpoints the web portal's /questions page uses.

A typical loop: poll list_pending_tool_calls(status="pending"), then call resolve_pending_tool_call(id, answer=...) for each one.

list_pending_tool_calls

List pending tool calls for the organization, optionally filtered by status.

response = client.list_pending_tool_calls(status="pending", limit=50)
for question in response.pending_tool_calls:
    print(question.id, question.question_text)

Returns a PendingToolCallListResponse whose pending_tool_calls is a list of PendingToolCallResponse (see schema below).

get_pending_tool_call

Fetch a single pending tool call by id.

question = client.get_pending_tool_call("ptc_abc123")

Returns a PendingToolCallResponse.

resolve_pending_tool_call

Answer a question, marking it resolved and scheduling dependent agent runs to resume. Provide exactly one of answer (the common ask_human case, wrapped as {"answer": ...}) or result (an arbitrary tool-result payload). The client raises ValueError before sending the request if both or neither are provided.

# Common case: answer an ask_human question.
resolved = client.resolve_pending_tool_call("ptc_abc123", answer="AWS ECS")

# Advanced: send a raw tool result payload.
resolved = client.resolve_pending_tool_call(
    "ptc_abc123", result={"answer": "AWS ECS", "confidence": 0.9}
)

Raises ValueError if both or neither of answer and result are provided. Returns the updated PendingToolCallResponse.

update_pending_tool_call_answer

Edit the answer of an already-resolved ask_human question. Editing schedules another resume of dependent agent runs with the new answer.

edited = client.update_pending_tool_call_answer("ptc_abc123", "Google Cloud Run")

Returns the updated PendingToolCallResponse.

mark_pending_tool_call_not_applicable

Resolve an ask_human question with the standard "user does not have information about this question" result, so dependent agent runs can proceed.

result = client.mark_pending_tool_call_not_applicable("ptc_abc123")

Returns the resolved PendingToolCallResponse (its result includes "not_applicable": true).

cancel_pending_tool_call

Cancel a still-pending question without answering it. Only questions in the pending status can be cancelled.

cancelled = client.cancel_pending_tool_call("ptc_abc123")

Returns the cancelled PendingToolCallResponse.

PendingToolCallListResponse Schema

PendingToolCallResponse Schema