agents-flex/agents-flex

Agents-flex is A lightweight Java AI agent development framework (positioned as a counterpart to Spring AI). It supports features such as RAG, MCP, Skills, Text2SQL , LLM Wiki, Sub-agents, Web Search, TTS (synchronous and streaming), and STT.

Agents-Flex란 무엇인가요?

Agents-Flex는 대규모 언어 모델(LLM) 및 기타 AI 서비스와 대화하는 애플리케이션을 구축하기 위한 Java 우선 프레임워크입니다. LLM 기반 시스템의 일반적인 구성 요소(채팅, 임베딩, 이미지/오디오 생성, 도구 호출, 검색 증강 생성(RAG), 벡터 저장소, 관측 가능성 등)를 자유롭게 조합 가능한 모듈식 Maven 아티팩트 세트로 묶어 제공합니다. 목표는 Java 개발자가 특정 런타임(일반 Java, Spring Boot, 기타 JVM 스택)에 얽매이지 않고 필요한 부분만 구성할 수 있도록 하는 것입니다.

핵심 아이디어 및 아키텍처

아이디어	코드에서의 구현
통합 모델 추상화	`ChatModel`, `EmbeddingModel`, `ImageModel`, `RerankModel`과 같은 인터페이스가 공급자별 API(OpenAI, Qwen, Ollama 등)를 숨깁니다.
동기 및 스트리밍 API	동일한 `Prompt`, `ChatOptions` 및 인터셉터 체인이 일반 `chat()` 호출과 `chatStream()` 콜백 모두에서 작동합니다.
도구 호출	주석이 달린 Java 메서드(`@ToolDef`, `@ToolParam`)가 `Tool` 객체로 스캔됩니다. 프레임워크가 요청을 빌드하고, 도구를 실행하며, 결과를 모델에 피드백합니다.
지속 가능한 에이전트 런타임	`agents-flex-agent`는 실행 상태를 일시 중지, 재개, 스냅샷 및 지속(JDBC/Redis 저장소)할 수 있는 상태 머신을 제공합니다.
RAG 빌딩 블록	문서 로더, 파서, 스플리터, 임베딩 생성기, 벡터 저장소 어댑터 및 리랭커는 서로 연결 가능한 별도의 모듈입니다.
프로덕션 준비 완료	모델 라우팅, 로드 밸런싱, 재시도, 서킷 브레이커 및 OpenTelemetry 익스포터가 내장되어 있습니다.
플러그인 스타일 확장성	해당 인터페이스를 구현하고 모듈을 Maven 의존성으로 추가하여 새로운 도구, 벡터 저장소 또는 모델 공급자를 추가할 수 있습니다.

주요 모듈(개요)

agents-flex-core – 기본 유형(Prompt, Message, Tool, Memory, Document).
agents-flex-chat, -embedding, -image, -audio, -ocr, -video – 많은 공급자를 위한 구체적인 모델 어댑터.
agents-flex-store – Redis, Qdrant, Chroma, Milvus, Elasticsearch 등을 위한 어댑터.
agents-flex-agent & -agent-store – 턴을 조정하고, 도구 호출을 처리하며, 상태를 지속하는 런타임.
agents-flex-tool & -toolsearch – 즉시 사용 가능한 유틸리티(쉘, 파일, 웹 가져오기) 및 검색 가능한 레지스트리.
agents-flex-mcp – 외부 MCP 서비스를 Tool 객체로 변환하는 클라이언트.
agents-flex-skills 제품군 – 샌드박스화 가능한 파일 시스템 기반 "스킬 패키지".
agents-flex-text2sql – 스키마 검색 기능을 갖춘 안전한 읽기 전용 자연어-SQL 변환.
agents-flex-wiki – 에이전트가 페이지별로 탐색할 수 있는 계층적 지식 베이스.
agents-flex-spring-boot-starter – 가장 일반적인 모델 및 저장소에 대한 자동 구성.
demos – 채팅, 도구 호출, RAG 및 에이전트 워크플로우를 보여주는 실행 가능한 예제.

일반적인 사용 흐름(예시)

