Clarify Tool

from praisonaiagents import Agent

agent = Agent(
    name="assistant",
    instructions="Ask clarifying questions when the request is ambiguous",
)

agent.start("Help me set up monitoring")

from praisonaiagents.tools.clarify import create_cli_clarify_handler

handler = create_cli_clarify_handler()
# Shows: 🤔 Which language?
# Choices:
#   1. python
#   2. rust
# Your choice (number or text): 1
# Returns: "python"

from praisonaiagents import Agent
from praisonaiagents.tools.clarify import clarify

agent = Agent(
    name="Deployer",
    instructions="If the user doesn't say which environment, ask with clarify before deploying.",
    tools=[clarify],
)
# On a bot session, a call like
#   clarify(question="Which environment?", choices=["staging", "production"])
# ends this turn restating the question. The two choices render as tappable
# buttons; the tap becomes the next turn's input.

from praisonaiagents.tools.clarify import (
    ClarifyHandler,
    set_clarify_handler,
    reset_clarify_handler,
)

async def my_turn(user_input):
    def ask(question, choices=None):
        # Deliver the question through your UI; return the answer as a string.
        return deliver_to_my_ui(question, choices)

    token = set_clarify_handler(ClarifyHandler(ask_callback=ask))
    try:
        return await run_agent(user_input)
    finally:
        reset_clarify_handler(token)

from praisonaiagents import Agent
from praisonaiagents.tools.clarify import clarify

async def my_clarify_handler(question, choices):
    # Custom UI/web interface
    return await show_dialog(question, choices)

agent = Agent(
    name="Assistant",
    tools=[clarify],
    ctx={"clarify_handler": my_clarify_handler}
)

# LLM sees this tool signature:
{
    "name": "clarify",
    "description": "Ask the user a focused clarifying question when genuinely ambiguous. Use sparingly - only when you cannot proceed without their input.",
    "parameters": {
        "type": "object",
        "properties": {
            "question": {
                "type": "string",
                "description": "The clarifying question to ask"
            },
            "choices": {
                "type": "array", 
                "items": {"type": "string"},
                "description": "Optional list of predefined answer choices"
            }
        },
        "required": ["question"]
    }
}

from praisonaiagents import BotConfig

config = BotConfig(
    default_tools=["clarify"],  # Included by default
    auto_approve_tools=True     # No approval prompt for clarify
)

from praisonaiagents import Agent
from praisonaiagents.tools.clarify import clarify

agent = Agent(
    name="CodeWriter",
    instructions="""
    Write code based on user requests. Use clarify for:
    1. Language/framework choice when unspecified
    2. Feature priorities when scope is broad
    3. Architecture decisions when requirements are complex
    """,
    tools=[clarify]
)

# Example interaction:
# User: "Build a REST API"
# Agent: clarify("Which language?", ["python", "node.js", "go"])
# User: "python"  
# Agent: clarify("Which framework?", ["fastapi", "flask", "django"])

async def smart_clarify_handler(question, choices):
    """Handler that considers conversation context"""
    # Check previous messages for hints
    context = get_conversation_context()

    if "python" in context and "web" in question.lower():
        # Auto-suggest based on context
        return "fastapi"

    return await show_user_dialog(question, choices)

result = await clarify("Which database?", ["postgres", "mysql"])
# Headless: "No interactive channel available. Please proceed with your best judgment for: Which database?"
# CLI with create_cli_clarify_handler() in ctx: the user is prompted.
# Bot turn: "Your question has been delivered to the user. Do not guess an answer: end your turn now by restating the question and its choices. Their answer will arrive as their next message."

if "no interactive channel" in result.lower():
    database = "postgres"  # headless default