feat(api): add claude 4 models, files API, code execution tool, MCP connector and more

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
-configured_endpoints: 21
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-087f1149681ef9bc1074184df28ed4b4b9cc37b86cba50eb18e6c18452864446.yml
-openapi_spec_hash: 2007ff815a3f39af8cebe1976d50f17d
-config_hash: 7b88da171a1b1bdb963ec2311e417cbe
+configured_endpoints: 26
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/anthropic%2Fanthropic-1fdf23e8226430012c21819427e8d1ed16c08c0fb2d4abf69b8e318a42e99552.yml
+openapi_spec_hash: 836bbb4ab7c33c37456d1842876d7aba
+config_hash: 7b17fe2f10f5942177ff51b0a13506fa

MIGRATION.md

@@ -77,6 +77,10 @@ This affects the following methods:
 - `client.beta.messages.batches.delete()`
 - `client.beta.messages.batches.cancel()`
 - `client.beta.messages.batches.results()`
+- `client.beta.files.list()`
+- `client.beta.files.delete()`
+- `client.beta.files.download()`
+- `client.beta.files.retrieveMetadata()`
 
 ### Removed `httpAgent` in favor of `fetchOptions`
 

README.md

@@ -184,6 +184,51 @@ This SDK provides support for tool use, aka function calling. More details can b
 
 We provide support for the [Anthropic Bedrock API](https://aws.amazon.com/bedrock/claude/) through a [separate package](https://github.com/anthropics/anthropic-sdk-typescript/tree/main/packages/bedrock-sdk).
 
+## File uploads
+
+Request parameters that correspond to file uploads can be passed in many different forms:
+
+- `File` (or an object with the same structure)
+- a `fetch` `Response` (or an object with the same structure)
+- an `fs.ReadStream`
+- the return value of our `toFile` helper
+
+Note that we recommend you set the content-type explicitly as the files API will not infer it for you:
+
+```ts
+import fs from 'fs';
+import Anthropic, { toFile } from '@anthropic-ai/sdk';
+
+const client = new Anthropic();
+
+// If you have access to Node `fs` we recommend using `fs.createReadStream()`:
+await client.beta.files.upload({
+  file: await toFile(fs.createReadStream('/path/to/file'), undefined, { type: 'application/json' }),
+  betas: ['files-api-2025-04-14'],
+});
+
+// Or if you have the web `File` API you can pass a `File` instance:
+await client.beta.files.upload({
+  file: new File(['my bytes'], 'file.txt', { type: 'text/plain' }),
+  betas: ['files-api-2025-04-14'],
+});
+// You can also pass a `fetch` `Response`:
+await client.beta.files.upload({
+  file: await fetch('https://somesite/file'),
+  betas: ['files-api-2025-04-14'],
+});
+
+// Or a `Buffer` / `Uint8Array`
+await client.beta.files.upload({
+  file: await toFile(Buffer.from('my bytes'), 'file', { type: 'text/plain' }),
+  betas: ['files-api-2025-04-14'],
+});
+await client.beta.files.upload({
+  file: await toFile(new Uint8Array([0, 1, 2]), 'file', { type: 'text/plain' }),
+  betas: ['files-api-2025-04-14'],
+});
+```
+
 ## Handling errors
 
 When the library is unable to connect to the API,
@@ -309,8 +354,9 @@ Passing `stream: true` or [overriding](#timeouts) the `timeout` option at the cl
 An expected request latency longer than the [timeout](#timeouts) for a non-streaming request
 will result in the client terminating the connection and retrying without receiving a response.
 
-When supported by the `fetch` implementation, we set a [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html)
-option in order to reduce the impact of idle connection timeouts on some networks.
+When supported by the `fetch` implementation, we set a [TCP socket keep-alive](https://tldp.org/HOWTO/TCP-Keepalive-HOWTO/overview.html) option in order
+to reduce the impact of idle connection timeouts on some networks.
+This can be [overriden](#configuring-an-https-agent-eg-for-proxies) by configuring a custom proxy.
 
 ## Auto-pagination
 

api.md

@@ -185,6 +185,7 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaBase64PDFBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaBase64PDFSource</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCacheControlEphemeral</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCacheCreation</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationCharLocation</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationCharLocationParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationContentBlockLocation</a></code>
@@ -195,12 +196,32 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationsConfigParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationsDelta</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaCitationsWebSearchResultLocation</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionOutputBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionOutputBlockParam</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionResultBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionResultBlockParam</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionTool20250522</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultBlockContent</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultBlockParam</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultBlockParamContent</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultError</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultErrorCode</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaCodeExecutionToolResultErrorParam</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaContainer</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaContainerUploadBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaContainerUploadBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaContentBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaContentBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaContentBlockSource</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaContentBlockSourceContent</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaFileDocumentSource</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaFileImageSource</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaImageBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaInputJSONDelta</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolResultBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolUseBlock</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaMCPToolUseBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMessage</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMessageDeltaUsage</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaMessageParam</a></code>
@@ -217,6 +238,9 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaRawMessageStreamEvent</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaRedactedThinkingBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaRedactedThinkingBlockParam</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaRequestMCPServerToolConfiguration</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaRequestMCPServerURLDefinition</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaRequestMCPToolResultBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaServerToolUsage</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaServerToolUseBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaServerToolUseBlockParam</a></code>
@@ -246,6 +270,7 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolResultBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolTextEditor20241022</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolTextEditor20250124</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaToolTextEditor20250429</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolUnion</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolUseBlock</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaToolUseBlockParam</a></code>
@@ -261,6 +286,7 @@ Types:
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaWebSearchToolResultBlockParam</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaWebSearchToolResultBlockParamContent</a></code>
 - <code><a href="./src/resources/beta/messages/messages.ts">BetaWebSearchToolResultError</a></code>
+- <code><a href="./src/resources/beta/messages/messages.ts">BetaWebSearchToolResultErrorCode</a></code>
 
 Methods:
 
@@ -289,3 +315,18 @@ Methods:
 - <code title="delete /v1/messages/batches/{message_batch_id}?beta=true">client.beta.messages.batches.<a href="./src/resources/beta/messages/batches.ts">delete</a>(messageBatchID, { ...params }) -> BetaDeletedMessageBatch</code>
 - <code title="post /v1/messages/batches/{message_batch_id}/cancel?beta=true">client.beta.messages.batches.<a href="./src/resources/beta/messages/batches.ts">cancel</a>(messageBatchID, { ...params }) -> BetaMessageBatch</code>
 - <code title="get /v1/messages/batches/{message_batch_id}/results?beta=true">client.beta.messages.batches.<a href="./src/resources/beta/messages/batches.ts">results</a>(messageBatchID, { ...params }) -> BetaMessageBatchIndividualResponse</code>
+
+## Files
+
+Types:
+
+- <code><a href="./src/resources/beta/files.ts">DeletedFile</a></code>
+- <code><a href="./src/resources/beta/files.ts">FileMetadata</a></code>
+
+Methods:
+
+- <code title="get /v1/files?beta=true">client.beta.files.<a href="./src/resources/beta/files.ts">list</a>({ ...params }) -> FileMetadataPage</code>
+- <code title="delete /v1/files/{file_id}?beta=true">client.beta.files.<a href="./src/resources/beta/files.ts">delete</a>(fileID, { ...params }) -> DeletedFile</code>
+- <code title="get /v1/files/{file_id}/content?beta=true">client.beta.files.<a href="./src/resources/beta/files.ts">download</a>(fileID, { ...params }) -> Response</code>
+- <code title="get /v1/files/{file_id}?beta=true">client.beta.files.<a href="./src/resources/beta/files.ts">retrieveMetadata</a>(fileID, { ...params }) -> FileMetadata</code>
+- <code title="post /v1/files?beta=true">client.beta.files.<a href="./src/resources/beta/files.ts">upload</a>({ ...params }) -> FileMetadata</code>

examples/mcp.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env -S npm run tsn -T
+
+import Anthropic from '@anthropic-ai/sdk';
+
+const anthropic = new Anthropic(); // gets API Key from environment variable ANTHROPIC_API_KEY
+
+const main = async () => {
+  const stream = anthropic.beta.messages.stream(
+    {
+      model: 'claude-3-7-sonnet-20250219',
+      max_tokens: 1000,
+      mcp_servers: [
+        {
+          type: 'url',
+          url: 'http://example-server.modelcontextprotocol.io/sse',
+          name: 'example',
+          tool_configuration: {
+            // Optional, defaults to allowing all tools
+            enabled: true, // Optional
+            allowed_tools: ['echo', 'add'], // Optional
+          },
+        },
+      ],
+      messages: [
+        {
+          role: 'user',
+          content: 'Calculate 1+2',
+        },
+      ],
+    },
+    {
+      headers: {
+        'anthropic-beta': 'mcp-client-2025-04-04',
+      },
+    },
+  );
+  for await (const event of stream) {
+    if (event.type === 'content_block_delta' && event.delta.type === 'text_delta') {
+      process.stdout.write(event.delta.text);
+    }
+  }
+  process.stdout.write('\n');
+};
+main();

src/client.ts

@@ -769,6 +769,20 @@ export class BaseAnthropic {
     return sleepSeconds * jitter * 1000;
   }
 
+  public calculateNonstreamingTimeout(maxTokens: number, maxNonstreamingTokens?: number): number {
+    const maxTime = 60 * 60 * 1000; // 10 minutes
+    const defaultTime = 60 * 10 * 1000; // 10 minutes
+
+    const expectedTime = (maxTime * maxTokens) / 128000;
+    if (expectedTime > defaultTime || (maxNonstreamingTokens != null && maxTokens > maxNonstreamingTokens)) {
+      throw new Errors.AnthropicError(
+        'Streaming is strongly recommended for operations that may token longer than 10 minutes. See https://github.com/anthropics/anthropic-sdk-typescript#long-requests for more details',
+      );
+    }
+
+    return defaultTime;
+  }
+
   buildRequest(
     inputOptions: FinalRequestOptions,
     { retryCount = 0 }: { retryCount?: number } = {},

src/internal/constants.ts

@@ -0,0 +1,12 @@
+// File containing shared constants
+
+/**
+ * Model-specific timeout constraints for non-streaming requests
+ */
+export const MODEL_NONSTREAMING_TOKENS: Record<string, number> = {
+  'claude-opus-4-20250514': 8192,
+  'claude-opus-4-0': 8192,
+  'claude-4-opus-20250514': 8192,
+  'anthropic.claude-opus-4-20250514-v1:0': 8192,
+  'claude-opus-4@20250514': 8192,
+};

src/internal/to-file.ts

@@ -90,12 +90,19 @@ export async function toFile(
   // If it's a promise, resolve it.
   value = await value;
 
-  // If we've been given a `File` we don't need to do anything
+  name ||= getName(value);
+
+  // If we've been given a `File` we don't need to do anything if the name / options
+  // have not been customised.
   if (isFileLike(value)) {
-    if (value instanceof File) {
+    if (value instanceof File && name == null && options == null) {
       return value;
     }
-    return makeFile([await value.arrayBuffer()], value.name);
+    return makeFile([await value.arrayBuffer()], name ?? value.name, {
+      type: value.type,
+      lastModified: value.lastModified,
+      ...options,
+    });
   }
 
   if (isResponseLike(value)) {
@@ -107,8 +114,6 @@ export async function toFile(
 
   const parts = await getBytes(value);
 
-  name ||= getName(value);
-
   if (!options?.type) {
     const type = parts.find((part) => typeof part === 'object' && 'type' in part && part.type);
     if (typeof type === 'string') {

src/internal/uploads.ts

@@ -138,7 +138,7 @@ export const createForm = async <T = Record<string, unknown>>(
 
 // We check for Blob not File because Bun.File doesn't inherit from File,
 // but they both inherit from Blob and have a `name` property at runtime.
-const isNamedBlob = (value: object) => value instanceof Blob && 'name' in value;
+const isNamedBlob = (value: object): value is Blob => value instanceof Blob && 'name' in value;
 
 const isUploadable = (value: unknown) =>
   typeof value === 'object' &&
@@ -168,11 +168,17 @@ const addFormValue = async (form: FormData, key: string, value: unknown): Promis
   if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
     form.append(key, String(value));
   } else if (value instanceof Response) {
-    form.append(key, makeFile([await value.blob()], getName(value)));
+    let options = {} as FilePropertyBag;
+    const contentType = value.headers.get('Content-Type');
+    if (contentType) {
+      options = { type: contentType };
+    }
+
+    form.append(key, makeFile([await value.blob()], getName(value), options));
   } else if (isAsyncIterable(value)) {
     form.append(key, makeFile([await new Response(ReadableStreamFrom(value)).blob()], getName(value)));
   } else if (isNamedBlob(value)) {
-    form.append(key, value, getName(value));
+    form.append(key, makeFile([value], getName(value), { type: value.type }));
   } else if (Array.isArray(value)) {
     await Promise.all(value.map((entry) => addFormValue(form, key + '[]', entry)));
   } else if (typeof value === 'object') {

src/lib/BetaMessageStream.ts

@@ -432,7 +432,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
             break;
           }
           case 'input_json_delta': {
-            if (content.type === 'tool_use' && content.input) {
+            if ((content.type === 'tool_use' || content.type === 'mcp_tool_use') && content.input) {
               this._emit('inputJson', event.delta.partial_json, content.input);
             }
             break;
@@ -528,6 +528,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
       case 'message_stop':
         return snapshot;
       case 'message_delta':
+        snapshot.container = event.delta.container;
         snapshot.stop_reason = event.delta.stop_reason;
         snapshot.stop_sequence = event.delta.stop_sequence;
         snapshot.usage.output_tokens = event.usage.output_tokens;
@@ -570,7 +571,7 @@ export class BetaMessageStream implements AsyncIterable<BetaMessageStreamEvent>
             break;
           }
           case 'input_json_delta': {
-            if (snapshotContent?.type === 'tool_use') {
+            if (snapshotContent?.type === 'tool_use' || snapshotContent?.type === 'mcp_tool_use') {
               // we need to keep track of the raw JSON string as well so that we can
               // re-parse it for each delta, for now we just store it as an untyped
               // non-enumerable property on the snapshot