Skip to content

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

59.5 KB
Raw Blame
# -*- coding: utf-8 -*-
# pylint: disable=unused-argument
"""Toolkit test case."""
import base64
import json
from typing import Any, AsyncGenerator, Awaitable, Generator, Literal
from unittest import TestCase
from unittest.async_case import IsolatedAsyncioTestCase


from pydantic import BaseModel, Field
from utils import AnyString, MockModel

from agentscope.agent import Agent
from agentscope.event import ToolResultStartEvent
from agentscope.mcp import HttpMCPConfig, MCPClient
from agentscope.state import AgentState
from agentscope.message import (
    AssistantMsg,
    TextBlock,
    ToolCallBlock,
    DataBlock,
    Base64Source,
    URLSource,
)
from agentscope.tool import (
    Toolkit,
    ToolBase,
    ToolChunk,
    ToolResponse,
    ToolGroup,
    FunctionTool,
)
from agentscope.permission import (
    PermissionContext,
    PermissionDecision,
    PermissionBehavior,
)
from agentscope.exception import (
    ToolNotFoundError,
    ToolGroupInactiveError,
)


class Tool1(ToolBase):
    """A simple tool for testing."""

    name: str = "tool_1"
    description: str = "A simple tool for testing."
    input_schema: dict = {
        "type": "object",
        "properties": {},
    }
    is_concurrency_safe: bool = True
    is_read_only: bool = True
    is_mcp: bool = False

    async def check_permissions(
        self,
        *args: Any,
        **kwargs: Any,
    ) -> PermissionDecision:
        """Check permissions for the tool."""
        return PermissionDecision(
            behavior=PermissionBehavior.ASK,
            message="Do you want to use my_tool?",
        )

    async def call(self, **kwargs: Any) -> ToolChunk:
        """Run the tool."""
        return ToolChunk(
            content=[TextBlock(text="Hello, world!")],
        )


class Tool2(ToolBase):
    """Test tool 2"""

    name: str = "tool_2"
    description: str = "Test tool 2."
    input_schema: dict = {
        "type": "object",
        "properties": {},
    }
    is_concurrency_safe: bool = True
    is_read_only: bool = True
    is_mcp: bool = False

    async def check_permissions(
        self,
        *args: Any,
        **kwargs: Any,
    ) -> PermissionDecision:
        """Check permissions for the tool."""
        return PermissionDecision(
            behavior=PermissionBehavior.ASK,
            message="Do you want to use my_tool?",
        )

    async def call(self, **kwargs: Any) -> AsyncGenerator[ToolChunk, None]:
        """Run the tool."""
        yield ToolChunk(
            content=[TextBlock(text="123", id="a")],
        )
        yield ToolChunk(
            content=[TextBlock(text="456", id="b")],
        )
        yield ToolChunk(
            content=[TextBlock(text="789", id="b")],
        )
        yield ToolChunk(
            content=[
                DataBlock(
                    id="1",
                    source=Base64Source(
                        data="abc",
                        media_type="image/jpeg",
                    ),
                ),
            ],
        )
        yield ToolChunk(
            content=[
                DataBlock(
                    id="2",
                    source=Base64Source(
                        data="***",
                        media_type="image/jpeg",
                    ),
                ),
            ],
        )
        yield ToolChunk(
            content=[
                DataBlock(
                    id="1",
                    source=Base64Source(
                        data="def",
                        media_type="image/jpeg",
                    ),
                ),
            ],
        )


