When your agent needs a human decision, it pauses. The desktop app shows the task in an approval queue. You review, approve or reject, and the agent resumes.
The input_required state is the bridge between autonomous agents and human judgment. When an agent encounters a decision it cannot or should not make on its own, it returns input_required instead of completed. The task pauses, the human is notified, and the workflow waits until a person weighs in.
This is useful for high-stakes operations like deploying to production, approving financial transactions, or reviewing breaking changes. The agent does the analysis, surfaces what matters, and lets a human make the final call.
The approval flow follows the standard A2A task lifecycle, with input_required acting as a pause point between the agent and the human operator.
An external client sends a task to your agent via A2A SendMessage. The task enters the submitted state.
The desktop app picks up the task, runs your agent's configured command, and pipes the task JSON to stdin. See the Building Agents guide for the full input format.
Instead of completing the task, the agent returns a response with state input_required and an explanation of what it needs.
{
"state": "input_required",
"text": "Found 3 breaking API changes. Should I proceed with the migration?"
}The desktop app updates the task status and shows a badge on the approvals tab. A macOS notification alerts the operator that a task is waiting for review.
The operator opens the task and sees the full conversation history, including any artifacts the agent produced during its analysis.
The operator has three options:
working and the agent is re-invoked to continuerejected and the caller is notifiedThe caller learns the outcome through GetTask polling or push notifications. The task includes the final status and any artifacts or messages produced during the approval flow.
Any agent can request human approval by returning input_required instead of completed. The key is deciding when to pause and what to show the human.
A simple script that reads the task, performs analysis, and requests approval before proceeding.
#!/bin/bash
# Read the task from stdin
INPUT=$(cat)
TASK_TEXT=$(echo "$INPUT" | jq -r '.message.parts[0].text')
# Do some analysis...
RESULT="Found 3 breaking API changes affecting 12 consumers."
# Request human approval
cat <<EOF
{
"state": "input_required",
"text": "$RESULT\n\nShould I proceed with the migration?"
}
EOFUse Claude Code as your agent runtime. The prompt instructs it to conditionally return input_required for dangerous operations and completed for safe ones.
claude -p "Analyze this request. If it involves breaking changes or destructive operations, respond with JSON: {\"state\": \"input_required\", \"text\": \"your explanation\"}. Otherwise respond with JSON: {\"state\": \"completed\", \"text\": \"your analysis\"}." --input-stdinWhen a task enters input_required, the desktop app shows the operator everything they need to make a decision:
When the operator chooses Send Response, the agent is re-invoked with the same contextId. The new message from the human is appended to the conversation, and the agent receives the full context on stdin.
The agent can return input_required again if it needs further clarification. This creates a back-and-forth conversation between the agent and the human, with each turn adding to the shared context. The cycle continues until the agent returns completed, failed, or the human chooses to reject.