概要
Embabel は JVM 上のエージェント AI フレームワークであり、LLM とのインタラクションをコードやドメインモデルと組み合わせます。動的プランニング、強い型付け、Spring との統合をサポートし、アノテーションベースと Kotlin DSL の2つの開発方式を提供します。
README プレビュー
# [Embabel Agent Framework](https://hub.embabel.com)\n\n\n\n[](https://docs.embabel.com/embabel-agent/guide/1.5.0-SNAPSHOT/)\n[](https://mvnrepository.com/artifact/com.embabel.agent/embabel-agent-api)\n\n[](https://www.yourkit.com/)\n[](https://www.ej-technologies.com/products/jprofiler/overview.html)\n[](https://sonarcloud.io/summary/new_code?id=embabel_embabel-agent)\n[](https://discord.gg/t6bjkyj93q)\n\n[//]: # ([](https://sonarcloud.io/summary/new_code?id=embabel_embabel-agent))\n\n[//]: # ([](https://sonarcloud.io/summary/new_code?id=embabel_embabel-agent))\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n[](https://www.apache.org/licenses/LICENSE-2.0)\n[](https://github.com/embabel/embabel-agent/pulse)\n\n \n\nEmbabel (Em-BAY-bel) is a framework for authoring agentic flows on the JVM that seamlessly mix LLM-prompted interactions\nwith code and domain models. Supports\nintelligent path finding towards goals. Written in Kotlin\nbut offers a natural usage\nmodel from Java.\nFrom the creator of Spring.\n\n \n\n## Talk to the Docs\n\nHave questions? [Talk to the docs via the Embabel-powered hub](https://hub.embabel.com) — an\nEmbabel agent that answers your questions about the framework in natural language.\n\n## Key Concepts\n\nModels agentic flows in terms of:\n\n- **Actions**: Steps an agent takes\n- **Goals**: What an agent is trying to achieve\n- **Conditions**: Conditions to assess before executing an action or determining that a goal has been achieved.\n Conditions are reassessed after each action is executed.\n- **Domain model**: Objects underpinning the flow and informing Actions, Goals and Conditions.\n- **Plan**: A sequence of actions to achieve a goa
FAQ (5)
トラブル対応返された Tool.Result.Error が成功した ToolCallResponseEvent として記録・カウントされてしまう問題を修正するには？
この障害は、EventPublishingTool がスローされた例外のみを Result.failure にマッピングするために発生します。返された Tool.Result.Error は成功ブランチに進み、Result.success("<error message>") として公開されます。ToolDecorators.kt 内の EventPublishingTool を修正し、デリゲートが Tool.Result.Error を返した場合に、call() が元の Error を返すままにしつつ、Result.failure(ToolReturnedError(message, cause)) を公開するようにしてください。返される中間結果は変更しないでください。下流のリカバリ処理と Spring の ToolExecutionException 変換がそれに依存しているためです。デリゲートが Tool.Result.Error を返すテストを追加し、responseEvent.result.isFailure が true であることと、call() が引き続き元の Error を返すことの両方をアサートしてください。これにより、result.isFailure、ツール統計、および embabel.tool.errors.total がその呼び出しを正しく報告するようになります。修正を含むリリースを使用するまでの間、カスタムツールは Tool.Result.Error を返す代わりに例外をスローできますが、アノテーション付きの MethodTool および ScriptTool のエラーにはパッチが必要です。
トラブル対応Embabel LM Studio autoconfigure を使用する際に、新しい OpenAI モデル（例：gpt-5.6-luna）が見つからない問題を修正するにはどうすればよいですか？
これは、embabel-agent-lmstudio-autoconfigure に古い重複した models/openai-models.yml が含まれているために発生します。その JAR が先にロードされると、OpenAiModelLoader は embabel-agent-openai-autoconfigure 内のカタログではなくそちらを使用するため、新しいモデルが登録されません。
修正方法:
1. 重複ファイルが embabel-agent-lmstudio-autoconfigure から削除された、issue #2064 の修正を含むリリースにアップグレードしてください。
2. 一時的な回避策として、LM Studio の JAR から古いリソースを削除してください:
jar tf embabel-agent-lmstudio-autoconfigure-*.jar | grep 'models/openai-models.yml'
zip -d embabel-agent-lmstudio-autoconfigure-*.jar 'models/openai-models.yml'その後、アプリケーションを再ビルドして再パッケージ化してください。あるいは、クラスパス上で
embabel-agent-openai-autoconfigure が LM Studio の JAR より前に配置されるようにしてください。ただし、JAR/クラスパスの順序付けは不安定になりがちです。3. 起動時のログを確認してください。正しいカタログがロードされていれば、次のようなエントリが表示されるはずです:
Registered OpenAI model bean: gpt56luna -> gpt-5.6-luna長期的な対策としては、OpenAiModelLoader で getResources("models/openai-models.yml") を呼び出し、カタログのコピーが複数見つかった場合に警告または失敗させる方法があります。
トラブル対応Embabelエージェントにアプリケーションのビルドバージョンではなく、バージョン0.1.0-SNAPSHOTが表示されるのはなぜですか？
明示的な @Agent(version = "...") を指定せずに宣言されたエージェントは、以前はフレームワークのデフォルト 0.1.0-SNAPSHOT にフォールバックしていました。これは、アノテーションがコンパイル時定数を必要とし、Maven/Gradle プロジェクトのバージョンを読み取ることができないためです。PR #2113 で修正され、AgentMetadataReader が使用する AgentVersionResolver によって、バージョンは次の順序で解決されます: 1) 設定されている場合は明示的な @Agent(version = "..."); 2) build-info が生成されている場合は Spring Boot の BuildProperties.version; 3) エージェントクラスのパッケージの JAR マニフェストの Implementation-Version; 4) 最終フォールバックとしての Semver.DEFAULT_VERSION。ビルドバージョンをエージェントメタデータに含めるには、バージョンを明示的に設定する（@Agent(description = "...", version = "2.0.0")）か、Spring Boot の build-info 生成を有効にしてください。Maven の場合: spring-boot-maven-plugin に build-info ゴールの実行を追加します。Gradle の場合: springBoot { buildInfo() } を追加します。これにより、デプロイされたエージェントのメタデータに実際のアプリケーションアーティファクトのバージョンが反映されます。
トラブル対応Spring AI 2.0でEmbabel MCPサーバーを非推奨のSSEからStreamable HTTPに移行するにはどうすればよいですか？
MCP Streamable HTTP 移行を含む Embabel リリースを使用してください。この移行では、SSE 専用の McpSseShutdownConfiguration が削除され、WebMvcSseServerTransportProvider は使用されなくなります。その後、以下を追加して Spring AI の自動設定にトランスポートを選択させます。
spring.ai.mcp.server.protocol=STREAMABLEまたは YAML:
spring:
ai:
mcp:
server:
protocol: STREAMABLEWebMvcSseServerTransportProvider、McpSseShutdownConfiguration、またはレガシー SSE エンドポイントを参照しているカスタム Bean や設定をすべて削除してください。./mvnw clean package でリビルドします。リモート MCP クライアントやエージェント間 (agent-to-agent) クライアントは、以前の SSE エンドポイントではなく、Streamable HTTP エンドポイントに接続する必要があります。この変更を含むバージョンでは、Embabel はトランスポート処理を Spring AI に委譲し、SSE 固有のシャットダウンコードパスを保持しなくなります。
トラブル対応低速なローカルのOpenAI互換またはDocker埋め込みモデルのタイムアウトを延長するにはどうすればよいですか？
issue #2083の修正を含むリリースにアップグレードし、ハードコードされたクライアントのデフォルト値に依存するのではなく、connect-timeoutとread-timeoutを設定してください。Docker Model Runnerの場合、例えば次のように設定します。
embabel:
agent:
platform:
models:
docker:
connect-timeout: 5s
read-timeout: 30m汎用的なOpenAI互換プロバイダーの場合は、そのプロバイダーの設定で同じconnect-timeoutとread-timeoutプロパティを設定してください。パッチが適用された実装では、これらの値は埋め込みクライアントとcompletion/chatクライアントの両方に適用され、Spring AIのリクエストごとのオプションにも伝播されます。このオプションは、そうしなければ60秒のタイムアウトを送信してHTTPクライアントの設定を上書きしてしまいます。デフォルトはconnectが5秒、readが10分のままです。古いバージョンでは、唯一の回避策は埋め込みのバッチサイズを小さくすることです。例えば、800チャンクのリクエストをより小さなリクエストに分割します。