feat(anthropic): add new citation types

[EurFelux]

Background

The Anthropic API has added new text citation types (content_block_location and search_result_location) that are not yet supported by the AI SDK. Additionally, the citation schema was duplicated in both response and chunk schemas, making maintenance harder.

See https://platform.claude.com/docs/en/api/typescript/messages#text_citation

Summary

• Extract textCitationSchema for reuse across response and chunk schemas, improving maintainability
• Add support for new text citation types: content_block_location and search_result_location

Manual Verification

N/A - schema changes only, no runtime behavior change for existing citation types.

Checklist

• Tests have been added / updated (for bug fixes / features)
• Documentation has been added / updated (for bug fixes / features)
• A patch changeset for relevant packages has been added (for bug fixes / features - run pnpm changeset in the project root)
• I have reviewed this pull request (self-review)

[aayush-kapoor]

do you have a specific instance of a code snippet where anthropic will return these types? will make it very easy to verify. no worries if not

[EurFelux]

Here is the examples provided in the official documentation:

content_block_location: https://platform.claude.com/docs/en/build-with-claude/citations#custom-content-documents

search_result_location: https://platform.claude.com/docs/en/build-with-claude/search-results#example-direct-search-results

[aayush-kapoor]

i have approved it - but before merging, please add unit tests (using fixtures as described in https://github.com/vercel/ai/blob/main/contributing/testing.md#manual-testing)

[aayush-kapoor]

i also realised we need to make the proper changes in anthropic-messages-language-model.ts to allow for these citation types to be passed

[EurFelux]

Hello, I’ve carefully reviewed the use cases provided by Claude and identified the following issue:

1. search_result_location is returned as part of the response only when the user actively provides search results.

For example: https://platform.claude.com/docs/en/build-with-claude/search-results#example-direct-search-results

messages: [
    {
      role: "user",
      content: [
        {
          type: "search_result" as const,
          source: "https://docs.company.com/api-reference",
          title: "API Reference - Authentication",
          content: [
            {
              type: "text" as const,
              text: "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium."
            }
          ],
          citations: { enabled: true }
        },
        {
          type: "search_result" as const,
          source: "https://docs.company.com/quickstart",
          title: "Getting Started Guide",
          content: [
            {
              type: "text" as const,
              text: "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key."
            }
          ],
          citations: { enabled: true }
        },
        {
          type: "text" as const,
          text: "Based on these search results, how do I authenticate API requests and what are the rate limits?"
        }
      ]
    }
  ]

As you can see, there is a Claude-specific type: "search_result" here, whereas the current UserContent interface in aisdk only includes:

ai/packages/provider-utils/src/types/user-model-message.ts

Line 22 in 5e6d932

export type UserContent = string | Array<TextPart | ImagePart | FilePart>;

This type of content does not belong to any of the current UserContent interfaces. This means we need to make more changes than we’d imagined to support this feature, because we don’t currently support this type of UserContent.

2. content_block_location is provided as part of the response when a user attempts to build custom document content.

See: https://platform.claude.com/docs/en/build-with-claude/citations#custom-content-documents

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"}
        ]
    },
    "title": "Document Title", # optional
    "context": "Context about the document that will not be cited from", # optional
    "citations": {"enabled": True}
}

Here, we might want to use FilePart to implement custom documents, even though it doesn’t actually represent a file that exists in the filesystem. However, in the current implementation, we primarily rely on the mediaType field to determine how to construct the document content in Anthropic format. In the case of custom documents, though, the mediaType field simply does not exist.

ai/packages/anthropic/src/convert-to-anthropic-messages-prompt.ts

Lines 183 to 185 in 8940d47

	case 'file': {
	if (part.mediaType.startsWith('image/')) {
	anthropicContent.push({

Of course, we could also use providerOptions to carry extra data and indirectly achieve these two functionalities, but that’s probably not a good design.

Since these two features require significant changes, I don’t think they should all be implemented in this single PR. Additionally, given that implementing these features may very likely necessitate modifying existing generic interfaces, we should discuss further whether it is truly necessary to implement them.