minimal-harness 0.1.0__tar.gz

minimal_harness-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.3
+Name: minimal-harness
+Version: 0.1.0
+Summary: Add your description here
+Author: J0ey1iu
+Author-email: J0ey1iu <549323981@qq.com>
+Requires-Dist: openai
+Requires-Dist: textual ; extra == 'demo'
+Requires-Dist: pytest>=9.0.2 ; extra == 'test'
+Requires-Dist: pytest-asyncio>=1.3.0 ; extra == 'test'
+Requires-Python: >=3.12
+Provides-Extra: demo
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# minimal-harness
+
+A lightweight Python agent harness with tool-calling support.
+
+## Features
+
+- Simple `Agent` class for building LLM-powered agents
+- Tool-calling support with concurrent execution
+- Streaming response support via chunk callbacks
+- Conversation history management with `Memory` interface
+- Built on OpenAI's API (supports any OpenAI-compatible endpoint)
+- Extensible LLM provider interface
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from minimal_harness import Agent, Tool, OpenAILLMProvider
+from openai import AsyncOpenAI
+
+async def get_weather(city: str) -> dict:
+    return {"city": city, "temperature": "22°C", "condition": "Sunny"}
+
+tools = [
+    Tool(
+        name="get_weather",
+        description="Get weather for a specified city",
+        parameters={
+            "type": "object",
+            "properties": {"city": {"type": "string", "description": "City name"}},
+            "required": ["city"],
+        },
+        fn=get_weather,
+    ),
+]
+
+client = AsyncOpenAI(api_key="your-api-key", base_url="https://aihubmix.com/v1")
+llm_provider = OpenAILLMProvider(client=client, model="minimax-m2.7")
+agent = Agent(llm_provider=llm_provider, tools=tools)
+
+async def on_chunk(chunk, is_done):
+    if is_done:
+        print()
+        return
+    delta = chunk.choices[0].delta if chunk.choices else None
+    if delta and delta.content:
+        print(delta.content, end="", flush=True)
+
+result = await agent.run("What's the weather in Beijing?", on_chunk=on_chunk)
+print(result)
+```
+
+## Agent
+
+The `Agent` class manages conversation context and tool execution.
+
+### Constructor
+
+```python
+Agent(
+    llm_provider: LLMProvider,
+    tools: list[Tool] | None = None,
+    max_iterations: int = 10,
+    memory: Memory | None = None,
+    tool_executor: ToolExecutor | None = None,
+)
+```
+
+### Methods
+
+- `run(user_input: str, on_chunk: ChunkCallback | None = None) -> str` - Run the agent with user input
+
+## LLMProvider
+
+The `LLMProvider` is a protocol that defines the interface for LLM backends. The library includes `OpenAILLMProvider` for OpenAI-compatible endpoints.
+
+### OpenAILLMProvider
+
+```python
+OpenAILLMProvider(client: AsyncOpenAI, model: str = "qwen3.5-27b")
+```
+
+## Memory
+
+Memory classes manage conversation history.
+
+### ConversationMemory
+
+```python
+ConversationMemory(system_prompt: str = "You are a helpful assistant.")
+```
+
+## Tool
+
+Define tools that the agent can call.
+
+```python
+Tool(
+    name: str,
+    description: str,
+    parameters: dict,  # OpenAI function parameters schema
+    fn: Callable[..., Awaitable[Any]],  # Async function implementation
+)
+```
+
+## ToolExecutor
+
+Executes tool calls concurrently and returns results as messages.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```

minimal_harness-0.1.0/README.md

