feat(api): tool use beta (#438)

https://docs.anthropic.com/claude/docs/tool-use

.stats.yml

@@ -1 +1 @@
-configured_endpoints: 2
+configured_endpoints: 3

api.md

@@ -27,3 +27,27 @@ Methods:
 
 - <code title="post /v1/messages">client.messages.<a href="./src/anthropic/resources/messages.py">create</a>(\*\*<a href="src/anthropic/types/message_create_params.py">params</a>) -> <a href="./src/anthropic/types/message.py">Message</a></code>
 - <code>client.messages.<a href="./src/anthropic/resources/messages.py">stream</a>(\*args) -> MessageStreamManager[MessageStream] | MessageStreamManager[MessageStreamT]</code>
+
+# Beta
+
+## Tools
+
+### Messages
+
+Types:
+
+```python
+from anthropic.types.beta.tools import (
+    Tool,
+    ToolResultBlockParam,
+    ToolUseBlock,
+    ToolUseBlockParam,
+    ToolsBetaContentBlock,
+    ToolsBetaMessage,
+    ToolsBetaMessageParam,
+)
+```
+
+Methods:
+
+- <code title="post /v1/messages?beta=tools">client.beta.tools.messages.<a href="./src/anthropic/resources/beta/tools/messages.py">create</a>(\*\*<a href="src/anthropic/types/beta/tools/message_create_params.py">params</a>) -> <a href="./src/anthropic/types/beta/tools/tools_beta_message.py">ToolsBetaMessage</a></code>

examples/tools.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from anthropic import Anthropic
+from anthropic.types.beta.tools import ToolParam, ToolsBetaMessageParam
+
+client = Anthropic()
+
+user_message: ToolsBetaMessageParam = {
+    "role": "user",
+    "content": "What is the weather in SF?",
+}
+tools: list[ToolParam] = [
+    {
+        "name": "get_weather",
+        "description": "Get the weather for a specific location",
+        "input_schema": {
+            "type": "object",
+            "properties": {"location": {"type": "string"}},
+        },
+    }
+]
+
+message = client.beta.tools.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[user_message],
+    tools=tools,
+)
+print(f"Initial response: {message.model_dump_json(indent=2)}")
+
+assert message.stop_reason == "tool_use"
+
+tool = next(c for c in message.content if c.type == "tool_use")
+response = client.beta.tools.messages.create(
+    model="claude-3-opus-20240229",
+    max_tokens=1024,
+    messages=[
+        user_message,
+        {"role": message.role, "content": message.content},
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": tool.id,
+                    "content": [{"type": "text", "text": "The weather is 73f"}],
+                }
+            ],
+        },
+    ],
+    tools=tools,
+)
+print(f"\nFinal response: {response.model_dump_json(indent=2)}")

src/anthropic/_client.py

@@ -58,6 +58,7 @@
 class Anthropic(SyncAPIClient):
     completions: resources.Completions
     messages: resources.Messages
+    beta: resources.Beta
     with_raw_response: AnthropicWithRawResponse
     with_streaming_response: AnthropicWithStreamedResponse
 
