ChatAnthropic integration

Anthropic is an AI safety and research company. They are the creator of Claude. This will help you getting started with ChatAnthropic chat models. For detailed documentation of all ChatAnthropic features and configurations head to the API reference.

Overview

Integration details

Class	Package	Serializable	PY support	Downloads	Version
`ChatAnthropic`	`@langchain/anthropic`	✅	✅

Model features

See the links in the table headers below for guides on how to use specific features.

Tool calling	Structured output	Image input	Audio input	Video input	Token-level streaming	Token usage	Logprobs
✅	✅	✅	❌	❌	✅	✅	❌

Setup

You’ll need to sign up and obtain an Anthropic API key, and install the @langchain/anthropic integration package.

Credentials

Head to Anthropic’s website to sign up to Anthropic and generate an API key. Once you’ve done this set the ANTHROPIC_API_KEY environment variable:

export ANTHROPIC_API_KEY="your-api-key"

If you want to get automated tracing of your model calls you can also set your LangSmith API key by uncommenting below:

# export LANGSMITH_TRACING="true"
# export LANGSMITH_API_KEY="your-api-key"

Installation

The LangChain ChatAnthropic integration lives in the @langchain/anthropic package:

npm install @langchain/anthropic @langchain/core

yarn add @langchain/anthropic @langchain/core

pnpm add @langchain/anthropic @langchain/core

Instantiation

Now we can instantiate our model object and generate chat completions:

import { ChatAnthropic } from "@langchain/anthropic"

const llm = new ChatAnthropic({
    model: "claude-haiku-4-5-20251001",
    // temperature: 0, // Non-default values are rejected on newer Claude models; see Sampling parameters
    maxTokens: undefined,
    maxRetries: 2,
    // other params...
});

Sampling parameters

Newer Claude models reject non-default sampling parameters. Setting temperature, topP, or topK to a non-default value on claude-opus-5, claude-fable-5, claude-opus-4-8, claude-opus-4-7, or claude-sonnet-5 returns a 400 error:

const model = new ChatAnthropic({ model: "claude-opus-5", temperature: 0 });
await model.invoke("Hello!");
// BadRequestError: 400
// {"type":"error","error":{"type":"invalid_request_error",
//  "message":"`temperature` is deprecated for this model."}}

Support by model:

Models	`temperature` / `topP` / `topK`
`claude-opus-5`, `claude-fable-5`, `claude-opus-4-8`, `claude-opus-4-7`, `claude-sonnet-5`	Non-default values rejected (400). Omit the parameters, or pass defaults only (for example, `temperature: 1`).
`claude-opus-4-6`, `claude-sonnet-4-6`, `claude-haiku-4-5`, and earlier	Accepted

Upgrading the model string?Code written as new ChatAnthropic({ model, temperature: 0 }) breaks when you upgrade the model to one of the newer models above. Remove the sampling parameters rather than adjusting their values. On these models, steer output style through prompting instead. See the Anthropic migration guide for details.

Invocation

const aiMsg = await llm.invoke([
    [
        "system",
        "You are a helpful assistant that translates English to French. Translate the user sentence.",
    ],
    ["human", "I love programming."],
])
aiMsg

AIMessage {
  "id": "msg_013WBXXiggy6gMbAUY6NpsuU",
  "content": "Voici la traduction en français :\n\nJ'adore la programmation.",
  "additional_kwargs": {
    "id": "msg_013WBXXiggy6gMbAUY6NpsuU",
    "type": "message",
    "role": "assistant",
    "model": "claude-haiku-4-5-20251001",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 29,
      "output_tokens": 20
    }
  },
  "response_metadata": {
    "id": "msg_013WBXXiggy6gMbAUY6NpsuU",
    "model": "claude-haiku-4-5-20251001",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 29,
      "output_tokens": 20
    },
    "type": "message",
    "role": "assistant"
  },
  "tool_calls": [],
  "invalid_tool_calls": [],
  "usage_metadata": {
    "input_tokens": 29,
    "output_tokens": 20,
    "total_tokens": 49
  }
}

console.log(aiMsg.content)

Voici la traduction en français :

J'adore la programmation.

Content blocks

One key difference to note between Anthropic models and most others is that the contents of a single Anthropic AIMessage can either be a single string or a list of content blocks. For example when an Anthropic model calls a tool, the tool invocation is part of the message content (as well as being exposed in the standardized AIMessage.tool_calls field):

import { ChatAnthropic } from "@langchain/anthropic";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import * as z from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

