목록으로
기술

스프링 AI 통합

·3분 읽기
#Koog#JetBrains#AI Agent#Kotlin#Java#JVM

원문: Koog Documentation — spring-ai-integration 이 글은 Koog 공식 문서의 spring-ai-integration 페이지를 한국어로 옮긴 번역본입니다. 문서 구조와 링크 의미를 유지하되, MkDocs 전용 UI 문법은 블로그에서 읽기 좋도록 정리했습니다.

스프링 AI 통합

Koog는 Spring AI의 추상화를 Koog 에이전트 프레임워크와 연결하는 Spring AI 통합 스타터를 제공합니다. 모델 액세스, 메모리 또는 벡터 저장을 위해 이미 Spring AI를 사용하고 있다면 이 스타터를 통해 Koog를 맨 위에 연결할 수 있습니다. 기존 Spring AI 구성을 교체하지 않고

koog-spring-boot-starter과의 차이점

koog-spring-boot-starter koog-spring-ai 스타터
LLM 운송 Koog의 자체 HTTP 클라이언트 ChatModel 및 EmbeddingModel과 같은 Spring AI Bean에 위임
구성 공급자당 ai.koog.* 속성 Spring AI 스타터가 관리하는 표준 spring.ai.* 속성과 koog.spring.ai.* 어댑터 속성
사용 시기 Koog가 모델 연결을 직접 관리하기를 원합니다. 이미 Spring AI를 사용하고 있으며 그 위에 Koog 에이전트, 메모리 또는 RAG가 필요합니다.

두 접근 방식 모두 독립적입니다. 직접적인 Koog 스타터 접근 방식은 Spring Boot Integration을 참조하세요.

사용 가능한 스타터

기준 치수 목적
koog-spring-ai-starter-model-chat 선택 사항인 ModerationModel이 포함된 Spring AI ChatModel를 Koog LLMClient 및 PromptExecutor에 적용합니다.
koog-spring-ai-starter-model-embedding Spring AI EmbeddingModel를 Koog LLMEmbeddingProvider에 적용합니다.
koog-spring-ai-starter-chat-memory Spring AI ChatMemoryRepository를 Koog ChatHistoryProvider에 적용합니다.
koog-spring-ai-starter-vector-store 수집, 검색 및 삭제를 위해 Spring AI VectorStore를 Koog KoogVectorStore에 적용합니다.

각 스타터는 자체 자동 구성 및 구성 속성을 갖춘 독립적인 Spring Boot 스타터입니다. 동일한 애플리케이션에서 하나의 스타터를 사용하거나 여러 개를 결합할 수 있습니다.

발송자 유형

4개의 스타터 모두 동일한 디스패처 구성 패턴을 지원합니다.

  • AUTO(기본값): 가능한 경우 Spring 관리 AsyncTaskExecutor를 사용하고, 그렇지 않으면 Dispatchers.IO로 대체합니다.
  • IO: 항상 Dispatchers.IO을 사용합니다.
  • dispatcher.parallelism: 0 및 type=IO보다 큰 경우 Dispatchers.IO.limitedParallelism(parallelism)을 사용합니다.

AUTO은 일반적으로 특히 Spring Boot 가상 스레드를 사용할 때 가장 간단한 선택입니다.

채팅 모델 스타터

개요

koog-spring-ai-starter-model-chat 스타터는 Spring AI의 채팅 모델 추상화를 Koog 에이전트 프레임워크와 연결합니다. 다음을 자동으로 구성합니다.

  • Spring AI ChatModel에 위임하는 Koog LLMClient(SpringAiLLMClient)
  • 사용 가능한 모든 LLMClient 빈에서 조립된 PromptExecutor(MultiLLMPromptExecutor)

도구는 항상 Koog 에이전트 프레임워크에 의해 실행됩니다. Spring AI는 도구 정의와 스키마만 수신하며 internalToolExecutionEnabled은 false으로 설정됩니다.

종속성 추가

Spring AI 채팅 모델 스타터와 함께 종속성을 추가합니다.

