feat(tool runner): add support for server-side tools (#1086)

Author: karpetrosyan

src/anthropic/lib/tools/_beta_runner.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import logging
+import warnings
 from abc import ABC, abstractmethod
 from typing import (
     TYPE_CHECKING,
@@ -298,6 +299,14 @@ def _generate_tool_call_response(self) -> BetaMessageParam | None:
         for tool_use in tool_use_blocks:
             tool = self._tools_by_name.get(tool_use.name)
             if tool is None:
+                warnings.warn(
+                    f"Tool '{tool_use.name}' not found in tool runner. "
+                    f"Available tools: {list(self._tools_by_name.keys())}. "
+                    f"If using a raw tool definition, handle the tool call manually and use `append_messages()` to add the result. "
+                    f"Otherwise, pass the tool using `beta_tool(func)` or a `@beta_tool` decorated function.",
+                    UserWarning,
+                    stacklevel=3,
+                )
                 results.append(
                     {
                         "type": "tool_result",
@@ -554,6 +563,14 @@ async def _generate_tool_call_response(self) -> BetaMessageParam | None:
         for tool_use in tool_use_blocks:
             tool = self._tools_by_name.get(tool_use.name)
             if tool is None:
+                warnings.warn(
+                    f"Tool '{tool_use.name}' not found in tool runner. "
+                    f"Available tools: {list(self._tools_by_name.keys())}. "
+                    f"If using a raw tool definition, handle the tool call manually and use `append_messages()` to add the result. "
+                    f"Otherwise, pass the tool using `beta_async_tool(func)` or a `@beta_async_tool` decorated function.",
+                    UserWarning,
+                    stacklevel=3,
+                )
                 results.append(
                     {
                         "type": "tool_result",

src/anthropic/resources/beta/messages/messages.py

@@ -48,7 +48,14 @@
 from ....lib._parse._response import ResponseFormatT, parse_response
 from ....lib._parse._transform import transform_schema
 from ....types.beta.beta_message import BetaMessage
-from ....lib.tools._beta_functions import BetaRunnableTool, BetaAsyncRunnableTool
+from ....lib.tools._beta_functions import (
+    BetaFunctionTool,
+    BetaRunnableTool,
+    BetaAsyncFunctionTool,
+    BetaAsyncRunnableTool,
+    BetaBuiltinFunctionTool,
+    BetaAsyncBuiltinFunctionTool,
+)
 from ....types.anthropic_beta_param import AnthropicBetaParam
 from ....types.beta.beta_message_param import BetaMessageParam
 from ....types.beta.beta_metadata_param import BetaMetadataParam
@@ -1175,7 +1182,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaRunnableTool],
+        tools: Iterable[BetaRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         container: Optional[message_create_params.Container] | Omit = omit,
         context_management: Optional[BetaContextManagementConfigParam] | Omit = omit,
@@ -1209,7 +1216,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaRunnableTool],
+        tools: Iterable[BetaRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         stream: Literal[True],
         max_iterations: int | Omit = omit,
@@ -1243,7 +1250,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaRunnableTool],
+        tools: Iterable[BetaRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         stream: bool,
         max_iterations: int | Omit = omit,
@@ -1276,7 +1283,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaRunnableTool],
+        tools: Iterable[BetaRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         max_iterations: int | Omit = omit,
         container: Optional[message_create_params.Container] | Omit = omit,
@@ -1316,6 +1323,15 @@ def tool_runner(
             **(extra_headers or {}),
         }
 
+        runnable_tools: list[BetaRunnableTool] = []
+        raw_tools: list[BetaToolUnionParam] = []
+
+        for tool in tools:
+            if isinstance(tool, (BetaFunctionTool, BetaBuiltinFunctionTool)):
+                runnable_tools.append(tool)
+            else:
+                raw_tools.append(tool)
+
         params = cast(
             message_create_params.ParseMessageCreateParamsBase[ResponseFormatT],
             {
@@ -1334,15 +1350,15 @@ def tool_runner(
                 "temperature": temperature,
                 "thinking": thinking,
                 "tool_choice": tool_choice,
-                "tools": [tool.to_dict() for tool in tools],
+                "tools": [*[tool.to_dict() for tool in runnable_tools], *raw_tools],
                 "top_k": top_k,
                 "top_p": top_p,
             },
         )
 
         if stream:
             return BetaStreamingToolRunner[ResponseFormatT](
-                tools=tools,
+                tools=runnable_tools,
                 params=params,
                 options={
                     "extra_headers": extra_headers,
@@ -1355,7 +1371,7 @@ def tool_runner(
                 compaction_control=compaction_control if is_given(compaction_control) else None,
             )
         return BetaToolRunner[ResponseFormatT](
-            tools=tools,
+            tools=runnable_tools,
             params=params,
             options={
                 "extra_headers": extra_headers,
@@ -2826,7 +2842,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaAsyncRunnableTool],
+        tools: Iterable[BetaAsyncRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         max_iterations: int | Omit = omit,
         container: Optional[message_create_params.Container] | Omit = omit,
@@ -2860,7 +2876,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaAsyncRunnableTool],
+        tools: Iterable[BetaAsyncRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         stream: Literal[True],
         max_iterations: int | Omit = omit,
@@ -2894,7 +2910,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaAsyncRunnableTool],
+        tools: Iterable[BetaAsyncRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         stream: bool,
         max_iterations: int | Omit = omit,
@@ -2927,7 +2943,7 @@ def tool_runner(
         max_tokens: int,
         messages: Iterable[BetaMessageParam],
         model: ModelParam,
-        tools: Iterable[BetaAsyncRunnableTool],
+        tools: Iterable[BetaAsyncRunnableTool | BetaToolUnionParam],
         compaction_control: CompactionControl | Omit = omit,
         max_iterations: int | Omit = omit,
         container: Optional[message_create_params.Container] | Omit = omit,
@@ -2967,6 +2983,15 @@ def tool_runner(
             **(extra_headers or {}),
         }
 
+        runnable_tools: list[BetaAsyncRunnableTool] = []
+        raw_tools: list[BetaToolUnionParam] = []
+
+        for tool in tools:
+            if isinstance(tool, (BetaAsyncFunctionTool, BetaAsyncBuiltinFunctionTool)):
+                runnable_tools.append(tool)
+            else:
+                raw_tools.append(tool)
+
         params = cast(
             message_create_params.ParseMessageCreateParamsBase[ResponseFormatT],
             {
@@ -2985,15 +3010,15 @@ def tool_runner(
                 "temperature": temperature,
                 "thinking": thinking,
                 "tool_choice": tool_choice,
-                "tools": [tool.to_dict() for tool in tools],
+                "tools": [*[tool.to_dict() for tool in runnable_tools], *raw_tools],
                 "top_k": top_k,
                 "top_p": top_p,
             },
         )
 
         if stream:
             return BetaAsyncStreamingToolRunner[ResponseFormatT](
-                tools=tools,
+                tools=runnable_tools,
                 params=params,
                 options={
                     "extra_headers": extra_headers,
@@ -3006,7 +3031,7 @@ def tool_runner(
                 compaction_control=compaction_control if is_given(compaction_control) else None,
             )
         return BetaAsyncToolRunner[ResponseFormatT](
-            tools=tools,
+            tools=runnable_tools,
             params=params,
             options={
                 "extra_headers": extra_headers,