const calculatorSchema = z.object({
  operation: z
    .enum(["add", "subtract", "multiply", "divide"])
    .describe("The type of operation to execute."),
  number1: z.number().describe("The first number to operate on."),
  number2: z.number().describe("The second number to operate on."),
});

const calculatorTool = {
  name: "calculator",
  description: "A simple calculator tool",
  input_schema: zodToJsonSchema(calculatorSchema),
};

const toolCallingLlm = new ChatAnthropic({
  model: "claude-haiku-4-5-20251001",
}).bindTools([calculatorTool]);

const toolPrompt = ChatPromptTemplate.fromMessages([
  [
    "system",
    "You are a helpful assistant who always needs to use a calculator.",
  ],
  ["human", "{input}"],
]);

// Chain your prompt and model together
const toolCallChain = toolPrompt.pipe(toolCallingLlm);

await toolCallChain.invoke({
  input: "What is 2 + 2?",
});

AIMessage {
  "id": "msg_01DZGs9DyuashaYxJ4WWpWUP",
  "content": [
    {
      "type": "text",
      "text": "Here is the calculation for 2 + 2:"
    },
    {
      "type": "tool_use",
      "id": "toolu_01SQXBamkBr6K6NdHE7GWwF8",
      "name": "calculator",
      "input": {
        "number1": 2,
        "number2": 2,
        "operation": "add"
      }
    }
  ],
  "additional_kwargs": {
    "id": "msg_01DZGs9DyuashaYxJ4WWpWUP",
    "type": "message",
    "role": "assistant",
    "model": "claude-haiku-4-5-20251001",
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 449,
      "output_tokens": 100
    }
  },
  "response_metadata": {
    "id": "msg_01DZGs9DyuashaYxJ4WWpWUP",
    "model": "claude-haiku-4-5-20251001",
    "stop_reason": "tool_use",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 449,
      "output_tokens": 100
    },
    "type": "message",
    "role": "assistant"
  },
  "tool_calls": [
    {
      "name": "calculator",
      "args": {
        "number1": 2,
        "number2": 2,
        "operation": "add"
      },
      "id": "toolu_01SQXBamkBr6K6NdHE7GWwF8",
      "type": "tool_call"
    }
  ],
  "invalid_tool_calls": [],
  "usage_metadata": {
    "input_tokens": 449,
    "output_tokens": 100,
    "total_tokens": 549
  }
}

Custom headers

You can pass custom headers in your requests like this:

import { ChatAnthropic } from "@langchain/anthropic";

const llmWithCustomHeaders = new ChatAnthropic({
  model: "claude-sonnet-4-6",
  maxTokens: 1024,
  clientOptions: {
    defaultHeaders: {
      "X-Api-Key": process.env.ANTHROPIC_API_KEY,
    },
  },
});

await llmWithCustomHeaders.invoke("Why is the sky blue?");

AIMessage {
  "id": "msg_019z4nWpShzsrbSHTWXWQh6z",
  "content": "The sky appears blue due to a phenomenon called Rayleigh scattering. Here's a brief explanation:\n\n1) Sunlight is made up of different wavelengths of visible light, including all the colors of the rainbow.\n\n2) As sunlight passes through the atmosphere, the gases (mostly nitrogen and oxygen) cause the shorter wavelengths of light, such as violet and blue, to be scattered more easily than the longer wavelengths like red and orange.\n\n3) This scattering of the shorter blue wavelengths occurs in all directions by the gas molecules in the atmosphere.\n\n4) Our eyes are more sensitive to the scattered blue light than the scattered violet light, so we perceive the sky as having a blue color.\n\n5) The scattering is more pronounced for light traveling over longer distances through the atmosphere. This is why the sky appears even darker blue when looking towards the horizon.\n\nSo in essence, the selective scattering of the shorter blue wavelengths of sunlight by the gases in the atmosphere is what causes the sky to appear blue to our eyes during the daytime.",
  "additional_kwargs": {
    "id": "msg_019z4nWpShzsrbSHTWXWQh6z",
    "type": "message",
    "role": "assistant",
    "model": "claude-3-sonnet-20240229",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 13,
      "output_tokens": 236
    }
  },
  "response_metadata": {
    "id": "msg_019z4nWpShzsrbSHTWXWQh6z",
    "model": "claude-3-sonnet-20240229",
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
      "input_tokens": 13,
      "output_tokens": 236
    },
    "type": "message",
    "role": "assistant"
  },
  "tool_calls": [],
  "invalid_tool_calls": [],
  "usage_metadata": {
    "input_tokens": 13,
    "output_tokens": 236,
    "total_tokens": 249
  }
}