그레이들(Kotlin DSL)

1dependencies {2    implementation("ai.koog:koog-agents-jvm:$koogVersion")3    implementation("ai.koog:koog-spring-ai-starter-model-chat:$koogVersion")4    implementation("org.springframework.ai:spring-ai-starter-model-openai")5}

메이븐

1<dependencies>2    <dependency>3        <groupId>ai.koog</groupId>4        <artifactId>koog-agents-jvm</artifactId>5        <version>${koog.version}</version>6    </dependency>7    <dependency>8        <groupId>ai.koog</groupId>9        <artifactId>koog-spring-ai-starter-model-chat</artifactId>10        <version>${koog.version}</version>11    </dependency>12    <dependency>13        <groupId>org.springframework.ai</groupId>14        <artifactId>spring-ai-starter-model-openai</artifactId>15    </dependency>16</dependencies>

이용 가능한 제공업체

스타터는 다음을 포함하여 Spring AI가 ChatModel을 생성하는 모든 공급자와 함께 작동합니다. Anthropic, Azure OpenAI, Bedrock Converse, DeepSeek, Google GenAI, HuggingFace, MiniMax, Mistral AI, OCI GenAI, Ollama, OpenAI, Vertex AI 및 ZhiPu AI.

구성

일치하는 Spring AI 스타터를 통해 공급자를 구성한 다음 필요한 경우 Koog 속성을 추가합니다.

1## example Spring AI provider configuration2spring.ai.openai.api-key=${OPENAI_API_KEY}34## Koog chat starter defaults5koog.spring.ai.chat.enabled=true6koog.spring.ai.chat.dispatcher.type=AUTO

단일 ChatModel 빈이 있으면 모든 것이 자동으로 작동합니다. 어댑터는 이를 Koog LLMClient로 래핑하고 즉시 사용 가능한 PromptExecutor를 생성합니다.

사용예

PromptExecutor을 삽입하고 이를 사용하여 Koog 에이전트를 실행합니다.

코틀린

1import ai.koog.agents.core.agent.AIAgent2import ai.koog.prompt.executor.clients.openai.OpenAIModels3import ai.koog.prompt.executor.model.PromptExecutor4import org.springframework.stereotype.Service56@Service7class MyAgentService(private val promptExecutor: PromptExecutor) {89    suspend fun askAgent(userMessage: String): String {10        val agent = AIAgent(11            promptExecutor = promptExecutor,12            llmModel = OpenAIModels.Chat.GPT5Nano,13            systemPrompt = "You are a helpful assistant."14        )1516        return agent.run(userMessage)17    }18}

자바

1import ai.koog.agents.core.agent.AIAgent;2import ai.koog.prompt.executor.clients.openai.OpenAIModels;3import ai.koog.prompt.executor.model.PromptExecutor;4import org.springframework.stereotype.Service;56@Service7public class MyAgentService {8    private final PromptExecutor promptExecutor;910    public MyAgentService(PromptExecutor promptExecutor) {11        this.promptExecutor = promptExecutor;12    }1314    public String askAgent(String userMessage) {15        var agent = AIAgent.builder()16                .promptExecutor(promptExecutor)17                .llmModel(OpenAIModels.Chat.GPT5Nano)18                .systemPrompt("You are a helpful assistant.")19                .build();2021        return agent.run(userMessage);22    }23}

또는 자체 PromptExecutor 빈을 제공하여 자동 구성된 빈을 완전히 재정의하세요.

구성 속성(koog.spring.ai.chat)

재산 유형 기본 설명
enabled Boolean true 채팅 자동 구성 활성화 또는 비활성화
chat-model-bean-name String? null 여러 모델이 존재할 때 사용할 ChatModel의 빈 이름
moderation-model-bean-name String? null 사용할 ModerationModel의 빈 이름
provider String? null ChatModel 클래스에서 자동 감지 대신 노출할 Koog 공급자 ID
dispatcher.type AUTO / IO AUTO 모델 호출 차단을 위한 디스패처
dispatcher.parallelism Int 0 (= 무제한) IO 디스패처의 최대 동시성

