feat(extension): support tool schema for completions chat api

agentscope-examples/chat-completions-web/src/main/java/io/agentscope/examples/chatcompletions/ChatCompletionsWebApplication.java

@@ -97,6 +97,89 @@ private static void printStartupInfo() {
                 """);
         System.out.println("\nNote: Accept: text/event-stream header is optional when stream=true");
         System.out.println("===================================================");
+        System.out.println("\nChat completion with Tool Schema (Tool Suspend).\n");
+        System.out.println(
+                """
+                curl -N -X POST http://localhost:8080/v1/chat/completions \\
+                  -H 'Content-Type: application/json' \\
+                  -d '{
+                    "model": "qwen3-max",
+                    "stream": true,
+                    "messages": [
+                      { "role": "user", "content": "What is the weather in Hangzhou?" }
+                    ],
+                    "tools": [
+                      {
+                        "type": "function",
+                        "function": {
+                          "name": "get_weather",
+                          "description": "Get the current weather for a city",
+                          "parameters": {
+                            "type": "object",
+                            "properties": {
+                              "city": {
+                                "type": "string",
+                                "description": "The city name"
+                              }
+                            },
+                            "required": ["city"]
+                          }
+                        }
+                      }
+                    ]
+                  }'
+                """);
+        System.out.println("\nNote: Tools are registered as schema-only tools, triggering tool");
+        System.out.println("      suspension. The response will include tool_calls with");
+        System.out.println("      finish_reason='tool_calls'. Execute tools externally, then");
+        System.out.println("      send tool results in the next request:");
+        System.out.println(
+                """
+
+                curl -N -X POST http://localhost:8080/v1/chat/completions \\
+                  -H 'Content-Type: application/json' \\
+                  -d '{
+                    "model": "qwen3-max",
+                    "stream": true,
+                    "messages": [
+                      { "role": "user", "content": "What is the weather in Hangzhou?" },
+                      {
+                        "role": "assistant",
+                        "tool_calls": [{
+                          "id": "call_abc123",
+                          "type": "function",
+                          "function": {
+                            "name": "get_weather",
+                            "arguments": "{\\"city\\":\\"Hangzhou\\"}"
+                          }
+                        }]
+                      },
+                      {
+                        "role": "tool",
+                        "tool_call_id": "call_abc123",
+                        "name": "get_weather",
+                        "content": "Sunny, 25°C"
+                      }
+                    ],
+                    "tools": [
+                      {
+                        "type": "function",
+                        "function": {
+                          "name": "get_weather",
+                          "description": "Get the current weather for a city",
+                          "parameters": {
+                            "type": "object",
+                            "properties": {
+                              "city": { "type": "string", "description": "The city name" }
+                            },
+                            "required": ["city"]
+                          }
+                        }
+                      }
+                    ]
+                  }'
+                """);
+        System.out.println("===================================================");
         System.out.println(
                 "\n⚠️  Important: stream=false with Accept: text/event-stream will return error");
         System.out.println(

agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/builder/ChatCompletionsResponseBuilder.java

@@ -23,6 +23,7 @@
 import io.agentscope.core.chat.completions.model.ChatMessage;
 import io.agentscope.core.chat.completions.model.ToolCall;
 import io.agentscope.core.message.ContentBlock;
+import io.agentscope.core.message.GenerateReason;
 import io.agentscope.core.message.Msg;
 import io.agentscope.core.message.MsgRole;
 import io.agentscope.core.message.TextBlock;
@@ -99,9 +100,13 @@ public ChatCompletionsResponse buildResponse(
         ChatMessage message = convertMsgToChatMessage(reply);
         choice.setMessage(message);
 
-        // Set finish_reason based on whether there are tool calls
-        if (message.getToolCalls() != null && !message.getToolCalls().isEmpty()) {
+        // Set finish_reason based on GenerateReason or tool calls
+        GenerateReason generateReason = reply != null ? reply.getGenerateReason() : null;
+        if (generateReason == GenerateReason.TOOL_SUSPENDED
+                || (message.getToolCalls() != null && !message.getToolCalls().isEmpty())) {
             choice.setFinishReason("tool_calls");
+        } else if (generateReason == GenerateReason.MAX_ITERATIONS) {
+            choice.setFinishReason("length");
         } else {
             choice.setFinishReason("stop");
         }
@@ -207,11 +212,29 @@ public String extractTextContent(Msg msg) {
     /**
      * Convert a ToolUseBlock to a ToolCall, serializing the input Map to JSON string.
      *
+     * <p>Prioritizes the content field (raw JSON string) over the input Map, as some providers
+     * like DashScope store arguments in the content field.
+     *
      * @param block The ToolUseBlock to convert
      * @return The OpenAI-compatible ToolCall
      */
     private ToolCall convertToolUseBlockToToolCall(ToolUseBlock block) {
-        String argumentsJson = serializeMapToJson(block.getInput());
+        // Prioritize content field (raw JSON string) over input map
+        // DashScope and some providers store arguments in content field
+        String argumentsJson;
+        String content = block.getContent();
+        Map<String, Object> input = block.getInput();
+
+        if (content != null && !content.isEmpty()) {
+            argumentsJson = content;
+        } else if (input != null && !input.isEmpty()) {
+            // Only serialize input if it's not empty
+            argumentsJson = serializeMapToJson(input);
+        } else {
+            // Both content and input are empty - use empty object for non-streaming
+            argumentsJson = "{}";
+        }
+
         return new ToolCall(block.getId(), block.getName(), argumentsJson);
     }
 

agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/converter/OpenAIToolConverter.java

@@ -0,0 +1,129 @@
+/*
+ * Copyright 2024-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * You may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.agentscope.core.chat.completions.converter;
+
+import io.agentscope.core.chat.completions.model.OpenAITool;
+import io.agentscope.core.chat.completions.model.OpenAIToolFunction;
+import io.agentscope.core.model.ToolSchema;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * Converter for converting OpenAI tool format to AgentScope ToolSchema.
+ *
+ * <p>This converter handles the transformation from OpenAI's tool format (used in Chat Completions
+ * API requests) to AgentScope's internal ToolSchema format. Tools converted by this converter are
+ * intended to be registered as schema-only tools, which will trigger tool suspension when called.
+ */
+public class OpenAIToolConverter {
+
+    private static final Logger log = LoggerFactory.getLogger(OpenAIToolConverter.class);
+
+    /**
+     * Converts a list of OpenAI tools to AgentScope ToolSchemas.
+     *
+     * <p>Only tools with type "function" are converted. Other tool types are skipped with a warning.
+     *
+     * @param tools The list of OpenAI tools to convert (may be null or empty)
+     * @return A list of converted ToolSchema objects; returns an empty list if input is null or
+     *     empty
+     */
+    public List<ToolSchema> convertToToolSchemas(List<OpenAITool> tools) {
+        if (tools == null || tools.isEmpty()) {
+            return List.of();
+        }
+
+        List<ToolSchema> schemas = new ArrayList<>();
+
+        for (OpenAITool tool : tools) {
+            if (tool == null) {
+                log.warn("Skipping null tool in conversion");
+                continue;
+            }
+
+            // Only support function type tools for now
+            if (!"function".equals(tool.getType())) {
+                log.warn(
+                        "Skipping tool with unsupported type: {}. Only 'function' type is"
+                                + " supported",
+                        tool.getType());
+                continue;
+            }
+
+            OpenAIToolFunction function = tool.getFunction();
+            if (function == null) {
+                log.warn("Skipping tool with null function definition");
+                continue;
+            }
+
+            String name = function.getName();
+            String description = function.getDescription();
+            Map<String, Object> parameters = function.getParameters();
+
+            // Validate required fields
+            if (name == null || name.isBlank()) {
+                log.warn("Skipping tool with null or empty name");
+                continue;
+            }
+
+            if (description == null || description.isBlank()) {
+                log.warn("Skipping tool '{}' with null or empty description", name);
+                // Use empty string as fallback for description
+                description = "";
+            }
+
+            try {
+                ToolSchema.Builder schemaBuilder =
+                        ToolSchema.builder().name(name).description(description);
+
+                if (parameters != null) {
+                    schemaBuilder.parameters(parameters);
+                }
+
+                if (function.getStrict() != null) {
+                    schemaBuilder.strict(function.getStrict());
+                }
+
+                ToolSchema schema = schemaBuilder.build();
+                schemas.add(schema);
+                log.debug("Converted OpenAI tool to ToolSchema: {}", name);
+
+            } catch (Exception e) {
+                log.error("Failed to convert tool '{}' to ToolSchema: {}", name, e.getMessage(), e);
+            }
+        }
+
+        return schemas;
+    }
+
+    /**
+     * Converts a single OpenAI tool to a ToolSchema.
+     *
+     * @param tool The OpenAI tool to convert
+     * @return The converted ToolSchema, or null if conversion fails
+     */
+    public ToolSchema convertToToolSchema(OpenAITool tool) {
+        if (tool == null) {
+            return null;
+        }
+
+        List<ToolSchema> schemas = convertToToolSchemas(List.of(tool));
+        return schemas.isEmpty() ? null : schemas.get(0);
+    }
+}

agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsChunk.java

@@ -148,6 +148,10 @@ public static ChatCompletionsChunk toolCallChunk(
      * standard OpenAI streaming response (since OpenAI doesn't execute tools), AgentScope's
      * ReActAgent executes tools internally, so we expose the results in the stream.
      *
+     * <p><b>Important:</b> In OpenAI's streaming API specification, delta.role can only be
+     * "assistant" or "user". The role "tool" is not supported in streaming responses. Therefore,
+     * tool results are formatted as assistant content with a prefix indicating the tool name.
+     *
      * <p><b>Example output:</b>
      *
      * <pre>
@@ -159,31 +163,29 @@ public static ChatCompletionsChunk toolCallChunk(
      *   "choices": [{
      *     "index": 0,
      *     "delta": {
-     *       "role": "tool",
-     *       "tool_call_id": "call_abc",
-     *       "name": "get_weather",
-     *       "content": "The weather is sunny..."
+     *       "role": "assistant",
+     *       "content": "[Tool: get_weather] The weather is sunny..."
      *     }
      *   }]
      * }
      * </pre>
      *
      * @param id Request ID
      * @param model Model name
-     * @param toolCallId The ID of the tool call this result corresponds to
+     * @param toolCallId The ID of the tool call this result corresponds to (currently unused in streaming)
      * @param toolName The name of the tool that was executed
      * @param content The tool execution result content
-     * @return ChatCompletionsChunk with tool result
+     * @return ChatCompletionsChunk with tool result formatted as assistant content
      */
     public static ChatCompletionsChunk toolResultChunk(
             String id, String model, String toolCallId, String toolName, String content) {
         ChatCompletionsChunk chunk = new ChatCompletionsChunk(id, model);
 
         ChatMessage delta = new ChatMessage();
-        delta.setRole("tool");
-        delta.setToolCallId(toolCallId);
-        delta.setName(toolName);
-        delta.setContent(content);
+        delta.setRole("assistant");
+        // Format tool result as assistant content for streaming compatibility
+        // OpenAI streaming API does not support role: "tool" in delta
+        delta.setContent("[Tool: " + toolName + "] " + content);
 
         ChatChoice choice = new ChatChoice();
         choice.setIndex(0);

agentscope-extensions/agentscope-extensions-chat-completions-web/src/main/java/io/agentscope/core/chat/completions/model/ChatCompletionsRequest.java

@@ -71,6 +71,15 @@ public class ChatCompletionsRequest {
     /** Whether to stream responses via Server-Sent Events (SSE). Optional, defaults to false. */
     private Boolean stream;
 
+    /**
+     * A list of tools the model may call. Currently, only functions are supported as a tool.
+     *
+     * <p>When tools are provided, they are registered as schema-only tools. When the agent decides
+     * to call a tool, execution is suspended and the tool call is returned to the client for
+     * external execution.
+     */
+    private List<OpenAITool> tools;
+
     public String getModel() {
         return model;
     }
@@ -94,4 +103,12 @@ public Boolean getStream() {
     public void setStream(Boolean stream) {
         this.stream = stream;
     }
+
+    public List<OpenAITool> getTools() {
+        return tools;
+    }
+
+    public void setTools(List<OpenAITool> tools) {
+        this.tools = tools;
+    }
 }