Prompt caching

Anthropic supports caching parts of your prompt in order to reduce costs for use-cases that require long context. You can cache tools and both entire messages and individual blocks. The initial request containing one or more blocks or tool definitions with a "cache_control": { "type": "ephemeral" } field will automatically cache that part of the prompt. This initial caching step will cost extra, but subsequent requests will be billed at a reduced rate. The cache has a lifetime of 5 minutes, but this is refreshed each time the cache is hit. For longer caching, specify "ttl": "1h" in the cache_control field. There is a minimum cacheable prompt length, which varies according to model. For more information, see prompt caching details. Here’s an example of caching part of a system message that contains the LangChain conceptual docs:

let CACHED_TEXT = "...";

// @lc-docs-hide-cell

CACHED_TEXT = `## Components

LangChain provides standard, extendable interfaces and external integrations for various components useful for building with LLMs.
Some components LangChain implements, some components we rely on third-party integrations for, and others are a mix.

### Chat models

<span data-heading-keywords="chat model,chat models"></span>

Language models that use a sequence of messages as inputs and return chat messages as outputs (as opposed to using plain text).
These are generally newer models (older models are generally \`LLMs\`, see below).
Chat models support the assignment of distinct roles to conversation messages, helping to distinguish messages from the AI, users, and instructions such as system messages.

Although the underlying models are messages in, message out, the LangChain wrappers also allow these models to take a string as input.
This gives them the same interface as LLMs (and simpler to use).
When a string is passed in as input, it will be converted to a \`HumanMessage\` under the hood before being passed to the underlying model.

LangChain does not host any Chat Models, rather we rely on third party integrations.

We have some standardized parameters when constructing ChatModels:

- \`model\`: the name of the model

Chat Models also accept other parameters that are specific to that integration.

<Warning>
**Some chat models have been fine-tuned for **tool calling** and provide a dedicated API for it.**

Generally, such models are better at tool calling than non-fine-tuned models, and are recommended for use cases that require tool calling.
Please see the [tool calling section](/oss/javascript/langchain/tools) for more information.
</Warning>

For specifics on how to use chat models, see the [relevant how-to guides here](/oss/javascript/langchain/models).

#### Multimodality

Some chat models are multimodal, accepting images, audio and even video as inputs.
These are still less common, meaning model providers haven't standardized on the "best" way to define the API.
Multimodal outputs are even less common. As such, we've kept our multimodal abstractions fairly light weight
and plan to further solidify the multimodal APIs and interaction patterns as the field matures.

In LangChain, most chat models that support multimodal inputs also accept those values in OpenAI's content blocks format.
So far this is restricted to image inputs. For models like Gemini which support video and other bytes input, the APIs also support the native, model-specific representations.

For specifics on how to use multimodal models, see the [relevant how-to guides here](/oss/javascript/how-to/#multimodal).

### LLMs

<span data-heading-keywords="llm,llms"></span>

<Warning>
**Pure text-in/text-out LLMs tend to be older or lower-level. Many popular models are best used as [chat completion models](/oss/javascript/langchain/models),**

even for non-chat use cases.

You are probably looking for [the section above instead](/oss/javascript/langchain/models).
</Warning>

Language models that takes a string as input and returns a string.
These are traditionally older models (newer models generally are [Chat Models](/oss/javascript/langchain/models), see above).

Although the underlying models are string in, string out, the LangChain wrappers also allow these models to take messages as input.
This gives them the same interface as [Chat Models](/oss/javascript/langchain/models).
When messages are passed in as input, they will be formatted into a string under the hood before being passed to the underlying model.

LangChain does not host any LLMs, rather we rely on third party integrations.

For specifics on how to use LLMs, see the [relevant how-to guides here](/oss/javascript/langchain/models).

### Message types

Some language models take an array of messages as input and return a message.
There are a few different types of messages.
All messages have a \`role\`, \`content\`, and \`response_metadata\` property.

The \`role\` describes WHO is saying the message.
LangChain has different message classes for different roles.

The \`content\` property describes the content of the message.
This can be a few different things:

- A string (most models deal this type of content)
- A List of objects (this is used for multi-modal input, where the object contains information about that input type and that input location)

#### HumanMessage

This represents a message from the user.

#### AIMessage

This represents a message from the model. In addition to the \`content\` property, these messages also have:

**\`response_metadata\`**

The \`response_metadata\` property contains additional metadata about the response. The data here is often specific to each model provider.
This is where information like log-probs and token usage may be stored.

**\`tool_calls\`**

These represent a decision from a language model to call a tool. They are included as part of an \`AIMessage\` output.
They can be accessed from there with the \`.tool_calls\` property.

This property returns a list of \`ToolCall\`s. A \`ToolCall\` is an object with the following arguments:

- \`name\`: The name of the tool that should be called.
- \`args\`: The arguments to that tool.
- \`id\`: The id of that tool call.

#### SystemMessage

This represents a system message, which tells the model how to behave. Not every model provider supports this.

#### ToolMessage

This represents the result of a tool call. In addition to \`role\` and \`content\`, this message has:

- a \`tool_call_id\` field which conveys the id of the call to the tool that was called to produce this result.
- an \`artifact\` field which can be used to pass along arbitrary artifacts of the tool execution which are useful to track but which should not be sent to the model.

#### (Legacy) FunctionMessage

This is a legacy message type, corresponding to OpenAI's legacy function-calling API. \`ToolMessage\` should be used instead to correspond to the updated tool-calling API.

This represents the result of a function call. In addition to \`role\` and \`content\`, this message has a \`name\` parameter which conveys the name of the function that was called to produce this result.

### Prompt templates

<span data-heading-keywords="prompt,prompttemplate,chatprompttemplate"></span>

Prompt templates help to translate user input and parameters into instructions for a language model.
This can be used to guide a model's response, helping it understand the context and generate relevant and coherent language-based output.

Prompt Templates take as input an object, where each key represents a variable in the prompt template to fill in.

Prompt Templates output a PromptValue. This PromptValue can be passed to an LLM or a ChatModel, and can also be cast to a string or an array of messages.
The reason this PromptValue exists is to make it easy to switch between strings and messages.

There are a few different types of prompt templates:

#### String PromptTemplates

These prompt templates are used to format a single string, and generally are used for simpler inputs.
For example, a common way to construct and use a PromptTemplate is as follows:

\`\`\`typescript
import { PromptTemplate } from "@langchain/core/prompts";

const promptTemplate = PromptTemplate.fromTemplate(
  "Tell me a joke about {topic}"
);

await promptTemplate.invoke({ topic: "cats" });
\`\`\`

#### ChatPromptTemplates

These prompt templates are used to format an array of messages. These "templates" consist of an array of templates themselves.
For example, a common way to construct and use a ChatPromptTemplate is as follows:

\`\`\`typescript
import { ChatPromptTemplate } from "@langchain/core/prompts";

const promptTemplate = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant"],
  ["user", "Tell me a joke about {topic}"],
]);

await promptTemplate.invoke({ topic: "cats" });
\`\`\`

In the above example, this ChatPromptTemplate will construct two messages when called.
The first is a system message, that has no variables to format.
The second is a HumanMessage, and will be formatted by the \`topic\` variable the user passes in.

#### MessagesPlaceholder

<span data-heading-keywords="messagesplaceholder"></span>

This prompt template is responsible for adding an array of messages in a particular place.
In the above ChatPromptTemplate, we saw how we could format two messages, each one a string.
But what if we wanted the user to pass in an array of messages that we would slot into a particular spot?
This is how you use MessagesPlaceholder.

\`\`\`typescript
import {
  ChatPromptTemplate,
  MessagesPlaceholder,
} from "@langchain/core/prompts";
import { HumanMessage } from "@langchain/core/messages";

const promptTemplate = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant"],
  new MessagesPlaceholder("msgs"),
]);

promptTemplate.invoke({ msgs: [new HumanMessage({ content: "hi!" })] });
\`\`\`

This will produce an array of two messages, the first one being a system message, and the second one being the HumanMessage we passed in.
If we had passed in 5 messages, then it would have produced 6 messages in total (the system message plus the 5 passed in).
This is useful for letting an array of messages be slotted into a particular spot.

An alternative way to accomplish the same thing without using the \`MessagesPlaceholder\` class explicitly is:

\`\`\`typescript
const promptTemplate = ChatPromptTemplate.fromMessages([
  ["system", "You are a helpful assistant"],
  ["placeholder", "{msgs}"], // <-- This is the changed part
]);
\`\`\`

For specifics on how to use prompt templates, see the [relevant how-to guides here](/oss/javascript/how-to/#prompt-templates).

### Example Selectors

One common prompting technique for achieving better performance is to include examples as part of the prompt.
This gives the language model concrete examples of how it should behave.
Sometimes these examples are hardcoded into the prompt, but for more advanced situations it may be nice to dynamically select them.
Example Selectors are classes responsible for selecting and then formatting examples into prompts.

For specifics on how to use example selectors, see the [relevant how-to guides here](/oss/javascript/how-to/#example-selectors).

### Output parsers

<span data-heading-keywords="output parser"></span>

<Note>
**The information here refers to parsers that take a text output from a model try to parse it into a more structured representation.**

More and more models are supporting function (or tool) calling, which handles this automatically.
It is recommended to use function/tool calling rather than output parsing.
See the [LangChain tools documentation](/oss/javascript/langchain/tools).

</Note>

Responsible for taking the output of a model and transforming it to a more suitable format for downstream tasks.
Useful when you are using LLMs to generate structured data, or to normalize output from chat models and LLMs.

There are two main methods an output parser must implement:

- "Get format instructions": A method which returns a string containing instructions for how the output of a language model should be formatted.
- "Parse": A method which takes in a string (assumed to be the response from a language model) and parses it into some structure.

And then one optional one:

- "Parse with prompt": A method which takes in a string (assumed to be the response from a language model) and a prompt (assumed to be the prompt that generated such a response) and parses it into some structure. The prompt is largely provided in the event the OutputParser wants to retry or fix the output in some way, and needs information from the prompt to do so.

Output parsers accept a string or \`BaseMessage\` as input and can return an arbitrary type.

LangChain has many different types of output parsers. This is a list of output parsers LangChain supports. The table below has various pieces of information:

**Name**: The name of the output parser

**Supports Streaming**: Whether the output parser supports streaming.

**Input Type**: Expected input type. Most output parsers work on both strings and messages, but some (like OpenAI Functions) need a message with specific arguments.

**Output Type**: The output type of the object returned by the parser.

**Description**: Our commentary on this output parser and when to use it.

The current date is ${new Date().toISOString()}`;