@@ -134,6 +135,7 @@ def __init__(
 
         self.completions = resources.Completions(self)
         self.messages = resources.Messages(self)
+        self.beta = resources.Beta(self)
         self.with_raw_response = AnthropicWithRawResponse(self)
         self.with_streaming_response = AnthropicWithStreamedResponse(self)
 
@@ -318,6 +320,7 @@ def _make_status_error(
 class AsyncAnthropic(AsyncAPIClient):
     completions: resources.AsyncCompletions
     messages: resources.AsyncMessages
+    beta: resources.AsyncBeta
     with_raw_response: AsyncAnthropicWithRawResponse
     with_streaming_response: AsyncAnthropicWithStreamedResponse
 
@@ -394,6 +397,7 @@ def __init__(
 
         self.completions = resources.AsyncCompletions(self)
         self.messages = resources.AsyncMessages(self)
+        self.beta = resources.AsyncBeta(self)
         self.with_raw_response = AsyncAnthropicWithRawResponse(self)
         self.with_streaming_response = AsyncAnthropicWithStreamedResponse(self)
 
@@ -579,24 +583,28 @@ class AnthropicWithRawResponse:
     def __init__(self, client: Anthropic) -> None:
         self.completions = resources.CompletionsWithRawResponse(client.completions)
         self.messages = resources.MessagesWithRawResponse(client.messages)
+        self.beta = resources.BetaWithRawResponse(client.beta)
 
 
 class AsyncAnthropicWithRawResponse:
     def __init__(self, client: AsyncAnthropic) -> None:
         self.completions = resources.AsyncCompletionsWithRawResponse(client.completions)
         self.messages = resources.AsyncMessagesWithRawResponse(client.messages)
+        self.beta = resources.AsyncBetaWithRawResponse(client.beta)
 
 
 class AnthropicWithStreamedResponse:
     def __init__(self, client: Anthropic) -> None:
         self.completions = resources.CompletionsWithStreamingResponse(client.completions)
         self.messages = resources.MessagesWithStreamingResponse(client.messages)
+        self.beta = resources.BetaWithStreamingResponse(client.beta)
 
 
 class AsyncAnthropicWithStreamedResponse:
     def __init__(self, client: AsyncAnthropic) -> None:
         self.completions = resources.AsyncCompletionsWithStreamingResponse(client.completions)
         self.messages = resources.AsyncMessagesWithStreamingResponse(client.messages)
+        self.beta = resources.AsyncBetaWithStreamingResponse(client.beta)
 
 
 Client = Anthropic

src/anthropic/resources/__init__.py

@@ -1,5 +1,13 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+from .beta import (
+    Beta,
+    AsyncBeta,
+    BetaWithRawResponse,
+    AsyncBetaWithRawResponse,
+    BetaWithStreamingResponse,
+    AsyncBetaWithStreamingResponse,
+)
 from .messages import (
     Messages,
     AsyncMessages,
@@ -30,4 +38,10 @@
     "AsyncMessagesWithRawResponse",
     "MessagesWithStreamingResponse",
     "AsyncMessagesWithStreamingResponse",
+    "Beta",
+    "AsyncBeta",
+    "BetaWithRawResponse",
+    "AsyncBetaWithRawResponse",
+    "BetaWithStreamingResponse",
+    "AsyncBetaWithStreamingResponse",
 ]

src/anthropic/resources/beta/__init__.py

@@ -0,0 +1,33 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from .beta import (
+    Beta,
+    AsyncBeta,
+    BetaWithRawResponse,
+    AsyncBetaWithRawResponse,
+    BetaWithStreamingResponse,
+    AsyncBetaWithStreamingResponse,
+)
+from .tools import (
+    Tools,
+    AsyncTools,
+    ToolsWithRawResponse,
+    AsyncToolsWithRawResponse,
+    ToolsWithStreamingResponse,
+    AsyncToolsWithStreamingResponse,
+)
+
+__all__ = [
+    "Tools",
+    "AsyncTools",
+    "ToolsWithRawResponse",
+    "AsyncToolsWithRawResponse",
+    "ToolsWithStreamingResponse",
+    "AsyncToolsWithStreamingResponse",
+    "Beta",
+    "AsyncBeta",
+    "BetaWithRawResponse",
+    "AsyncBetaWithRawResponse",
+    "BetaWithStreamingResponse",
+    "AsyncBetaWithStreamingResponse",
+]

src/anthropic/resources/beta/beta.py

@@ -0,0 +1,81 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from .tools import (
+    Tools,
+    AsyncTools,
+    ToolsWithRawResponse,
+    AsyncToolsWithRawResponse,
+    ToolsWithStreamingResponse,
+    AsyncToolsWithStreamingResponse,
+)
+from ..._compat import cached_property
+from ..._resource import SyncAPIResource, AsyncAPIResource
+from .tools.tools import Tools, AsyncTools
+
+__all__ = ["Beta", "AsyncBeta"]
+
+
+class Beta(SyncAPIResource):
+    @cached_property
+    def tools(self) -> Tools:
+        return Tools(self._client)
+
+    @cached_property
+    def with_raw_response(self) -> BetaWithRawResponse:
+        return BetaWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> BetaWithStreamingResponse:
+        return BetaWithStreamingResponse(self)
+
+
+class AsyncBeta(AsyncAPIResource):
+    @cached_property
+    def tools(self) -> AsyncTools:
+        return AsyncTools(self._client)
+
+    @cached_property
+    def with_raw_response(self) -> AsyncBetaWithRawResponse:
+        return AsyncBetaWithRawResponse(self)
+
+    @cached_property
+    def with_streaming_response(self) -> AsyncBetaWithStreamingResponse:
+        return AsyncBetaWithStreamingResponse(self)
+
+
+class BetaWithRawResponse:
+    def __init__(self, beta: Beta) -> None:
+        self._beta = beta
+
+    @cached_property
+    def tools(self) -> ToolsWithRawResponse:
+        return ToolsWithRawResponse(self._beta.tools)
+
+
+class AsyncBetaWithRawResponse:
+    def __init__(self, beta: AsyncBeta) -> None:
+        self._beta = beta
+
+    @cached_property
+    def tools(self) -> AsyncToolsWithRawResponse:
+        return AsyncToolsWithRawResponse(self._beta.tools)
+
+
+class BetaWithStreamingResponse:
+    def __init__(self, beta: Beta) -> None:
+        self._beta = beta
+
+    @cached_property
+    def tools(self) -> ToolsWithStreamingResponse:
+        return ToolsWithStreamingResponse(self._beta.tools)
+
+
+class AsyncBetaWithStreamingResponse:
+    def __init__(self, beta: AsyncBeta) -> None:
+        self._beta = beta
+
+    @cached_property
+    def tools(self) -> AsyncToolsWithStreamingResponse:
+        return AsyncToolsWithStreamingResponse(self._beta.tools)

src/anthropic/resources/beta/tools/__init__.py

@@ -0,0 +1,33 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from .tools import (
+    Tools,
+    AsyncTools,
+    ToolsWithRawResponse,
+    AsyncToolsWithRawResponse,
+    ToolsWithStreamingResponse,
+    AsyncToolsWithStreamingResponse,
+)
+from .messages import (
+    Messages,
+    AsyncMessages,
+    MessagesWithRawResponse,
+    AsyncMessagesWithRawResponse,
+    MessagesWithStreamingResponse,
+    AsyncMessagesWithStreamingResponse,
+)
+
+__all__ = [
+    "Messages",
+    "AsyncMessages",
+    "MessagesWithRawResponse",
+    "AsyncMessagesWithRawResponse",
+    "MessagesWithStreamingResponse",
+    "AsyncMessagesWithStreamingResponse",
+    "Tools",
+    "AsyncTools",
+    "ToolsWithRawResponse",
+    "AsyncToolsWithRawResponse",
+    "ToolsWithStreamingResponse",
+    "AsyncToolsWithStreamingResponse",
+]