Loading repository data…
ace19-dev / repository
LangGraph is a domain-agnostic multi-agent framework that aims to provide reusable LangChain tools and an MCP (Model Context Protocol) backend (memory, search (RAG), HTTP, scheduler, notifications, authentication, logging). You might find the flight search agent example particularly helpful.
A transparent discovery signal based on current public GitHub metadata.
This score does not audit code, security, maintainers, documentation quality, or suitability. Verify the repository and its current documentation before adoption.
도메인에 관계없이 멀티 에이전트 아키텍처에서 재사용할 수 있는 공통 Tool 및 MCP(Model Context Protocol) 구현체와, 이를 조합하여 실제 사용 사례를 보여주는 예시 시나리오로 구성된 프레임워크입니다.
Agentic AI의 핵심 구성 요소 — LLM + Tools + Memory + Evaluation + Loop.
이 프로젝트는 위 개념을 LangGraph + MCP 기반으로 실제 구현한 것입니다.
| Layer | 역할 | 구성 요소 |
|---|---|---|
| Multi-Agent Graph | LLM 에이전트들이 협력하여 작업 수행 | Planner → Executor → Reviewer |
| Tool Layer (2가지 경로) | LLM이 호출 가능한 tool 노출 | ① in-process LangChain @tool 래퍼(tools/, 동기) ② 실제 MCP 서버(mcp_servers/, FastMCP stdio — 도구명·docstring 동일) |
| Service Layer | 실제 백엔드 시스템과 연결되는 퍼사드 | 8개 서비스 클래스 (services/, 플러그인 백엔드) |
두 tool 경로는 병행 운영됩니다: main.py의 기본 워크플로우는 MCP 서버 경유(stdio 서브프로세스 + ainvoke), examples/ 3종과 flight_monitor는 기존 in-process 경로(동기 invoke)를 사용합니다. 어느 경로든 동일한 services/ 퍼사드로 수렴하므로 동작은 같습니다.
Breaking changes (2026-07):
- 과거 최상위 패키지
mcp/는 공식mcpPyPI SDK와 이름이 충돌하여services/로 개명되었습니다. 외부 프로젝트에서from mcp.xxx import ...로 퍼사드를 직접 import했다면from services.xxx import ...로 바꿔야 합니다.from tools import .../ALL_TOOLSAPI는 변경 없습니다.- 의존성이 langchain/langgraph 1.x 라인으로 올라갔습니다. langgraph 0.2.x 시절 API(
MemorySaver,interrupt/Command등)를 쓰는 소비 프로젝트는 1.x로 마이그레이션하거나 별도 가상환경을 쓰세요. 또한 MCP 경유 도구 결과가 문자열이 아닌 content block 리스트([{"type": "text", "text": ...}])로 반환됩니다 — LLM 경유(ToolNode)는 영향 없고, 결과를 직접 문자열 비교하는 코드만 텍스트 추출이 필요합니다.
START
│
▼
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Planner │──────▶│ Executor │──────▶│ Reviewer │
│ (계획 수립) │ │ (도구 실행) │◀──────│ (품질 검증) │
└─────────────┘ │ ↕ │ rev. └──────┬───────┘
│ ToolNode │ │ approved
└──────────────┘ ▼
END
Selected from shared topics, language and repository description—not editorial ratings.
getclyro /
Clyro is a governance platform for AI agents. While most tools let you watch agents fail, Clyro stops failures before they happen, catching infinite loops, runaway costs, and policy violations in real time.
79/100 healthtool_calls를 자동으로 실행하고 결과를 메시지로 반환아래 도구들은 in-process
@tool래퍼(tools/)와 MCP 서버(mcp_servers/) 어느 경로로 호출해도 이름·파라미터·반환 형식('ERROR: ...'규약 포함)이 동일합니다.
MemoryMCP — SQLite 기반 영속 KV 스토어 (네임스페이스 + TTL 지원)
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
memory_get | 저장된 값 조회 | key, namespace="default" |
memory_set | 값 저장 (TTL 선택) | key, value, namespace, ttl=0 |
memory_delete | 키 삭제 | key, namespace |
memory_list_keys | 네임스페이스 내 전체 키 목록 | namespace="default" |
RetrievalMCP — 플러그인 가능한 문서 검색 엔진
RETRIEVAL_BACKEND 환경 변수로 백엔드를 선택합니다.
| 백엔드 | 값 | 특징 | 추가 설치 |
|---|---|---|---|
| BM25 + SQLite FTS5 | bm25_sqlite | BM25 랭킹, 추가 의존성 없음, 수백만 doc 이상 처리 가능 | — |
| Vector (ChromaDB) | vector (기본값) | 임베딩 시맨틱 검색, 동의어/패러프레이즈 처리 | chromadb |
| PostgreSQL | postgres | tsvector 전문 검색, 대규모 코퍼스 | psycopg2-binary |
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
retrieval_index | 문서를 인덱스에 추가/업데이트 (청킹 선택) | doc_id, content, metadata="{}", chunk_size=0, chunk_overlap=50 |
retrieval_delete_chunks | 소스 문서의 청크 전체 삭제 | source_doc_id |
retrieval_delete | 특정 문서(또는 청크) 삭제 | doc_id |
retrieval_search | 자연어 쿼리로 문서 검색 (메타데이터 필터 지원) | query, top_k=5, filter="{}" |
retrieval_build_context | 검색 결과를 LLM 프롬프트용 컨텍스트 문자열로 조립 | query, top_k=5, max_chars=3000, filter="{}" |
RAG 흐름:
1. retrieval_index(chunk_size=500) ← 문서를 청크 단위로 분할·인덱싱
2. retrieval_build_context(query) ← 관련 청크를 검색·조립하여 LLM 컨텍스트 반환
↳ "[Source: doc-id | Score: 0.85]\n청크 내용...\n\n---\n\n[Source: ...]"
filter 파라미터로 메타데이터 필터링:
filter='{"category": "billing"}' # 단일 필터
filter='{"_source_id": "faq-001"}' # 특정 소스 문서의 청크만 검색
filter='{"category": "docs", "lang": "ko"}' # 다중 필터 (AND 조건)
crawl_tools — 웹 페이지를 fetch·정제·청킹하여 Retrieval 인덱스에 자동 적재하는 RAG 수집 파이프라인
HTML 파싱 전략: BeautifulSoup 설치 시 고품질 텍스트 추출, 미설치 시 정규식 fallback
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
crawl_and_index | 단일 URL을 fetch하여 청킹·인덱싱 | url, doc_id="", chunk_size=500, chunk_overlap=50, metadata="{}", css_selector="" |
crawl_and_index_urls | JSON 배열로 받은 여러 URL을 일괄 수집 | urls_json, chunk_size=500, chunk_overlap=50, metadata="{}", css_selector="", request_delay=1.0 |
crawl_sitemap | sitemap.xml을 파싱하여 전체 사이트 크롤링 | sitemap_url, max_pages=50, chunk_size=500, chunk_overlap=50, metadata="{}", css_selector="", request_delay=1.0 |
crawl_recursive | 시작 URL에서 링크를 BFS로 따라가며 재귀 크롤링 | start_url, max_pages=20, same_domain_only=True, chunk_size=500, chunk_overlap=50, metadata="{}", css_selector="", request_delay=1.0 |
크롤링 워크플로우:
crawl_and_index(url)
↓
fetch URL → BeautifulSoup 정제 → delete_chunks(기존 청크 제거)
↓
TextChunker(chunk_size=500, chunk_overlap=50) → retrieval_index x N
↓
"indexed 'url': 12 chunks"
beautifulsoup4설치를 권장합니다.crawl_recursive는 필수입니다.
HttpMCP — 자동 재시도·백오프·타임아웃이 적용된 HTTP 클라이언트
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
http_get | HTTP GET 요청 | url, headers="{}", params="{}" |
http_post | HTTP POST (JSON body) | url, json_body="{}", headers="{}" |
응답: {"status_code": int, "body": str, "ok": bool, "headers": dict}
SchedulerMCP — 플러그인 가능한 백그라운드 작업 스케줄러
SCHEDULER_BACKEND 환경 변수로 백엔드를 선택합니다.
| 백엔드 | 값 | 특징 | 추가 설치 |
|---|---|---|---|
| APScheduler | apscheduler (기본값) | 인-프로세스, SQLite 영속 | — |
| Celery | celery | 분산 실행, Redis/RabbitMQ 브로커 | celery[redis] |
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
schedule_create | 새 작업 스케줄 등록 | job_id, func_name, trigger, trigger_args, kwargs="{}" |
schedule_list | 활성 스케줄 목록 조회 | — |
schedule_remove | 스케줄 취소 및 삭제 | job_id |
trigger 값: "interval" · "cron" · "date"
trigger_args 예시:
interval → '{"seconds": 30}' or '{"minutes": 5}'
cron → '{"hour": "*/2", "minute": "0"}'
date → '{"run_date": "2026-05-01 09:00:00"}'
NotificationMCP — 멀티 채널 알림 서비스 (dry-run 지원)
Retrieval/Scheduler와 달리 채널은 단일 선택이 아닌 동시 구성입니다. 에이전트가 상황에 따라 적합한 채널 tool을 직접 선택합니다. 환경 변수가 설정된 채널만 실제 발송되며, 미설정 채널은 자동으로 콘솔 출력으로 폴백됩니다.
| 채널 | 용도 | 환경 변수 |
|---|---|---|
| SMTP 이메일 | 보고서·요약 전달 | SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD |
| Slack | 팀 전체 알림 | SLACK_WEBHOOK_URL |
| Discord | 개발팀·커뮤니티 알림 | DISCORD_WEBHOOK_URL |
| Telegram | 온콜 담당자 모바일 푸시 | TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID |
| MS Teams | 기업 내부 채널 알림 | TEAMS_WEBHOOK_URL |
| Console | 항상 활성, dry-run 폴백 | — |
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
notify_email | 이메일 발송 | to, subject, body |
notify_slack | Slack 채널 메시지 | channel, message |
notify_discord | Discord 채널 메시지 | message |
notify_telegram | Telegram Bot 메시지 | message |
notify_teams | MS Teams 채널 메시지 (Adaptive Card) | message |
notify_console | 구조화된 콘솔 로그 | level, message |
NOTIFICATION_DRY_RUN=true설정 시 모든 채널이 실제 발송 없이 콘솔에 출력합니다.
AuthMCP — Fernet 대칭 암호화 기반 API 키 볼트 (SQLite 저장)
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
auth_store_key | API 키 암호화 저장 | service, key |
auth_get_key | 저장된 키 복호화 조회 | service |
auth_validate | 키 존재 여부 확인 (평문 노출 없음) | service |
auth_list_services | 저장된 전체 서비스 목록 조회 (평문 노출 없음) | — |
auth_revoke | 저장된 키 영구 삭제 | service |
LoggingMCP — 구조화 로그 기록·조회·삭제. 에이전트가 실행 이력을 남기고 추후 분석할 수 있습니다.
LOGGING_BACKEND 환경 변수로 백엔드를 선택합니다.
| 백엔드 | 값 | write | query/tail | clear | 추가 설치 |
|---|---|---|---|---|---|
| SQLite | sqlite (기본값) | ✅ | ✅ | ✅ | — |
| File (Rotating) | file | ✅ | ✅ (현재 파일) | ✅ | — |
| Grafana Loki | loki | ✅ | ✅ (LogQL) | ❌ immutable | — |
| Elasticsearch / OpenSearch | elasticsearch | ✅ | ✅ | ✅ | — |
| Datadog | datadog | ✅ | ✅ (App key 필요) | ❌ immutable | — |
| PostgreSQL | postgres | ✅ | ✅ | ✅ | psycopg2-binary |
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
log_write | 구조화 로그 엔트리 기록 | level, message, source="", metadata="{}" |
log_query | 조건(레벨·소스·기간)으로 로그 검색 | level="", source="", since="", until="", limit=50 |
log_tail | 최신 N개 엔트리 조회 | n=20, source="" |
log_clear | 오래된 로그 삭제 | before="" (ISO 8601), source="" |
각 로그 엔트리는 다음 구조로 반환됩니다:
{
"id": 42,
"timestamp": "2026-04-30T14:30:00.123456+00:00",
"level": "INFO",
"source": "search_agent",
"message": "항공편 검색 완료",
"metadata": {"check": 3, "cheapest_price": 198.45}
}
백엔드별 설정:
# SQLite (기본값 — 설정 불필요)
LOGGING_BACKEND=sqlite
LOGGING_DB_PATH=data/agent_logs.db
# File — 10 MB 회전, 백업 5개
LOGGING_BACKEND=file
LOGGING_FILE_PATH=data/agent.log
LOGGING_FILE_MAX_BYTES=10485760
LOGGING_FILE_BACKUP_COUNT=5
# Grafana Loki
LOGGING_BACKEND=loki
LOGGING_LOKI_URL=http://localhost:3100
LOGGING_LOKI_LABELS={"app": "agentic-ai", "env": "dev"}
# Elasticsearch / OpenSearch
LOGGING_BACKEND=elasticsearch
LOGGING_ES_URL=http://localhost:9200
LOGGING_ES_INDEX=agentic-ai-logs
LOGGING_ES_API_KEY= # 선택사항
# Datadog
LOGGING_BACKEND=datadog
LOGGING_DATADOG_API_KEY=<dd-api-key>
LOGGING_DATADOG_APP_KEY=<dd-app-key> # query/tail에 필요
LOGGING_DATADOG_SITE=datadoghq.com # 또는 datadoghq.eu / us3 / us5 / ap1
LOGGING_DATADOG_SERVICE=agentic-ai
# PostgreSQL (metadata 컬럼이 JSONB — 필드 직접 쿼리 가능)
LOGGING_BACKEND=postgres
LOGGING_POSTGRES_DSN=postgresql://user:password@localhost:5432/dbname
LOGGING_POSTGRES_TABLE=agent_logs
Loki와 Datadog는 로그가 불변(immutable) 이므로
log_clear를 지원하지 않습니다.
Loki는 retention 정책, Datadog는 콘솔의 Archive 설정으로 데이터를 관리합니다.
flight_tools — 항공편 검색 tool. Mock(기본값) 또는 SerpAPI(Google Flights 실시간) 백엔드로 동작합니다.
flight_search는ALL_TOOLS에 포함되지 않습니다.configure_flight_client()로 백엔드를 초기화한 후 에이전트별로 직접 추가해야 합니다.
| Tool | 설명 | 주요 파라미터 |
|---|---|---|
flight_search | 두 공항 간 항공편을 검색하고 최저가·임계값 비교 결과 반환 | origin, destination, date, max_price, check_number=0, adults=1, return_date="", depart_after="", depart_before="" |
반환값 (JSON):
{
"check_number": 1,
"mode": "mock",
"origin": "ICN",
"destination": "NRT",
"date": "2026-08-01",
"max_price_threshold": 250000,
"cheapest_price": 198000,
"below_threshold": true,
"total_flights_found": 8,
"top5_flights": [{"flight_id": "KE703", "airline": "Korean Air", "price": 198000, ...}],
"searched_at": "2026-05-23T10:00:00"
}
백엔드 설정:
# SerpAPI (기본값 — Google Flights 실시간)
FLIGHT_API_MODE=serpapi
SERP_API_KEY=<your-serpapi-key>
FLIGHT_CURRENCY=KRW
# Mock — API 키 불필요, 로컬 테스트용
FLIGHT_API_MODE=mock
core/ — LangChain tool이 아닌 에이전트 내부에서 직접 임포트하는 공통 Python API.
core/llm.py — Provider-agnostic LLM Factory| 함수 | 설명 | 주요 파라미터 |
|---|---|---|
make_llm(tools, structured_output, thinking) | 활성 provider에 맞는 LLM 반환. tools/structured_output 지정 시 자동 바인딩 | tools=None, structured_output=None, thinking=None |
| `make_thi |