<h4 align="right"><strong class="">English</strong> | <a href="./readme_zh.md">简体中文</a></h4>
<p align="center">
<img src="https://raw.githubusercontent.com/agents-flex/agents-flex/HEAD/docs/assets/images/banner-v2.png" alt="Agents-Flex banner"/>
</p>
Agents-Flex
Agents-Flex는 Java 생태계를 위한 경량 AI 애플리케이션 개발 프레임워크입니다. 이 프레임워크는 LLM 호출, Tool Calling, Agent, 검색 증강 생성(RAG), 벡터 저장소(vector stores), 임베딩(Embedding), 이미지 생성, 오디오, MCP, Skills, Text2SQL 및 관련 기능을 명확한 모듈로 구성하여, 개발자가 특정 런타임이나 애플리케이션 프레임워크에 종속되지 않고 필요한 기능만을 조합할 수 있도록 합니다.
이 프레임워크는 지능형 고객 서비스, 엔터프라이즈 지식 기반, 자연어 데이터 분석, Agent 워크플로우, 모델 게이트웨이, AI 지원 오피스 도구, 플러그인 기반 도구 시스템 및 여러 모델 제공업체에 동시에 연결해야 하는 Java 서비스를 구축하는 데 적합합니다.
주요 특징 (Highlights)
- Java 네이티브: 핵심 모듈은 Java 8+와 호환되며 순수 Java, Spring Boot 또는 기타 JVM 스택에서 실행될 수 있습니다.
- 통합 모델 추상화(Unified model abstractions):
ChatModel, EmbeddingModel, ImageModel, RerankModel 등 다양한 인터페이스가 제공업체별 기능을 감싸서 사용합니다.
- 일관된 동기 및 스트리밍 API: 동일한 Prompt, Options, Interceptor, 그리고 Context 메커니즘이 일반 채팅 출력과 스트리밍 출력을 모두 처리할 수 있습니다.
- 완벽한 Tool Calling 흐름: 어노테이션 기반 스캐닝, 프로그래밍 방식 도구 구축, 도구 실행, 도구 메시지 피드백 및 도구 수준의 관측 가능성(observability)을 지원합니다.
- 내구성 있는 Agent 런타임 (Durable Agent runtime): 스냅샷 복구, 도구 승인, 버전 안전한 영속성(persistence), 미들웨어, 이벤트 스트림 기능을 제공합니다.
- 완벽한 RAG 구축 블록: 문서 모델, 파싱(parsing), 분할(splitting), 임베딩(Embedding), 벡터 저장소, 검색(retrieval) 및 Rerank 지원을 포함합니다.
- 프로덕션 지향 설계 (Production-oriented design): 모델 라우팅, 재시도(retry), 부하 분산(load balancing), 서킷 브레이킹(circuit breaking), OpenTelemetry 관측 가능성, 그리고 Text2SQL 안전 인터셉터를 포함합니다.
모듈 (Modules)
| 모듈 (Module) | 설명 (Description) |
|---|
agents-flex-core | 핵심 추상화 요소: 채팅(Chat), 프롬프트(Prompt), 메시지(Message), 도구(Tool), 메모리(Memory), 문서(Document), 저장소(Store), 및 관찰 가능성(observability) |
요구사항 (Requirements)
- 대부분의 모듈: JDK 8 이상
agents-flex-mcp: JDK 17 이상- 빌드 도구: Maven
현재 리포지토리 버전은 루트 pom.xml의 revision 속성에 의해 정의되며, 현재는 2.3.1입니다.
설치 (Installation)
일반 Java 프로젝트의 경우, 집계 의존성(aggregate dependency)을 사용할 수 있습니다:
<dependency>
<groupId>com.agentsflex</groupId>
<artifactId>agents-flex-bom</artifactId>
...
Spring Boot 프로젝트의 경우, 스타터(starter)를 사용하십시오:
<dependency>
<groupId>com.agentsflex</groupId>
<artifactId>agents-flex-spring-boot-starter</artifactId>
...
필요한 모듈만 개별적으로 의존성을 추가할 수도 있습니다:
<dependency>
<groupId>com.agentsflex</groupId>
<artifactId>agents-flex-chat-openai</artifactId>
...
빠른 시작 (Quick Start)
다음 예제는 OpenAI와 호환되는 API를 사용합니다. endpoint, model, 및 apiKey를 자체 모델 서비스 구성으로 교체하십시오.
import com.agentsflex.core.model.chat.ChatModel;
import com.agentsflex.model.chat.openai.OpenAIChatConfig;
...
스트리밍 출력(Streaming output):
import com.agentsflex.core.model.chat.StreamResponseListener;
import com.agentsflex.core.model.chat.response.AiMessageResponse;
import com.agentsflex.core.model.client.StreamContext;
...
비즈니스 메서드는 어노테이션을 사용하여 도구(tool)로 노출될 수 있습니다:
import com.agentsflex.core.model.chat.tool.annotation.ToolDef;
import com.agentsflex.core.model.chat.tool.annotation.ToolParam;
...
도구를 Prompt에 등록한 후, 모델은 필요할 때 해당 도구를 호출할 수 있습니다:
import com.agentsflex.core.model.chat.response.AiMessageResponse;
import com.agentsflex.core.prompt.SimplePrompt;
...
도구가 런타임 구성(runtime configuration), 플러그인 시스템, 또는 워크플로우 노드에서 오는 경우에도 Tool.builder()를 사용하여 동적으로 구축할 수 있습니다.
더 큰 도구 세트의 경우, ToolGroup을 사용하여 최신 사용자 프롬프트와 일치할 때만 도구와 시스템 지침을 연결하십시오. 일치하지 않는 그룹은 요청 본문에서 제외됩니다:
ToolGroup weatherGroup = ToolGroup.builder("weather")
.addTools(ToolScanner.scan(WeatherTools.class))
.systemPrompt("Always use a weather tool for live weather questions.")
...
프롬프트는 여러 그룹을 포함할 수 있습니다. 모든 요청은 최신 사용자 메시지에 대해 다시 일치 여부가 확인되므로, 한 턴에서 선택된 도구가 나중에 관련 없는 턴으로 누출되지 않습니다. promptContains와 promptMatches 외에도, matcher(context -> ...)는 애플리케이션별 전략을 지원합니다.
요청 본문은 모든 인터셉터가 체인의 끝에 도달한 후에만 구성됩니다. 따라서 chain.proceed() 이전에 이루어진 Prompt 및 ChatOptions 변경 사항은 최종 요청에 영향을 미칩니다:
ChatInterceptor interceptor = new ChatInterceptor() {
@Override
public AiMessageResponse intercept(BaseChatModel<?> model, ChatContext context, SyncChain chain) {
...
ChatRequestSpec은 URL, 헤더 및 재시도 구성만 포함하며 더 이상 본문을 노출하지 않습니다. 인터셉터는 원본 본문 JSON을 다시 작성하는 대신 구조화된 Prompt 및 ChatOptions 변경을 통해 요청 내용에 영향을 미칩니다.
인터셉터는 또한 각 요청에 대해 조건부로 활성화될 수 있습니다. 매처는 등록이 체인 내의 위치에 도달할 때 실행되므로, 이전 인터셉터가 만든 변경 사항을 볼 수 있습니다:
chatModel.addInterceptorRegistration(
ChatInterceptorRegistration.builder("premium-audit", new AuditChatInterceptor())
.matcher(context -> "premium".equals(context.getAttribute("plan")))
...
이후 생성되는 채팅 모델에서 공유되는 조건부 인터셉터에는 GlobalChatInterceptors.addRegistration(...)을 사용하십시오. 기존의 addInterceptor(...) API는 계속 사용할 수 있으며, 항상 일치하는 인터셉터를 등록합니다.
각 요청마다 등록(Registrations)은 오름차순의 order 값에 따라 안정적으로 정렬됩니다. 프레임워크 기본값은 관측 가능성(observability)을 -1000, 일반 인터셉터(ordinary interceptors)를 0, 그리고 Tool Group 해상도와 같은 요청 준비 작업을 1000에 배치합니다. 이 값들은 경계가 아닌 권장 사항입니다: 애플리케이션은 관측 가능성보다 먼저 실행되거나 Tool Group 해상도 이후에 실행되는 임의의 정수 값을 사용할 수 있습니다. 동일한 order를 가진 등록 항목들은 원래의 등록 순서를 유지합니다.
Agents-Flex는 구성 가능한 Agent 런타임과 범용(general-purpose) 도구 모듈을 제공합니다:
AgentRunner: 도구 호출, 승인, 일시 중지, 재개 및 지속성(persistence)을 통해 단일 AgentTurn을 진행합니다.SubagentTools: 선택적 백그라운드 작업 실행 및 출력 검색을 위한 독립적인 범용 도구입니다.SkillsTool: 로컬 Skills 디렉터리를 읽고 필요에 따라 전문화된 기능 지침과 리소스를 로드합니다.McpClientManager: MCP 서버에 연결하고 원격 도구를 Tool 인스턴스로 래핑(wrap)합니다.
이러한 기능들은 동일한 Tool, Prompt, 및 ChatModel 추상화 계층을 기반으로 구축되어 있어 결합하거나 대체하기 쉽습니다.
RAG 및 지식 기반 (RAG And Knowledge Bases)
RAG 관련 기능들은 여러 모듈에 분산되어 있습니다:
- 문서 모델:
Document, VectorData, Metadata
- 텍스트 처리: Loader, Parser, Splitter, Doc Extractor
- 벡터화(Vectorization): OpenAI, Ollama, Qwen Embedding
- 벡터 저장소: Redis, Qdrant, Chroma, Pgvector, MariaDB, Milvus, OpenSearch, Elasticsearch 등 다수
- 검색(Retrieval):
SearchWrapper, DocumentStore, VectorStore
- 관련성 최적화: Rerank 모델
일반적인 흐름은 다음과 같습니다: 문서를 로드하고, 텍스트를 분할하며, 임베딩(Embeddings)을 생성한 후, 이를 벡터 저장소에 기록하고, 사용자 질문에 대한 관련 구절을 검색하여, 최종적으로 ChatModel이 답변을 생성하도록 합니다.
LLM Wiki
LLM Wiki는 Agent를 위해 설계된 계층적 지식 기반으로 이해할 수 있습니다. 단순히 지식을 평면적인 청크로 나누는 대신, 경로(paths), 제목(titles), 요약(summaries), 페이지 본문(page bodies), 자식 페이지(child pages)를 가진 위키 트리 형태로 콘텐츠를 구성합니다. Agent는 먼저 사용 가능한 페이지의 요약을 보고, 필요할 때만 도구를 호출하여 더 구체적인 자식 페이지를 읽어내므로, 적은 컨텍스트로 단계별 탐색이 가능합니다.
agents-flex-wiki는 이 패턴을 위한 기본 추상화 요소인 Wiki, WikiProvider, 그리고 WikiTool을 제공합니다. WikiTool은 루트 또는 현재 노드의 사용 가능한 자식 Wiki를 모델에 노출하고, get_wiki_content(path)를 통해 경로별로 콘텐츠를 읽어옵니다. 이는 목차처럼 Agent가 지식을 탐색하기를 원하는 명확한 챕터 구조를 가진 문서화 시스템에 유용합니다. 또한 기존의 RAG(Retrieval-Augmented Generation), WebSearch, 그리고 Skills와 결합될 수 있습니다.
MCP, Skills, 및 Text2SQL
agents-flex-mcp는 stdio, http-sse, 그리고 http-stream 전송 방식을 지원합니다. mcp-servers.json에서 MCP 서비스를 로드하고 MCP 도구를 Agents-Flex 도구로 변환할 수 있습니다.
agents-flex-skills는 파일 시스템 기반의 Skills를 지원하며, 이는 코드 검토(code review), 문서 생성(document generation), 파일 처리(file processing), 그리고 로컬 지식 검색과 같은 반복 가능한 전문 작업을 패키징하는 데 유용합니다.
agents-flex-text2sql은 자연어 데이터 분석을 목표로 합니다. 이 도구는 데이터 소스 목록화, 테이블 스키마 검사, SQL 실행 기능을 제공하며, 내장된 읽기 전용 SQL 검사(read-only SQL checks), 매개변수화된 쿼리 제약 조건(parameterized-query constraints), LIMIT 제어, 테넌트 격리(tenant isolation), 및 감사 확장 지점(audit extension points)을 포함합니다.
모델 라우팅 및 관측 가능성 (Model Routing And Observability)
이 프레임워크에는 여러 모델 인스턴스를 하나의 RoutedChatModel 또는 RoutedEmbeddingModel로 결합할 수 있는 모델 라우팅 기능이 포함되어 있습니다. 이는 다음을 지원합니다:
- 최소 활성 부하 분산(Least-active load balancing)
- 가중치 기반 무작위 부하 분산(Weighted random load balancing)
- 태그 기반 라우팅(Tag-based routing)
- 자동 재시도(Automatic retry)
- 회로 차단 및 반개방 복구(Circuit breaking and half-open recovery)
- 런타임 메트릭(Runtime metrics)
관측 가능성(Observability)은 OpenTelemetry를 기반으로 하며 트레이싱(tracing) 및 메트릭 수집을 지원합니다. 시스템 속성을 사용하여 Logging, OTLP 또는 사용자 정의 익스포터(exporters) 간에 전환할 수 있습니다:
-Dagentsflex.otel.enabled=true
-Dagentsflex.otel.exporter.type=otlp
-Dagentsflex.otel.metric.export.interval=30
Spring Boot
agents-flex-spring-boot-starter는 다음 항목에 대한 자동 구성을 제공합니다:
- Chat: OpenAI, Qwen, Ollama, DeepSeek
- Store: Alibaba Cloud, Chroma, Elasticsearch, OpenSearch, Tencent Cloud
이는 기존 Spring Boot 서비스에 모델과 벡터 스토어(vector store)를 빠르게 통합하도록 설계되었습니다.
Repository Structure
agents-flex-core/ Core API 및 기본 구현체
agents-flex-async-task/ 내구성 있는 비동기 작업 추적 및 스케줄링
agents-flex-async-task-store/ JDBC 및 Redis 기반 비동기 작업 저장소
...
Local Build
의존성을 가진 단일 모듈을 빌드하거나 테스트하려면:
mv -pl agents-flex-chat/agents-flex-chat-openai -am test
Documentation
- 중국어 문서 홈:
docs/zh/index.md
- 영어 문서 홈:
docs/en/index.md
- 빠른 시작 가이드:
docs/zh/chat/getting-started.md
- Maven 의존성:
docs/zh/intro/maven.md
- MCP:
docs/zh/chat/mcp.md
- Skills:
docs/zh/chat/skills.md
- Subagent:
docs/zh/chat/subagent.md
- Text2SQL:
docs/zh/chat/text2sql.md
- WebSearch:
docs/zh/chat/websearch.md
License
Agents-Flex는 Apache License 2.0에 따라 오픈 소스입니다. 자세한 내용은 LICENSE를 참조하십시오.
Contributors
<img src="https://contrib.rocks/image?repo=agents-flex/agents-flex" />