다중 모델 컨텍스트

여러 ChatModel 또는 ModerationModel Bean이 등록된 경우 사용할 항목을 지정합니다.

1koog.spring.ai.chat.chat-model-bean-name=openAiChatModel2koog.spring.ai.chat.moderation-model-bean-name=openAiModerationModel

선택기가 없으면 단일 후보가 존재할 때만 자동 구성이 활성화됩니다.

확장 포인트

  • ChatOptionsCustomizer: ChatOptions을 사용자 정의하기 위해 이 인터페이스를 구현하는 Spring Bean을 등록합니다.

코틀린

1@Bean2fun chatOptionsCustomizer() = ChatOptionsCustomizer { options, params, model ->3    options4}

자바

1@Bean2public ChatOptionsCustomizer chatOptionsCustomizer() {3    return (options, params, model) -> options;4}
  • 사용자 정의 LLMClient: 자신만의 LLMClient Bean을 등록합니다. springAiChatModelLLMClient라는 이름의 Bean을 교체하지 않는 한 자동 구성된 어댑터와 함께 구성됩니다.
  • 사용자 정의 PromptExecutor: 자체 PromptExecutor Bean을 등록하여 자동 구성된 MultiLLMPromptExecutor를 재정의합니다.

모델 스타터 삽입

개요

koog-spring-ai-starter-model-embedding 스타터는 Spring AI의 임베딩 모델 추상화를 Koog 에이전트 프레임워크와 연결합니다. 다음을 자동으로 구성합니다.

  • Spring AI EmbeddingModel에 위임하는 Koog LLMEmbeddingProvider(SpringAiLLMEmbeddingProvider)

어댑터는 Koog 모델 ID를 Spring AI EmbeddingOptions로 전달하므로 런타임 모델 선택을 지원하는 백엔드가 이를 존중할 수 있습니다.

종속성 추가

Spring AI 임베딩 모델 스타터와 함께 종속성을 추가합니다.

그레이들(Kotlin DSL)

1dependencies {2    implementation("ai.koog:koog-agents-jvm:$koogVersion")3    implementation("ai.koog:koog-spring-ai-starter-model-embedding:$koogVersion")4    implementation("org.springframework.ai:spring-ai-starter-model-openai")5}

메이븐

1<dependencies>2    <dependency>3        <groupId>ai.koog</groupId>4        <artifactId>koog-agents-jvm</artifactId>5        <version>${koog.version}</version>6    </dependency>7    <dependency>8        <groupId>ai.koog</groupId>9        <artifactId>koog-spring-ai-starter-model-embedding</artifactId>10        <version>${koog.version}</version>11    </dependency>12    <dependency>13        <groupId>org.springframework.ai</groupId>14        <artifactId>spring-ai-starter-model-openai</artifactId>15    </dependency>16</dependencies>

이용 가능한 제공업체

스타터는 다음을 포함하여 Spring AI가 EmbeddingModel을 생성하는 모든 공급자와 작동합니다. Anthropic, Azure OpenAI, Bedrock, Google GenAI, HuggingFace, Mistral AI, OCI GenAI, Ollama, OpenAI, Transformers, Vertex AI 및 ZhiPu AI.

구성

Spring AI를 통해 임베딩 공급자를 구성한 후 필요한 경우 Koog 속성을 추가합니다.

1## example Spring AI provider configuration2spring.ai.openai.api-key=${OPENAI_API_KEY}34## Koog embedding starter defaults5koog.spring.ai.embedding.enabled=true6koog.spring.ai.embedding.dispatcher.type=AUTO

단일 EmbeddingModel 빈이 있으면 모든 것이 자동으로 작동합니다. 어댑터는 이를 Koog LLMEmbeddingProvider로 래핑합니다.

사용예

LLMEmbeddingProvider을 주입하고 이를 삽입 작업에 사용합니다.

코틀린

