Skip to main content

Connection String to Anthropic

Define the connection string - from Studio​

connection string to anthropic

  1. Name
    Enter a name for this connection string.

  2. Identifier (optional)
    Learn more about the identifier in the connection string identifier section.

  3. Model Type
    Select "Chat".
    Anthropic is not listed as a connector when "Text Embeddings" is selected.

  4. Connector
    Select Anthropic from the dropdown menu.

  5. API key
    Enter the Anthropic API key used to authenticate requests.
    RavenDB sends the key in the x-api-key request header.

  6. Endpoint (optional)

    • The base URL of the Claude API.
      If not set, https://api.anthropic.com/v1/ is used.
      If set to https://api.anthropic.com, RavenDB adds the v1/ path automatically.
    • Any other URL is used as is, so it must include the path under which the Messages API is served (e.g., when using a proxy or gateway).
      RavenDB sends chat requests to <endpoint>/messages.
  7. Model
    Select or enter the Claude model to use, e.g., claude-sonnet-5-5.
    After you enter an API key, the dropdown lists the models available to that key.

  8. Max output tokens (optional)

    • The maximum number of tokens the model can generate in a single response.
      RavenDB sends this value to Anthropic in the max_tokens field of the API request.
      Thinking tokens count toward this limit.
    • If not set, 16000 is used. The value must be a positive integer.
    • See Token limits and errors.
  9. Reasoning effort (optional)

    • Turns on adaptive thinking and sets how much reasoning the model does before answering.
      RavenDB sends thinking: { "type": "adaptive" } and the selected effort level in output_config.effort.
    • Select low, medium, high, xhigh, or max, or enter another value supported by the model.
    • The selected model must support adaptive thinking and the requested effort level; otherwise, Anthropic rejects the request. Supported levels vary by model. Check Anthropic's documentation for the model you use.
    • RavenDB trims the value and converts it to lowercase, but does not validate it.
      This allows new Anthropic effort levels to be used without waiting for a RavenDB release.
    • If not set, RavenDB sends no thinking or effort configuration, and the model applies its own defaults.
    • Thinking content is not included in the answer.
      Thinking tokens are reported in ReasoningTokens (see Token usage) and count toward MaxOutputTokens.
  10. Prompt caching (optional)

    • When caching applies, RavenDB adds Anthropic's top-level cache_control field ({ "type": "ephemeral" }) to the request, allowing Anthropic to cache the prompt prefix and reuse it in later requests.

    • Anthropic bills a cache write above the normal input-token price and a cache read well below it.
      Caching therefore pays off only when the same prompt prefix is sent again within the cache lifetime:

      • In an AI agent conversation, every turn resends the system prompt and the prior messages.
      • In a GenAI task, the prompt is resent only when the model calls a tool (e.g., a query tool) and RavenDB sends the tool result back. A GenAI task without tools sends each document once, so caching would only add the cost of the cache write.
    • Caching is controlled by EnablePromptCache.
      The Studio options correspond to the following values:

      EnablePromptCacheAI agentsGenAI tasks with toolsGenAI tasks without tools
      null (Studio: Default)EnabledEnabledDisabled
      true (Studio: True)EnabledEnabledEnabled
      false (Studio: False)DisabledDisabledDisabled
    • RavenDB does not control Anthropic's caching behavior, such as the cache lifetime or the minimum prompt length that can be cached. Cache reads and writes are reported as described in Token usage.

  11. API version (optional)
    The Anthropic API version, sent in the anthropic-version request header.
    If not set, 2023-06-01 is used.

  12. Click Test Connection to confirm the connection string is set up correctly.

  13. Click Save to store the connection string or Cancel to discard changes.

Define the connection string - from the Client API​

using (var store = new DocumentStore
{
// Replace the server URL and database name with your own values.
Urls = new[] { "https://your-ravendb-server" },
Database = "YourDatabase"
}.Initialize())
{
// Define the connection string to Anthropic
var connectionString = new AiConnectionString
{
// Connection string Name & Identifier
Name = "ConnectionStringToAnthropic",
Identifier = "identifier-to-the-connection-string", // optional

// Model type
// Anthropic supports chat models only
ModelType = AiModelType.Chat,

// Anthropic connection settings
AnthropicSettings = new AnthropicSettings
{
ApiKey = "your-api-key",

// Name of the Claude model to use
Model = "claude-sonnet-5-5",

// Optionally, raise the output-token cap (default: 16000)
MaxOutputTokens = 32000,

// Optionally, turn on adaptive thinking with the given effort level.
// The model must support adaptive thinking and this effort level.
ReasoningEffort = "medium"

// Endpoint, EnablePromptCache, and ApiVersion are not set,
// so their defaults apply.
}
};

// Deploy the connection string to the server
var putConnectionStringOp =
new PutConnectionStringOperation<AiConnectionString>(connectionString);
var putConnectionStringResult = store.Maintenance.Send(putConnectionStringOp);
}

Syntax​

public class AiConnectionString
{
public string Name { get; set; }
public string Identifier { get; set; }
public AiModelType ModelType { get; set; } // Must be AiModelType.Chat for Anthropic
public AnthropicSettings AnthropicSettings { get; set; }
}

