개요
Embabel은 JVM 기반의 에이전트 AI 프레임워크로, LLM 상호작용을 코드 및 도메인 모델과 결합합니다. 동적 계획, 강력한 타입, Spring 통합을 지원하며, 어노테이션 방식과 Kotlin DSL 두 가지 개발 방식을 제공합니다.
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을 수정하여, delegate가 Tool.Result.Error를 반환할 때 call()은 여전히 원래 Error를 반환하면서도 Result.failure(ToolReturnedError(message, cause))를 발행하도록 하세요. 반환되는 중간 결과는 변경하지 마세요. 다운스트림 복구와 Spring의 ToolExecutionException 변환이 이에 의존하기 때문입니다. delegate가 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에 오래된(stale) 중복 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가 classpath에서 LM Studio JAR보다 먼저 오도록 할 수도 있지만, JAR/classpath 순서 지정은 불안정할 수 있습니다.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 goal의 execution을 추가하세요. Gradle의 경우: springBoot { buildInfo() }를 추가하세요. 그러면 배포된 에이전트 메타데이터가 실제 애플리케이션 아티팩트 버전을 반영합니다.
문제 해결Spring AI 2.0으로 Embabel MCP 서버를 더 이상 지원되지 않는(deprecated) 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 엔드포인트를 참조하는 모든 커스텀 빈이나 구성을 제거하세요. ./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청크 요청을 더 작은 요청으로 분할합니다.