@@ -0,0 +1,121 @@
+# minimal-harness
+
+A lightweight Python agent harness with tool-calling support.
+
+## Features
+
+- Simple `Agent` class for building LLM-powered agents
+- Tool-calling support with concurrent execution
+- Streaming response support via chunk callbacks
+- Conversation history management with `Memory` interface
+- Built on OpenAI's API (supports any OpenAI-compatible endpoint)
+- Extensible LLM provider interface
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import asyncio
+from minimal_harness import Agent, Tool, OpenAILLMProvider
+from openai import AsyncOpenAI
+
+async def get_weather(city: str) -> dict:
+    return {"city": city, "temperature": "22°C", "condition": "Sunny"}
+
+tools = [
+    Tool(
+        name="get_weather",
+        description="Get weather for a specified city",
+        parameters={
+            "type": "object",
+            "properties": {"city": {"type": "string", "description": "City name"}},
+            "required": ["city"],
+        },
+        fn=get_weather,
+    ),
+]
+
+client = AsyncOpenAI(api_key="your-api-key", base_url="https://aihubmix.com/v1")
+llm_provider = OpenAILLMProvider(client=client, model="minimax-m2.7")
+agent = Agent(llm_provider=llm_provider, tools=tools)
+
+async def on_chunk(chunk, is_done):
+    if is_done:
+        print()
+        return
+    delta = chunk.choices[0].delta if chunk.choices else None
+    if delta and delta.content:
+        print(delta.content, end="", flush=True)
+
+result = await agent.run("What's the weather in Beijing?", on_chunk=on_chunk)
+print(result)
+```
+
+## Agent
+
+The `Agent` class manages conversation context and tool execution.
+
+### Constructor
+
+```python
+Agent(
+    llm_provider: LLMProvider,
+    tools: list[Tool] | None = None,
+    max_iterations: int = 10,
+    memory: Memory | None = None,
+    tool_executor: ToolExecutor | None = None,
+)
+```
+
+### Methods
+
+- `run(user_input: str, on_chunk: ChunkCallback | None = None) -> str` - Run the agent with user input
+
+## LLMProvider
+
+The `LLMProvider` is a protocol that defines the interface for LLM backends. The library includes `OpenAILLMProvider` for OpenAI-compatible endpoints.
+
+### OpenAILLMProvider
+
+```python
+OpenAILLMProvider(client: AsyncOpenAI, model: str = "qwen3.5-27b")
+```
+
+## Memory
+
+Memory classes manage conversation history.
+
+### ConversationMemory
+
+```python
+ConversationMemory(system_prompt: str = "You are a helpful assistant.")
+```
+
+## Tool
+
+Define tools that the agent can call.
+
+```python
+Tool(
+    name: str,
+    description: str,
+    parameters: dict,  # OpenAI function parameters schema
+    fn: Callable[..., Awaitable[Any]],  # Async function implementation
+)
+```
+
+## ToolExecutor
+
+Executes tool calls concurrently and returns results as messages.
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+pytest
+```

