Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(tool): add AskUser, an external tool for asking the user questions (#2573)
DavdGao033a3613401a
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex e0a8e4b6a..e0ccced4e 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -2009,6 +2009,13 @@ class Agent:elif isinstance(event, ExternalExecutionResultEvent):# Directly append the execution results into contextfor tool_result in event.execution_results:+ # Whoever executed this promised a shape; a result that+ # breaks it is their bug to fix, and the reply stays+ # parked so they can send it again.+ tool = await self.toolkit.get_tool(tool_result.name)+ if tool is not None:+ await tool.check_external_result(tool_result)+async for evt in self._convert_tool_chunk_to_event(tool_result.id,tool_result.output,diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.pyindex ed536d67c..e1ce5f820 100644--- a/src/agentscope/tool/__init__.py+++ b/src/agentscope/tool/__init__.py@@ -7,6 +7,10 @@ from ._toolkit import Toolkitfrom ._base import ToolBase, ParamsBase, ToolMiddlewareBasefrom ._adapters import MCPTool, FunctionToolfrom ._builtin import (+ AskUser,+ AskUserAnswer,+ AskUserMetadata,+ AskUserParams,ResetTools,Bash,PowerShell,@@ -29,6 +33,10 @@ from ._task import (from ._tool_group import ToolGroup__all__ = [+ "AskUser",+ "AskUserAnswer",+ "AskUserMetadata",+ "AskUserParams",# Basic tool related types and functions"ToolChoice","Function",diff --git a/src/agentscope/tool/_base.py b/src/agentscope/tool/_base.pyindex 33cc11ba5..f0ced7b64 100644--- a/src/agentscope/tool/_base.py+++ b/src/agentscope/tool/_base.py@@ -5,7 +5,9 @@ import inspectimport osfrom abc import abstractmethod, ABCfrom pathlib import Path-from typing import AsyncGenerator, Any, Callable, List+from typing import AsyncGenerator, Any, Callable, List, TYPE_CHECKING++import jsonschemafrom pydantic import BaseModel@@ -19,6 +21,9 @@ from ..permission import (from ._response import ToolChunkfrom ._utils import _remove_title_field+if TYPE_CHECKING:+ from ..message import ToolResultBlock+class ParamsBase(BaseModel):"""A base class for tool parameters that remove the title field from the@@ -113,6 +118,15 @@ class ToolBase(ABC):the state will be injected by an argument named `_agent_state`. Note yourtool should be able to accept such argument."""+ metadata_schema: dict[str, Any] | None = None+ """What an external executor must put in+ :attr:`~..message.ToolResultBlock.metadata`, as a JSON schema.++ The counterpart of :attr:`input_schema`: that one tells the model how+ to call the tool, this one tells whoever executes it how to answer.+ ``output`` stays whatever reads well to the model — this is the half+ a caller may depend on. ``None`` means nothing is promised."""+is_mcp: bool = False"""If this tool is an MCP tool, which will be used in the permission"""mcp_name: str | None = None@@ -255,6 +269,27 @@ class ToolBase(ABC):) -> PermissionDecision:"""Check permissions for the tool usage."""+ async def check_external_result(+ self,+ result: "ToolResultBlock",+ ) -> None:+ """Reject a result an external executor sent back.++ Called only for externally executed calls — a tool that produced+ its own result has nothing to check. Shape only, against+ :attr:`metadata_schema`; whether the content is any good is the+ caller's judgement, not this tool's, since a user who answers+ "no idea" has produced a perfectly valid result.++ Raises:+ `jsonschema.ValidationError`:+ If the metadata does not match what the tool promised its+ caller. The reply stays parked, so the executor can fix+ what it sent and try again.+ """+ if self.metadata_schema is not None:+ jsonschema.validate(result.metadata, self.metadata_schema)+async def check_read_only(self,tool_input: dict[str, Any],diff --git a/src/agentscope/tool/_builtin/__init__.py b/src/agentscope/tool/_builtin/__init__.pyindex ef17336fe..05cb7c1ba 100644--- a/src/agentscope/tool/_builtin/__init__.py+++ b/src/agentscope/tool/_builtin/__init__.py@@ -1,6 +1,12 @@# -*- coding: utf-8 -*-"""The builtin tools in agentscope."""+from ._ask_user import (+ AskUser,+ AskUserAnswer,+ AskUserMetadata,+ AskUserParams,+)from ._backend import BackendBase, DirEntry, ExecResult, LocalBackendfrom ._bash import Bashfrom ._edit import Edit@@ -13,6 +19,10 @@ from ._skill import SkillViewerfrom ._write import Write__all__ = [+ "AskUser",+ "AskUserAnswer",+ "AskUserMetadata",+ "AskUserParams","ResetTools","SkillViewer","Bash",diff --git a/src/agentscope/tool/_builtin/_ask_user.py b/src/agentscope/tool/_builtin/_ask_user.pynew file mode 100644index 000000000..62f3c2882--- /dev/null+++ b/src/agentscope/tool/_builtin/_ask_user.py@@ -0,0 +1,211 @@+# -*- coding: utf-8 -*-+"""The asking user tool class."""+from typing import Any++from pydantic import BaseModel, Field++from .._base import ToolBase+from ...permission import (+ PermissionContext,+ PermissionDecision,+ PermissionBehavior,+)++_HEADER_MAX_CHARS = 12+++class _Option(BaseModel):+ """A single selectable option within a question."""++ label: str = Field(+ description=(+ "The display text for this option that the user will see and "+ "select. Should be concise (1-5 words) and clearly describe the "+ "choice."+ ),+ )++ description: str = Field(+ description=(+ "Explanation of what this option means or what will happen if "+ "chosen. Useful for providing context about trade-offs or "+ "implications."+ ),+ )++ preview: str | None = Field(+ default=None,+ description=(+ "Optional preview content rendered when this option is focused. "+ "Use for mockups, code snippets, or visual comparisons that help "+ "users compare options. Only supported in single-select questions."+ ),+ )+++class _Question(BaseModel):+ """A single question presented to the user."""++ question: str = Field(+ description=(+ "The complete question to ask the user. Should be clear, "+ "specific, and end with a question mark. "+ 'Example: "Which library should we use for date formatting?" '+ "If multi_select is true, phrase it accordingly, "+ 'e.g. "Which features do you want to enable?"'+ ),+ )++ header: str = Field(+ max_length=_HEADER_MAX_CHARS,+ description=(+ f"Very short label displayed as a chip/tag "+ f"(max {_HEADER_MAX_CHARS} chars). "+ 'Examples: "Auth method", "Library", "Approach".'+ ),+ )++ context: str | None = Field(+ default=None,+ description=(+ "What the user should look at while answering — the draft "+ "being reviewed, the two designs being compared, the error "+ "that prompted the question. Shown above the options."+ ),+ )++ options: list[_Option] = Field(+ min_length=2,+ max_length=4,+ description=(+ "The available choices for this question. Must have 2-4 options. "+ "Each option should be a distinct, mutually exclusive choice "+ "(unless multi_select is enabled). There should be no 'Other' "+ "option — that will be provided automatically."+ ),+ )++ multi_select: bool = Field(+ default=False,+ description=(+ "Set to true to allow the user to select multiple options instead "+ "of just one. Use when choices are not mutually exclusive. "+ "Note: preview is only supported when multi_select is false."+ ),+ )+++class AskUserAnswer(BaseModel):+ """One question's answer, as the caller must return it.++ An entry of :attr:`AskUserMetadata.answers`; a frontend building+ them one at a time has this to build them with.+ """++ question: str = Field(+ description="The question this answers, verbatim.",+ )++ selected: list[str] = Field(+ default_factory=list,+ description="Labels of the options the user chose.",+ )++ other: str | None = Field(+ default=None,+ description=(+ "What the user typed instead of choosing, when they answered "+ "in their own words."+ ),+ )+++class AskUserMetadata(BaseModel):+ """What the caller must put in ``ToolResultBlock.metadata``.++ ``output`` is for the model to read; this is the half a program may+ branch on — a step deciding whether its work was approved cannot do+ that on prose.+ """++ answers: list[AskUserAnswer]+++class AskUserParams(BaseModel):+ """What a caller asks for — the questions, and their options.++ A model fills this in from :attr:`AskUser.input_schema`; a program+ building the call itself has this to build it with."""++ questions: list[_Question] = Field(+ min_length=1,+ max_length=4,+ description=(+ "Questions to ask the user (1-4 questions). Question texts must "+ "be unique; option labels must be unique within each question."+ ),+ )+++class AskUser(ToolBase):+ """The tool to collect information from the user via multiple-choice+ questions.++ External by nature: only whatever is driving the agent can put a+ question in front of a person, so the agent yields the call and waits+ for the answer to come back rather than executing anything itself.+ """++ name: str = "AskUser"+ """The tool name."""++ # pylint: disable=line-too-long+ description: str = """Asks the user multiple-choice questions to gather information, clarify ambiguity, understand preferences, make decisions, or offer choices.++Use this tool when you need to ask the user questions during execution:+1. Gather user preferences or requirements.+2. Clarify ambiguous instructions before proceeding.+3. Get decisions on implementation choices as you work.+4. Offer the user a set of directions to take.++## Usage rules+- You may batch 1–4 questions in a single call; batch related questions together.+- Each question must have 2–4 options. Option labels must be unique within a question.+- Question texts must be unique across the batch.+- Users will always be able to select "Other" to provide free-text input — do not add an "Other" option yourself.+- Use `multi_select: true` only when the choices are genuinely not mutually exclusive.+- If you recommend a specific option, place it first and append "(Recommended)" to its label.+- The `preview` field on an option renders a side-by-side visual comparison; only use it for concrete artifacts (code snippets, ASCII mockups, config examples) where seeing the content helps the user choose. Preview is only supported for single-select questions.+- Put whatever the user must look at to answer — a draft, a diff, an error — in `context` rather than in the question text.++## What comes back+`output` is written for you to read. The caller also returns the same answers in `ToolResultBlock.metadata`, shaped by `AskUserMetadata`, for programs that must branch on the choice rather than read prose.""" # noqa: E501+ """The description presented to the agent."""++ input_schema: dict[str, Any] = AskUserParams.model_json_schema()++ metadata_schema: dict[+ str,+ Any,+ ] | None = AskUserMetadata.model_json_schema()++ is_read_only: bool = True+ is_state_injected: bool = False+ is_concurrency_safe: bool = True+ is_external_tool: bool = True++ async def check_permissions(+ self,+ tool_input: dict[str, Any],+ context: PermissionContext,+ ) -> PermissionDecision:+ """Never asks to ask.++ The call is answered by the user in the first place, so a+ confirmation in front of it would only be a prompt about a+ prompt.+ """+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ message="The AskUser tool is always permitted.",+ )diff --git a/tests/ask_user_tool_test.py b/tests/ask_user_tool_test.pynew file mode 100644index 000000000..89b7b9c86--- /dev/null+++ b/tests/ask_user_tool_test.py@@ -0,0 +1,100 @@+# -*- coding: utf-8 -*-+"""Unittests for the AskUser tool."""+from unittest import IsolatedAsyncioTestCase++import jsonschema+from pydantic import ValidationError++from agentscope.message import ToolResultBlock, ToolResultState+from agentscope.permission import PermissionBehavior, PermissionContext+from agentscope.tool import AskUser, AskUserMetadata, AskUserParams+++class AskUserTest(IsolatedAsyncioTestCase):+ """Test the AskUser tool."""++ def setUp(self) -> None:+ """Build the tool."""+ self.tool = AskUser()++ async def test_the_call_is_left_to_whoever_can_ask(self) -> None:+ """Nothing executes it here — the agent yields it instead."""+ self.assertTrue(self.tool.is_external_tool)+ with self.assertRaises(RuntimeError):+ await self.tool()++ async def test_it_never_asks_to_ask(self) -> None:+ """A confirmation in front of a question is a prompt about a+ prompt."""+ decision = await self.tool.check_permissions(+ {"questions": []},+ PermissionContext(),+ )+ self.assertEqual(decision.behavior, PermissionBehavior.ALLOW)++ async def test_a_question_needs_between_two_and_four_options(+ self,+ ) -> None:+ """One option is not a choice, and five is a menu."""+ option = {"label": "a", "description": "d"}+ for count in (1, 5):+ with self.assertRaises(ValidationError):+ AskUserParams.model_validate(+ {+ "questions": [+ {+ "question": "Which?",+ "header": "Pick",+ "options": [option] * count,+ },+ ],+ },+ )++ async def test_a_header_stays_short_enough_to_be_a_chip(self) -> None:+ """It is rendered as a tag, so it cannot run on."""+ with self.assertRaises(ValidationError):+ AskUserParams.model_validate(+ {+ "questions": [+ {+ "question": "Which?",+ "header": "a header far too long to be a chip",+ "options": [+ {"label": "a", "description": "d"},+ {"label": "b", "description": "d"},+ ],+ },+ ],+ },+ )++ async def test_a_result_that_breaks_its_promise_is_refused(self) -> None:+ """The shape is the caller's to keep; prose alone is not enough."""+ result = ToolResultBlock(+ id="call-1",+ name="AskUser",+ output="通过",+ state=ToolResultState.SUCCESS,+ )+ with self.assertRaises(jsonschema.ValidationError):+ await self.tool.check_external_result(result)++ result.metadata = AskUserMetadata(+ answers=[+ {"question": "批准吗?", "selected": ["通过"], "other": None},+ ],+ ).model_dump()+ await self.tool.check_external_result(result)++ async def test_the_schema_reaches_the_model_whole(self) -> None:+ """Nested models mean $defs, which the model layers inline."""+ schema = self.tool.input_schema+ self.assertListEqual(+ sorted(schema["$defs"]),+ ["_Option", "_Question"],+ )+ self.assertEqual(+ schema["properties"]["questions"]["items"]["$ref"],+ "#/$defs/_Question",+ )