// Noop statement to hide output
void 0;

import { ChatAnthropic } from "@langchain/anthropic";

const modelWithCaching = new ChatAnthropic({
  model: "claude-sonnet-4-6",
});

const LONG_TEXT = `You are a pirate. Always respond in pirate dialect.

Use the following as context when answering questions:

${CACHED_TEXT}`;

const messages = [
  {
    role: "system",
    content: [
      {
        type: "text",
        text: LONG_TEXT,
        // Tell Anthropic to cache this block
        cache_control: { type: "ephemeral" },
      },
    ],
  },
  {
    role: "user",
    content: "What types of messages are supported in LangChain?",
  },
];

const res = await modelWithCaching.invoke(messages);

console.log("USAGE:", res.response_metadata.usage);

USAGE: {
  input_tokens: 18,
  cache_creation_input_tokens: 2960,
  cache_read_input_tokens: 0,
  cache_creation: { ephemeral_5m_input_tokens: 2960, ephemeral_1h_input_tokens: 0 },
  output_tokens: 433,
  service_tier: 'standard',
  inference_geo: 'global'
}

We can see that there’s a new field called cache_creation_input_tokens in the raw usage field returned from Anthropic. If we use the same messages again, we can see that the long text’s input tokens are read from the cache:

const res2 = await modelWithCaching.invoke(messages);