minimal_harness-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "minimal-harness"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "J0ey1iu", email = "549323981@qq.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "openai"
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+]
+demo = [
+    "textual",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.12,<0.11.0"]
+build-backend = "uv_build"

minimal_harness-0.1.0/src/minimal_harness/__init__.py

@@ -0,0 +1,24 @@
+from .agent import OpenAIAgent
+from .llm import LLMProvider, LLMResponse, OpenAILLMProvider, Stream
+from .memory import (
+    InputContentPart,
+    Memory,
+    ConversationMemory,
+    TextContentPart,
+)
+from .tool import Tool
+from .tool_executor import ToolExecutor
+
+__ALL__ = [
+    OpenAIAgent,
+    LLMProvider,
+    LLMResponse,
+    Stream,
+    Memory,
+    ConversationMemory,
+    OpenAILLMProvider,
+    Tool,
+    ToolExecutor,
+    InputContentPart,
+    TextContentPart,
+]

minimal_harness-0.1.0/src/minimal_harness/agent.py

@@ -0,0 +1,100 @@
+from typing import Awaitable, Callable, Iterable, Protocol, cast
+
+from openai.types.chat import ChatCompletionChunk
+
+from minimal_harness.llm import ChunkCallback, ToolResultCallback
+from minimal_harness.llm.openai import OpenAILLMProvider
+from minimal_harness.memory import (
+    ExtendedInputContentPart,
+    InputContentPart,
+    ConversationMemory,
+    Memory,
+    Message,
+    UserMessage,
+)
+from minimal_harness.tool import Tool
+from minimal_harness.tool_executor import ToolExecutor
+
+
+InputContentConversionFunction = Callable[
+    [Iterable[ExtendedInputContentPart]], Awaitable[Iterable[InputContentPart]]
+]
+
+
+class Agent(Protocol):
+    async def run(
+        self,
+        user_input: Iterable[InputContentPart],
+        on_chunk: ChunkCallback | None = None,
+        on_tool_result: ToolResultCallback | None = None,
+    ) -> str: ...
+
+
+class OpenAIAgent:
+    def __init__(
+        self,
+        llm_provider: OpenAILLMProvider,
+        tools: list[Tool] | None = None,
+        max_iterations: int = 10,
+        memory: Memory | None = None,
+        tool_executor: ToolExecutor | None = None,
+        on_tool_result: ToolResultCallback | None = None,
+    ):
+        self._llm_provider = llm_provider
+        self._tools: dict[str, Tool] = {t.name: t for t in (tools or [])}
+        self._tool_executor = tool_executor or ToolExecutor(self._tools, on_tool_result)
+        self._max_iterations = max_iterations
+        self._memory = memory or ConversationMemory()
+
+    async def run(
+        self,
+        user_input: Iterable[ExtendedInputContentPart],
+        custom_input_conversion: InputContentConversionFunction | None = None,
+        on_chunk: ChunkCallback[ChatCompletionChunk] | None = None,
+        on_tool_result: ToolResultCallback | None = None,
+    ) -> str:
+        if on_tool_result:
+            self._tool_executor._on_tool_result = on_tool_result
+
+        converted_user_input = user_input
+        if custom_input_conversion:
+            converted_user_input = await custom_input_conversion(converted_user_input)
+        self._memory.add_message(
+            cast(UserMessage, {"role": "user", "content": converted_user_input})
+        )
+
+        for _ in range(self._max_iterations):
+            response = await self._llm_provider.chat(
+                messages=self._memory.get_all_messages(),
+                tools=list(self._tools.values()),
+                on_chunk=on_chunk,
+            )
+
+            async for _ in response:
+                pass
+
+            llm_response = response.response
+            self._memory.add_message(
+                cast(
+                    Message,
+                    {
+                        "role": "assistant",
+                        "content": llm_response.content,
+                        "tool_calls": llm_response.tool_calls or None,
+                    },
+                )
+            )
+
+            if llm_response.usage:
+                self._memory.add_usage(llm_response.usage)
+
+            if not llm_response.tool_calls:
+                return str(llm_response.content) or ""
+
+            results = await self._tool_executor.execute(llm_response.tool_calls)
+            for msg in results:
+                self._memory.add_message(msg)
+
+        raise RuntimeError(
+            f"Agent exceeded maximum iterations ({self._max_iterations})"
+        )

minimal_harness-0.1.0/src/minimal_harness/llm/__init__.py

@@ -0,0 +1,23 @@
+from .llm import (
+    ChunkCallback,
+    LLMProvider,
+    LLMResponse,
+    Stream,
+    TokenUsage,
+    ToolCall,
+    ToolCallFunction,
+    ToolResultCallback,
+)
+from .openai import OpenAILLMProvider
+
+__ALL__ = [
+    ChunkCallback,
+    LLMProvider,
+    LLMResponse,
+    Stream,
+    TokenUsage,
+    ToolCall,
+    ToolCallFunction,
+    ToolResultCallback,
+    OpenAILLMProvider,
+]

minimal_harness-0.1.0/src/minimal_harness/llm/llm.py

@@ -0,0 +1,85 @@
+from typing import Protocol, AsyncIterator, Any, Callable, Awaitable, TypeVar, TypedDict
+
+from minimal_harness.memory import Message
+from minimal_harness.tool import Tool
+
+
+T = TypeVar("T")
+
+ChunkCallback = Callable[[T, bool], Awaitable[None]]
+
+
+class ToolCallFunction(TypedDict):
+    name: str
+    arguments: str
+
+
+class ToolCall(TypedDict):
+    id: str
+    type: str
+    function: ToolCallFunction
+
+
+ToolResultCallback = Callable[[ToolCall, Any], Awaitable[None]]
+
+
+class TokenUsage(TypedDict):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class LLMResponse:
+    content: str | None
+    tool_calls: list[ToolCall]
+    finish_reason: str | None
+    usage: TokenUsage | None
+
+    def __init__(
+        self,
+        content: str | None,
+        tool_calls: list[ToolCall],
+        finish_reason: str | None,
+        usage: TokenUsage | None = None,
+    ):
+        self.content = content
+        self.tool_calls = tool_calls
+        self.finish_reason = finish_reason
+        self.usage = usage
+
+
+class Stream[T]:
+    def __init__(self, agen: AsyncIterator[T]):
+        self._agen = agen
+        self._response: LLMResponse | None = None
+
+    def __aiter__(self) -> AsyncIterator:
+        return self
+
+    async def __anext__(self) -> Any:
+        try:
+            chunk = await self._agen.__anext__()
+
+            if isinstance(chunk, LLMResponse):
+                self._response = chunk
+                raise StopAsyncIteration
+
+            return chunk
+
+        except StopAsyncIteration:
+            raise
+
+    @property
+    def response(self) -> LLMResponse:
+        if self._response is None:
+            raise RuntimeError("Stream not exhausted yet")
+        return self._response
+
+
+class LLMProvider(Protocol):
+    async def chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool],
+        on_chunk: ChunkCallback | None,
+    ) -> Stream: ...

