MicrosoftExtensions: Idiomatic CacheControl Support

Anthropic.sln

@@ -1,7 +1,7 @@
 
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 18
-VisualStudioVersion = 18.0.11205.157 d18.0
+VisualStudioVersion = 18.0.11205.157
 MinimumVisualStudioVersion = 10.0.40219.1
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Anthropic", "src\Anthropic\Anthropic.csproj", "{5816A0C1-3BA1-454E-8D08-85B23DEF309D}"
 EndProject
@@ -15,15 +15,23 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Anthropic.Bedrock", "src\An
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{93E58BA5-CEFE-447E-AC0C-F2C5BC4C411D}"
 	ProjectSection(SolutionItems) = preProject
-		CHANGELOG.md
-		.csharpierignore
-		.editorconfig
-		.gitignore
-		LICENSE
-		README.md
-		SECURITY.md
+		CHANGELOG.md = CHANGELOG.md
+		.csharpierignore = .csharpierignore
+		.editorconfig = .editorconfig
+		.gitignore = .gitignore
+		LICENSE = LICENSE
+		README.md = README.md
+		SECURITY.md = SECURITY.md
 	EndProjectSection
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Anthropic.Vertex", "src\Anthropic.Vertex\Anthropic.Vertex.csproj", "{A316C280-3880-4674-9B0C-2F6FE77B8B49}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "examples", "examples", "{B36A84DF-456D-A817-6EDD-3EC3E7F6E11F}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "StreamingAggregationBetaExample", "StreamingAggregationBetaExample", "{6D5DEC39-3673-615E-54FA-C74C69400686}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StreamingAggregationExample", "examples\StreamingAggregationBetaExample\StreamingAggregationExample.csproj", "{0E525CB1-B565-4ABE-B477-48C53F9BB258}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -82,6 +90,30 @@ Global
 		{72FC9906-07F4-4911-8D6B-F9814974BB37}.Release|x64.Build.0 = Release|Any CPU
 		{72FC9906-07F4-4911-8D6B-F9814974BB37}.Release|x86.ActiveCfg = Release|Any CPU
 		{72FC9906-07F4-4911-8D6B-F9814974BB37}.Release|x86.Build.0 = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|x64.Build.0 = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Debug|x86.Build.0 = Debug|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|x64.ActiveCfg = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|x64.Build.0 = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|x86.ActiveCfg = Release|Any CPU
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49}.Release|x86.Build.0 = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|x64.Build.0 = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Debug|x86.Build.0 = Debug|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|x64.ActiveCfg = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|x64.Build.0 = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|x86.ActiveCfg = Release|Any CPU
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -91,5 +123,8 @@ Global
 		{0732C8A6-7313-4C33-AE2E-FFAA82EFB481} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{DD0E539D-6D5F-45EB-A807-01BE0A443604} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
 		{72FC9906-07F4-4911-8D6B-F9814974BB37} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{A316C280-3880-4674-9B0C-2F6FE77B8B49} = {827E0CD3-B72D-47B6-A68D-7590B98EB39B}
+		{6D5DEC39-3673-615E-54FA-C74C69400686} = {B36A84DF-456D-A817-6EDD-3EC3E7F6E11F}
+		{0E525CB1-B565-4ABE-B477-48C53F9BB258} = {6D5DEC39-3673-615E-54FA-C74C69400686}
 	EndGlobalSection
 EndGlobal

README.md

@@ -123,6 +123,13 @@ To send a request to the Anthropic API, build an instance of some `Params` class
 
 For example, `client.Messages.Create` should be called with an instance of `MessageCreateParams`, and it will return an instance of `Task<Message>`.
 
