Merge pull request #37 from spring-ai-alibaba/feature/support_search_ext_params

feat(SearchProvider): 添加扩展参数支持机制

Author: canfuu

assistant-agent-extensions/src/main/java/com/alibaba/assistant/agent/extension/search/spi/SearchExtendedParameter.java

@@ -0,0 +1,134 @@
+/*
+ * Copyright 2024-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 com.alibaba.assistant.agent.extension.search.spi;
+
+/**
+ * SearchProvider 的扩展参数描述。
+ *
+ * <p>SearchProvider 实现类可以通过 {@link SearchProvider#getExtendedParameters()} 声明额外的工具参数，
+ * 框架会自动将这些参数注册到 Tool 的 inputSchema / ParameterTree 中，
+ * 调用时传入的值会被放入 {@link com.alibaba.assistant.agent.extension.search.model.SearchRequest#getFilters()} 中。
+ *
+ * @author Assistant Agent Team
+ * @since 1.0.0
+ */
+public class SearchExtendedParameter {
+
+	/**
+	 * 参数名称（对应 JSON Schema property name，同时也是 filters 中的 key）
+	 */
+	private final String name;
+
+	/**
+	 * JSON Schema 类型，如 "string", "integer", "boolean" 等
+	 */
+	private final String type;
+
+	/**
+	 * 参数描述
+	 */
+	private final String description;
+
+	/**
+	 * 是否必填
+	 */
+	private final boolean required;
+
+	/**
+	 * 默认值，可为 null
+	 */
+	private final Object defaultValue;
+
+	private SearchExtendedParameter(Builder builder) {
+		this.name = builder.name;
+		this.type = builder.type;
+		this.description = builder.description;
+		this.required = builder.required;
+		this.defaultValue = builder.defaultValue;
+	}
+
+	public String getName() {
+		return name;
+	}
+
+	public String getType() {
+		return type;
+	}
+
+	public String getDescription() {
+		return description;
+	}
+
+	public boolean isRequired() {
+		return required;
+	}
+
+	public Object getDefaultValue() {
+		return defaultValue;
+	}
+
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	public static class Builder {
+
+		private String name;
+
+		private String type = "string";
+
+		private String description = "";
+
+		private boolean required = false;
+
+		private Object defaultValue;
+
+		public Builder name(String name) {
+			this.name = name;
+			return this;
+		}
+
+		public Builder type(String type) {
+			this.type = type;
+			return this;
+		}
+
+		public Builder description(String description) {
+			this.description = description;
+			return this;
+		}
+
+		public Builder required(boolean required) {
+			this.required = required;
+			return this;
+		}
+
+		public Builder defaultValue(Object defaultValue) {
+			this.defaultValue = defaultValue;
+			return this;
+		}
+
+		public SearchExtendedParameter build() {
+			if (name == null || name.isEmpty()) {
+				throw new IllegalArgumentException("SearchExtendedParameter name must not be empty");
+			}
+			return new SearchExtendedParameter(this);
+		}
+
+	}
+
+}
+

assistant-agent-extensions/src/main/java/com/alibaba/assistant/agent/extension/search/spi/SearchProvider.java

@@ -19,6 +19,7 @@
 import com.alibaba.assistant.agent.extension.search.model.SearchResultItem;
 import com.alibaba.assistant.agent.extension.search.model.SearchSourceType;
 
+import java.util.Collections;
 import java.util.List;
 
 /**
@@ -52,5 +53,19 @@ public interface SearchProvider {
 	default String getName() {
 		return this.getClass().getSimpleName();
 	}
+
+	/**
+	 * 获取该Provider声明的扩展参数列表。
+	 *
+	 * <p>框架会将这些参数动态注册到搜索工具的 inputSchema / ParameterTree 中，
+	 * 调用时传入的值会被放入 {@link SearchRequest#getFilters()} 供 Provider 在 search 中读取。
+	 *
+	 * <p>默认返回空列表，即不声明任何扩展参数。
+	 *
+	 * @return 扩展参数列表
+	 */
+	default List<SearchExtendedParameter> getExtendedParameters() {
+		return Collections.emptyList();
+	}
 }
 