1import ai.koog.prompt.executor.clients.LLMEmbeddingProvider2import ai.koog.prompt.executor.clients.openai.OpenAIModels3import org.springframework.stereotype.Service45@Service6class MyEmbeddingService(private val embeddingProvider: LLMEmbeddingProvider) {78    suspend fun getEmbedding(text: String): List<Double> {9        return embeddingProvider.embed(10            text,11            OpenAIModels.Embeddings.TextEmbedding3Small12        )13    }14}

자바

1import ai.koog.prompt.executor.clients.LLMEmbeddingProvider;2import ai.koog.prompt.executor.clients.openai.OpenAIModels;3import org.springframework.stereotype.Service;4import java.util.List;56@Service7public class MyEmbeddingService {8    private final LLMEmbeddingProvider embeddingProvider;910    public MyEmbeddingService(LLMEmbeddingProvider embeddingProvider) {11        this.embeddingProvider = embeddingProvider;12    }1314    public List<Double> getEmbedding(String text) {15        return embeddingProvider.embed(16                text,17                OpenAIModels.Embeddings.TextEmbedding3Small18        );19    }20}

또는 자체 LLMEmbeddingProvider Bean을 제공하여 자동 구성된 어댑터를 완전히 재정의합니다.

구성 속성(koog.spring.ai.embedding)

재산 유형 기본 설명
enabled Boolean true 내장 자동 구성 활성화 또는 비활성화
embedding-model-bean-name String? null 여러 모델이 존재할 때 사용할 EmbeddingModel의 빈 이름
dispatcher.type AUTO / IO AUTO 임베딩 호출을 차단하는 디스패처
dispatcher.parallelism Int 0 (= 무제한) IO 디스패처의 최대 동시성

다중 모델 컨텍스트

여러 개의 EmbeddingModel Bean이 등록된 경우 사용할 항목을 지정하십시오.

1koog.spring.ai.embedding.embedding-model-bean-name=openAiEmbeddingModel

선택기가 없으면 단일 후보가 존재할 때만 자동 구성이 활성화됩니다.

확장 포인트

  • 사용자 정의 LLMEmbeddingProvider: 자체 Bean을 등록하여 자동 구성된 어댑터를 완전히 재정의합니다.

채팅 메모리 스타터

개요

koog-spring-ai-starter-chat-memory 스타터는 Spring AI의 채팅 메모리 추상화를 Koog 에이전트 프레임워크와 연결합니다. 다음을 자동으로 구성합니다.

  • Spring AI ChatMemoryRepository에 위임하는 Koog ChatHistoryProvider(SpringAiChatHistoryProvider)

이 스타터는 전체 Koog 실행 상태 지속성이 아닌 텍스트 전용 대화 지속성을 제공합니다.

텍스트 전용 계약

일반 텍스트 System, User 및 Assistant 메시지만 지속됩니다. 다음은 상점에 자동으로 삭제됩니다.

  • Message.Tool.Call
  • Message.Tool.Result
  • Message.Reasoning
  • 첨부 파일이 포함된 모든 메시지

로드 시 Spring AI TOOL 행은 자동으로 건너뜁니다. 타임스탬프, 토큰 수, 완료 이유, 사용자 정의 메타데이터 등의 메타데이터는 보존되지 않습니다.

종속성 추가

Spring AI 채팅 메모리 저장소 구현과 함께 종속성을 추가합니다.

그레이들(Kotlin DSL)

1dependencies {2    implementation("ai.koog:koog-agents-jvm:$koogVersion")3    implementation("ai.koog:koog-spring-ai-starter-chat-memory:$koogVersion")4    implementation("org.springframework.ai:spring-ai-starter-model-chat-memory-repository-jdbc")5}

메이븐

1<dependencies>2    <dependency>3        <groupId>ai.koog</groupId>4        <artifactId>koog-agents-jvm</artifactId>5        <version>${koog.version}</version>6    </dependency>7    <dependency>8        <groupId>ai.koog</groupId>9        <artifactId>koog-spring-ai-starter-chat-memory</artifactId>10        <version>${koog.version}</version>11    </dependency>12    <dependency>13        <groupId>org.springframework.ai</groupId>14        <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>15    </dependency>16</dependencies>

