79 lines
4.4 KiB
Python
79 lines
4.4 KiB
Python
from typing import Literal
|
|
|
|
from langchain.tools import tool
|
|
|
|
|
|
# ClarificationMiddleware owns the stop behaviour: it returns a Command that
|
|
# writes the ToolMessage and explicitly routes to END. ``return_direct=True``
|
|
# makes the prebuilt tool node short-circuit before that Command update is
|
|
# checkpointed in some LangGraph versions, leaving an assistant tool call
|
|
# without its matching ToolMessage. The next user reply then fails provider
|
|
# validation with "tool_calls must be followed by tool messages".
|
|
@tool("ask_clarification", parse_docstring=True, return_direct=False)
|
|
def ask_clarification_tool(
|
|
question: str,
|
|
clarification_type: Literal[
|
|
"missing_info",
|
|
"ambiguous_requirement",
|
|
"approach_choice",
|
|
"risk_confirmation",
|
|
"suggestion",
|
|
],
|
|
context: str | None = None,
|
|
options: list[str] | None = None,
|
|
allow_multiple: bool | None = None,
|
|
) -> str:
|
|
"""Ask the user for clarification when you need more information to proceed.
|
|
|
|
Use this tool when you encounter situations where you cannot proceed without user input:
|
|
|
|
- **Missing information**: Required details not provided (e.g., file paths, URLs, specific requirements)
|
|
- **Ambiguous requirements**: Multiple valid interpretations exist
|
|
- **Approach choices**: Several valid approaches exist and you need user preference
|
|
- **Risky operations**: Destructive actions that need explicit confirmation (e.g., deleting files, modifying production)
|
|
- **Suggestions**: You have a recommendation but want user approval before proceeding
|
|
|
|
The execution will be interrupted and the question will be presented to the user.
|
|
Wait for the user's response before continuing.
|
|
|
|
When to use ask_clarification:
|
|
- You need information that wasn't provided in the user's request
|
|
- The requirement can be interpreted in multiple ways
|
|
- Multiple valid implementation approaches exist
|
|
- You're about to perform a potentially dangerous operation
|
|
- You have a recommendation but need user approval
|
|
|
|
Batching multiple independent questions:
|
|
- **You CAN and SHOULD call ask_clarification multiple times in the same turn** when the user's
|
|
request leaves several **independent** aspects unclear (e.g. project type AND tech stack AND
|
|
deployment target). Emit one tool call per aspect — do NOT cram several unrelated questions
|
|
into one `question` string.
|
|
- The frontend automatically groups all clarification cards in one turn into a single submission,
|
|
so the user answers them together in one reply. You will then receive one combined user message
|
|
addressing every question in order.
|
|
- When the questions DEPEND on each other (the second only makes sense after the first is answered),
|
|
ask only the first one and wait for the reply before asking the next.
|
|
|
|
Best practices:
|
|
- One question per ask_clarification call — keep each `question` focused on a single decision.
|
|
- Be specific and clear in your question.
|
|
- Provide `options` (with concise labels) whenever there is a discrete set of reasonable choices.
|
|
- By default the UI is **single-select** (click an option to send). Pass `allow_multiple=True`
|
|
only when the user may legitimately pick several options together (e.g. multiple constraints).
|
|
- Don't make assumptions when clarification is needed.
|
|
- For risky operations, ALWAYS ask for confirmation.
|
|
- After calling this tool (or several in one turn), execution will be interrupted automatically.
|
|
|
|
Args:
|
|
question: The clarification question to ask the user. Focused on a single decision; be specific and clear.
|
|
clarification_type: The type of clarification needed (missing_info, ambiguous_requirement, approach_choice, risk_confirmation, suggestion).
|
|
context: Optional context explaining why clarification is needed. Helps the user understand the situation.
|
|
options: Optional list of choices. Present clear options for the user to choose from.
|
|
allow_multiple: When True, the UI allows multi-select plus a submit button. When False or
|
|
omitted, the UI is single-select and sends immediately on click (default).
|
|
"""
|
|
# This is a placeholder implementation
|
|
# The actual logic is handled by ClarificationMiddleware which intercepts this tool call
|
|
# and interrupts execution to present the question to the user
|
|
return "Clarification request processed by middleware"
|