minimal_harness-0.1.0/src/minimal_harness/llm/openai.py

@@ -0,0 +1,102 @@
+from typing import AsyncIterator
+
+from openai import AsyncOpenAI
+from openai.types.chat import ChatCompletionChunk
+
+from minimal_harness.llm import (
+    ChunkCallback,
+    LLMResponse,
+    Stream,
+    TokenUsage,
+    ToolCall,
+    ToolCallFunction,
+)
+from minimal_harness.memory import Message
+from minimal_harness.tool import Tool
+
+
+class OpenAILLMProvider:
+    def __init__(self, client: AsyncOpenAI, model: str = "qwen3.5-27b"):
+        self._client = client
+        self._model = model
+
+    async def chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool],
+        on_chunk: ChunkCallback | None,
+    ) -> Stream[ChatCompletionChunk | LLMResponse]:
+        agen = self._chat(messages, tools, on_chunk)
+        return Stream(agen)
+
+    async def _chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool],
+        on_chunk: ChunkCallback | None,
+    ) -> AsyncIterator[ChatCompletionChunk | LLMResponse]:
+        stream = await self._client.chat.completions.create(
+            model=self._model,
+            messages=messages,  # type: ignore[arg-type]
+            tools=[t.to_schema() for t in tools],
+            tool_choice="auto" if tools else "none",
+            stream=True,
+        )
+
+        content_parts = []
+        tool_calls_acc: dict[int, ToolCall] = {}
+        finish_reason = None
+        usage: TokenUsage | None = None
+
+        async for chunk in stream:
+            if on_chunk:
+                await on_chunk(chunk, False)
+
+            delta = chunk.choices[0].delta if chunk.choices else None
+
+            # there should only be one single chunk with usage in a request
+            if getattr(chunk, "usage") and chunk.usage:
+                usage = {
+                    "prompt_tokens": chunk.usage.prompt_tokens,
+                    "completion_tokens": chunk.usage.completion_tokens,
+                    "total_tokens": chunk.usage.total_tokens,
+                }
+
+            if delta is None:
+                continue
+
+            if delta.content:
+                content_parts.append(delta.content)
+
+            if delta.tool_calls:
+                for tc_delta in delta.tool_calls:
+                    idx = tc_delta.index
+                    if idx not in tool_calls_acc:
+                        tool_calls_acc[idx] = ToolCall(
+                            id="",
+                            type="function",
+                            function=ToolCallFunction(name="", arguments=""),
+                        )
+                    acc = tool_calls_acc[idx]
+                    if tc_delta.id:
+                        acc["id"] += tc_delta.id
+                    if tc_delta.function:
+                        if tc_delta.function.name:
+                            acc["function"]["name"] += tc_delta.function.name
+                        if tc_delta.function.arguments:
+                            acc["function"]["arguments"] += tc_delta.function.arguments
+
+            if chunk.choices and chunk.choices[0].finish_reason:
+                finish_reason = chunk.choices[0].finish_reason
+
+            yield chunk
+
+        if on_chunk:
+            await on_chunk(None, True)
+
+        yield LLMResponse(
+            content="".join(content_parts) or None,
+            tool_calls=list(tool_calls_acc.values()) if tool_calls_acc else [],
+            finish_reason=finish_reason,
+            usage=usage,
+        )