console.log("USAGE:", res2.response_metadata.usage);

USAGE: {
  input_tokens: 18,
  cache_creation_input_tokens: 0,
  cache_read_input_tokens: 2960,
  cache_creation: { ephemeral_5m_input_tokens: 0, ephemeral_1h_input_tokens: 0 },
  output_tokens: 393,
  service_tier: 'standard',
  inference_geo: 'global'
}

Tool caching

You can also cache tools by setting the same "cache_control": { "type": "ephemeral" } within a tool definition. This currently requires you to bind a tool in Anthropic’s raw tool format Here’s an example:

const SOME_LONG_DESCRIPTION = "...";

// Tool in Anthropic format
const anthropicTools = [{
  name: "get_weather",
  description: SOME_LONG_DESCRIPTION,
  input_schema: {
    type: "object",
    properties: {
      location: {
        type: "string",
        description: "Location to get the weather for",
      },
      unit: {
        type: "string",
        description: "Temperature unit to return",
      },
    },
    required: ["location"],
  },
  // Tell Anthropic to cache this tool
  cache_control: { type: "ephemeral" },
}]

const modelWithCachedTools = modelWithCaching.bindTools(anthropicTools);

await modelWithCachedTools.invoke("what is the weather in SF?");

For more on how prompt caching works, see Anthropic’s docs.