class ToolkitTest(IsolatedAsyncioTestCase):
    """The toolkit test case."""

    async def asyncSetUp(self) -> None:
        """The async setup method."""

    async def test_initialize(self) -> None:
        """The template test."""

        # Initialize the toolkit
        toolkit = Toolkit()

        # No tools
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 0)

        # Initialize the toolkit with tools
        toolkit = Toolkit(tools=[Tool1(), Tool2()])
        schemas = await toolkit.get_tool_schemas()
        self.assertListEqual(
            schemas,
            [
                {
                    "type": "function",
                    "function": {
                        "name": "tool_1",
                        "description": "A simple tool for testing.",
                        "parameters": {
                            "type": "object",
                            "properties": {},
                        },
                    },
                },
                {
                    "type": "function",
                    "function": {
                        "name": "tool_2",
                        "description": "Test tool 2.",
                        "parameters": {
                            "type": "object",
                            "properties": {},
                        },
                    },
                },
            ],
        )

    async def test_tool(self) -> None:
        """Test executing a tool."""
        toolkit = Toolkit(tools=[Tool1(), Tool2()])
        state = AgentState()

        # Test Tool1 (returns single ToolChunk)
        tool_call_1 = ToolCallBlock(
            id="test_1",
            name="tool_1",
            input=json.dumps({}),
        )

        chunks_1 = []
        response_1 = None
        async for result in toolkit.call_tool(tool_call_1, state):
            if isinstance(result, ToolChunk):
                chunks_1.append(result)
            elif isinstance(result, ToolResponse):
                response_1 = result

        # Verify Tool1 chunks
        self.assertEqual(len(chunks_1), 1)
        self.assertDictEqual(
            chunks_1[0].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Hello, world!",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Verify Tool1 response
        self.assertIsNotNone(response_1)
        self.assertDictEqual(
            response_1.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Hello, world!",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_1",
            },
        )

        # Test Tool2 (returns async generator of ToolChunks)
        tool_call_2 = ToolCallBlock(
            id="test_2",
            name="tool_2",
            input=json.dumps({}),
        )

        chunks_2 = []
        response_2 = None
        async for result in toolkit.call_tool(tool_call_2, state):
            if isinstance(result, ToolChunk):
                chunks_2.append(result)
            elif isinstance(result, ToolResponse):
                response_2 = result

        # Verify Tool2 chunks
        self.assertEqual(len(chunks_2), 6)

        # First chunk - TextBlock id="a"
        self.assertDictEqual(
            chunks_2[0].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "a",
                        "text": "123",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Second chunk - TextBlock id="b"
        self.assertDictEqual(
            chunks_2[1].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "b",
                        "text": "456",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Third chunk - TextBlock id="b" (same id as second)
        self.assertDictEqual(
            chunks_2[2].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "b",
                        "text": "789",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Fourth chunk - DataBlock id="1"
        self.assertDictEqual(
            chunks_2[3].model_dump(),
            {
                "content": [
                    {
                        "type": "data",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "1",
                        "name": None,
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": "abc",
                        },
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Fifth chunk - DataBlock id="2"
        self.assertDictEqual(
            chunks_2[4].model_dump(),
            {
                "content": [
                    {
                        "type": "data",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "2",
                        "name": None,
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": "***",
                        },
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Sixth chunk - DataBlock id="1" (same id as fourth)
        self.assertDictEqual(
            chunks_2[5].model_dump(),
            {
                "content": [
                    {
                        "type": "data",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "1",
                        "name": None,
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": "def",
                        },
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Verify Tool2 response - blocks with same id are merged,
        # and consecutive TextBlocks are also merged
        # TextBlock id="a" (123) + id="b" (456) + id="b" (789) -> merged to
        # "123456789" with id="a"
        # DataBlock id="1" appears twice, should be merged to "abcdef"
        self.assertIsNotNone(response_2)
        self.assertDictEqual(
            response_2.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "a",
                        # All consecutive TextBlocks merged
                        "text": "123456789",
                    },
                    {
                        "type": "data",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "1",
                        "name": None,
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": "abcdef",  # Merged: "abc" + "def"
                        },
                    },
                    {
                        "type": "data",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": "2",
                        "name": None,
                        "source": {
                            "type": "base64",
                            "media_type": "image/jpeg",
                            "data": "***",
                        },
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_2",
            },
        )

    async def test_tool_response_merges_base64_chunks_by_bytes(self) -> None:
        """Base64 chunks with padding should merge as bytes, not strings."""
        response = ToolResponse(id="tool")
        first = base64.b64encode(b"hello").decode("ascii")
        second = base64.b64encode(b"world").decode("ascii")

        response.append_chunk(
            ToolChunk(
                content=[
                    DataBlock(
                        id="image",
                        source=Base64Source(
                            data=first,
                            media_type="image/png",
                        ),
                    ),
                ],
            ),
        )
        response.append_chunk(
            ToolChunk(
                content=[
                    DataBlock(
                        id="image",
                        source=Base64Source(
                            data=second,
                            media_type="image/png",
                        ),
                    ),
                ],
            ),
        )

        self.assertEqual(
            response.model_dump(),
            {
                "id": "tool",
                "state": "success",
                "metadata": {},
                "content": [
                    {
                        "type": "data",
                        "id": "image",
                        "source": {
                            "type": "base64",
                            "media_type": "image/png",
                            "data": base64.b64encode(b"helloworld").decode(),
                        },
                        "name": None,
                        "created_at": AnyString(),
                        "finished_at": None,
                    },
                ],
            },
        )

    async def test_tool_response_groups_streamed_blocks(self) -> None:
        """The response and event replay preserve interleaved tool output."""

        class CustomDataBlock(DataBlock):
            """A tool-provided data block subclass."""

        text = TextBlock(id="s", text="progress")
        before = TextBlock(id="s", text="before")
        after = TextBlock(id="s", text="after")
        first = CustomDataBlock(
            id="s",
            source=Base64Source(data="YQ==", media_type="audio/wav"),
        )
        second = DataBlock(
            id="s",
            source=Base64Source(data="Yg==", media_type="audio/wav"),
        )
        urls = [
            DataBlock(
                id="s",
                source=URLSource(url=url, media_type="image/png"),
            )
            for url in ("https://example.org/one", "https://example.org/two")
        ]
        blocks = [text, urls[0], first, before, urls[1], second, after]
        expected: dict[str, Any] = {
            "id": "tool",
            "state": "success",
            "metadata": {},
            "content": [
                text.model_dump(),
                urls[0].model_dump(),
                {
                    **first.model_dump(),
                    "source": {
                        "type": "base64",
                        "data": "YWI=",
                        "media_type": "audio/wav",
                    },
                },
                before.model_dump(),
                urls[1].model_dump(),
                after.model_dump(),
            ],
        }

        agent = Agent(name="agent", system_prompt="", model=MockModel())
        for chunks in ([blocks], [[block] for block in blocks]):
            with self.subTest(chunk_count=len(chunks)):
                response = ToolResponse(id="tool")
                message = AssistantMsg(
                    name=agent.name,
                    id=agent.state.reply_id,
                    content=[],
                )
                message.append_event(
                    ToolResultStartEvent(
                        reply_id=message.id,
                        tool_call_id=response.id,
                        tool_call_name="stream",
                    ),
                )
                for content in chunks:
                    response.append_chunk(ToolChunk(content=content))
                    # pylint: disable-next=protected-access
                    async for event in agent._convert_tool_chunk_to_event(
                        response.id,
                        content,
                    ):
                        message.append_event(event)
                self.assertEqual(response.model_dump(), expected)
                self.assertEqual(
                    message.content[0].model_dump()["output"],
                    [
                        {
                            **block,
                            "created_at": AnyString(),
                            "id": AnyString()
                            if block["type"] == "text"
                            else block["id"],
                        }
                        for block in expected["content"]
                    ],
                )


class RegisterFunctionTest(IsolatedAsyncioTestCase):
    """Test registering different functions in the toolkit."""

    async def test_sync_function_returning_awaitable(self) -> None:
        """Await the coroutine returned by a sync function."""

        async def finish(value: str) -> ToolChunk:
            """Create the deferred tool result."""
            return ToolChunk(content=[TextBlock(text=value)])

        def deferred(value: str) -> Awaitable[ToolChunk]:
            """Return a coroutine without executing it."""
            return finish(value)

        toolkit = Toolkit(tools=[FunctionTool(deferred)])
        results = [
            item
            async for item in toolkit.call_tool(
                ToolCallBlock(
                    id="awaitable",
                    name="deferred",
                    input='{"value": "completed"}',
                ),
                AgentState(),
            )
        ]
        self.assertDictEqual(
            results[-1].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "completed",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "awaitable",
            },
        )

    async def test_async_callable_tool(self) -> None:
        """Await an async callable object."""

        class Deferred:
            """A callable tool that resolves asynchronously."""

            async def __call__(self, value: str) -> ToolChunk:
                """Create a tool result asynchronously.

                Args:
                    value (`str`):
                        The text to include in the result.

                Returns:
                    `ToolChunk`:
                        The completed tool result.
                """
                return ToolChunk(content=[TextBlock(text=value)])

        tool = FunctionTool(Deferred(), name="deferred")
        result = await tool.call(value="completed")
        self.assertDictEqual(
            result.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "completed",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

    async def test_sync_non_streaming_function(self) -> None:
        """Test registering a synchronous non-streaming function."""

        def add_numbers(a: int, b: int) -> ToolChunk:
            """Add two numbers together.

            Args:
                a: The first number
                b: The second number
            """
            result = a + b
            return ToolChunk(
                content=[TextBlock(text=f"Result: {result}")],
            )

        toolkit = Toolkit(
            tools=[FunctionTool(add_numbers)],
        )

        # Test schema
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 1)
        self.assertDictEqual(
            schemas[0],
            {
                "type": "function",
                "function": {
                    "name": "add_numbers",
                    "description": "Add two numbers together.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "a": {
                                "type": "integer",
                                "description": "The first number",
                            },
                            "b": {
                                "type": "integer",
                                "description": "The second number",
                            },
                        },
                        "required": ["a", "b"],
                    },
                },
            },
        )

        # Test execution
        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_add",
            name="add_numbers",
            input=json.dumps({"a": 3, "b": 5}),
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        # Verify chunks
        self.assertEqual(len(chunks), 1)
        self.assertDictEqual(
            chunks[0].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Result: 8",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Verify response
        self.assertIsNotNone(response)
        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Result: 8",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_add",
            },
        )

    async def test_sync_function_returning_plain_string(self) -> None:
        """Test wrapping a sync function that returns a plain string."""

        def get_weather(location: str) -> str:
            """Get weather information.

            Args:
                location: The location to get weather for
            """
            return f"The weather in {location} is sunny."

        toolkit = Toolkit(
            tools=[FunctionTool(get_weather)],
        )

        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_weather",
            name="get_weather",
            input=json.dumps({"location": "Chengdu"}),
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        self.assertEqual(len(chunks), 1)
        self.assertDictEqual(
            chunks[0].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "The weather in Chengdu is sunny.",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        self.assertIsNotNone(response)
        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "The weather in Chengdu is sunny.",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_weather",
            },
        )

    async def test_async_function_returning_json_serializable_value(
        self,
    ) -> None:
        """Test wrapping an async function that returns a JSON value."""

        async def get_weather(location: str) -> dict:
            """Get weather information.

            Args:
                location: The location to get weather for
            """
            return {
                "location": location,
                "weather": {
                    "condition": "sunny",
                    "temperature": 22,
                },
            }

        toolkit = Toolkit(
            tools=[FunctionTool(get_weather)],
        )

        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_weather_json",
            name="get_weather",
            input=json.dumps({"location": "成都"}),
        )
        expected_text = json.dumps(
            {
                "location": "成都",
                "weather": {
                    "condition": "sunny",
                    "temperature": 22,
                },
            },
            ensure_ascii=False,
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        self.assertEqual(len(chunks), 1)
        self.assertEqual(chunks[0].content[0].text, expected_text)

        self.assertIsNotNone(response)
        self.assertEqual(response.content[0].text, expected_text)

    async def test_sync_streaming_function(self) -> None:
        """Test registering a synchronous streaming function."""

        def count_to_n(n: int) -> Generator[ToolChunk, None, None]:
            """Count from 1 to n.

            Args:
                n: The number to count to
            """
            for i in range(1, n + 1):
                yield ToolChunk(
                    content=[TextBlock(text=str(i))],
                )

        toolkit = Toolkit(
            tools=[
                FunctionTool(
                    func=count_to_n,
                ),
            ],
        )

        # Test schema
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 1)
        self.assertDictEqual(
            schemas[0],
            {
                "type": "function",
                "function": {
                    "name": "count_to_n",
                    "description": "Count from 1 to n.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "n": {
                                "type": "integer",
                                "description": "The number to count to",
                            },
                        },
                        "required": ["n"],
                    },
                },
            },
        )

        # Test execution
        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_count",
            name="count_to_n",
            input=json.dumps({"n": 3}),
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        # Verify chunks
        self.assertEqual(len(chunks), 3)
        for i, chunk in enumerate(chunks, 1):
            self.assertDictEqual(
                chunk.model_dump(),
                {
                    "content": [
                        {
                            "type": "text",
                            "created_at": AnyString(),
                            "finished_at": None,
                            "id": AnyString(),
                            "text": str(i),
                        },
                    ],
                    "state": "running",
                    "is_last": True,
                    "metadata": {},
                    "id": AnyString(),
                },
            )

        # Verify response - consecutive TextBlocks are merged
        self.assertIsNotNone(response)
        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "123",  # All consecutive TextBlocks merged
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_count",
            },
        )

    async def test_sync_streaming_function_returning_plain_values(
        self,
    ) -> None:
        """Test wrapping a sync generator that yields plain values."""

        def stream_weather() -> Generator[Any, None, None]:
            """Stream weather information."""
            yield "checking"
            yield {
                "condition": "sunny",
                "temperature": 22,
            }

        toolkit = Toolkit(
            tools=[FunctionTool(stream_weather)],
        )

        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_weather_stream",
            name="stream_weather",
            input=json.dumps({}),
        )
        expected_dict_text = json.dumps(
            {
                "condition": "sunny",
                "temperature": 22,
            },
            ensure_ascii=False,
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        self.assertEqual(
            [chunk.content[0].text for chunk in chunks],
            ["checking", expected_dict_text],
        )

        self.assertIsNotNone(response)
        self.assertEqual(
            response.content[0].text,
            f"checking{expected_dict_text}",
        )

    async def test_async_non_streaming_function(self) -> None:
        """Test registering an asynchronous non-streaming function."""

        async def multiply_numbers(x: float, y: float) -> ToolChunk:
            """Multiply two numbers.

            Args:
                x: The first number
                y: The second number
            """
            result = x * y
            return ToolChunk(
                content=[TextBlock(text=f"Product: {result}")],
            )

        toolkit = Toolkit(
            tools=[FunctionTool(multiply_numbers)],
        )

        # Test schema
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 1)
        self.assertDictEqual(
            schemas[0],
            {
                "type": "function",
                "function": {
                    "name": "multiply_numbers",
                    "description": "Multiply two numbers.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "x": {
                                "type": "number",
                                "description": "The first number",
                            },
                            "y": {
                                "type": "number",
                                "description": "The second number",
                            },
                        },
                        "required": ["x", "y"],
                    },
                },
            },
        )

        # Test execution
        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_multiply",
            name="multiply_numbers",
            input=json.dumps({"x": 2.5, "y": 4.0}),
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        # Verify chunks
        self.assertEqual(len(chunks), 1)
        self.assertDictEqual(
            chunks[0].model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Product: 10.0",
                    },
                ],
                "state": "running",
                "is_last": True,
                "metadata": {},
                "id": AnyString(),
            },
        )

        # Verify response
        self.assertIsNotNone(response)
        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "Product: 10.0",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_multiply",
            },
        )

    async def test_async_streaming_function(self) -> None:
        """Test registering an asynchronous streaming function."""

        async def generate_sequence(
            start: int,
            end: int,
        ) -> AsyncGenerator[ToolChunk, None]:
            """Generate a sequence of numbers.

            Args:
                start: The starting number
                end: The ending number
            """
            for i in range(start, end + 1):
                yield ToolChunk(
                    content=[TextBlock(text=f"Number: {i}")],
                )

        toolkit = Toolkit(
            tools=[FunctionTool(generate_sequence)],
        )

        # Test schema
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 1)
        self.assertDictEqual(
            schemas[0],
            {
                "type": "function",
                "function": {
                    "name": "generate_sequence",
                    "description": "Generate a sequence of numbers.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "start": {
                                "type": "integer",
                                "description": "The starting number",
                            },
                            "end": {
                                "type": "integer",
                                "description": "The ending number",
                            },
                        },
                        "required": ["start", "end"],
                    },
                },
            },
        )

        # Test execution
        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_sequence",
            name="generate_sequence",
            input=json.dumps({"start": 5, "end": 7}),
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        # Verify chunks
        self.assertEqual(len(chunks), 3)
        for chunk, num in zip(chunks, [5, 6, 7]):
            self.assertDictEqual(
                chunk.model_dump(),
                {
                    "content": [
                        {
                            "type": "text",
                            "created_at": AnyString(),
                            "finished_at": None,
                            "id": AnyString(),
                            "text": f"Number: {num}",
                        },
                    ],
                    "state": "running",
                    "is_last": True,
                    "metadata": {},
                    "id": AnyString(),
                },
            )

        # Verify response - consecutive TextBlocks are merged
        self.assertIsNotNone(response)
        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        # All consecutive TextBlocks merged
                        "text": "Number: 5Number: 6Number: 7",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_sequence",
            },
        )

    async def test_async_streaming_function_returning_plain_values(
        self,
    ) -> None:
        """Test wrapping an async generator that yields plain values."""

        async def stream_status() -> AsyncGenerator[Any, None]:
            """Stream status information."""
            yield "started"
            yield {
                "done": True,
            }

        toolkit = Toolkit(
            tools=[FunctionTool(stream_status)],
        )

        state = AgentState()
        tool_call = ToolCallBlock(
            id="test_status_stream",
            name="stream_status",
            input=json.dumps({}),
        )
        expected_dict_text = json.dumps(
            {
                "done": True,
            },
            ensure_ascii=False,
        )

        chunks = []
        response = None
        async for result in toolkit.call_tool(tool_call, state):
            if isinstance(result, ToolChunk):
                chunks.append(result)
            elif isinstance(result, ToolResponse):
                response = result

        self.assertEqual(
            [chunk.content[0].text for chunk in chunks],
            ["started", expected_dict_text],
        )

        self.assertIsNotNone(response)
        self.assertEqual(
            response.content[0].text,
            f"started{expected_dict_text}",
        )

    async def test_state_injected_function(self) -> None:
        """Infer business parameters and inject state at invocation."""

        def echo(value: str, _agent_state: AgentState) -> str:
            """Return a value with the current session.

            Args:
                value: The value to return.
                _agent_state: The agent state injected by the toolkit.
            """
            return f"{value}:{_agent_state.session_id}"

        tool = FunctionTool(echo, is_state_injected=True)
        self.assertDictEqual(
            tool.input_schema,
            {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "string",
                        "description": "The value to return.",
                    },
                },
                "required": ["value"],
            },
        )

        state = AgentState(session_id="test-session")
        toolkit = Toolkit(tools=[tool])
        response = None
        async for result in toolkit.call_tool(
            ToolCallBlock(
                id="test_state_injection",
                name="echo",
                input=json.dumps({"value": "hello"}),
            ),
            state,
        ):
            if isinstance(result, ToolResponse):
                response = result

        self.assertDictEqual(
            response.model_dump(),
            {
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "hello:test-session",
                    },
                ],
                "state": "success",
                "metadata": {},
                "id": "test_state_injection",
            },
        )

    async def test_custom_input_schema(self) -> None:
        """Test overriding the auto-extracted schema with a custom one."""

        def set_mode(mode: str) -> str:
            """Set the working mode.

            Args:
                mode: The mode to use
            """
            return f"Mode set to {mode}"

        toolkit = Toolkit(
            tools=[
                FunctionTool(
                    set_mode,
                    input_schema={
                        "type": "object",
                        "properties": {
                            "mode": {
                                "type": "string",
                                "description": "The mode to use",
                                "enum": ["fast", "slow"],
                            },
                        },
                        "required": ["mode"],
                    },
                ),
            ],
        )

        schemas = await toolkit.get_tool_schemas()
        self.assertListEqual(
            schemas,
            [
                {
                    "type": "function",
                    "function": {
                        "name": "set_mode",
                        "description": "Set the working mode.",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "mode": {
                                    "type": "string",
                                    "description": "The mode to use",
                                    "enum": ["fast", "slow"],
                                },
                            },
                            "required": ["mode"],
                        },
                    },
                },
            ],
        )

    async def test_base_model_input_schema(self) -> None:
        """Test passing a pydantic BaseModel class as the input schema."""

        class SetModeInput(BaseModel):
            """The input model of the set_mode tool."""

            mode: Literal["fast", "slow"] = Field(
                description="The mode to use",
            )
            level: int = Field(
                default=5,
                ge=1,
                le=10,
                description="The level to use",
            )

        def set_mode(mode: str, level: int = 5) -> str:
            """Set the working mode."""
            return f"Mode set to {mode} at level {level}"

        toolkit = Toolkit(
            tools=[
                FunctionTool(
                    set_mode,
                    input_schema=SetModeInput,
                ),
            ],
        )

        schemas = await toolkit.get_tool_schemas()
        self.assertListEqual(
            schemas,
            [
                {
                    "type": "function",
                    "function": {
                        "name": "set_mode",
                        "description": "Set the working mode.",
                        "parameters": {
                            "type": "object",
                            "description": (
                                "The input model of the set_mode tool."
                            ),
                            "properties": {
                                "mode": {
                                    "type": "string",
                                    "description": "The mode to use",
                                    "enum": ["fast", "slow"],
                                },
                                "level": {
                                    "type": "integer",
                                    "description": "The level to use",
                                    "default": 5,
                                    "minimum": 1,
                                    "maximum": 10,
                                },
                            },
                            "required": ["mode"],
                        },
                    },
                },
            ],
        )

    async def test_permission(self) -> None:
        """Test the permission decision of the function tool."""

        def set_mode(mode: str) -> str:
            """Set the working mode.

            Args:
                mode: The mode to use
            """
            return f"Mode set to {mode}"

        # Ask the user by default
        self.assertEqual(
            await FunctionTool(set_mode).check_permissions(
                {"mode": "fast"},
                PermissionContext(),
            ),
            PermissionDecision(
                behavior=PermissionBehavior.ASK,
                message="Custom function tools must be explicitly allowed "
                "by the user.",
            ),
        )

        # The given decision takes effect
        decision = PermissionDecision(
            behavior=PermissionBehavior.ALLOW,
            message="set_mode is always allowed.",
        )
        self.assertEqual(
            await FunctionTool(
                set_mode,
                permission=decision,
            ).check_permissions(
                {"mode": "fast"},
                PermissionContext(),
            ),
            decision,
        )