assistant-agent-extensions/src/main/java/com/alibaba/assistant/agent/extension/search/tools/BaseSearchCodeactTool.java

@@ -29,6 +29,7 @@
 import com.alibaba.assistant.agent.extension.search.model.SearchResultItem;
 import com.alibaba.assistant.agent.extension.search.model.SearchResultSet;
 import com.alibaba.assistant.agent.extension.search.model.SearchSourceType;
+import com.alibaba.assistant.agent.extension.search.spi.SearchExtendedParameter;
 import com.alibaba.assistant.agent.extension.search.spi.SearchProvider;
 import com.fasterxml.jackson.annotation.JsonIgnore;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -165,7 +166,7 @@ private CodeactToolDefinition buildCodeactDefinition() {
 		String inputSchema = toolDefinition.inputSchema();
 
 		// 构建 ParameterTree
-		ParameterTree parameterTree = ParameterTree.builder()
+		ParameterTree.Builder treeBuilder = ParameterTree.builder()
 			.rawInputSchema(inputSchema)
 			.addParameter(ParameterNode.builder()
 				.name("query")
@@ -179,9 +180,29 @@ private CodeactToolDefinition buildCodeactDefinition() {
 				.description("返回结果数量限制")
 				.required(false)
 				.defaultValue(10)
-				.build())
-			.addRequiredName("query")
-			.build();
+				.build());
+
+		// 动态添加 Provider 声明的扩展参数
+		List<SearchExtendedParameter> extParams = searchProvider.getExtendedParameters();
+		if (extParams != null) {
+			for (SearchExtendedParameter ext : extParams) {
+				ParameterNode.Builder nodeBuilder = ParameterNode.builder()
+					.name(ext.getName())
+					.type(ParameterType.fromJsonSchemaType(ext.getType()))
+					.description(ext.getDescription())
+					.required(ext.isRequired());
+				if (ext.getDefaultValue() != null) {
+					nodeBuilder.defaultValue(ext.getDefaultValue());
+				}
+				treeBuilder.addParameter(nodeBuilder.build());
+				if (ext.isRequired()) {
+					treeBuilder.addRequiredName(ext.getName());
+				}
+			}
+		}
+
+		treeBuilder.addRequiredName("query");
+		ParameterTree parameterTree = treeBuilder.build();
 
 		return DefaultCodeactToolDefinition.builder()
 			.name(toolName)
@@ -277,8 +298,28 @@ private String buildInputSchema() {
 		limitProp.put("default", 10);
 		properties.put("limit", limitProp);
 
+		// 动态添加 Provider 声明的扩展参数
+		List<String> requiredNames = new ArrayList<>();
+		requiredNames.add("query");
+
+		List<SearchExtendedParameter> extParams = searchProvider.getExtendedParameters();
+		if (extParams != null) {
+			for (SearchExtendedParameter ext : extParams) {
+				Map<String, Object> extProp = new LinkedHashMap<>();
+				extProp.put("type", ext.getType());
+				extProp.put("description", ext.getDescription());
+				if (ext.getDefaultValue() != null) {
+					extProp.put("default", ext.getDefaultValue());
+				}
+				properties.put(ext.getName(), extProp);
+				if (ext.isRequired()) {
+					requiredNames.add(ext.getName());
+				}
+			}
+		}
+
 		schema.put("properties", properties);
-		schema.put("required", Arrays.asList("query"));
+		schema.put("required", requiredNames);
 
 		try {
 			return objectMapper.writeValueAsString(schema);
@@ -303,6 +344,17 @@ private SearchRequest buildSearchRequest(Map<String, Object> params) {
 		request.getSourceTypes().add(sourceType);
 		request.setTopK(limit);
 
+		// 将 Provider 声明的扩展参数值放入 filters
+		List<SearchExtendedParameter> extParams = searchProvider.getExtendedParameters();
+		if (extParams != null) {
+			for (SearchExtendedParameter ext : extParams) {
+				Object value = params.get(ext.getName());
+				if (value != null) {
+					request.getFilters().put(ext.getName(), value);
+				}
+			}
+		}
+
 		return request;
 	}