minimal_harness-0.1.0/src/minimal_harness/memory.py

@@ -0,0 +1,88 @@
+from typing import Protocol, TypedDict, Literal, Any
+
+
+class TextContentPart(TypedDict):
+    type: Literal["text"]
+    text: str
+
+
+class FileMetadata(TypedDict):
+    file_id: str
+    file_name: str
+    file_size: int
+    backend_type: str
+
+
+class FileContentPart(TypedDict):
+    type: Literal["file"]
+    file: FileMetadata
+
+
+InputContentPart = TextContentPart
+ExtendedInputContentPart = FileContentPart | TextContentPart
+
+
+class SystemMessage(TypedDict):
+    role: Literal["system"]
+    content: str
+
+
+class UserMessage(TypedDict):
+    role: Literal["user"]
+    content: list[InputContentPart]
+
+
+class AssistantMessage(TypedDict):
+    role: Literal["assistant"]
+    content: str | None
+    tool_calls: list[Any] | None
+
+
+class ToolMessage(TypedDict):
+    role: Literal["tool"]
+    tool_call_id: str
+    content: str
+
+
+Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage
+
+
+class TokenUsage(TypedDict):
+    prompt_tokens: int
+    completion_tokens: int
+    total_tokens: int
+
+
+class Memory(Protocol):
+    def add_message(self, message: Message) -> None: ...
+    def get_all_messages(self) -> list[Message]: ...
+    def clear_messages(self) -> None: ...
+    def add_usage(self, usage: TokenUsage) -> None: ...
+    def get_total_usage(self) -> TokenUsage: ...
+
+
+class ConversationMemory:
+    def __init__(self, system_prompt: str = "You are a helpful assistant."):
+        self._messages: list[Message] = [{"role": "system", "content": system_prompt}]
+        self._total_usage: TokenUsage = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        }
+
+    def add_message(self, message: Message) -> None:
+        self._messages.append(message)
+
+    def get_all_messages(self) -> list[Message]:
+        return self._messages.copy()
+
+    def clear_messages(self) -> None:
+        self._messages.clear()
+
+    def add_usage(self, usage: TokenUsage) -> None:
+        self._total_usage["prompt_tokens"] += usage["prompt_tokens"]
+        self._total_usage["completion_tokens"] += usage["completion_tokens"]
+        self._total_usage["total_tokens"] += usage["total_tokens"]
+
+    def get_total_usage(self) -> TokenUsage:
+        return self._total_usage.copy()

minimal_harness-0.1.0/src/minimal_harness/tool/__init__.py

@@ -0,0 +1,3 @@
+from minimal_harness.tool.base import Tool, ToolFunction
+
+__all__ = ["Tool", "ToolFunction"]

minimal_harness-0.1.0/src/minimal_harness/tool/base.py

@@ -0,0 +1,22 @@
+from openai.types.chat import ChatCompletionToolUnionParam
+from typing import Any, Callable, Awaitable
+
+ToolFunction = Callable[..., Awaitable[Any]]
+
+
+class Tool:
+    def __init__(self, name: str, description: str, parameters: dict, fn: ToolFunction):
+        self.name = name
+        self.description = description
+        self.parameters = parameters
+        self.fn = fn
+
+    def to_schema(self) -> ChatCompletionToolUnionParam:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }

minimal_harness-0.1.0/src/minimal_harness/tool/glob.py