Maven 의존성 추가 – BOM(agents-flex-bom) 또는 필요한 특정 모듈(예: agents-flex-chat-openai + agents-flex-store-redis)을 추가합니다.
모델 구성 – 공급자별 구성 빌더를 통해 ChatModel을 생성합니다(빠른 시작 참조). 동일한 모델을 일반 호출 또는 스트리밍 호출에 사용할 수 있습니다.
도구 정의 – Java 메서드에 @ToolDef/@ToolParam을 주석으로 달거나 프로그래밍 방식으로 빌드합니다. 도구를 Prompt 또는 ToolGroup에 등록합니다.
프롬프트 빌드 – 사용자 텍스트, 시스템 지침 및 선택한 도구 그룹을 결합합니다.
모델 호출 – chat()은 AiMessageResponse를 반환합니다. hasToolCalls()가 true이면 도구를 실행하고(executeToolCallsAndGetToolMessages()) 업데이트된 프롬프트를 다시 보냅니다.
(선택 사항) 에이전트 실행 – 위 내용을 AgentRunner로 래핑하여 자동 스냅샷, 승인 후크 및 지속성을 얻습니다.
(선택 사항) RAG 추가 – 문서 로드, 분할, 임베딩, 벡터 저장소에 저장, 구절 검색, 선택적 리랭크를 수행한 다음 검색된 텍스트를 프롬프트에 입력합니다.
관찰 – OpenTelemetry 익스포터가 스팬/메트릭을 내보냅니다. -Dagentsflex.otel.enabled=true를 통해 활성화할 수 있습니다.

누가 사용해야 하나요?

Java 백엔드 팀: Python으로 전환하지 않고 LLM 기반 기능(챗봇, 코드 어시스턴트, 데이터 분석 에이전트)을 추가해야 하는 팀.
기업: 내구성, 감사 가능성 및 기존 JVM 인프라(Spring Boot, JDBC, Redis 등)와의 통합이 필요한 기업.
멀티 모델 서비스를 구축하는 개발자: 라우팅 및 로드 밸런싱 기능을 통해 OpenAI, Qwen, Ollama 등을 단일 엔드포인트에서 혼합할 수 있습니다.
플러그인 도구 생태계를 원하는 팀: 주석 기반 도구 스캐너와 MCP 클라이언트를 통해 내부 서비스를 LLM 호출 가능 도구로 쉽게 노출할 수 있습니다.

강점 및 제한 사항

강점	제한 사항
Java 네이티브 – JNI나 외부 Python 런타임이 필요 없습니다.	생태계 규모 – Python 중심 라이브러리보다 커뮤니티 기여 모듈이 적습니다.
모듈식 Maven 아티팩트 – 사용하는 것만 배포하여 최종 JAR을 작게 유지할 수 있습니다.	학습 곡선 – 인터셉터 체인과 도구 그룹 매칭으로 인해 개념적 오버헤드가 증가합니다.
프로덕션 기능 내장 (라우팅, 서킷 브레이커, OpenTelemetry).	문서 – 주로 중국어/영어 마크다운이며, 예제는 `demos` 폴더로 제한됩니다.
풍부한 도구 호출 지원 (주석, 동적 그룹, MCP).	런타임 유연성 – JVM에 묶여 있어 엣지 장치나 비 Java 스택에는 적합하지 않습니다.

빠른 시작

<dependency>
  <groupId>com.agentsflex</groupId>
  <artifactId>agents-flex-bom</artifactId>
  <version>2.3.0</version>
  <type>pom</type>
  <scope>import</scope>
</dependency>

ChatModel model = OpenAIChatConfig.builder()
    .endpoint("https://api.openai.com/v1")
    .model("gpt-4o")
    .apiKey(System.getenv("OPENAI_KEY"))
    .buildModel();

SimplePrompt p = new SimplePrompt("Summarize the latest Java 21 features.");
System.out.println(model.chat(p).getMessage().getContent());

도구 호출 및 스트리밍을 포함한 더 완전한 예제는 demos/chat-demo 모듈을 실행하세요.

라이선스 및 커뮤니티

Agents-Flex는 Apache 2.0 라이선스이며 상업적 사용이 무료입니다. 저장소에는 contrib.rocks에서 생성한 기여자 배지가 표시되어 오픈 소스 커뮤니티임을 나타내지만, README에는 개별 기여자가 나열되어 있지 않습니다.

요약: Agents-Flex는 Java 개발자에게 LLM 채팅, 도구 오케스트레이션, RAG 및 관련 AI 기능을 위한 프로덕션급 도구 상자를 제공하며, 이 모든 것은 모든 JVM 애플리케이션에 드롭인할 수 있는 교체 가능한 Maven 모듈로 패키징되어 있습니다.