+> [!IMPORTANT]
+> We highly encourage you to use [streaming](#streaming) for longer running requests.
+
+We do not recommend setting a large `MaxTokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [timeout](#timeouts) without receiving a response from Anthropic. We periodically ping the API to keep the connection alive and reduce the impact of these networks.
+
+The SDK throws an error if a non-streaming request is expected to take longer than 10 minutes. Using a [streaming method](#streaming) or [overriding the timeout](#timeouts) at the client or request level disables the error.
+
 ## Streaming
 
 The SDK defines methods that return response "chunk" streams, where each chunk can be individually processed as soon as it arrives instead of waiting on the full response. Streaming methods generally correspond to [SSE](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) or [JSONL](https://jsonlines.org) responses.
@@ -155,6 +162,43 @@ await foreach (var message in client.Messages.CreateStreaming(parameters))
 }
 ```
 
+### Aggregators
+
+Both the [Messages](src/Anthropic/Models/Messages/Message.cs) and [BetaMessages](src/Anthropic/Models/Beta/Messages/BetaMessage.cs) streaming endpoints have built-in aggregators that can produce the same object as its non-streaming counterparts.
+
+It is possible to either only get the full result object via the `.Aggregate()` extension on the `IAsyncEnumerable` returned by the `CreateStreaming` method or insert an external aggregator into a LINQ tree:
+
+```csharp
+IAsyncEnumerable<RawMessageStreamEvent> responseUpdates = client.Messages.CreateStreaming(
+    parameters
+);
+
+// This produces a single object based on the streaming output.
+var message = await responseUpdates.Aggregate().ConfigureAwait(false);
+
+// You can also add an aggregator as part of your LINQ chain to get realtime streaming and aggregation
+
+var aggregator = new MessageContentAggregator();
+await foreach (RawMessageStreamEvent rawEvent in responseUpdates.CollectAsync(aggregator))
+{
+    // Do something with the stream events
+    if (rawEvent.TryPickContentBlockDelta(out var delta))
+    {
+        if (delta.Delta.TryPickThinking(out var thinkingDelta))
+        {
+            Console.Write(thinkingDelta.Thinking);
+        }
+        else if (delta.Delta.TryPickText(out var textDelta))
+        {
+            Console.Write(textDelta.Text);
+        }
+    }
+}
+
+// And then get the full aggregated message.
+var fullMessage = await aggregator.Message();
+```
+
 ## `IChatClient`
 
 The SDK provides an implementation of the `IChatClient` interface from the `Microsoft.Extensions.AI.Abstractions` library.

examples/Anthropic.Examples.sln

@@ -13,10 +13,13 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MessagesStreamingExample",
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ChatClientExample", "ChatClientExample\ChatClientExample.csproj", "{AA6ED2E6-A693-4FD8-AF20-1D339FBFBF96}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "StreamingAggregationExample", "StreamingAggregationExample\StreamingAggregationExample.csproj", "{8E03AF57-D948-47B7-9038-D6F1468B6BCC}"
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MessagesExample.Foundry", "MessagesExample.Foundry\MessagesExample.Foundry.csproj", "{5AD47EFB-4DE0-4F91-A6CB-C1DE6EFD5BD2}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MessagesExample.Bedrock", "MessagesExample.Bedrock\MessagesExample.Bedrock.csproj", "{7AD57F3D-FF5A-472B-ABEF-FC381D5CCC0C}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MessagesExample.Vertex", "MessagesExample.Vertex\MessagesExample.Vertex.csproj", "{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -87,6 +90,18 @@ Global
 		{AA6ED2E6-A693-4FD8-AF20-1D339FBFBF96}.Release|x64.Build.0 = Release|Any CPU
 		{AA6ED2E6-A693-4FD8-AF20-1D339FBFBF96}.Release|x86.ActiveCfg = Release|Any CPU
 		{AA6ED2E6-A693-4FD8-AF20-1D339FBFBF96}.Release|x86.Build.0 = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|x64.Build.0 = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Debug|x86.Build.0 = Debug|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|x64.ActiveCfg = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|x64.Build.0 = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|x86.ActiveCfg = Release|Any CPU
+		{8E03AF57-D948-47B7-9038-D6F1468B6BCC}.Release|x86.Build.0 = Release|Any CPU
 		{5AD47EFB-4DE0-4F91-A6CB-C1DE6EFD5BD2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{5AD47EFB-4DE0-4F91-A6CB-C1DE6EFD5BD2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{5AD47EFB-4DE0-4F91-A6CB-C1DE6EFD5BD2}.Debug|x64.ActiveCfg = Debug|Any CPU
@@ -111,6 +126,18 @@ Global
 		{7AD57F3D-FF5A-472B-ABEF-FC381D5CCC0C}.Release|x64.Build.0 = Release|Any CPU
 		{7AD57F3D-FF5A-472B-ABEF-FC381D5CCC0C}.Release|x86.ActiveCfg = Release|Any CPU
 		{7AD57F3D-FF5A-472B-ABEF-FC381D5CCC0C}.Release|x86.Build.0 = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|x64.ActiveCfg = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|x64.Build.0 = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|x86.ActiveCfg = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Debug|x86.Build.0 = Debug|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|x64.ActiveCfg = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|x64.Build.0 = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|x86.ActiveCfg = Release|Any CPU
+		{E2B0C44D-3B9C-4ACD-BA53-2E27F4111004}.Release|x86.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

examples/MessagesExample.Bedrock/Program.cs

@@ -32,8 +32,8 @@ await AnthropicBedrockCredentialsHelper.FromEnv().ConfigureAwait(false)
 var message = string.Join(
     "",
     response
-        .Content.Where(message => message.Value is TextBlock)
-        .Select(message => message.Value as TextBlock)
+        .Content.Select(message => message.Value)
+        .OfType<TextBlock>()
         .Select((textBlock) => textBlock.Text)
 );
 

examples/MessagesExample.Vertex/MessagesExample.Vertex.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Anthropic\Anthropic.csproj" />
+    <ProjectReference Include="..\..\src\Anthropic.Vertex\Anthropic.Vertex.csproj" />
+  </ItemGroup>
+</Project>

examples/MessagesExample.Vertex/Program.cs

@@ -0,0 +1,51 @@
+using Anthropic.Models.Messages;
+using Anthropic.Vertex;
+using Google.Apis.Auth.OAuth2;
+
+// The google vertex client needs a Project ID, use the ID from the google cloud dashboard.
+// The region parameter is optional.
+
+// By default the Vertex Credential provider tries to load system wide credentials generated via the "gcloud" tool.
+// For application wide credentials we recommend using service accounts instead and providing your own GoogleCredentials. Example:
+/*
+var client = new AnthropicVertexClient(new AnthropicVertexCredentials(null, "YourProjectId", GoogleCredential.FromJson(
+"""
+{
+    ServiceAccount JSON
+}
+""").CreateScoped("https://www.googleapis.com/auth/cloud-platform")));
+*/
+
+// or you can load the credentials from your system after you set it with the necessary environment variables by calling
+// var client = new AnthropicVertexClient(await DefaultAnthropicVertexCredentials.FromEnvAsync());
+
+// The main variables you can set are below. There are more options available; consult the method's documentation for more info.
+// <code>
+// ANTHROPIC_VERTEX_PROJECT_ID=your_project_id
+// CLOUD_ML_REGION=region_name
+// VERTEX_ACCESS_TOKEN=vertex_access_token
+// </code>
+
+var client = new AnthropicVertexClient(new AnthropicVertexCredentials(null, "YourProjectId"));
+
+MessageCreateParams parameters = new()
+{
+    MaxTokens = 2048,
+    Messages =
+    [
+        new() { Content = "Tell me a story about building the best SDK!", Role = Role.User },
+    ],
+    Model = "claude-3-7-sonnet@20250219",
+};
+
+var response = await client.Messages.Create(parameters);
+
+var message = string.Join(
+    "",
+    response
+        .Content.Select(message => message.Value)
+        .OfType<TextBlock>()
+        .Select((textBlock) => textBlock.Text)
+);
+
+Console.WriteLine(message);

examples/StreamingAggregationBetaExample/Program.cs

@@ -0,0 +1,48 @@
+using Anthropic;
+using Anthropic.Helpers;
+using Anthropic.Models.Beta.Messages;
+using Anthropic.Services.Beta.Messages;
+using Messages = Anthropic.Models.Messages;
+
+// Configured using the ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL environment variables
+AnthropicClient client = new();
+
+var responseUpdates = client.Beta.Messages.CreateStreaming(
+    new()
+    {
+        MaxTokens = 2048,
+        Messages =
+        [
+            new() { Content = "Tell me a story about building the best SDK!", Role = Role.User },
+        ],
+        Model = Messages::Model.Claude4Sonnet20250514,
+    }
+);
+
+// some streaming endpoints have built-in aggregators that create logically aggregated objects.
+// these represent the full stream as a single object.
+var message = await responseUpdates.Aggregate().ConfigureAwait(false);
+Console.WriteLine(message);
+
+// you can also add an aggregator as part of your LINQ chain to get real-time streaming and aggregation
+
+var aggregator = new BetaMessageContentAggregator();
+await foreach (BetaRawMessageStreamEvent rawEvent in responseUpdates.CollectAsync(aggregator))
+{
+    // do something with the stream events
+    if (rawEvent.TryPickContentBlockDelta(out var delta))
+    {
+        if (delta.Delta.TryPickThinking(out var thinkingDelta))
+        {
+            Console.Write(thinkingDelta.Thinking);
+        }
+        else if (delta.Delta.TryPickText(out var textDelta))
+        {
+            Console.Write(textDelta.Text);
+        }
+    }
+}
+
+// and then get the full aggregated message
+var message2 = aggregator.Message();
+Console.WriteLine(message2);

examples/StreamingAggregationBetaExample/StreamingAggregationExample.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Anthropic\Anthropic.csproj" />
+  </ItemGroup>
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>

examples/StreamingAggregationExample/Program.cs

@@ -0,0 +1,50 @@
+using Anthropic;
+using Anthropic.Helpers;
+using Anthropic.Models.Messages;
+using Anthropic.Services.Messages;
+
+// Configured using the ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN and ANTHROPIC_BASE_URL environment variables
+AnthropicClient client = new();
+
+MessageCreateParams parameters = new()
+{
+    MaxTokens = 2048,
+    Messages =
+    [
+        new() { Content = "Tell me a story about building the best SDK!", Role = Role.User },
+    ],
+    Model = Model.Claude4Sonnet20250514,
+    Thinking = new ThinkingConfigEnabled() { BudgetTokens = 1024 },
+};
+
+IAsyncEnumerable<RawMessageStreamEvent> responseUpdates = client.Messages.CreateStreaming(
+    parameters
+);
+
+// some streaming endpoints have built-in aggregators that create logically aggregated objects.
+// these represent the full stream as a single object.
+var message = await responseUpdates.Aggregate().ConfigureAwait(false);
+Console.WriteLine(message);
+
+// you can also add an aggregator as part of your LINQ chain to get real-time streaming and aggregation
+
+var aggregator = new MessageContentAggregator();
+await foreach (RawMessageStreamEvent rawEvent in responseUpdates.CollectAsync(aggregator))
+{
+    // do something with the stream events
+    if (rawEvent.TryPickContentBlockDelta(out var delta))
+    {
+        if (delta.Delta.TryPickThinking(out var thinkingDelta))
+        {
+            Console.Write(thinkingDelta.Thinking);
+        }
+        else if (delta.Delta.TryPickText(out var textDelta))
+        {
+            Console.Write(textDelta.Text);
+        }
+    }
+}
+
+// and then get the full aggregated message
+var message2 = aggregator.Message();
+Console.WriteLine(message2);

examples/StreamingAggregationExample/StreamingAggregationExample.csproj

@@ -0,0 +1,11 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Anthropic\Anthropic.csproj" />
+  </ItemGroup>
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+</Project>