From f157ebb8f0048713d989783c44ba16501a4005fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=99=8E=E9=B8=A3?= Date: Fri, 9 May 2025 21:12:49 +0800 Subject: [PATCH] chore: Add IgnoredInToolInputSchema annotation to ignore the additional parameter when generating tool's input schema. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 虎鸣 --- .../ai/chat/model/ToolContext.java | 6 ++-- .../annotation/IgnoredInToolInputSchema.java | 36 +++++++++++++++++++ .../util/json/schema/JsonSchemaGenerator.java | 26 +++++++------- 3 files changed, 53 insertions(+), 15 deletions(-) create mode 100644 spring-ai-model/src/main/java/org/springframework/ai/tool/annotation/IgnoredInToolInputSchema.java diff --git a/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ToolContext.java b/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ToolContext.java index a359decc29f..456ef61fc9b 100644 --- a/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ToolContext.java +++ b/spring-ai-model/src/main/java/org/springframework/ai/chat/model/ToolContext.java @@ -16,12 +16,13 @@ package org.springframework.ai.chat.model; +import org.springframework.ai.chat.messages.Message; +import org.springframework.ai.tool.annotation.IgnoredInToolInputSchema; + import java.util.Collections; import java.util.List; import java.util.Map; -import org.springframework.ai.chat.messages.Message; - /** * Represents the context for tool execution in a function calling scenario. * @@ -43,6 +44,7 @@ * @author Christian Tzolov * @since 1.0.0 */ +@IgnoredInToolInputSchema public final class ToolContext { /** diff --git a/spring-ai-model/src/main/java/org/springframework/ai/tool/annotation/IgnoredInToolInputSchema.java b/spring-ai-model/src/main/java/org/springframework/ai/tool/annotation/IgnoredInToolInputSchema.java new file mode 100644 index 00000000000..a76cc235288 --- /dev/null +++ b/spring-ai-model/src/main/java/org/springframework/ai/tool/annotation/IgnoredInToolInputSchema.java @@ -0,0 +1,36 @@ +/* + * Copyright 2023-2025 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 + * + * https://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 org.springframework.ai.tool.annotation; + +import java.lang.annotation.Documented; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marks a type should be ignored when generate the tool input schema. + * + * @author He-Pin + * @since 1.0.0 + */ +@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE }) +@Retention(RetentionPolicy.RUNTIME) +@Documented +public @interface IgnoredInToolInputSchema { + +} diff --git a/spring-ai-model/src/main/java/org/springframework/ai/util/json/schema/JsonSchemaGenerator.java b/spring-ai-model/src/main/java/org/springframework/ai/util/json/schema/JsonSchemaGenerator.java index 27fae0fcc55..284a2772d16 100644 --- a/spring-ai-model/src/main/java/org/springframework/ai/util/json/schema/JsonSchemaGenerator.java +++ b/spring-ai-model/src/main/java/org/springframework/ai/util/json/schema/JsonSchemaGenerator.java @@ -16,13 +16,6 @@ package org.springframework.ai.util.json.schema; -import java.lang.reflect.Method; -import java.lang.reflect.Parameter; -import java.lang.reflect.Type; -import java.util.ArrayList; -import java.util.List; -import java.util.stream.Stream; - import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.annotation.JsonPropertyDescription; import com.fasterxml.jackson.databind.JsonNode; @@ -38,15 +31,21 @@ import com.github.victools.jsonschema.module.jackson.JacksonOption; import com.github.victools.jsonschema.module.swagger2.Swagger2Module; import io.swagger.v3.oas.annotations.media.Schema; - -import org.springframework.ai.chat.model.ToolContext; +import org.springframework.ai.tool.annotation.IgnoredInToolInputSchema; import org.springframework.ai.tool.annotation.ToolParam; import org.springframework.ai.util.json.JsonParser; +import org.springframework.core.annotation.AnnotationUtils; import org.springframework.lang.Nullable; import org.springframework.util.Assert; -import org.springframework.util.ClassUtils; import org.springframework.util.StringUtils; +import java.lang.reflect.Method; +import java.lang.reflect.Parameter; +import java.lang.reflect.Type; +import java.util.ArrayList; +import java.util.List; +import java.util.stream.Stream; + /** * Utilities to generate JSON Schemas from Java types and method signatures. It's designed * to work well in the context of tool calling and structured outputs, aiming at ensuring @@ -129,9 +128,10 @@ public static String generateForMethodInput(Method method, SchemaOption... schem String parameterName = method.getParameters()[i].getName(); Type parameterType = method.getGenericParameterTypes()[i]; if (parameterType instanceof Class parameterClass - && ClassUtils.isAssignable(parameterClass, ToolContext.class)) { - // A ToolContext method parameter is not included in the JSON Schema - // generation. + && AnnotationUtils.findAnnotation(parameterClass, IgnoredInToolInputSchema.class) != null) { + // A ToolContext or any other method parameter which annotated with + // `IgnoredInToolInputSchema` + // is not included in the JSON Schema generation. // It's a special type used by Spring AI to pass contextual data to tools // outside the model interaction flow. continue;