class ToolGroupTest(IsolatedAsyncioTestCase):
    """The tool group test case."""

    async def asyncSetUp(self) -> None:
        """The async setup method."""
        self.meta_tool_description = (
            "This tool allows you to reset your equipped tools based on your "
            "current task requirements. These tools are organized into "
            "different groups, and you can activate/deactivate them "
            "by specifying the boolean values for each group in the input.\n\n"
            "**Important: The input booleans are the final state of their "
            "corresponding tool groups, not incremental changes.** Any "
            "group not explicitly set to True will be deactivated, "
            "regardless of its previous state.\n\n"
            "**Best practice**: Actively manage your tool groups——activate "
            "only what you need for the current task, and promptly "
            "deactivate groups as soon as they are no longer needed to"
            " conserve context space.\n\n"
            "This tool will return the usage instructions for the activated "
            "tool groups, which you **MUST pay attention to and follow**. "
            "You can also reuse this tool to re-check the instructions."
        )

    async def test_meta_tool(self) -> None:
        """Test creating a tool group."""
        toolkit = Toolkit()

        # Test meta tool when no groups exist
        schemas = await toolkit.get_tool_schemas()
        self.assertEqual(len(schemas), 0)

        toolkit = Toolkit(
            tool_groups=[
                ToolGroup(
                    name="group_1",
                    description="Group 1",
                ),
            ],
        )

        # The group is created successfully
        self.assertEqual(len(toolkit.tool_groups), 2)
        # The builtin meta tool is activated
        schemas = await toolkit.get_tool_schemas()

        self.assertListEqual(
            schemas,
            [
                {
                    "type": "function",
                    "function": {
                        "name": "reset_tools",
                        "description": self.meta_tool_description,
                        "parameters": {
                            "properties": {
                                "group_1": {
                                    "default": False,
                                    "description": "Group 1",
                                    "type": "boolean",
                                },
                            },
                            "type": "object",
                        },
                    },
                },
            ],
        )

        # Name conflict
        with self.assertRaises(ValueError):
            Toolkit(
                tool_groups=[
                    ToolGroup(
                        name="group_2",
                        description="Group 2",
                    ),
                    ToolGroup(
                        name="group_2",
                        description="Group 2",
                    ),
                ],
            )

        # A new group with tools
        toolkit = Toolkit(
            tool_groups=[
                ToolGroup(
                    name="group_1",
                    description="Group 1",
                ),
                ToolGroup(
                    name="group_2",
                    description="Group 2",
                    tools=[Tool1(), Tool2()],
                    instructions="This is group 2.",
                ),
            ],
        )

        self.assertEqual(len(toolkit.tool_groups), 3)
        schemas = await toolkit.get_tool_schemas()
        self.assertListEqual(
            schemas,
            [
                {
                    "type": "function",
                    "function": {
                        "name": "reset_tools",
                        "description": self.meta_tool_description,
                        "parameters": {
                            "properties": {
                                "group_1": {
                                    "default": False,
                                    "description": "Group 1",
                                    "type": "boolean",
                                },
                                "group_2": {
                                    "default": False,
                                    "description": "Group 2",
                                    "type": "boolean",
                                },
                            },
                            "type": "object",
                        },
                    },
                },
            ],
        )

        # Active one group
        state = AgentState()
        res = toolkit.call_tool(
            ToolCallBlock(
                id="xxx",
                name="reset_tools",
                input=json.dumps({"group_2": True}),
            ),
            state,
        )

        chunk = await anext(res)
        self.assertIsInstance(chunk, ToolChunk)

        chunk = await anext(res)
        self.assertIsInstance(chunk, ToolResponse)
        self.assertDictEqual(
            chunk.model_dump(),
            {
                "id": AnyString(),
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": """The currently activated tool group(s): group_2.
<tool-instructions>
The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
<group name="group_2">This is group 2.</group>
</tool-instructions>""",  # noqa: E501
                    },
                ],
                "metadata": {},
                "state": "success",
            },
        )

        # Activate both groups
        res = toolkit.call_tool(
            ToolCallBlock(
                id="xxx",
                name="reset_tools",
                input=json.dumps({"group_2": True, "group_1": True}),
            ),
            state,
        )

        last_chunk = None
        async for chunk in res:
            last_chunk = chunk

        self.assertDictEqual(
            last_chunk.model_dump(),
            {
                "id": AnyString(),
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": """The currently activated tool group(s): group_1, group_2.
<tool-instructions>
The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.
<group name="group_2">This is group 2.</group>
</tool-instructions>""",  # noqa: E501
                    },
                ],
                "metadata": {},
                "state": "success",
            },
        )

        # deactivate all groups
        res = toolkit.call_tool(
            ToolCallBlock(
                id="xxx",
                name="reset_tools",
                input=json.dumps({}),
            ),
            state,
        )

        last_chunk = None
        async for chunk in res:
            last_chunk = chunk

        self.assertDictEqual(
            last_chunk.model_dump(),
            {
                "id": AnyString(),
                "content": [
                    {
                        "type": "text",
                        "created_at": AnyString(),
                        "finished_at": None,
                        "id": AnyString(),
                        "text": "All tool groups are currently deactivated.",
                    },
                ],
                "metadata": {},
                "state": "success",
            },
        )

    async def test_broken_mcp_is_skipped_not_fatal(self) -> None:
        """One unreachable MCP must not take the whole reply down with
        it: an expired token or a server that is simply down would
        otherwise end the conversation instead of just withdrawing that
        server's tools."""
        toolkit = Toolkit(
            mcps=[
                MCPClient(
                    name="broken",
                    is_stateful=False,
                    # Nothing listens on port 1; the connection is
                    # refused rather than hanging.
                    mcp_config=HttpMCPConfig(
                        url="http://127.0.0.1:1/mcp",
                        timeout=1.0,
                    ),
                ),
            ],
        )

        self.assertEqual(await toolkit.get_tool_schemas(), [])

    async def test_check_tool_available_distinguishes_inactive_group(
        self,
    ) -> None:
        """A tool in an inactive group raises ToolGroupInactiveError with
        the activation hint (matching call_tool), while an unregistered
        name still raises ToolNotFoundError."""
        toolkit = Toolkit(
            tool_groups=[
                ToolGroup(
                    name="group_1",
                    description="Group 1",
                    tools=[Tool1()],
                ),
            ],
        )

        # Inactive group -> the agent-facing check names the group and
        # the meta tool, instead of claiming the tool doesn't exist.
        with self.assertRaises(ToolGroupInactiveError) as ctx:
            await toolkit.check_tool_available("tool_1", [])
        self.assertIn("group_1", str(ctx.exception))
        self.assertIn(
            toolkit.builtin_meta_tool.tool.name,
            str(ctx.exception),
        )

        # Activated group -> resolves normally.
        tool = await toolkit.check_tool_available("tool_1", ["group_1"])
        self.assertEqual(tool.name, "tool_1")

        # Unregistered name -> still not found.
        with self.assertRaises(ToolNotFoundError):
            await toolkit.check_tool_available("no_such_tool", [])


class RemoveTitleFieldTest(TestCase):
    """Unit tests for _remove_title_field."""

    def setUp(self) -> None:
        from agentscope.tool._utils import _remove_title_field

        self.fn = _remove_title_field

    def test_removes_top_level_title(self) -> None:
        """The top level title field must be removed."""
        schema = {"title": "Root", "type": "object", "properties": {}}
        self.fn(schema)
        self.assertNotIn("title", schema)

    def test_removes_property_titles(self) -> None:
        """Titles inside properties must be removed."""
        schema: dict[str, Any] = {
            "type": "object",
            "properties": {
                "name": {"title": "Name", "type": "string"},
            },
        }
        self.fn(schema)
        self.assertNotIn("title", schema["properties"]["name"])

    def test_removes_defs_titles(self) -> None:
        """Titles inside $defs must be recursively stripped."""
        schema: dict[str, Any] = {
            "type": "object",
            "properties": {"x": {"$ref": "#/$defs/MyModel"}},
            "$defs": {
                "MyModel": {
                    "title": "MyModel",
                    "type": "object",
                    "properties": {
                        "val": {"title": "Val", "type": "string"},
                    },
                },
            },
        }
        self.fn(schema)

        self.assertDictEqual(
            schema,
            {
                "type": "object",
                "properties": {"x": {"$ref": "#/$defs/MyModel"}},
                "$defs": {
                    "MyModel": {
                        "type": "object",
                        "properties": {
                            "val": {"type": "string"},
                        },
                    },
                },
            },
        )

    def test_does_not_mutate_non_dict_defs(self) -> None:
        """Boolean schema values inside $defs should not raise."""
        schema: dict[str, Any] = {
            "type": "object",
            "properties": {},
            "$defs": {"AlwaysTrue": True},
        }
        self.fn(schema)
        self.assertEqual(schema["$defs"]["AlwaysTrue"], True)