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

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

.stats.yml

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

api.md

@@ -25,3 +25,23 @@ Methods:
 
 - <code title="post /v1/messages">client.messages.<a href="./src/resources/messages.ts">create</a>({ ...params }) -> Message</code>
 - <code>client.messages.<a href="./src/resources/messages.ts">stream</a>(body, options?) -> MessageStream</code>
+
+# Beta
+
+## Tools
+
+### Messages
+
+Types:
+
+- <code><a href="./src/resources/beta/tools/messages.ts">Tool</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolResultBlockParam</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolUseBlock</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolUseBlockParam</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolsBetaContentBlock</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolsBetaMessage</a></code>
+- <code><a href="./src/resources/beta/tools/messages.ts">ToolsBetaMessageParam</a></code>
+
+Methods:
+
+- <code title="post /v1/messages?beta=tools">client.beta.tools.messages.<a href="./src/resources/beta/tools/messages.ts">create</a>({ ...params }) -> ToolsBetaMessage</code>

examples/tools.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import Anthropic from '@anthropic-ai/sdk';
+import assert from 'node:assert';
+
+const client = new Anthropic(); // gets API Key from environment variable ANTHROPIC_API_KEY
+
+async function main() {
+  const userMessage: Anthropic.Beta.Tools.ToolsBetaMessageParam = {
+    role: 'user',
+    content: 'What is the weather in SF?',
+  };
+  const tools: Anthropic.Beta.Tools.Tool[] = [
+    {
+      name: 'get_weather',
+      description: 'Get the weather for a specific location',
+      input_schema: {
+        type: 'object',
+        properties: { location: { type: 'string' } },
+      },
+    },
+  ];
+
+  const message = await client.beta.tools.messages.create({
+    model: 'claude-3-opus-20240229',
+    max_tokens: 1024,
+    messages: [userMessage],
+    tools,
+  });
+  console.log('Initial response:');
+  console.dir(message, { depth: 4 });
+
+  assert(message.stop_reason === 'tool_use');
+
+  const tool = message.content.find(
+    (content): content is Anthropic.Beta.Tools.ToolUseBlock => content.type === 'tool_use',
+  );
+  assert(tool);
+
+  const result = await client.beta.tools.messages.create({
+    model: 'claude-3-opus-20240229',
+    max_tokens: 1024,
+    messages: [
+      userMessage,
+      { 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,
+  });
+  console.log('\nFinal response');
+  console.dir(result, { depth: 4 });
+}
+
+main();

src/index.ts

@@ -122,6 +122,7 @@ export class Anthropic extends Core.APIClient {
 
   completions: API.Completions = new API.Completions(this);
   messages: API.Messages = new API.Messages(this);
+  beta: API.Beta = new API.Beta(this);
 
   protected override defaultQuery(): Core.DefaultQuery | undefined {
     return this._options.defaultQuery;
@@ -257,6 +258,8 @@ export namespace Anthropic {
   export import MessageCreateParamsNonStreaming = API.MessageCreateParamsNonStreaming;
   export import MessageCreateParamsStreaming = API.MessageCreateParamsStreaming;
   export import MessageStreamParams = API.MessageStreamParams;
+
+  export import Beta = API.Beta;
 }
 
 export default Anthropic;

src/resources/beta/beta.ts

@@ -0,0 +1,12 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '@anthropic-ai/sdk/resource';
+import * as ToolsAPI from '@anthropic-ai/sdk/resources/beta/tools/tools';
+
+export class Beta extends APIResource {
+  tools: ToolsAPI.Tools = new ToolsAPI.Tools(this._client);
+}
+
+export namespace Beta {
+  export import Tools = ToolsAPI.Tools;
+}

src/resources/beta/index.ts

@@ -0,0 +1,4 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Beta } from './beta';
+export { Tools } from './tools/index';

src/resources/beta/tools/index.ts

@@ -0,0 +1,16 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Tool,
+  ToolResultBlockParam,
+  ToolUseBlock,
+  ToolUseBlockParam,
+  ToolsBetaContentBlock,
+  ToolsBetaMessage,
+  ToolsBetaMessageParam,
+  MessageCreateParams,
+  MessageCreateParamsNonStreaming,
+  MessageCreateParamsStreaming,
+  Messages,
+} from './messages';
+export { Tools } from './tools';