11 November, 2025

Spring AI 与 Google ADK 集成实战：基于 Azure OpenAI 的智能体开发探索

笔记

TL;DR

本文用于验证 Spring AI 与 Google ADK 集成的可能性，为未来的正式版本提供实践经验和架构参考。核心收获在于验证了分层设计的可行性：Spring AI 处理 AI 服务抽象，ADK 管理智能体生命周期，两者通过标准接口实现实验性衔接。

需要注意的是，Google ADK 的 Spring AI 支持确实处于早期 SNAPSHOT 阶段，API 可能存在变更风险，但整体架构设计已经展现了良好的技术融合潜力。

在企业级 AI 应用开发领域，如何将 Spring 生态的强大企业级特性与现代化智能体开发框架有机结合一直是技术团队面临的核心挑战。尤其是在探索 Google ADK（Agent Development Kit）与 Spring AI 的集成可能性时，开发者往往面临技术选型、架构设计和兼容性测试的多重考量。传统 AI 应用开发需要手动处理复杂的模型集成、工具调用和会话管理，导致代码耦合度高、维护成本大。本文通过一个简单但完整的时间查询智能体，展示了 Spring AI 的 Azure OpenAI 集成与 Google ADK 的智能体框架的融合可能性。特别需要注意的是，Google ADK 的 Java 版本中，Spring AI 支持目前仍处于 0.3.1-SNAPSHOT 的早期阶段，这种集成具有明显的实验性质。项目源码可参考 adk-java 仓库。

解决思路

针对现代智能体开发的技术挑战，本文采用了多层次的技术栈整合策略。核心思路是通过 Spring AI 提供的统一 AI 服务抽象层，将 Azure OpenAI 的 gpt-4o-mini 模型包装为标准化的 AI 服务，然后利用 Google ADK 的智能体开发框架实现业务逻辑与 AI 能力的解耦分离。技术选型方面，选择了 Azure Entra ID 认证方式，虽然配置复杂度较高，但提供了企业级的安全性和可管理性。Google ADK 作为模型无关的智能体开发框架，虽然主要优化用于 Gemini 和 Vertex AI 生态，但通过适配器模式实验性地支持其他提供商的模型，包括 OpenAI、Anthropic 等。架构设计上采用内存存储策略简化部署，避免外部依赖，便于快速原型验证和演示。

技术选型考量：

Spring AI 作为 AI 服务抽象层，可集成多种 AI 模型（包括 Azure OpenAI、OpenAI、Anthropic、DeepSeek 等）
Google ADK Java 版本 0.3.1-SNAPSHOT 作为智能体框架
内存存储策略适合实验性项目，便于快速验证

架构优势对比：

传统方式：直接调用 Azure OpenAI API，手动管理会话和工具
新方案：通过 Spring AI 和 ADK 的组合，提供声明式配置和标准化流程
风险评估：ADK Spring AI 支持仍为快照版本，存在稳定性风险
价值评估：为未来正式版本提供宝贵的集成经验和最佳实践

前置条件

1. Azure OpenAI 服务部署

在开始集成之前，需要先部署 Azure OpenAI 服务。本文使用免费级别的 Azure OpenAI 服务，具体部署步骤可参考 Azure OpenAI服务认证指南。

2. ADK 源码构建安装

由于 adk-java 0.3.1-SNAPSHOT 版本尚未发布到 Maven 中央仓库，需要从 GitHub 下载源码并本地构建安装：

# 克隆 adk-java 仓库
git clone https://github.com/google/adk-java.git
cd adk-java

# 编译并安装到本地 Maven 库
mvn clean install -DskipTests

构建完成后，ADK 相关的依赖包将安装到本地 Maven 仓库中，项目即可正常引用。

实施步骤

1. 项目基础配置 (pom.xml)

在 Maven 项目中引入必要的依赖包，需要特别关注 ADK 版本的实验性：

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring-ai.version>1.1.0-M4</spring-ai.version>
    <adk.version>0.3.1-SNAPSHOT</adk.version>
    <spring-cloud-azure-starter.version>6.0.0</spring-cloud-azure-starter.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <!-- ADK Dependencies -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk</artifactId>
            <version>${adk.version}</version>
        </dependency>
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk-spring-ai</artifactId>
            <version>${adk.version}</version>
        </dependency>
        <!-- Dev UI -->
        <dependency>
            <groupId>com.google.adk</groupId>
            <artifactId>google-adk-dev</artifactId>
            <version>${adk.version}</version>
        </dependency>
        <dependency>
            <groupId>com.azure.spring</groupId>
            <artifactId>spring-cloud-azure-starter</artifactId>
            <version>${spring-cloud-azure-starter.version}</version>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- Spring AI Azure OpenAI 集成 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-azure-openai</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-azure-openai</artifactId>
    </dependency>

    <!-- Google ADK 组件（0.3.1-SNAPSHOT实验版本） -->
    <dependency>
        <groupId>com.google.adk</groupId>
        <artifactId>google-adk</artifactId>
    </dependency>
    <dependency>
        <groupId>com.google.adk</groupId>
        <artifactId>google-adk-spring-ai</artifactId>
    </dependency>
    <dependency>
        <groupId>com.google.adk</groupId>
        <artifactId>google-adk-dev</artifactId>
    </dependency>