Custom clients

Anthropic models may be hosted on cloud services such as Gemini Enterprise Agent Platform that rely on a different underlying client with the same interface as the primary Anthropic client. You can access these services by providing a createClient method that returns an initialized instance of an Anthropic client. Here’s an example:

import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";

const customClient = new AnthropicVertex();

const modelWithCustomClient = new ChatAnthropic({
  modelName: "claude-sonnet-4-6",
  maxRetries: 0,
  createClient: () => customClient,
});

await modelWithCustomClient.invoke([{ role: "user", content: "Hello!" }]);

Citations

Anthropic supports a citations feature that lets Claude attach context to its answers based on source material supplied by the user. This source material can be provided either as document content blocks, which describe full documents, or as search results, which describe relevant passages or snippets returned from a retrieval system. When "citations": { "enabled": true } is included in a query, Claude may generate direct citations to the provided material in its response.

Document example

In this example we pass a plain text document. In the background, Claude automatically chunks the input text into sentences, which are used when generating citations.

import { ChatAnthropic } from "@langchain/anthropic";

const citationsModel = new ChatAnthropic({
  model: "claude-haiku-4-5-20251001",
});

const messagesWithCitations = [
  {
    role: "user",
    content: [
      {
        type: "document",
        source: {
          type: "text",
          media_type: "text/plain",
          data: "The grass is green. The sky is blue.",
        },
        title: "My Document",
        context: "This is a trustworthy document.",
        citations: {
          enabled: true,
        },
      },
      {
        type: "text",
        text: "What color is the grass and sky?",
      },
    ],
  }
];

const responseWithCitations = await citationsModel.invoke(messagesWithCitations);

console.log(JSON.stringify(responseWithCitations.content, null, 2));

[
  {
    "type": "text",
    "text": "Based on the document, I can tell you that:\n\n- "
  },
  {
    "type": "text",
    "text": "The grass is green",
    "citations": [
      {
        "type": "char_location",
        "cited_text": "The grass is green. ",
        "document_index": 0,
        "document_title": "My Document",
        "start_char_index": 0,
        "end_char_index": 20
      }
    ]
  },
  {
    "type": "text",
    "text": "\n- "
  },
  {
    "type": "text",
    "text": "The sky is blue",
    "citations": [
      {
        "type": "char_location",
        "cited_text": "The sky is blue.",
        "document_index": 0,
        "document_title": "My Document",
        "start_char_index": 20,
        "end_char_index": 36
      }
    ]
  }
]

Search results example

In this example, we pass in search results as part of our message content. This allows Claude to cite specific passages or snippets from your own retrieval system in its response. This approach is helpful when you want Claude to cite information from a specific set of knowledge, but you want to bring your own pre-fetched/cached content directly rather than having the model search or retrieve them automatically.

import { ChatAnthropic } from "@langchain/anthropic";

const citationsModel = new ChatAnthropic({
  model: "claude-haiku-4-5-20251001",
});

const messagesWithCitations = [
  {
    type: "user",
    content: [
      {
        type: "search_result",
        title: "History of France",
        source: "https://some-uri.com",
        citations: { enabled: true },
        content: [
          {
            type: "text",
            text: "The capital of France is Paris.",
          },
          {
            type: "text",
            text: "The old capital of France was Lyon.",
          },
        ],
      },
      {
        type: "text",
        text: "What is the capital of France?",
      },
    ],
  },
];

const responseWithCitations = await citationsModel.invoke(messagesWithCitations);

console.log(JSON.stringify(responseWithCitations.content, null, 2));

Search results from a tool

You can also use a tool to provide search results that the model can cite in its responses. This is well suited for RAG (or Retrieval-Augmented Generation) workflows where Claude can decide when and where to retrieve information from. When returning this information as search results, it gives Claude the ability to create citations from the material returned from the tool. Here’s how you can create a tool that returns search results in the format expected by Anthropic’s citations API:

import { ChatAnthropic } from "@langchain/anthropic";
import { tool } from "@langchain/core/tools";