이용 가능한 제공업체

이 스타터는 ChatMemoryRepository을 노출하는 모든 Spring AI 채팅 메모리 저장소 구현과 함께 작동합니다. JDBC, Redis, Cassandra, Cosmos DB, MongoDB 및 Neo4j 기반 리포지토리를 포함합니다.

구성

일반적으로 Spring AI 저장소 설정 외에는 추가 구성이 필요하지 않습니다.

1## Koog chat-memory starter defaults2koog.spring.ai.chat-memory.enabled=true3koog.spring.ai.chat-memory.dispatcher.type=AUTO

단일 ChatMemoryRepository 빈이 있으면 모든 것이 자동으로 작동합니다. 어댑터는 이를 Koog ChatHistoryProvider로 래핑합니다.

사용예

자동 구성된 ChatHistoryProvider을 사용하여 에이전트에 ChatMemory 기능을 설치합니다.

코틀린

1import ai.koog.agents.chatMemory.feature.ChatMemory2import ai.koog.agents.chatMemory.feature.ChatHistoryProvider3import ai.koog.agents.core.agent.AIAgent4import ai.koog.prompt.executor.clients.openai.OpenAIModels5import ai.koog.prompt.executor.model.PromptExecutor6import org.springframework.stereotype.Service78@Service9class MyAgentService(10    private val promptExecutor: PromptExecutor,11    private val chatStorage: ChatHistoryProvider,12) {1314    suspend fun askAgent(userMessage: String, sessionId: String): String {15        val agent = AIAgent(16            promptExecutor = promptExecutor,17            llmModel = OpenAIModels.Chat.GPT5Nano,18            systemPrompt = "You are a helpful assistant.",19        ) {20            install(ChatMemory) {21                chatHistoryProvider = chatStorage22            }23        }2425        return agent.run(userMessage, sessionId)26    }27}

구성 속성(koog.spring.ai.chat-memory)

재산 유형 기본 설명
enabled Boolean true 채팅 메모리 자동 구성 활성화 또는 비활성화
chat-memory-repository-bean-name String? null 여러 저장소가 있을 때 사용할 ChatMemoryRepository의 Bean 이름
dispatcher.type AUTO / IO AUTO 저장소 호출 차단을 위한 디스패처
dispatcher.parallelism Int 0 (= 무제한) IO 디스패처의 최대 동시성

다중 저장소 컨텍스트

여러 개의 ChatMemoryRepository Bean이 등록된 경우 사용할 항목을 지정하십시오.

1koog.spring.ai.chat-memory.chat-memory-repository-bean-name=jdbcChatMemoryRepository

선택기가 없으면 단일 후보가 존재할 때만 자동 구성이 활성화됩니다.

현재 제한사항

  • 문자 대화 기록만 유지됩니다.
  • 도구 호출, 도구 결과, 추론 메시지 및 첨부 파일은 유지되지 않습니다.
  • Spring AI TOOL 메시지는 로드 시 건너뜁니다.
  • 메시지 메타데이터는 왕복을 통해 보존되지 않습니다.

벡터 스토어 스타터

개요

koog-spring-ai-starter-vector-store 스타터는 Spring AI 벡터 저장소 추상화를 Koog의 RAG 저장소 인터페이스와 연결합니다. 다음을 자동으로 구성합니다.

  • Koog KoogVectorStore로 노출된 SpringAiKoogVectorStore 어댑터

KoogVectorStore은 다음을 결합합니다.

  • WriteStorage<TextDocument>
  • SearchStorage<TextDocument, SimilaritySearchRequest>
  • FilteringDeletionStorage

예에서는 일반적으로 구체적인 문서 유형으로 DocumentWithMetadata을 사용합니다.

종속성 추가

Spring AI 벡터 저장소 스타터와 함께 종속성을 추가합니다.

그레이들(Kotlin DSL)

1dependencies {2    implementation("ai.koog:koog-spring-ai-starter-vector-store:$koogVersion")3    implementation("org.springframework.ai:spring-ai-starter-vector-store-pgvector")4}

메이븐

1<dependencies>2    <dependency>3        <groupId>ai.koog</groupId>4        <artifactId>koog-spring-ai-starter-vector-store</artifactId>5        <version>${koog.version}</version>6    </dependency>7    <dependency>8        <groupId>org.springframework.ai</groupId>9        <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>10    </dependency>11</dependencies>

이용 가능한 제공업체

스타터는 PgVector를 포함하여 VectorStore을 노출하는 모든 Spring AI 구현과 함께 작동합니다. Azure AI 검색, Cassandra, Chroma, Elasticsearch, Milvus, MongoDB Atlas, Neo4j, OpenSearch, 오라클, Pinecone, Qdrant, Redis, Typesense 및 Weaviate.

구성

일반적으로 Spring AI 벡터 저장소 설정 외에는 추가 Koog 구성이 필요하지 않습니다.

1## Koog vector-store starter defaults2koog.spring.ai.vectorstore.enabled=true3koog.spring.ai.vectorstore.dispatcher.type=AUTO

단일 VectorStore 빈이 있으면 모든 것이 자동으로 작동합니다. 어댑터는 이를 Koog KoogVectorStore로 래핑합니다.

사용예

KoogVectorStore을 Spring 구성 요소에 직접 주입합니다.

코틀린

1import ai.koog.rag.base.TextDocument2import ai.koog.rag.base.storage.search.SearchResult3import ai.koog.rag.base.storage.search.SimilaritySearchRequest4import ai.koog.spring.ai.vectorstore.DocumentWithMetadata5import ai.koog.spring.ai.vectorstore.KoogVectorStore6import org.springframework.stereotype.Service78@Service9class MyKnowledgeBase(10    private val vectorStore: KoogVectorStore,11) {1213    suspend fun ingest(text: String): List<String> {14        return vectorStore.add(15            listOf(16                DocumentWithMetadata(17                    content = text,18                    metadata = mapOf("source" to "user")19                )20            )21        )22    }2324    suspend fun search(query: String): List<SearchResult<TextDocument>> {25        return vectorStore.search(26            SimilaritySearchRequest(queryText = query, limit = 5)27        )28    }2930    suspend fun remove(ids: List<String>) {31        vectorStore.delete(ids)32    }33}

구성 속성(koog.spring.ai.vectorstore)

재산 유형 기본 설명
enabled Boolean true 벡터 저장소 자동 구성 활성화 또는 비활성화
vector-store-bean-name String? null 여러 상점이 있을 때 사용할 VectorStore의 빈 이름
dispatcher.type AUTO / IO AUTO 벡터 저장 호출을 차단하는 디스패처
dispatcher.parallelism Int 0 (= 무제한) IO 디스패처의 최대 동시성

다중 매장 컨텍스트

여러 개의 VectorStore Bean이 등록된 경우 사용할 항목을 지정하십시오.

1koog.spring.ai.vectorstore.vector-store-bean-name=pgVectorStore

선택기가 없으면 단일 후보가 존재할 때만 자동 구성이 활성화됩니다.

현재 제한사항

  • Spring AI의 VectorStore 계약은 유사성 검색만 노출합니다.
  • 업데이트는 delete(ids) 다음에 add(documents)으로 구현되므로 트랜잭션이 아닙니다.
  • LookupStorage은 Spring AI에 이식 가능한 ID별 읽기 API가 없으므로 구현되지 않습니다.
  • delete(ids)은 변경되지 않은 입력 ID를 반환합니다. Spring AI는 어떤 문서가 실제로 삭제되었는지 확인하지 않습니다.
  • delete(filterExpression)은 빈 목록을 반환합니다. Spring AI는 일치하는 문서의 ID를 반환하지 않습니다.
  • 네임스페이스 범위 지정이 구현되지 않았습니다.
  • 메타데이터 값은 String, Number 또는 Boolean와 같은 기본 값이어야 합니다.

다음 단계

#Koog#JetBrains#AI Agent#Kotlin#Java#JVM