Skip to content

Build and run agents you can see, understand and trust.

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.py
index 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 context
for 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__.py
index ed536d67c..e1ce5f820 100644
--- a/src/agentscope/tool/__init__.py
+++ b/src/agentscope/tool/__init__.py
@@ -7,6 +7,10 @@ from ._toolkit import Toolkit
from ._base import ToolBase, ParamsBase, ToolMiddlewareBase
from ._adapters import MCPTool, FunctionTool
from ._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.py
index 33cc11ba5..f0ced7b64 100644
--- a/src/agentscope/tool/_base.py
+++ b/src/agentscope/tool/_base.py
@@ -5,7 +5,9 @@ import inspect
import os
from abc import abstractmethod, ABC
from pathlib import Path
-from typing import AsyncGenerator, Any, Callable, List
+from typing import AsyncGenerator, Any, Callable, List, TYPE_CHECKING
+
+import jsonschema
from pydantic import BaseModel
@@ -19,6 +21,9 @@ from ..permission import (
from ._response import ToolChunk
from ._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 your
tool 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__.py
index 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, LocalBackend
from ._bash import Bash
from ._edit import Edit
@@ -13,6 +19,10 @@ from ._skill import SkillViewer
from ._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.py
new file mode 100644
index 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.py
new file mode 100644
index 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",
+ )