// Create a tool that returns search results
const ragTool = tool(
  () => [
    {
      type: "search_result",
      title: "History of France",
      source: "https://some-uri.com",
      citations: { enabled: true },
      content: [
        {
          type: "text",
          text: "The capital of France is Paris.",
        },
        {
          type: "text",
          text: "The old capital of France was Lyon.",
        },
      ],
    },
    {
      type: "search_result",
      title: "Geography of France",
      source: "https://some-uri.com",
      citations: { enabled: true },
      content: [
        {
          type: "text",
          text: "France is a country in Europe.",
        },
        {
          type: "text",
          text: "The capital of France is Paris.",
        },
      ],
    },
  ],
  {
    name: "my_rag_tool",
    description: "Retrieval system that accesses my knowledge base.",
    schema: z.object({
      query: z.string().describe("query to search in the knowledge base"),
    }),
  }
);

// Create model with search results beta header
const model = new ChatAnthropic({
  model: "claude-haiku-4-5-20251001",
}).bindTools([ragTool]);

const result = await model.invoke([
  {
    role: "user",
    content: "What is the capital of France?",
  },
]);

console.log(JSON.stringify(result.content, null, 2));

Learn more about how RAG works in LangChain Learn more about tool calling

Using with text splitters

Anthropic also lets you specify your own splits using custom document types. LangChain text splitters can be used to generate meaningful splits for this purpose. See the below example, where we split the LangChain.js README (a markdown document) and pass it to Claude as context:

import { ChatAnthropic } from "@langchain/anthropic";
import { MarkdownTextSplitter } from "@langchain/classic/text_splitter";

function formatToAnthropicDocuments(documents: string[]) {
  return {
    type: "document",
    source: {
      type: "content",
      content: documents.map((document) => ({ type: "text", text: document })),
    },
    citations: { enabled: true },
  };
}

// Pull readme
const readmeResponse = await fetch(
  "https://raw.githubusercontent.com/langchain-ai/langchainjs/master/README.md"
);

const readme = await readmeResponse.text();

// Split into chunks
const splitter = new MarkdownTextSplitter({
  chunkOverlap: 0,
  chunkSize: 50,
});
const documents = await splitter.splitText(readme);

// Construct message
const messageWithSplitDocuments = {
  role: "user",
  content: [
    formatToAnthropicDocuments(documents),
    { type: "text", text: "Give me a link to LangChain's tutorials. Cite your sources" },
  ],
};

// Query LLM
const citationsModelWithSplits = new ChatAnthropic({
  model: "claude-sonnet-4-6",
});
const resWithSplits = await citationsModelWithSplits.invoke([messageWithSplitDocuments]);

console.log(JSON.stringify(resWithSplits.content, null, 2));

[
  {
    "type": "text",
    "text": "Based on the documentation, I can provide you with a link to LangChain's tutorials:\n\n"
  },
  {
    "type": "text",
    "text": "The tutorials can be found at: https://js.langchain.com/docs/tutorials/",
    "citations": [
      {
        "type": "content_block_location",
        "cited_text": "[Tutorial](https://js.langchain.com/docs/tutorials/) walkthroughs",
        "document_index": 0,
        "document_title": null,
        "start_block_index": 191,
        "end_block_index": 194
      }
    ]
  }
]

Mid-conversation system messages

Mid-conversation system messages require @langchain/anthropic>=1.5.11.

Supported Claude models accept a system message partway through a conversation. Its instructions apply from that point onward. Adding one leaves the earlier turns unchanged, so it does not invalidate the prompt cache for them. ChatAnthropic sends leading system messages in the top-level system field, and every later SystemMessage at its own position in the conversation. A later SystemMessage must follow a human or tool message, and must either be the last message or be followed by an AI message. Not every Claude model supports mid-conversation system messages. The Claude documentation lists which ones do. ChatAnthropic does not check the model or the message’s position, so the API returns a 400 error when either is invalid.

import { ChatAnthropic } from "@langchain/anthropic";
import { AIMessage, HumanMessage, SystemMessage } from "@langchain/core/messages";

const llm = new ChatAnthropic({ model: "claude-opus-5-5" });

const response = await llm.invoke([
  new SystemMessage("You are a travel assistant."),
  new HumanMessage("Suggest a day trip from Lisbon."),
  new AIMessage("Sintra is a good choice: palaces, gardens, and a short train ride."),
  new HumanMessage("How do I get there?"),
  new SystemMessage("The user has switched to the mobile app. Keep answers under 50 words."), 
]);

For wording guidance and the full placement rules, see the Claude documentation.

Change tools mid-conversation

Mid-conversation tool changes require @langchain/anthropic>=1.5.12.

