alibaba/spring-ai-alibaba · critical · IllegalStateException

Could not find executeAgent method in AgentToolExecutor clas

Error message

Could not find executeAgent method in AgentToolExecutor class

What it means

AgentTool.create uses reflection (ReflectionUtils.findMethod) to locate AgentToolExecutor.executeAgent(String, ToolContext). If that method is missing it throws IllegalStateException, meaning the AgentToolExecutor class in the classpath does not have the expected method signature — typically a version mismatch or partially built artifact.

Source

Thrown at spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/AgentTool.java:81

	public static ToolCallback getFunctionToolCallback(ReactAgent agent) {
		return AgentTool.create(agent);
	}

	/**
	 * Create a ToolCallback using MethodToolCallback.
	 * This method uses reflection to find the executeAgent method and builds MethodToolCallback
	 * directly without requiring @Tool annotation.
	 * 
	 * @param agent the ReactAgent instance
	 * @return ToolCallback created with MethodToolCallback
	 */
	public static ToolCallback create(ReactAgent agent) {
		// Find the executeAgent method using reflection
		java.lang.reflect.Method method = ReflectionUtils.findMethod(AgentToolExecutor.class, 
				"executeAgent", String.class, ToolContext.class);
		
		if (method == null) {
			throw new IllegalStateException("Could not find executeAgent method in AgentToolExecutor class");
		}

		// Get the original schema from inputSchema or inputType
		String originalSchema = StringUtils.hasLength(agent.getInputSchema())
				? agent.getInputSchema()
				: (agent.getInputType() != null)
				? JsonSchemaGenerator.generateForType(agent.getInputType())
				: null;

		// Wrap the original schema in an "input" parameter

		// Create ToolDefinition using ToolDefinition.builder() with the method
		DefaultToolDefinition.Builder builder = ToolDefinitions.builder(method)
				.name(agent.name())
				.description(agent.description());

		if (StringUtils.hasLength(originalSchema)) {
			String wrappedInputSchema = wrapSchemaInInputParameter(originalSchema);

View on GitHub (pinned to f82da0b50f)

Solutions

1. Run a clean rebuild: ./mvnw clean package -DskipTests=true to ensure AgentTool and AgentToolExecutor come from the same build.
2. Check AgentToolExecutor for a method exactly named executeAgent with parameters (String, ToolContext); restore or rename it back.
3. Align dependency versions via spring-ai-alibaba-bom so no mixed framework jars exist on the classpath.
4. mvn dependency:tree and remove older/duplicate spring-ai-alibaba artifacts.

Example fix

// before (AgentToolExecutor after refactor)
public ToolResponse invoke(String input, ToolContext ctx) { ... }
// after
public String executeAgent(String input, ToolContext toolContext) { ... }

Method m = ReflectionUtils.findMethod(AgentToolExecutor.class, "executeAgent", String.class, ToolContext.class);
if (m == null) throw new IllegalStateException("Incompatible spring-ai-alibaba-agent-framework on classpath: executeAgent missing");

try { ToolCallback tool = AgentTool.create(agent); } catch (IllegalStateException e) { throw new IllegalStateException("Framework jar mismatch; rebuild/align versions", e); }

When it happens

Trigger: Calling ReactAgent tool creation that runs AgentTool.create(agent) when the AgentToolExecutor class on the classpath lacks an executeAgent(String, ToolContext) method — e.g. a stale jar, a renamed/refactored executor, or mixed framework versions.

Common situations: Upgrading spring-ai-alibaba-agent-framework partially so AgentTool and AgentToolExecutor come from different versions; a shaded/repackaged jar dropping the method; local edits renaming executeAgent.

Related errors

• Cannot instantiate array type: {}
• not found default-default-application.yml
• Content Type used for store state '%s' is different from one
• Cannot instantiate class {} for @class deserialization
• Cannot instantiate class {} for @typeHint deserialization

AI-assisted analysis of alibaba/spring-ai-alibaba@f82da0b50f (2026-09-09). Data as JSON: /api/errors/84b65a254c828b51. Report an issue: GitHub.