Skip to content
Robotadocs

@robota-sdk/agent-provider/anthropic

Anthropic Claude provider for the Robota SDK, built on the official @anthropic-ai/sdk. AnthropicProvider implements the @robota-sdk/agent-core provider contract over the Anthropic Messages API, so a ConversationAgent agent can run on Claude models with streaming and tool calling. It can also attach Anthropic's server-side web search tool to requests when you turn it on.

Installation

npm install @robota-sdk/agent-provider @robota-sdk/agent-core @anthropic-ai/sdk

Usage

import { ConversationAgent } from '@robota-sdk/agent-core';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
 
const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });
 
const agent = new ConversationAgent({
  name: 'MyAgent',
  aiProviders: [provider],
  defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
});
 
const response = await agent.run('Hello!');
console.log(response);

The provider registers under the name anthropic, which is the value defaultModel.provider must use. A call that names no model uses the provider's defaultModel option (a ConversationAgent agent passes defaultModel.model on every call); with neither, the call throws. createAnthropicProvider(options) is a factory that returns the same provider typed as IAIProvider.

Structured output and reasoning effort

A request that carries a json_schema response format (as a ConversationAgent run with an output schema can) is sent through Anthropic's native structured output, output_config.format. Every object in the schema is closed (additionalProperties: false) on the way out, because Anthropic rejects open objects. The text and json_object formats have no Anthropic equivalent; they rely on the agent-core validation loop instead.

A reasoning-effort selection (defaultModel.effort on a ConversationAgent agent, or effort on a chat call) is sent as output_config.effort for models in the provider's verified effort table. The table applies only when baseURL is not set: a gateway's behavior is not Anthropic's, so the provider claims no effort support there.

import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
 
const provider = new AnthropicProvider({
  apiKey: process.env.ANTHROPIC_API_KEY,
  enableWebTools: true,
});

With enableWebTools on, Anthropic's web_search server tool is included in requests; the API runs it, so no local tool is registered. A call with toolChoice: 'none' leaves it out. Web fetch is not offered by this provider.

chat() writes the search into the reply text: a search marker, a [Web Search Results] list, and at the end a [Sources] list of what the reply cites, one per address. Anthropic's documentation asks for citations to be shown with the output, and they otherwise arrive beside the text. Titles and addresses come from web pages, so control characters and markdown link syntax are removed from titles, and only http(s) addresses are listed, with brackets and backticks encoded. chatStream() carries neither list.

The choice is made when the provider is built and nothing switches it on afterwards, so a session or a provider swap never changes it. A provider profile built through createAnthropicProviderDefinition() turns it on with the profile option nativeWebTools:

{
  "type": "anthropic",
  "model": "claude-sonnet-4-6",
  "options": { "nativeWebTools": { "webSearch": true } }
}

Without the option, search stays off. webSearch must be a boolean; webFetch may only be false. Any other key or value is an error rather than a silently disabled search.

Options

new AnthropicProvider(options: IAnthropicProviderOptions). One of apiKey, client or executor is required; the constructor throws otherwise.

OptionTypeDescription
apiKeystringAnthropic API key used to create the SDK client.
baseURLstringEndpoint base URL (default: Anthropic's official endpoint). Any endpoint that speaks the Anthropic Messages API works.
timeoutnumberRequest timeout in milliseconds.
defaultModelstringModel to request when a call names none.
clientAnthropicA pre-built @anthropic-ai/sdk client, used instead of apiKey (for authentication set up outside the API-key flow).
executorIExecutorDelegates chat calls to an executor instead of calling the API directly.
enableWebToolsbooleanAttach Anthropic's server-side web_search tool to requests (default: off). See above.

For OpenAI-protocol gateways (Vercel AI Gateway, LiteLLM, OpenRouter), use @robota-sdk/agent-provider/openai with the gateway's baseURL and model slug instead.

Errors

A failed API call throws a typed error from @robota-sdk/agent-core: RateLimitError (with retryAfter from the retry-after header), AuthenticationError, ModelNotAvailableError or NetworkError when the failure is one of those, otherwise a ProviderError that carries the HTTP status and Anthropic's error type (for example overloaded_error) and keeps the SDK error as originalError. A failure Anthropic reports in the middle of a stream is mapped the same way. An aborted call rethrows the abort unchanged. See Provider failures.

Exports

  • AnthropicProvider, createAnthropicProvider() and the option types (IAnthropicProviderOptions, TAnthropicProviderOptionValue).
  • createAnthropicProviderDefinition(): the provider definition used by Robota's built-in provider registry, with its default constants (for example DEFAULT_ANTHROPIC_PROVIDER_MODEL).

See docs/SPEC.md for the package contract.

License

This package is dual-licensed under the GNU AGPL-3.0 or a commercial license. See LICENSING.md.