public sealed class AnthropicSettings : AbstractAiSettings
{
public AnthropicSettings();
public AnthropicSettings(string apiKey, string model, string endpoint = null,
int? maxOutputTokens = null, string reasoningEffort = null);

public string ApiKey { get; set; }
public string Model { get; set; }
public string Endpoint { get; set; } // optional
public int? MaxOutputTokens { get; set; } // optional
public string ReasoningEffort { get; set; } // optional
public bool? EnablePromptCache { get; set; } // optional
public string ApiVersion { get; set; } // optional
}
PropertyTypeRequiredDescription
ApiKeystringYesThe Anthropic API key, sent in the x-api-key request header.
ModelstringYesThe Claude model ID, e.g., claude-sonnet-5-5.
EndpointstringNoThe base URL of the Claude API.
Default: https://api.anthropic.com/v1/.
When set to https://api.anthropic.com, v1/ is added automatically. Any other URL is used as is.
MaxOutputTokensint?NoThe maximum number of tokens per response, sent as max_tokens. Thinking tokens count toward this limit.
Default: 16000. Must be positive.
ReasoningEffortstringNoEnables adaptive thinking and sets the effort level.
Not sent when null or whitespace.
See Reasoning effort.
EnablePromptCachebool?NoControls prompt caching for AI agents and GenAI tasks.
Default: null (Studio: Default).
See Prompt caching.
ApiVersionstringNoThe Anthropic API version, sent in the anthropic-version request header.
Default: 2023-06-01.
  • Set ModelType to AiModelType.Chat.
    RavenDB rejects the connection string if ModelType is set to AiModelType.TextEmbeddings.

  • AnthropicSettings has no Temperature setting; RavenDB does not send temperature to Anthropic.

  • EmbeddingsMaxConcurrentBatches, inherited from AbstractAiSettings, has no effect, since Anthropic is not used for embeddings.

Anthropic-specific behavior​

Tools and output schemas​

A tool's parameters schema defines the arguments the model can pass to that tool.
An output schema defines the structure of the model's final answer.

  • RavenDB sends every tool to Anthropic in strict mode (strict: true).
    Strict mode constrains the arguments generated for each tool call to the tool's parameters schema.

  • In the JSON schema for a tool's parameters, each object must include "additionalProperties": false.
    This allows only the properties declared for that object.

    • Schemas that RavenDB generates from a parameters sample object already meet this requirement.

    • For a hand-written ParametersSchema, RavenDB adds additionalProperties: false to the root (outermost) object if it is missing. If the root object's schema explicitly sets "additionalProperties": true, RavenDB preserves that value and Anthropic rejects the request. Include "additionalProperties": false in every nested object; otherwise, Anthropic rejects the request.

      In the following example, customer is the nested object. Its schema sets additionalProperties: false,
      and RavenDB adds this property to the root object before sending the schema to Anthropic:

      {
      "type": "object",
      "properties": {
      "customer": {
      "type": "object",
      "properties": {
      "id": { "type": "string" }
      },
      "required": ["id"],
      "additionalProperties": false
      }
      },
      "required": ["customer"]
      }
  • Anthropic allows at most 20 strict tools per request.
    All tools sent with a request count toward this limit: query tools, action tools, and sub-agents, plus the built-in RetrieveAttachment tool, which RavenDB adds when attachments are stored on the conversation document so the model can re-read them.

  • Both tool parameters schemas and output schemas must follow Anthropic's JSON Schema limitations.
    Anthropic rejects requests whose schemas use unsupported features, such as the numeric constraint minimum or the string constraint maxLength. Limits on optional parameters and parameters that allow multiple types apply across the tool and output schemas in the request.

  • Learn more about agent tools in Query tools, Action tools, and Sub-agents as tools.


Token usage​

RavenDB represents token-usage statistics using the AiUsage class.
The following table shows how RavenDB populates its properties from the token counts reported by Anthropic.

AiUsage propertyAnthropic usage fields
PromptTokensinput_tokens + cache_read_input_tokens + cache_creation_input_tokens
CompletionTokensoutput_tokens
TotalTokensPromptTokens + CompletionTokens
CachedTokenscache_read_input_tokens (cache reads only)
ReasoningTokensoutput_tokens_details.thinking_tokens (thinking tokens)

Cache writes are included in PromptTokens, but are not reported separately.


Token limits and errors​

A model's context window limits the total number of tokens in the input and generated response.
RavenDB handles Anthropic token limits as follows:

SituationResultWhat to do
The input exceeds the model's context window.
Anthropic rejects the request with HTTP 400 prompt is too long.
RavenDB throws TooManyTokensException.Shorten the input or the conversation history,
e.g., with chat trimming.
The response reaches MaxOutputTokens
(stop_reason: max_tokens).
RavenDB returns a truncated text answer or throws TooManyTokensException.
See Returning truncated text below.
Increase MaxOutputTokens.
The input and generated response together reach the model's context limit.
(stop_reason: model_context_window_exceeded).
RavenDB returns a truncated text answer or throws TooManyTokensException.
See Returning truncated text below.
Shorten the input or the conversation history.

Returning truncated text​

When generation stops because of an output or context limit,
RavenDB returns a truncated text answer without throwing an exception only when all of the following apply:

  • No output schema is specified.
  • The response contains some text.
  • The response contains no tool calls.

Other Anthropic responses that RavenDB maps to specific exceptions:

  • Refusal (stop_reason: refusal):
    RavenDB throws RefusedToAnswerException.

  • HTTP 429 with a valid Retry-After header:
    RavenDB throws RateLimitException, with RetryAfter set from the header.

    • In an AI agent conversation, the exception reaches your code; RavenDB does not retry the request.
      Retry after the RetryAfter delay.
    • For a GenAI task, the RavenDB server retries automatically after the delay specified by Anthropic's Retry-After header. It temporarily limits the task to one concurrent request to the model.
  • HTTP 429 without a valid Retry-After header
    (e.g., when the organization reaches its usage tier's monthly spend cap):
    RavenDB throws InsufficientQuotaException rather than treating the response as a temporary rate limit.

  • A rate-limit error during a streamed AI agent response
    (an error event whose error.type is rate_limit_error):
    RavenDB throws InsufficientQuotaException. Handle the exception in your application.
    RavenDB does not automatically retry the request, and no retry delay is provided.

In this article