feat(anthropic): add prompt caching support and cached tokens in usage (#2223)

[Leeaoyin]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

Fixes #2223

The Anthropic formatter did not add cache_control to system messages, conversation
messages, or tool definitions, and usage did not include cached tokens. Long system
prompts, large tool definitions, and multi-turn conversations could not benefit from
Anthropic prompt caching.

Implementation follows the official Anthropic prompt caching documentation:
https://platform.claude.com/docs/zh-CN/build-with-claude/prompt-caching

• Cache breakpoints are set with cache_control: {"type": "ephemeral"} on content blocks
• The cache prefix order is tools -> system -> messages, so marking the last tool
  definition, the system block, and the last message caches the full conversation prefix
• Cached token counts come from cache_read_input_tokens and cache_creation_input_tokens
  in the API response usage

Changes:

• AnthropicBaseFormatter: send system message as a text block with cache_control
  when caching is enabled; add applyCacheControl that marks the last cacheable
  content block of the last message so the conversation prefix is cached
• AnthropicToolsHelper: mark the last tool definition with cache_control
• AnthropicChatModel: wire the steps above when GenerateOptions.cacheControl is enabled
• AnthropicResponseParser: fill cachedTokens in usage from
  cache_read_input_tokens / cache_creation_input_tokens for both streaming
  and non-streaming responses

How to test: mvn test -pl agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic -am
(171 tests passing; new tests in AnthropicCacheControlTest, plus additions to
AnthropicResponseParserTest and AnthropicChatModelTest)

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Code is ready for review

[Copilot]

Pull request overview

Adds Anthropic prompt caching support (cache_control) across system prompts, conversation messages, and tool definitions, and extends usage parsing to include cached token accounting for both streaming and non-streaming responses (fixes #2223).

Changes:

• Add cache_control support to system messages, message content blocks (automatic “mark last cacheable block” strategy), and the last tool definition when caching is enabled.
• Parse cache_read_input_tokens / cache_creation_input_tokens and incorporate them into ChatUsage (including streaming aggregation via message_start + message_delta combination).
• Add/extend tests covering cache control formatting and cached token usage parsing.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicBaseFormatter.java	Adds cache-control aware system prompt handling and automatic message cache-control marking.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicToolsHelper.java	Marks the last tool definition with cache_control when caching is enabled.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/AnthropicChatModel.java	Wires cache control behavior into request building when GenerateOptions.cacheControl is enabled.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicResponseParser.java	Adds cached-token accounting and combines streaming start/delta usage.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicResponseParserTest.java	Extends tests for cached token parsing and streaming usage combination.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicCacheControlTest.java	New tests validating cache-control placement for messages, system prompt, and tools.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/AnthropicChatModelTest.java	Adds request-building smoke tests around cacheControl toggles (but currently not asserting request contents).

Comments suppressed due to low confidence (1)

agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicResponseParser.java:251

• For non-message_start events, messageId is typically null. Now that message_delta responses are emitted for usage, ensure the response id falls back to the id captured from message_start so the final usage chunk can be associated with the same message.

        }

        return ChatResponse.builder().id(messageId).content(contentBlocks).usage(usage).build();

[codecov]

Codecov Report

❌ Patch coverage is 94.64286% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...el/anthropic/formatter/AnthropicBaseFormatter.java	94.82%	0 Missing and 3 partials ⚠️
...l/anthropic/formatter/AnthropicResponseParser.java	94.59%	0 Missing and 2 partials ⚠️
...extensions/model/anthropic/AnthropicChatModel.java	88.88%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!