From 1bec43afad0e3ccb98debaefc936d5947e7585f0 Mon Sep 17 00:00:00 2001 From: Richard Tang Date: Mon, 20 Apr 2026 16:38:29 -0700 Subject: [PATCH] feat: ask_user tool prompt --- .../agent_loop/internals/synthetic_tools.py | 89 +++++++------------ 1 file changed, 31 insertions(+), 58 deletions(-) diff --git a/core/framework/agent_loop/internals/synthetic_tools.py b/core/framework/agent_loop/internals/synthetic_tools.py index e72dd413..016cfe42 100644 --- a/core/framework/agent_loop/internals/synthetic_tools.py +++ b/core/framework/agent_loop/internals/synthetic_tools.py @@ -91,64 +91,37 @@ def sanitize_ask_user_inputs( return q, recovered -ask_user_prompt = ( - "You MUST call this tool whenever you need the user's response. " - "Always call it after greeting the user, asking a question, or " - "requesting approval. Do NOT call it for status updates or " - "summaries that don't require a response.\n\n" - "USAGE:\n" - "Pass a 'questions' array with 1-8 entries. Each entry has an " - "'id' (short identifier used in the user's reply), a 'prompt' " - "(the question text), and optional 'options' (2-3 predefined " - "choices). For a single question, pass a one-item array. For " - "several clarifications, batch them in one call so the user can " - "answer everything in one interaction instead of going back and " - "forth — ALWAYS prefer a batch over multiple sequential calls.\n\n" - "STRUCTURE RULES (CRITICAL):\n" - "- The 'prompt' field is PLAIN TEXT shown to the user. Do NOT " - "include XML tags, pseudo-tags like , or option lists " - "in the prompt string. The UI does not parse them — they render " - "as raw text and look broken.\n" - "- The 'options' parameter is the ONLY way to render buttons. " - "If you want buttons, put them in the 'options' array, not in " - "the prompt string. Do NOT write 'OPTIONS: [...]', " - "'_options: [...]', or any inline list inside 'prompt'.\n" - "- Each prompt must read as a single clean sentence with no " - "markup. Example: 'What would you like to do?' — not " - "'What would you like to do?'.\n\n" - "OPTIONS GUIDANCE:\n" - "Include 2-3 predefined options in most cases. The UI " - "automatically appends an 'Other' free-text input after your " - "options, so NEVER include catch-all options like 'Custom idea', " - "'Something else', 'Other', or 'None of the above' — the UI " - "handles that. When the question primarily needs a typed answer " - "but you must include options, make one option signal that " - "typing is expected (e.g. \"I'll type my response\"). Omit " - "options ONLY when the question demands a free-form answer the " - "user must type out (e.g. 'Describe your agent idea', 'Paste " - "the error message'). Workers MUST always provide options — " - "only the queen may ask free-form questions.\n\n" - "IMPORTANT: Do NOT repeat the questions in your text response — " - "the widget renders them. Keep your text to a brief intro only.\n\n" - "SINGLE-QUESTION EXAMPLE:\n" - '{"questions": [{"id": "next", "prompt": "What would you like ' - 'to do?", "options": ["Build a new agent", ' - '"Modify existing agent", "Run tests"]}]}\n\n' - "BATCH EXAMPLE:\n" - '{"questions": [' - '{"id": "scope", "prompt": "What scope?", ' - '"options": ["Full", "Partial"]}, ' - '{"id": "format", "prompt": "Output format?", ' - '"options": ["PDF", "CSV", "JSON"]}, ' - '{"id": "details", "prompt": "Any special requirements?"}' - "]}\n\n" - "FREE-FORM EXAMPLE (queen only):\n" - '{"questions": [{"id": "idea", "prompt": "Describe the agent ' - 'you want to build."}]}\n\n' - "WRONG (do NOT do this — buttons will not render):\n" - '{"questions": [{"id": "q", "prompt": "What now?\\n' - '_OPTIONS: [\\"A\\", \\"B\\"]"}]}' -) +ask_user_prompt = """\ +Use this tool when you need to ask the user questions during execution. Reach for it when: + +- The task is ambiguous and the user needs to choose an approach +- You need missing information to continue +- You want approval before taking a meaningful action +- A decision has real trade-offs the user should weigh in on +- You want post-task feedback, or to offer saving a skill or updating memory + +Usage notes: +- Users will always be able to select "Other" to provide custom text input +- Use multiSelect: true to allow multiple answers to be selected for a question +- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label +- Call this tool whenever you need the user's response. +- The prompt field must be plain text only. +- Do not include XML, pseudo-tags, or inline option lists inside prompt. +- Omit options only when the question truly requires a free-form response the user must type out, such as describing an idea or pasting an error message. +- Do not repeat the questions in your normal text response. The widget renders them, so keep any surrounding text to a brief intro only. +Example — single question with options: +{"questions": [{"id": "next", "prompt": "What would you like to do?", "options": ["Build a new agent (Recommended)", "Modify existing agent", "Run tests"]}]} + +Example — batch: +{"questions": [ + {"id": "scope", "prompt": "What scope?", "options": ["Full", "Partial"]}, + {"id": "format", "prompt": "Output format?", "options": ["PDF", "CSV", "JSON"]}, + {"id": "details", "prompt": "Any special requirements?"} +]} + +Example — free-form (queen only): +{"questions": [{"id": "idea", "prompt": "Describe the agent you want to build."}]} +""" def build_ask_user_tool() -> Tool: