Skip to content

Spring AIとの統合

Koogは、Spring AIの抽象化とKoogエージェントフレームワークを橋渡しするSpring AI統合スターターを提供します。 モデルアクセス、メモリ、またはベクトルストレージにすでにSpring AIを使用している場合、これらのスターターを使用することで、既存のSpring AI設定を置き換えることなく、その上にKoogを組み込むことができます。

koog-spring-boot-starter との違い

koog-spring-boot-starterkoog-spring-ai スターター
LLMトランスポートKoog独自のHTTPクライアントChatModelEmbeddingModel などのSpring AI Beanに委譲
設定プロバイダーごとの ai.koog.* プロパティSpring AIスターターによって管理される標準的な spring.ai.* プロパティと、koog.spring.ai.* アダプタープロパティ
利用シーンKoogにモデルの接続性を直接管理させたい場合すでにSpring AIを使用しており、その上でKoogのエージェント、メモリ、またはRAGを利用したい場合

どちらのアプローチも独立しています。 直接的なKoogスターターのアプローチについては、Spring Boot統合を参照してください。

利用可能なスターター

モジュール目的
koog-spring-ai-starter-model-chatSpring AIの ChatModel(およびオプションの ModerationModel)をKoogの LLMClient および PromptExecutor に適合させます
koog-spring-ai-starter-model-embeddingSpring AIの EmbeddingModel をKoogの LLMEmbeddingProvider に適合させます
koog-spring-ai-starter-chat-memorySpring AIの ChatMemoryRepository をKoogの ChatHistoryProvider に適合させます
koog-spring-ai-starter-vector-storeSpring AIの VectorStore を、インジェクション、検索、および削除用のKoog KoogVectorStore に適合させます

各スターターは、独自の自動構成と設定プロパティを備えた独立したSpring Bootスターターです。 1つのスターターのみを使用することも、同じアプリケーション内で複数のスターターを組み合わせることも可能です。

ディスパッチャーのタイプ (Dispatcher Types)

4つのスターターすべてが、同じディスパッチャー構成パターンをサポートしています。

  • AUTO (デフォルト): 利用可能な場合はSpring管理の AsyncTaskExecutor を使用し、そうでない場合は Dispatchers.IO にフォールバックします。
  • IO: 常に Dispatchers.IO を使用します。
  • dispatcher.parallelism: 0 より大きく、かつ type=IO の場合、Dispatchers.IO.limitedParallelism(parallelism) を使用します。

通常、特にSpring Bootの仮想スレッド(Virtual threads)を使用している場合は、AUTO が最もシンプルな選択肢です。

チャットモデルスターター (Chat Model Starter)

概要

koog-spring-ai-starter-model-chat スターターは、Spring AIのチャットモデル抽象化とKoogエージェントフレームワークを橋渡しします。 以下の内容を自動構成します:

  • Spring AIの ChatModel に委譲する Koog の LLMClient (SpringAiLLMClient)
  • 利用可能なすべての LLMClient Beanから組み立てられた PromptExecutor (MultiLLMPromptExecutor)

ツールは常にKoogエージェントフレームワークによって実行されます。 Spring AIはツールの定義とスキーマのみを受け取り、internalToolExecutionEnabledfalse に設定されます。

依存関係の追加

任意のSpring AIチャットモデルスターターと一緒に依存関係を追加します:

kotlin
dependencies {
    implementation("ai.koog:koog-agents-jvm:$koogVersion")
    implementation("ai.koog:koog-spring-ai-starter-model-chat:$koogVersion")
    implementation("org.springframework.ai:spring-ai-starter-model-openai")
}
xml
<dependencies>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-agents-jvm</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-spring-ai-starter-model-chat</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
</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のプロパティを追加します:

properties
# Spring AI プロバイダー設定の例
spring.ai.openai.api-key=${OPENAI_API_KEY}

# Koog チャットスターターのデフォルト値
koog.spring.ai.chat.enabled=true
koog.spring.ai.chat.dispatcher.type=AUTO

単一の ChatModel Beanが存在する場合、すべてが自動的に動作します。 アダプターがそれをKoogの LLMClient でラップし、すぐに使用可能な PromptExecutor を作成します。

使用例

PromptExecutor をインジェクトし、それを使用してKoogエージェントを実行します:

kotlin
import ai.koog.agents.core.agent.AIAgent
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.model.PromptExecutor
import org.springframework.stereotype.Service

@Service
class MyAgentService(private val promptExecutor: PromptExecutor) {

    suspend fun askAgent(userMessage: String): String {
        val agent = AIAgent(
            promptExecutor = promptExecutor,
            llmModel = OpenAIModels.Chat.GPT5Nano,
            systemPrompt = "You are a helpful assistant."
        )

        return agent.run(userMessage)
    }
}
java
import ai.koog.agents.core.agent.AIAgent;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;
import ai.koog.prompt.executor.model.PromptExecutor;
import org.springframework.stereotype.Service;

@Service
public class MyAgentService {
    private final PromptExecutor promptExecutor;

    public MyAgentService(PromptExecutor promptExecutor) {
        this.promptExecutor = promptExecutor;
    }

    public String askAgent(String userMessage) {
        var agent = AIAgent.builder()
                .promptExecutor(promptExecutor)
                .llmModel(OpenAIModels.Chat.GPT5Nano)
                .systemPrompt("You are a helpful assistant.")
                .build();

        return agent.run(userMessage);
    }
}

または、独自の PromptExecutor Beanを提供して、自動構成されたものを完全に上書きすることもできます。

設定プロパティ (koog.spring.ai.chat)

プロパティデフォルト値説明
enabledBooleantrueチャットの自動構成を有効または無効にします
chat-model-bean-nameString?null複数のモデルが存在する場合に使用する ChatModel の Bean 名
moderation-model-bean-nameString?null使用する ModerationModel の Bean 名
providerString?nullChatModel クラスから自動検出する代わりに公開するKoogプロバイダーID
dispatcher.typeAUTO / IOAUTOブロッキングモデル呼び出し用のディスパッチャー
dispatcher.parallelismInt0 (= 無制限)IO ディスパッチャーの最大並行数

マルチモデルコンテキスト

複数の ChatModel または ModerationModel Beanが登録されている場合は、使用するものを指定します:

properties
koog.spring.ai.chat.chat-model-bean-name=openAiChatModel
koog.spring.ai.chat.moderation-model-bean-name=openAiModerationModel

セレクターがない場合、自動構成は候補が1つだけ存在する場合にのみ有効になります。

拡張ポイント

  • ChatOptionsCustomizer: ChatOptions をカスタマイズするために、このインターフェースを実装したSpring Beanを登録します。
kotlin
@Bean
fun chatOptionsCustomizer() = ChatOptionsCustomizer { options, params, model ->
    options
}
java
@Bean
public ChatOptionsCustomizer chatOptionsCustomizer() {
    return (options, params, model) -> options;
}
  • カスタム LLMClient: 独自の LLMClient Beanを登録します。springAiChatModelLLMClient という名前のBeanを置き換えない限り、自動構成されたアダプターと一緒に構成されます。
  • カスタム PromptExecutor: 独自の PromptExecutor Beanを登録して、自動構成された MultiLLMPromptExecutor を上書きします。

エンベディングモデルスターター (Embedding Model Starter)

概要

koog-spring-ai-starter-model-embedding スターターは、Spring AIのエンベディングモデル抽象化とKoogエージェントフレームワークを橋渡しします。 以下の内容を自動構成します:

  • Spring AIの EmbeddingModel に委譲する Koog の LLMEmbeddingProvider (SpringAiLLMEmbeddingProvider)

アダプターはKoogのモデルIDをSpring AIの EmbeddingOptions に転送するため、実行時のモデル選択をサポートするバックエンドはそれを尊重できます。

依存関係の追加

任意のSpring AIエンベディングモデルスターターと一緒に依存関係を追加します:

kotlin
dependencies {
    implementation("ai.koog:koog-agents-jvm:$koogVersion")
    implementation("ai.koog:koog-spring-ai-starter-model-embedding:$koogVersion")
    implementation("org.springframework.ai:spring-ai-starter-model-openai")
}
xml
<dependencies>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-agents-jvm</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-spring-ai-starter-model-embedding</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
</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のプロパティを追加します:

properties
# Spring AI プロバイダー設定の例
spring.ai.openai.api-key=${OPENAI_API_KEY}

# Koog エンベディングスターターのデフォルト値
koog.spring.ai.embedding.enabled=true
koog.spring.ai.embedding.dispatcher.type=AUTO

単一の EmbeddingModel Beanが存在する場合、すべてが自動的に動作します。 アダプターがそれをKoogの LLMEmbeddingProvider でラップします。

使用例

LLMEmbeddingProvider をインジェクトし、エンベディング操作に使用します:

kotlin
import ai.koog.prompt.executor.clients.LLMEmbeddingProvider
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import org.springframework.stereotype.Service

@Service
class MyEmbeddingService(private val embeddingProvider: LLMEmbeddingProvider) {

    suspend fun getEmbedding(text: String): List<Double> {
        return embeddingProvider.embed(
            text,
            OpenAIModels.Embeddings.TextEmbedding3Small
        )
    }
}
java
import ai.koog.prompt.executor.clients.LLMEmbeddingProvider;
import ai.koog.prompt.executor.clients.openai.OpenAIModels;
import org.springframework.stereotype.Service;
import java.util.List;

@Service
public class MyEmbeddingService {
    private final LLMEmbeddingProvider embeddingProvider;

    public MyEmbeddingService(LLMEmbeddingProvider embeddingProvider) {
        this.embeddingProvider = embeddingProvider;
    }

    public List<Double> getEmbedding(String text) {
        return embeddingProvider.embed(
                text,
                OpenAIModels.Embeddings.TextEmbedding3Small
        );
    }
}

または、独自の LLMEmbeddingProvider Beanを提供して、自動構成されたアダプターを完全に上書きすることもできます。

設定プロパティ (koog.spring.ai.embedding)

プロパティデフォルト値説明
enabledBooleantrueエンベディングの自動構成を有効または無効にします
embedding-model-bean-nameString?null複数のモデルが存在する場合に使用する EmbeddingModel の Bean 名
dispatcher.typeAUTO / IOAUTOブロッキングエンベディング呼び出し用のディスパッチャー
dispatcher.parallelismInt0 (= 無制限)IO ディスパッチャーの最大並行数

マルチモデルコンテキスト

複数の EmbeddingModel Beanが登録されている場合は、使用するものを指定します:

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

セレクターがない場合、自動構成は候補が1つだけ存在する場合にのみ有効になります。

拡張ポイント

  • カスタム LLMEmbeddingProvider: 独自のBeanを登録して、自動構成されたアダプターを完全に上書きします。

チャットメモリスターター (Chat Memory Starter)

概要

koog-spring-ai-starter-chat-memory スターターは、Spring AIのチャットメモリ抽象化とKoogエージェントフレームワークを橋渡しします。 以下の内容を自動構成します:

  • Spring AIの ChatMemoryRepository に委譲する Koog の ChatHistoryProvider (SpringAiChatHistoryProvider)

このスターターは、Koogの完全な実行状態の永続化ではなく、テキストのみの会話の永続化を提供します。

テキストのみの制約

プレーンテキストの SystemUser、および Assistant メッセージのみが永続化されます。 保存時に以下のメッセージは黙って破棄されます:

  • Message.Tool.Call
  • Message.Tool.Result
  • Message.Reasoning
  • 添付ファイル(attachments)を持つすべてのメッセージ

読み込み時、Spring AIの TOOL 行は黙ってスキップされます。 タイムスタンプ、トークン数、終了理由、カスタムメタデータなどのメタデータは保持されません。

依存関係の追加

Spring AIチャットメモリリポジトリの実装と一緒に依存関係を追加します:

kotlin
dependencies {
    implementation("ai.koog:koog-agents-jvm:$koogVersion")
    implementation("ai.koog:koog-spring-ai-starter-chat-memory:$koogVersion")
    implementation("org.springframework.ai:spring-ai-starter-model-chat-memory-repository-jdbc")
}
xml
<dependencies>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-agents-jvm</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-spring-ai-starter-chat-memory</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-chat-memory-repository-jdbc</artifactId>
    </dependency>
</dependencies>

利用可能なプロバイダー

このスターターは、JDBC、Redis、Cassandra、Cosmos DB、MongoDB、および Neo4j ベースのリポジトリを含む、ChatMemoryRepository を公開するすべての Spring AI チャットメモリリポジトリ実装で動作します。

設定

通常、Spring AI リポジトリの設定以外に特別な構成は必要ありません:

properties
# Koog チャットメモリスターターのデフォルト値
koog.spring.ai.chat-memory.enabled=true
koog.spring.ai.chat-memory.dispatcher.type=AUTO

単一の ChatMemoryRepository Beanが存在する場合、すべてが自動的に動作します。 アダプターがそれをKoogの ChatHistoryProvider でラップします。

使用例

自動構成された ChatHistoryProvider を使用して、エージェントに ChatMemory 機能をインストールします:

kotlin
import ai.koog.agents.chatMemory.feature.ChatMemory
import ai.koog.agents.chatMemory.feature.ChatHistoryProvider
import ai.koog.agents.core.agent.AIAgent
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.model.PromptExecutor
import org.springframework.stereotype.Service

@Service
class MyAgentService(
    private val promptExecutor: PromptExecutor,
    private val chatStorage: ChatHistoryProvider,
) {

    suspend fun askAgent(userMessage: String, sessionId: String): String {
        val agent = AIAgent(
            promptExecutor = promptExecutor,
            llmModel = OpenAIModels.Chat.GPT5Nano,
            systemPrompt = "You are a helpful assistant.",
        ) {
            install(ChatMemory) {
                chatHistoryProvider = chatStorage
            }
        }

        return agent.run(userMessage, sessionId)
    }
}

設定プロパティ (koog.spring.ai.chat-memory)

プロパティデフォルト値説明
enabledBooleantrueチャットメモリの自動構成を有効または無効にします
chat-memory-repository-bean-nameString?null複数のリポジトリが存在する場合に使用する ChatMemoryRepository の Bean 名
dispatcher.typeAUTO / IOAUTOブロッキングリポジトリ呼び出し用のディスパッチャー
dispatcher.parallelismInt0 (= 無制限)IO ディスパッチャーの最大並行数

マルチリポジトリコンテキスト

複数の ChatMemoryRepository Beanが登録されている場合は、使用するものを指定します:

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

セレクターがない場合、自動構成は候補が1つだけ存在する場合にのみ有効になります。

現在の制限事項

  • テキストの会話履歴のみが永続化されます
  • ツール呼び出し、ツール結果、推論メッセージ、および添付ファイルは永続化されません
  • 読み込み時、Spring AIの TOOL メッセージはスキップされます
  • ラウンドトリップを通じてメッセージのメタデータは保持されません

ベクトルストアスターター (Vector Store Starter)

概要

koog-spring-ai-starter-vector-store スターターは、Spring AIのベクトルストア抽象化とKoogのRAGストレージインターフェースを橋渡しします。 以下の内容を自動構成します:

  • Koog KoogVectorStore として公開される SpringAiKoogVectorStore アダプター

KoogVectorStore は以下を組み合わせたものです:

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

例では通常、具体的なドキュメント型として DocumentWithMetadata を使用します。

依存関係の追加

Spring AIベクトルストアスターターと一緒に依存関係を追加します:

kotlin
dependencies {
    implementation("ai.koog:koog-spring-ai-starter-vector-store:$koogVersion")
    implementation("org.springframework.ai:spring-ai-starter-vector-store-pgvector")
}
xml
<dependencies>
    <dependency>
        <groupId>ai.koog</groupId>
        <artifactId>koog-spring-ai-starter-vector-store</artifactId>
        <version>${koog.version}</version>
    </dependency>
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-vector-store-pgvector</artifactId>
    </dependency>
</dependencies>

利用可能なプロバイダー

このスターターは、PgVector, Azure AI Search, Cassandra, Chroma, Elasticsearch, Milvus, MongoDB Atlas, Neo4j, OpenSearch, Oracle, Pinecone, Qdrant, Redis, Typesense, および Weaviate を含む、VectorStore を公開するすべての Spring AI 実装で動作します。

設定

通常、Spring AI ベクトルストアの設定以外に特別な Koog 構成は必要ありません:

properties
# Koog ベクトルストアスターターのデフォルト値
koog.spring.ai.vectorstore.enabled=true
koog.spring.ai.vectorstore.dispatcher.type=AUTO

単一の VectorStore Beanが存在する場合、すべてが自動的に動作します。 アダプターがそれをKoogの KoogVectorStore でラップします。

使用例

KoogVectorStore を Spring コンポーネントに直接インジェクトします:

kotlin
import ai.koog.rag.base.TextDocument
import ai.koog.rag.base.storage.search.SearchResult
import ai.koog.rag.base.storage.search.SimilaritySearchRequest
import ai.koog.spring.ai.vectorstore.DocumentWithMetadata
import ai.koog.spring.ai.vectorstore.KoogVectorStore
import org.springframework.stereotype.Service

@Service
class MyKnowledgeBase(
    private val vectorStore: KoogVectorStore,
) {

    suspend fun ingest(text: String): List<String> {
        return vectorStore.add(
            listOf(
                DocumentWithMetadata(
                    content = text,
                    metadata = mapOf("source" to "user")
                )
            )
        )
    }

    suspend fun search(query: String): List<SearchResult<TextDocument>> {
        return vectorStore.search(
            SimilaritySearchRequest(queryText = query, limit = 5)
        )
    }

    suspend fun remove(ids: List<String>) {
        vectorStore.delete(ids)
    }
}

設定プロパティ (koog.spring.ai.vectorstore)

プロパティデフォルト値説明
enabledBooleantrueベクトルストアの自動構成を有効または無効にします
vector-store-bean-nameString?null複数のストアが存在する場合に使用する VectorStore の Bean 名
dispatcher.typeAUTO / IOAUTOブロッキングベクトルストア呼び出し用のディスパッチャー
dispatcher.parallelismInt0 (= 無制限)IO ディスパッチャーの最大並行数

マルチストアコンテキスト

複数の VectorStore Beanが登録されている場合は、使用するものを指定します:

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

セレクターがない場合、自動構成は候補が1つだけ存在する場合にのみ有効になります。

現在の制限事項

  • Spring AIの VectorStore コントラクトは類似性検索(similarity search)のみを公開しています
  • 更新(Update)は delete(ids) の後に add(documents) を行う形式で実装されているため、トランザクションではありません
  • Spring AIにはポータブルなIDによる読み込みAPIがないため、LookupStorage は実装されていません
  • delete(ids) は入力されたIDを変更せずに返します。Spring AIはどのドキュメントが実際に削除されたかを返しません
  • delete(filterExpression) は空のリストを返します。Spring AIは一致したドキュメントのIDを返しません
  • ネームスペースによるスコーピングは実装されていません
  • メタデータの値は StringNumber、または Boolean などのプリミティブ値である必要があります

次のステップ