feat(starters): add AgentBuilderCustomizer and auto-assembly extensions

[dracula337435]

AgentScope-Java Version

2.0.1-SNAPSHOT

Description

This PR adds an AgentBuilderCustomizer SPI to the core Spring Boot starter, mirroring the existing ChatModelBuilderCustomizer pattern, and provides several auto-assembly conveniences that reduce boilerplate when building agents.

The core starter currently creates a bare ReActAgent with only name/sysPrompt/model/toolkit/maxIters. Developers must manually call toolkit.registerTool(...), builder.middleware(...), builder.permissionContext(...), etc. This PR makes all of these declarative — declare a @Bean and it's auto-injected.

Changes

1. AgentBuilderCustomizer (SPI)

• New @FunctionalInterface interface, extends Consumer<ReActAgent.Builder>
• AgentscopeAutoConfiguration#agentscopeReActAgent now accepts ObjectProvider<AgentBuilderCustomizer> and applies all customizers before build()
• Backward compatible: no customizer beans → orderedStream() is empty → behavior unchanged

2. Tool auto-registration (@ToolBean)

• New @ToolBean marker annotation for beans whose @Tool methods should be auto-registered
• New ToolAutoRegistrationBeanPostProcessor (static @Bean) that scans for @ToolBean beans and calls toolkit.registerTool(...) on every Toolkit instance
• Eliminates manual toolkit.registerTool(...) calls in @Bean Toolkit methods

3. Middleware auto-assembly

• New middlewareAutoCustomizer bean: collects all MiddlewareBase beans via ObjectProvider and injects them into the agent builder, ordered by @Order

4. PermissionContextState auto-injection

• New permissionContextAutoCustomizer bean: if a PermissionContextState bean exists in the context, auto-applies it to the builder. No-op when absent.

5. Hook auto-assembly (isolated)

• New HookAutoConfiguration class: auto-injects Hook beans into the agent builder
• Isolated in a separate auto-configuration class because Hook and HookEvent are @Deprecated(forRemoval = true, since = "2.0.0"). This class can be removed together with the Hook API.

Documentation

• Updated tool docs (EN + ZH): added @ToolBean auto-registration tip
• Updated middleware docs (EN + ZH): added Spring Boot auto-assembly tip

Tests

• AgentscopeAutoConfigurationTest: 9 tests (4 existing + 5 new — customizer application, tool auto-registration, middleware auto-injection, permission auto-injection with/without bean)
• HookAutoConfigurationTest: 1 test (hook auto-injection)

Example usage

// Before: manual assembly
@Bean
Toolkit myToolkit() {
    Toolkit tk = new Toolkit();
    tk.registerTool(new MyTools());       // manual registration
    return tk;
}

@Bean
ReActAgent myAgent(Model model, Toolkit toolkit) {
    return ReActAgent.builder()
        .name("assistant")
        .model(model)
        .toolkit(toolkit)
        .middleware(new TimingMiddleware())  // manual middleware
        .build();
}

// After: declarative, auto-assembled
@ToolBean
class MyTools {
    @Tool(name = "search", description = "Search the web")
    public String search(@ToolParam(name = "query") String query) { ... }
}

@Bean
MiddlewareBase timingMiddleware() { return new TimingMiddleware(); }
// Agent bean is auto-created with tools + middleware injected.
// No @Bean ReActAgent needed — the auto-configuration handles it.

Validation

Check	Result
mvn spotless:apply	Pass
mvn test (10 tests)	Pass — 10 run, 0 failures, 0 errors

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (tool + middleware docs, EN + ZH)
• Code is ready for review

[gemini-code-assist]

Caution

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

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!