A mid-conversation SystemMessage can also add or remove tools with Anthropic’s tool_addition and tool_removal content blocks. Editing tools on the request invalidates the prompt cache for the whole conversation. These blocks leave tools unchanged, so the cached prefix still matches. The placement and model rules above apply. ChatAnthropic adds the required beta header, so you do not need to set betas. To add a tool partway through, bind it with extras: { defer_loading: true } so Claude does not see it at first. Then reference it by name in a tool_addition block:

import { ChatAnthropic } from "@langchain/anthropic";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";
import { tool } from "@langchain/core/tools";
import * as z from "zod";

const getTime = tool(async () => "12:00", {
  name: "get_time",
  description: "Get the current time.",
  schema: z.object({}),
});

const getWeather = tool(async ({ location }) => `It is sunny in ${location}.`, {
  name: "get_weather",
  description: "Get the current weather for a location.",
  schema: z.object({ location: z.string() }),
  extras: { defer_loading: true }, 
});

const llm = new ChatAnthropic({ model: "claude-opus-5-5" });
const llmWithTools = llm.bindTools([getTime, getWeather]);

const response = await llmWithTools.invoke([
  new HumanMessage("What's the weather in San Francisco?"),
  new SystemMessage({
    content: [
      {
        type: "tool_addition", 
        tool: { type: "tool_reference", name: "get_weather" }, 
      },
    ],
  }),
]);

The API rejects a request in which every tool is deferred, so bind at least one tool without defer_loading. To withdraw a tool, reference it in a tool_removal block. A later tool_addition can offer it again.

new SystemMessage({
  content: [
    {
      type: "tool_removal",
      tool: { type: "tool_reference", name: "get_weather" },
    },
  ],
});

To add a tool that you did not bind up front, define it inline with a tool_definition. Inline definitions are in beta and available only on the Claude API.

import { ChatAnthropic } from "@langchain/anthropic";
import { HumanMessage, SystemMessage } from "@langchain/core/messages";

const llm = new ChatAnthropic({ model: "claude-opus-5-5" });

const response = await llm.invoke([
  new HumanMessage("How many orders did we get yesterday?"),
  new SystemMessage({
    content: [
      {
        type: "tool_addition",
        tool: {
          type: "tool_definition", 
          definition: { 
            name: "db_query",
            description: "Run a read-only SQL query against the analytics database.",
            input_schema: {
              type: "object",
              properties: { sql: { type: "string" } },
              required: ["sql"],
            },
          },
        },
      },
    ],
  }),
]);

You can also write these blocks wrapped in a non_standard block, in content or contentBlocks. ChatAnthropic sends the same request for either form.

Context management

Anthropic supports a context editing feature that will automatically manage the model’s context window (e.g., by clearing tool results). See Anthropic documentation for details and configuration options.

Context management is supported since @langchain/anthropic@0.3.29

import { ChatAnthropic } from "@langchain/anthropic";

const llm = new ChatAnthropic({
  model: "claude-sonnet-4-6",
  clientOptions: {
    defaultHeaders: {
      "anthropic-beta": "context-management-2025-06-27",
    },
  },
  contextManagement: { edits: [{ type: "clear_tool_uses_20250919" }] },
)
const llmWithTools = llm.bindTools([{ type: "web_search_20250305", name: "web_search" }]);
const response = await llmWithTools.invoke("Search for recent developments in AI");

API reference

For detailed documentation of all ChatAnthropic features and configurations head to the API reference.

Connect these docs to your agent of choice via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Popular Providers

General integrations

RAG integrations

Overview

Integration details

Model features

Setup

Credentials

Installation

Instantiation

Sampling parameters

Invocation

Content blocks

Custom headers

Prompt caching

Tool caching

Custom clients

Citations

Document example

Search results example

Search results from a tool

Using with text splitters

Mid-conversation system messages

Change tools mid-conversation

Context management

API reference

​Overview

​Integration details

​Model features

​Setup

​Credentials

​Installation

​Instantiation

​Sampling parameters

​Invocation

​Content blocks

​Custom headers

​Prompt caching

​Tool caching

​Custom clients

​Citations

​Document example

​Search results example

​Search results from a tool

​Using with text splitters

​Mid-conversation system messages

​Change tools mid-conversation

​Context management

​API reference

Overview

Integration details

Model features

Setup

Credentials

Installation

Instantiation

Sampling parameters

Invocation

Content blocks

Custom headers

Prompt caching

Tool caching

Custom clients

Citations

Document example

Search results example

Search results from a tool

Using with text splitters

Mid-conversation system messages

Change tools mid-conversation

Context management

API reference