@@ -0,0 +1,39 @@
+import fnmatch
+
+from minimal_harness.tool.base import Tool
+
+
+async def glob_handler(path: str = ".", pattern: str = "*") -> list[str]:
+    import os
+
+    matched = []
+    for root, dirs, files in os.walk(path):
+        for name in files:
+            if fnmatch.fnmatch(name, pattern):
+                matched.append(os.path.join(root, name))
+    return matched
+
+
+glob_tool = Tool(
+    name="glob",
+    description="Fast file pattern matching tool that works with any codebase size. Use this to find files by name patterns.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "The directory to search in. Defaults to the current working directory.",
+            },
+            "pattern": {
+                "type": "string",
+                "description": "The glob pattern to match files against (e.g., '*.js', 'src/**/*.ts').",
+            },
+        },
+        "required": ["pattern"],
+    },
+    fn=glob_handler,
+)
+
+
+def get_tools() -> dict[str, Tool]:
+    return {"glob": glob_tool}

minimal_harness-0.1.0/src/minimal_harness/tool/grep.py

@@ -0,0 +1,72 @@
+import fnmatch
+import re
+
+from minimal_harness.tool.base import Tool
+
+
+async def grep_handler(
+    pattern: str,
+    include: str | None = None,
+    path: str | None = None,
+) -> list[dict]:
+    import os
+
+    results = []
+    target_path = path or "."
+
+    if include:
+        include_patterns = [p.strip() for p in include.split(",")]
+    else:
+        include_patterns = None
+
+    for root, dirs, files in os.walk(target_path):
+        for filename in files:
+            if include_patterns:
+                if not any(fnmatch.fnmatch(filename, p) for p in include_patterns):
+                    continue
+
+            filepath = os.path.join(root, filename)
+            try:
+                with open(filepath, "r", encoding="utf-8", errors="ignore") as f:
+                    for line_num, line in enumerate(f, 1):
+                        if re.search(pattern, line):
+                            results.append(
+                                {
+                                    "file": filepath,
+                                    "line": line_num,
+                                    "content": line.rstrip(),
+                                }
+                            )
+            except (UnicodeDecodeError, IOError):
+                continue
+
+    return results
+
+
+grep_tool = Tool(
+    name="grep",
+    description="Fast content search tool that works with any codebase size. Searches file contents using regular expressions.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": "The regex pattern to search for in file contents",
+            },
+            "include": {
+                "type": "string",
+                "description": "File pattern to include in the search (e.g., '*.js', '*.{ts,tsx}')",
+            },
+            "path": {
+                "type": "string",
+                "description": "The directory to search in. Defaults to the current working directory.",
+            },
+        },
+        "required": ["pattern"],
+    },
+    fn=grep_handler,
+)
+
+
+def get_tools() -> dict[str, Tool]:
+    return {"grep": grep_tool}

minimal_harness-0.1.0/src/minimal_harness/tool_executor.py

@@ -0,0 +1,54 @@
+import json
+import asyncio
+from typing import Any
+
+from minimal_harness.llm import ToolCall, ToolResultCallback
+from minimal_harness.memory import Message
+from minimal_harness.tool import Tool
+
+
+class ToolExecutor:
+    def __init__(
+        self, tools: dict[str, Tool], on_tool_result: ToolResultCallback | None = None
+    ):
+        self._tools = tools
+        self._on_tool_result = on_tool_result
+
+    async def execute(self, tool_calls: list[ToolCall]) -> list[Message]:
+        tasks = [self._execute_single(tc) for tc in tool_calls]
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+
+        messages: list[Message] = []
+        for tc, result in zip(tool_calls, results):
+            if self._on_tool_result:
+                await self._on_tool_result(tc, result)
+
+            if isinstance(result, Exception):
+                content = f"[Tool Error] {tc['function']['name']}: {result}"
+            else:
+                content = (
+                    json.dumps(result, ensure_ascii=False)
+                    if not isinstance(result, str)
+                    else result
+                )
+
+            messages.append(
+                {
+                    "role": "tool",
+                    "tool_call_id": tc["id"],
+                    "content": content,
+                }
+            )
+
+        return messages
+
+    async def _execute_single(self, tc: ToolCall) -> Any:
+        name = tc["function"]["name"]
+        raw_args = tc["function"]["arguments"]
+
+        if name not in self._tools:
+            raise ValueError(f"Unknown tool: {name}")
+
+        args = json.loads(raw_args) if raw_args else {}
+        print(f"[Tool Call] {name}({args})")
+        return await self._tools[name].fn(**args)