feat(anthropic): supported Anthropic server tools

[Leeaoyin]

概述

Fixes #2236。

引入 Anthropic 专属的版本化 AnthropicServerTool 抽象（显式指定 type，如web_search_20250305），支持 Claude 内置 server tools（在单次模型调用内于 Anthropic服务端执行）。

描述

• 版本化抽象：显式指定版本化 type + 按 API 字段名传参，内部通过 SDK 的 JSON 模型（ToolUnion）转换并即时校验，SDK 已知的全部 server tools 均可用（web_search、web_fetch、code_execution、tool_search 各版本）；未知参数原样透传由服务端校验，新增 API 字段无需改代码。
• 统一的响应处理：流式与非流式均解析 server_tool_use 及全部 6 种结果块，结果块以原始 ContentBlockParam JSON 保留在 metadata 中，多轮对话时原样回传。
• ReAct 循环感知：服务端工具通过 metadata 标记，agent 跳过本地执行；结果内联时视为本轮完成。
• SDK 升级：将 anthropic-java 从 2.14.0 升级到 2.52.0，以获得上述工具的稳定 API 类型支持。已验证升级对既有代码零影响（编译与既有测试全部通过）。

用法

Web 搜索（支持域名过滤、次数限制、用户位置）：

AnthropicChatModel model = AnthropicChatModel.builder()
        .apiKey(...)
        .modelName("claude-sonnet-4-5")
        .addServerTool(AnthropicServerTool.webSearch()
                .param("max_uses", 5)
                .param("allowed_domains", List.of("example.com", "docs.example.com"))
                .param("user_location", Map.of(
                        "type", "approximate",
                        "city", "Hangzhou",
                        "timezone", "Asia/Shanghai"))
                .build())
        .build();

Web 抓取（抓取网页/PDF 内容，支持引用与内容长度限制）：

AnthropicServerTool webFetch = AnthropicServerTool.webFetch()
        .param("max_uses", 10)
        .param("allowed_domains", List.of("docs.anthropic.com"))
        .param("citations", Map.of("enabled", true))
        .param("max_content_tokens", 100_000)
        .build();

代码执行（在 Anthropic 沙箱中运行 Python/Bash）：

AnthropicServerTool codeExecution = AnthropicServerTool.codeExecution().build();

显式指定任意版本（上面的方法只是预填常用版本，SDK 已知的任意版本化 type 都可直接使用，无需改框架代码）：

// 新版 web fetch（增加响应包含控制）
AnthropicServerTool.builder().type("web_fetch_20260318").build();

// 新版 code execution（REPL 状态持久化 + 程序化工具调用）
AnthropicServerTool.builder().type("code_execution_20260120").build();

// 工具搜索
AnthropicServerTool.builder().type("tool_search_tool_bm25_20251119").build();

同时启用多个 server tools：

AnthropicChatModel model = AnthropicChatModel.builder()
        .apiKey(...)
        .modelName("claude-sonnet-4-5")
        .addServerTool(AnthropicServerTool.webSearch().param("max_uses", 5).build())
        .addServerTool(AnthropicServerTool.codeExecution().build())
        .build();

参数按 Anthropic API 字段名原样透传并由 SDK 即时校验，未知字段透传给服务端校验，
API 新增参数无需升级框架就能使用。

改动

core：ToolUseBlock/ToolResultBlock 增加 server tool 标记；ReasoningContext 透传并聚合模型返回的工具结果；ReActAgent 跳过服务端工具执行并修正结束判定。
anthropic 扩展：新增 AnthropicServerTool；Builder.addServerTool(...) 请求注入； AnthropicResponseParser / AnthropicMessageConverter 统一解析与回传。
BOM：anthropic-java 2.14.0 → 2.52.0

测试

• 新增单测：AnthropicServerToolTest、ReActAgentServerToolTest，以及 parser / converter / ReasoningContext 中的 server tool 用例

• core + anthropic 模块全量测试通过（173 个测试，0 失败）

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

Pull request overview

This PR adds first-class support for Anthropic “server tools” (e.g., web_search, web_fetch, code_execution, tool_search) so they can be enabled on requests, parsed from Anthropic responses (streaming and non-streaming), and correctly handled in AgentScope’s ReAct loop without being executed by the local toolkit.

Changes:

• Introduces AnthropicServerTool (versioned type + passthrough params) and wires it into AnthropicChatModel request construction.
• Extends Anthropic formatting/parsing to recognize server_tool_use and server tool result blocks, preserving raw result JSON in metadata for multi-turn echoing.
• Updates core ReAct flow and accumulators to skip local execution for server tools and to treat inline server tool results as completing those tool calls, with added tests.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 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/tool/AnthropicServerTool.java	New versioned server-tool abstraction that converts to Anthropic SDK ToolUnion.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/tool/AnthropicServerToolTest.java	Unit tests validating server tool typing, param validation, and serialization passthrough.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/AnthropicChatModel.java	Adds builder support for server tools and injects them into message-create params.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicResponseParser.java	Parses server_tool_use and multiple server tool result block types; stores raw result JSON in metadata.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicResponseParserTest.java	Adds coverage for parsing server tool use + results (including error cases) and streaming start events.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/main/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicMessageConverter.java	Ensures server tool blocks stay inline and are echoed back verbatim while preserving existing client-tool splitting behavior.
agentscope-extensions/agentscope-extensions-model/agentscope-extensions-model-anthropic/src/test/java/io/agentscope/extensions/model/anthropic/formatter/AnthropicMessageConverterTest.java	Tests correct inline handling and echoing of server tool use/results without breaking client tool result splitting.
agentscope-dependencies-bom/pom.xml	Upgrades anthropic-java to 2.52.0 for server tool API type support.
agentscope-core/src/main/java/io/agentscope/core/message/ToolUseBlock.java	Adds metadata flag + helper for identifying provider server tool calls.
agentscope-core/src/main/java/io/agentscope/core/message/ToolResultBlock.java	Adds metadata flag + helper for identifying provider server tool results.
agentscope-core/src/main/java/io/agentscope/core/ReActAgent.java	Skips server tools when computing pending tool executions and finishes when all tool calls are completed server tools inline.
agentscope-core/src/main/java/io/agentscope/core/agent/accumulator/ReasoningContext.java	Collects server tool results during streaming and places them after their corresponding tool calls in the final message.
agentscope-core/src/test/java/io/agentscope/core/agent/ReActAgentServerToolTest.java	New tests verifying ReAct behavior for server tools (inline result finishes; missing result continues loop).
agentscope-core/src/test/java/io/agentscope/core/agent/accumulator/ReasoningContextTest.java	New tests validating passthrough/ordering of server tool results and preserving prior behavior for non-server tool results.

[codecov]

Codecov Report

❌ Patch coverage is 68.92857% with 87 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...l/anthropic/formatter/AnthropicResponseParser.java	62.96%	57 Missing and 3 partials ⚠️
...anthropic/formatter/AnthropicMessageConverter.java	68.75%	9 Missing and 6 partials ⚠️
...extensions/model/anthropic/AnthropicChatModel.java	18.18%	8 Missing and 1 partial ⚠️
...ions/model/anthropic/tool/AnthropicServerTool.java	93.54%	1 Missing and 1 partial ⚠️
...scope/core/agent/accumulator/ReasoningContext.java	93.33%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!