</dependencies>

实验性风险提示：google-adk-spring-ai 为 SNAPSHOT 版本，可能存在 API 变更风险。

2. Azure OpenAI 服务配置 (application.yaml)

配置 Azure OpenAI 连接参数，gpt-4o-mini 模型部署：

spring:
  ai:
    azure:
      openai:
        chat:
          options:
            deployment-name: "gpt-4o-mini"
        endpoint: "https://{your-resource-name}.openai.azure.com/"
  cloud:
    azure:
      credential:
        client-id: "${AZURE_CLIENT_ID}"
        client-secret: "${AZURE_CLIENT_SECRET}"
      profile:
        tenant-id: "${AZURE_TENANT_ID}"

安全建议：生产环境应使用环境变量管理敏感配置。

3. 智能体框架配置 (AgentConfiguration.java)

通过 Spring 配置 ADK 智能体组件，注意使用实验性版本：

@Configuration
public class AgentConfiguration {
    
    @Bean
    public AzureOpenAIClientBuilderCustomizer azureOpenAIClientBuilderCustomizer(TokenCredential tokenCredential) {
        return clientBuilder -> clientBuilder.credential(tokenCredential); // 使用 ClientSecretCredential
    }

    @Bean
    public BaseLlm springAI(AzureOpenAiChatModel chatModel) {
        return new SpringAI(chatModel); // Spring AI集成
    }

    @Bean
    public LlmAgent llmAgent(BaseLlm springAI) {
        return LlmAgent.builder()
                .name("hello-time-agent")
                .description("Tell the current time")
                .instruction("""
                        You are a helpful assistant that tells the current date or time.
                        When the user asks for the current date or time, use the 'getCurrentDateAndTime' to get the relative information.
                        Then return the information to the user.
                        """)
                .tools(FunctionTool.create(HelloTime.class, "getCurrentDateAndTime"))
                .model(springAI)
                .build();
    }
}

实现特点：

SpringAI 作为 BaseLlm 的适配器
工具调用通过反射机制实现
智能体配置声明式定义

4. 业务工具实现 (HelloTime.java)

创建业务工具类，为智能体提供具体功能：

public class HelloTime {
    @Schema(description = "Get the current local date and time as a string")
    public static Map<String, String> getCurrentDateAndTime() {
        return Map.of(
                "currentTime", java.time.LocalTime.now().toString(),
                "currentDate", java.time.LocalDate.now().toString()
        );
    }
}

设计特点：

静态方法便于智能体调用
使用@Schema 提供 API 描述
返回结构化数据便于处理

5. 智能体应用启动 (AgentApp.java)

实现 Spring Boot 应用，集成智能体运行器：

@SpringBootApplication
public class AgentApp implements ApplicationRunner {

    private final Runner runner;
    private final String userId;

    public AgentApp(LlmAgent llmAgent) {
        this.runner = new InMemoryRunner(llmAgent, "adk-sample-app");
        userId = UUID.randomUUID().toString();
    }

    public static void main(String[] args) {
        new SpringApplicationBuilder(AgentApp.class)
                .web(WebApplicationType.NONE)
                .run(args);
    }

    @Override
    public void run(ApplicationArguments args) throws Exception {
        Session session = runner.sessionService().createSession(runner.appName(), this.userId).blockingGet();
        Content userMsg = Content.fromParts(
                Part.fromText("What can you do?"),
                Part.fromText("What's the time now?"),
                Part.fromText("What's the date today?")
        );

        Flowable<Event> events = runner.runAsync(session.userId(), session.id(), userMsg, RunConfig.builder().build());
        events.blockingForEach(event -> System.out.println(event.stringifyContent()));
    }
}

运行流程：

创建内存智能体运行器
建立用户会话
发送测试消息
流式处理智能体响应

6. 编译测试和部署验证

# 项目编译
mvn clean compile

# 运行测试
mvn spring-boot:run

应用启动后，观察控制台输出，将看到如下的内容：

2025-11-11T16:54:54.355+08:00  INFO 68001 --- [           main] c.g.a.m.s.o.SpringAIObservabilityHandler : Request completed successfully: model=azureopenai, type=chat, duration=6804ms, tokens=381
I can provide you with the current date and time. 

Right now, the time is 16:54:52 and today's date is November 11, 2025.

验证要点：

智能体能够正确接收用户输入
工具调用能够成功执行
时间信息能够正确返回
响应流处理正常

建议

实践建议：

密切关注 ADK 版本更新，及时升级适配
建立完整的错误处理和重试机制
添加详细的日志记录便于调试
考虑为生产环境准备备用方案

ADK 支持 Python、Go、Java 多语言，为不同技术栈团队提供了统一选择。该框架的模型无关特性为企业混合使用不同 AI 提供商服务提供了技术保障，Spring AI 的集成进一步增强了其在企业级应用中的适用性。虽然当前处于实验阶段，但为未来的智能体开发提供了有价值的技术路径。