<p>This library for the Anthropic API is meant to simplify development in C# for Anthropic users.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>This is an unofficial SDK for the Anthropic API. It was not built in consultation with Anthropic or any member of their organization.</p>
</div>
<p>This SDK was developed independently using existing libraries and the Anthropic API documentation as the starting point with the intention of making development of integrations done in C# with Anthropic quicker and more convenient.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>This client library is heavily inspired by the <ahref="https://github.com/tghamm/Anthropic.SDK">Anthropic.SDK</a> library. I chose to create a new library because I wanted to handle streaming and tool calling differently as well as have control over the client library as I plan to use it to build a connector for <ahref="https://github.com/microsoft/semantic-kernel">SemanticKernel</a>. However if you are looking for a client library the Anthropic.SDK is a great place to start.</p>
</div>
<h2id="-issues">📝 Issues</h2>
<p>If you encounter any issues while using this library please open an issue <ahref="https://github.com/StevanFreeborn/anthropic-client/issues">here</a>.</p>
<h2id="-license">📜 License</h2>
<p>This library is licensed under the <ahref="https://choosealicense.com/licenses/mit/">MIT License</a> and is free to use and modify.</p>
<h2id="-contributing">📝 Contributing</h2>
<p>If you would like to contribute to this library please open a pull request <ahref="https://github.com/StevanFreeborn/anthropic-client/pulls">here</a>.</p>
<p>In order to use the Anthropic API you will need an API key. You can get one by signing up at <ahref="https://www.anthropic.com/api">Anthropic</a>. Please keep your API key secure and do not share it with others. Be mindful of where you store your API key and do not commit it to a public repository.</p>
<p>The most common way to use the SDK is to create an <code>AnthropicApiClient</code> instance and call its methods. Its constructor requires two parameters:</p>
<ul>
<li><code>apiKey</code> - your Anthropic API key</li>
<li><code>httpClient</code> - an <code>HttpClient</code> instance. You can configure and customize the <code>HttpClient</code> instance as needed. This library however will perform the necessary configuration to work with the Anthropic API. Such as setting the base address and adding the proper headers.</li>
</ul>
<divclass="NOTE">
<h5>Note</h5>
<p>This library does not manage the lifecycle of the <code>HttpClient</code> instance. You should create and manage the lifecycle of the <code>HttpClient</code> instance in your application.</p>
</div>
<p>It is best practice to read the API key from a secure location such as a configuration file or environment variable. For example using the <code>appsettings.json</code> file:</p>
<pre><codeclass="lang-json">{
"AnthropicApiKey": "YOUR_API"
}
</code></pre>
<p>Example constructing an <code>AnthropicApiClient</code> instance:</p>
<p>The library does expose an interface <code>IAnthropicApiClient</code> that can be used for dependency injection and testing. The interface is implemented by the <code>AnthropicApiClient</code> class.</p>
<h3id="full-api-documentation">Full API Documentation</h3>
<p>This library was developed to make using the Anthropic API easier within a .NET application. If you are looking for the full API documentation you can find it at <ahref="https://docs.anthropic.com/">Anthropic API Documentation</a>.</p>
<h2id="usage">Usage</h2>
<p>The primary use case for working with the Anthropic API is to create a message in response to a request that includes one or more other messages. The created message can then be received either as a complete response or a stream of events. This can be used to create a conversation between the caller and Anthropic's AI models and/or to use Anthropic's AI models to perform a task.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>The following examples assume that you have already created an instance of the <code>AnthropicApiClient</code> class named <code>client</code>. You can also find these snippets in the examples directory.</p>
<p>The <code>AnthropicApiClient</code> exposes a method named <code>CountMessageTokensAsync</code> that can be used to count the number of tokens in a message. The method requires a <code>CountMessageTokensRequest</code> instance as a parameter.</p>
<p>The <code>AnthropicApiClient</code> exposes a method named <code>ListModelsAsync</code> that can be used to list the available models. The method takes an optional <code>PagingRequest</code> instance as a parameter.</p>
<p>The <code>AnthropicApiClient</code> exposes a method named <code>CreateMessageAsync</code> that can be used to create a message. The method requires a <code>MessageRequest</code> or a <code>StreamMessageRequest</code> instance as a parameter. The <code>MessageRequest</code> class is used to create a message whose response is not streamed and the <code>StreamMessageRequest</code> class is used to create a message whose response is streamed. The <code>MessageRequest</code> instance's properties can be set to configure how the message is created.</p>
<p>Anthropic uses Server-Sent Events (SSE) to stream messages. The possible events and the format of those events are documented in the <ahref="https://docs.anthropic.com/en/api/messages-streaming">Anthropic API Documentation</a>. This library provides a way to consume them after they have been deserialized into strongly-typed C# objects that are returned in an <code>IAsyncEnumerable</code> collection.</p>
<p>This allows you to consume the events as they are received and process them in the way that best fits your use case. The following example demonstrates how to consume the streamed events and build up the complete text response from the model.</p>
<p>This library also provides a custom <code>message_complete</code> event that is yielded when all the message's events have been received. This event is not part of Anthropic's SSE events but is provided to allow for easier consumption of the entire message response if desired and make it easier to implement built-in tool calling.</p>
var events = client.CreateMessageAsync(new StreamMessageRequest(
AnthropicModels.Claude3Haiku,
[
new(
MessageRole.User,
[new TextContent("Please write a haiku about the ocean.")]
)
]
));
MessageResponse? response = null;
await foreach (var e in events)
{
switch (e.Data)
{
case var data when data is MessageCompleteEventData msgData:
response = msgData.Message;
break;
}
}
var textContent = response?.Content
.OfType<TextContent>()
.Aggregate(new StringBuilder(), (sb, c) => sb.Append(c.Text))
.ToString();
Console.WriteLine(textContent);
</code></pre>
<h3id="tool-use">Tool Use</h3>
<p>Anthropic's models support the use of tools to perform tasks. This allows the models to interact with external client-side tools that can perform actions the models cannot do natively. This gives you the ability to further extend the model's abilities with your own custom tools. This feature is covered in depth in <ahref="https://docs.anthropic.com/en/docs/build-with-claude/tool-use">Anthropic's API Documentation</a>. This library aims to make using tools convenient by allowing you to create, provide, and call tools from within your application by leveraging the reflection capabilities of C#.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>All tools are user provided. The models do no not have access to any built-in server-side tools.</p>
</div>
<h4id="create-a-tool">Create a tool</h4>
<p>You can create a tool in 4 different ways and then provide that tool when creating a message.</p>
<ol>
<li>Create a tool from a class</li>
<li>Create a tool from a static method</li>
<li>Create a tool from an instance method</li>
<li>Create a tool from a delegate</li>
</ol>
<h5id="create-a-tool-from-a-class">Create a tool from a class</h5>
<p>When creating a tool from a class the class must implement the <code>ITool</code> interface.</p>
return $"The weather in {location} is 72 degrees Fahrenheit";
}
}
var toolInstance = new GetWeatherTool();
var getWeatherTool = Tool.CreateFromInstanceMethod(
"Get Weather",
"Get the weather for a location in the specified units",
toolInstance,
nameof(toolInstance.GetWeather)
);
</code></pre>
<h5id="create-a-tool-from-a-delegate">Create a tool from a delegate</h5>
<p>When creating a tool from a delegate the delegate must be a <code>Func<TResult></code>, <code>Func<T, TResult></code>, or <code>Func<T1, T2, TResult></code>. If you need to create a tool from a delegate that takes more than 2 parameters you should create a complex type and pass that as the parameter.</p>
<p>When you create a tool from one of the methods above and send it to Anthropic in your request a JSON representation of the tool is provided in the message. This JSON representation includes the name, description, and input schema of the tool. This information is used by Anthropic's models to discern if and when it should use a tool.</p>
<p>This library provides a <code>FunctionParameterAttribute</code> that can be used to provide additional information about the parameters of the tool. This information is used to provide a more detailed input schema for the tool.</p>
<p>This library also provides a <code>FunctionPropertyAttribute</code> that can be used to provide additional information about the members of complex types used as parameters in the tool. This information is used to provide a more detailed input schema for the tool.</p>
public string Units { get; } = "Fahrenheit";
}
var tool = (GetWeatherInput input) => $"The weather in {input.Location} is 72 degrees {input.Units}";
var getWeatherTool = Tool.CreateFromFunction(
"Get Weather",
"Get the weather for a location in the specified units",
tool
);
</code></pre>
<h4id="call-a-tool">Call a tool</h4>
<p>It is important to remember that while Anthropic's models do support tool use they don't actually have access to any built-in server-side tools. All tools are user provided. This means that while Anthropic's models can respond to a request to create a message with a request to use a tool that is all it is - a request. It is still up to the client to handle the tool request by calling the tool with the input provided by the model and then providing the result of that call back to the model.</p>
<p>This library aims to make this process convenient by allowing you to simply provide the tools you want Anthropic's models to consider for use when creating a message, receive the response, check if the response contains a tool call, and if it does invoke the tool to get the result.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>Anthropic's API expects requests to contain messages that alternate between the user and the assistant. In addition if you receive a tool use from the model the API expects you to respond with a message that contains the result of the tool call. The tool use content will always be from the assistant while the tool result will always be from the user.</p>
foreach (var content in finalResponse.Value.Content)
{
switch (content)
{
case TextContent textContent:
Console.WriteLine(textContent.Text);
break;
}
}
</code></pre>
<p>If an exception is thrown while invoking the tool the <code>InvokeAsync</code> method will return a <code>ToolCallResult</code> with the exception contained in the <code>Error</code> property.</p>
<divclass="NOTE">
<h5>Note</h5>
<p>The <code>InvokeAsync</code> method does accept a generic type parameter that can be used to specify the type of the <code>Value</code> property of the <code>ToolCallResult</code>. If it is not specified it will be an <code>object</code>.</p>
</div>
<h4id="call-a-tool-in-streamed-message">Call a tool in streamed message</h4>
<p>Tool calling is also supported when streaming the message response. The following example demonstrates how you can handle a tool call in a streamed message response.</p>
foreach (var content in finalResponse.Value.Content)
{
switch (content)
{
case TextContent textContent:
Console.WriteLine(textContent.Text);
break;
}
}
</code></pre>
<p>If you do find that you need more control over how exactly provided tools are called and how the result of those tools are returned you can avoid using the <code>InvokeAsync</code> method and instead use the <code>Tool</code> and <code>ToolUse</code> properties of the <code>ToolCall</code> instance to implement your own solution.</p>
<p>Anthropic's models support the use of system prompts to provide additional context to the user. This can be used to provide additional information to the user or to ask for additional information from the user. This feature is covered in depth in <ahref="https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/system-prompts">Anthropic's API Documentation</a>. This library aims to make using system prompts convenient by allowing you to provide the system prompts you want Anthropic's models to consider for use when creating a message.</p>
<h4id="system-message">System Message</h4>
<p>You can create a system prompt by providing a <code>string</code> as the <code>system</code> parameter in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor.</p>
<p>You can create a more complex system prompt by providing a <code>List<TextContent></code> as the <code>systemMessages</code> parameter in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor.</p>
<p>Anthropic provides a feature called <ahref="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching">Prompt Caching</a> that allows you to cache all or part of the prompt you send to the model. This can be used to improve the performance of your application by reducing latency and token usage. This feature is covered in depth in <ahref="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching">Anthropic's API Documentation</a>.</p>
<p>Prompt caching can be used to cache all parts of the prompt including system messages, user messages, and tools. You should refer to the <ahref="https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching">Anthropic API Documentation</a> for specifics on limitations and requirements for using prompt caching. This library aims to make using prompt caching convenient and give you complete control over what parts of the prompt are cached. Currently there is only one type of cache control available - <code>EphemeralCacheControl</code>.</p>
<h4id="caching-system-messages">Caching System Messages</h4>
<p>System messages can be cached by providing a <code>List<TextContent></code> as the <code>systemMessages</code> parameter in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor and having one or more of the <code>TextContent</code> instances have the <code>CacheControl</code> property set.</p>
<h4id="caching-user-messages">Caching User Messages</h4>
<p>User messages can be cached by providing a <code>List<Content></code> as the <code>messages</code> parameter in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor and having one or more of the <code>Content</code> instances have the <code>CacheControl</code> property set.</p>
<p>Tools can be cached by providing a <code>List<Tool></code> as the <code>tools</code> parameter in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor and having one or more of the <code>Tool</code> instances have the <code>CacheControl</code> property set. This property can be set after the tool is created manually or by using one of the static methods on the <code>Tool</code> class.</p>
<p>Anthropic provides a feature called <ahref="https://docs.anthropic.com/en/docs/build-with-claude/pdf-support">PDF Support</a> that allows Claude to support PDF input and understand both text and visual content within documents. This feature is covered in depth in <ahref="https://docs.anthropic.com/en/docs/build-with-claude/pdf-support">Anthropic's API Documentation</a>.</p>
<p>PDF support can be used to provide a PDF document as input to the model. This can be used to provide additional context to the model or to ask for additional information from the model. This library aims to make using PDF support convenient by allowing you to provide the PDF document you want Anthropic's models to consider for use when creating a message.</p>
<h4id="pdf-document">PDF Document</h4>
<p>You can provide a PDF document by providing its base64 encoded content as a <code>DocumentContent</code> instance in the list of messages in the <code>MessageRequest</code> or <code>StreamMessageRequest</code> constructor.</p>
