10xGraph

과거 Agentflow였던 이름입니다. 10xScale의 10xGraph가 개발한, 프로덕션 AI 에이전트를 위한 그래프 엔지니어링 도구입니다.

Release

PyPI

Python

License

10xGraph는 멀티 에이전트 AI 시스템을 구축하고 이를 프로덕션 환경에서 실행하기 위한 오픈 소스 Python 프레임워크입니다. 사용자는 노드와 도구(tool)의 그래프 형태로 에이전트를 작성합니다. 10xGraph는 충돌 후에도 도구가 두 번 실행되는 것을 방지하고, 상태 쓰기(state writes)를 보호하며, 시간 초과(timeouts)를 강제합니다. 또한 10xgraph-api 패키지를 통해 그래프 주변에 API 서버를 생성할 수 있게 합니다.

이 저장소는 핵심 엔진(PyPI의 10xgraph, 임포트 시 tenxgraph)입니다. 문서는 10xgraph.com에서 확인할 수 있습니다.

제공하는 기능

1. 실패에도 올바르게 작동 (이 패키지)

• 재실행 안전 도구(Replay-safe tools). 실행 루프는 노드를 실행하기 전에 현재 노드를 영속화(persists)하므로, 노드 중간에 프로세스가 종료되어도 재개 시 해당 노드를 다시 실행합니다. 도구를 호출하기 전에 10xGraph는 체크포인터의 도구 원장(tool ledger)을 확인하고 완료된 모든 호출을 즉시 기록합니다. 이미 실행된 도구는 다시 실행되지 않습니다: 이중 청구나 중복 이메일 발송이 없습니다. 체크포인터가 필요합니다.
• 버전 관리되는 상태 쓰기(Versioned state writes). 영속적인 쓰기는 낙관적 비교 및 교환(optimistic compare-and-swap)을 사용하여, 한 스레드에서 실행되는 두 번의 작업이 서로 덮어쓰는 것을 방지합니다. Redis 캐시 쓰기 또한 버전 보호를 받습니다.
• 실제 노드 및 도구 시간 초과(Real node and tool timeouts). 실행 설정(run config)에서 node_timeout과 tool_timeout을 설정할 수 있습니다 (기본값은 각각 900초와 300초). 이를 통해 멈춘 도구가 워커를 영원히 점유하는 것을 막습니다.
• 도구 내부의 인간 승인(Human approval inside a tool). interrupt() 함수는 실행을 일시 중지하고 스레드를 저장하며, 결정과 함께 재개할 수 있습니다.

2. 프로덕션 서버가 기본으로 제공됨 (10xgraph-api, MIT)

10xgraph-api는 컴파일된 그래프를 기반으로 프로덕션 서버를 생성합니다: REST, SSE 스트리밍, WebSocket 및 실시간 오디오 엔드포인트; JWT 또는 사용자 지정 인증(auth); 모든 엔드포인트에 대한 범위별 권한 부여(scoped authorization); 스레드 소유권 격리(thread ownership isolation); 속도 제한(rate limiting); 그리고 Docker Compose 및 Kubernetes 파일. 10xgraph 명령어(10xgraph init, 10xgraph api, 10xgraph build)로 구동할 수 있습니다. 생태계 테이블을 참조하세요.

3. 확장성(Scale)에 최적화됨

• 2단계 영속성(Two-tier persistence). PgCheckpointer는 활성 스레드 상태를 Redis에 캐시하고 이를 먼저 읽습니다 (기본 TTL 24시간); PostgreSQL은 버전별 쓰기로 영구적인 기록을 보관합니다. 스레드는 재시작 및 캐시 만료 후에도 유지됩니다. SqliteCheckpointer는 로컬 작업을 처리합니다.
• Kafka, Redis Pub/Sub, RabbitMQ 및 OpenTelemetry로의 이벤트 발행(Event publishing).
• Qdrant 또는 Mem0에 장기 메모리(Long-term memory)를 구현합니다.

4. 백엔드부터 프론트엔드까지 단일 스택

• 원격 도구(Remote tools). 모델이 사용자 브라우저나 클라이언트에서 실행되는 도구를 호출할 수 있습니다. 그래프에 선언하거나 `config[

적합한 경우

설치

pip install 10xgraph

Provider SDK 및 인프라 통합은 선택적 추가 기능입니다. 사용하는 것만 설치하세요:

pip install "10xgraph[google-genai,openai,anthropic,mcp,pg_checkpoint]"

그런 다음 제공자 키를 설정하세요. 작업 디렉터리에 있는 .env 파일이 자동으로 로드됩니다.

export GEMINI_API_KEY=...        # Google Gemini
export OPENAI_API_KEY=sk-...     # OpenAI 또는 모든 OpenAI 호환 엔드포인트
export ANTHROPIC_API_KEY=sk-...  # Anthropic Claude

Python 3.12 이상이 필요합니다.

빠른 시작: 승인 단계가 있는 지원 에이전트

lookup_order는 데이터를 읽습니다. refund_order는 돈을 이동시키므로, 행동하기 전에 interrupt()를 사용하여 사람의 결정을 기다립니다. 체크포인터(checkpointer)를 사용하면 환불 후 충돌하거나 재시도해도 두 번 발행되지 않습니다.

from tenxgraph.core.state import Message
from tenxgraph.prebuilt.agent import ReactAgent
from tenxgraph.storage.checkpointer import InMemoryCheckpointer
...

ReactAgent를 RAGAgent, SwarmAgent, SupervisorTeamAgent 또는 PlanActReflectAgent로 교체해도 형태는 동일합니다. 프로덕션 환경에서는 PgCheckpointer (Postgres와 Redis)를 사용하고, 로컬 작업에는 SqliteCheckpointer를 사용하세요.

스트리밍하기:

async for chunk in app.astream(
    {"messages": [Message.text_message("Order A-1001은 어디에 있나요?")]},
    config={"thread_id": "2"},
...

fastmcp 클라이언트를 전달하여 MCP 도구 추가하기; 원격 도구가 로컬 도구와 결합됩니다:

from fastmcp import Client

mcp_client = Client({
...

자신만의 그래프 구축하기

사전 구축된 에이전트(Prebuilt agents)는 그래프입니다. 커스텀 제어 흐름(custom control flow)이 필요할 때는 직접 구축하세요:

from tenxgraph.core.graph import Agent, StateGraph, ToolNode
from tenxgraph.core.state import AgentState
from tenxgraph.utils.constants import END
...

노드(Nodes)는 일반 함수일 수도 있어, 제공업체 SDK를 직접 호출할 수 있습니다. examples/react/를 참고하세요.

실시간 오디오 에이전트 (Realtime Audio Agents)

Gemini Live를 통한 라이브 오디오-오디오 세션입니다. 제공업체가 턴 루프(turn loop)를 소유하므로, 세션은 arealtime을 통해 실행됩니다. 입력 큐에 데이터를 푸시하고 정규화된 이벤트(normalized events)를 소비합니다.

from tenxgraph.prebuilt.agent import AudioAgent
from tenxgraph.core.realtime import LiveInputQueue, RealtimeConfig
...

배지인(Barge-in), 영속화된 스크립트(persisted transcripts) (원시 오디오는 절대 저장되지 않음), 세션 재개와 자동 재연결, 이미지/비디오 프레임 입력이 자동으로 처리됩니다. system_prompt, skills, 그리고 memory는 다른 모든 에이전트에서 작동하는 방식과 동일합니다. pip install "10xgraph[realtime]"가 필요합니다.

사전 구축된 에이전트 및 패턴 (Prebuilt agents and patterns)

• 에이전트(Agents): React, RAG, Guarded, Plan-Act-Reflect, Audio, Swarm, SupervisorTeam, StructuredOutput
• 오케스트레이션(Orchestration): Router, MapReduce, Sequential, Branch-Join
• 기타(Other): InjectQ를 통한 의존성 주입(dependency injection), 스킬(skills) (Agent Skills spec), 3계층 메모리 (작업 상태(working state), 체크포인터(checkpointer), Qdrant 및 Mem0과 같은 벡터 저장소(vector stores)), 퍼블리셔(publishers) (Console, Redis, Kafka, RabbitMQ, OpenTelemetry), 평가 및 테스트 도우미

Agentflow에서 이동하기 (Moving from Agentflow)

10xGraph는 Agentflow의 새 이름입니다. 프레임워크, 라이선스 및 유지 관리자는 동일합니다. 10xscale-agentflow 0.10.1이 마지막 릴리스였습니다.

pip uninstall 10xscale-agentflow
pip install 10xgraph

먼저 제거하세요: 두 배포판 모두 agentflow 모듈을 제공하므로 나란히 설치해서는 안 됩니다.

# 이전 (before)
from agentflow.core.graph import StateGraph
# 이후 (after)
...

임포트 이름은 tenxgraph입니다. 이는 Python 식별자가 숫자로 시작할 수 없기 때문입니다. 모든 정식 경로는 agentflow가 tenxgraph로 대체된 이전 경로를 따릅니다 (예: tenxgraph.core.graph, tenxgraph.storage.checkpointer, tenxgraph.prebuilt.agent). import agentflow는 2.0 버전까지 사용 중단된 별칭(deprecated alias)으로 작동하며, 이때 DeprecationWarning이 발생합니다.

다른 이름이 변경된 식별자들 (기존 값은 명시된 곳에서 여전히 작동):

생태계 (Ecosystem)

설치부터 실행 서비스까지:

pip install 10xgraph-api         # 10xgraph를 가져옴
10xgraph init --path my-agent && cd my-agent
10xgraph api                     # :8000 포트에서 REST 및 WebSocket API 제공
...

JWT 인증 및 Redis 속도 제한이 적용된 프로덕션 스캐폴드:

10xgraph init --path my-agent --yes --template production --auth jwt --rate-limit redis

예시 (Examples)

examples/에서 실행 가능한 스크립트:

실행 예시:

export GEMINI_API_KEY=...   # 또는 OPENAI_API_KEY
python examples/react/react_single_class.py

일부 예시는 아직 이름이 변경되기 전의 임포트 경로를 사용합니다. 정식 경로는 CLAUDE.md에 나열되어 있습니다.

한계점 (Limitations)

• LangGraph나 CrewAI에 비해 커뮤니티 규모가 작고 통합(integration) 기능이 적습니다.
• 1.0 이전 버전 (현재 릴리스 라인 0.10.x): 버전을 고정하고 변경 로그(changelog)를 확인하세요.
• Agentflow에서 이름이 변경되면서 브랜드 인지도가 초기화되었습니다; "10xGraph"는 아직 검색 기록이 없습니다.
• LangGraph가 더 강력한 시각적 도구(Studio, LangSmith 관측 가능성(observability))를 갖추고 있습니다.
• Python 3.12 이상을 요구합니다. 코드로 작성하는 방식이며, 노코드 빌더(no-code builder)는 아닙니다.
• 자동화된 도구별 권한 부여(per-tool permissions)(사용자 A가 refund 호출 가능하지만 사용자 B는 불가능할 수 있음) 기능은 기본적으로 구현되어 있지 않습니다. 도구들은 tenxgraph.core.authz.has_scope를 사용하여 호출자의 검증된 범위(verified scopes)를 확인할 수 있습니다.

로드맵 (Roadmap)

• 완료됨 (Done): 노드와 엣지를 갖춘 핵심 그래프 엔진
• 완료됨 (Done): 상태 관리 및 체크포인팅
• 완료됨 (Done): 도구 통합 (MCP, 사용자 정의 도구, 병렬 실행)
• 완료됨 (Done): 스트리밍 및 이벤트 발행
• 완료됨 (Done): 인간 참여형 루프 지원(Human-in-the-loop support)
• 완료됨 (Done): 사전 구축된 에이전트 패턴
• 완료됨 (Done): 에이전트 간(Agent-to-Agent, A2A) 통신 프로토콜
• 완료됨 (Done): 관측 가능성 및 추적(Observability and tracing) (OpenTelemetry)
• 완료됨 (Done): 실시간 음성-음성 에이전트 (Gemini Live)
• 계획 중 (Planned): 분산 처리를 위한 원격 노드 실행
• 계획 중 (Planned): 더 많은 영속성 백엔드 (Redis, DynamoDB)
• 계획 중 (Planned): 병렬/분기 전략
• 계획 중 (Planned): 시각적 그래프 에디터

기여하기 (Contributing)

당신의 아바타가 이 벽에 속합니다.

위에 언급된 모든 사람은 현재 프로덕션 에이전트 내부에서 실행되는 코드를 배포했습니다. 풀 리퀘스트(pull request) 하나를 병합하여 이곳과 10xgraph.com/maintainers의 기여자 페이지에서 그들과 합류하세요.

첫 번째 풀 리퀘스트는 작아도 괜찮습니다. 이들은 오늘날 실제로 존재하며, 독립적이고 유용한 기능들입니다:

• Type one module. pyproject.toml에 나열되어 있지만 여전히 mypy가 건너뛰는 모듈을 선택합니다. 해당 모듈의 타입을 수정하고, 목록에서 그 줄을 삭제합니다. 이 목록은 점점 짧아질 것입니다.
• 존재했으면 좋았을 예시를 추가합니다. 실제 사용 사례(예: 지원 에이전트, 연구 파이프라인, 승인 흐름)에 대한 실행 가능한 스크립트를 examples/에 추가합니다.
• 버그를 실패하는 테스트로 만듭니다. 문제를 재현하는 테스트는 가장 유용한 버그 보고서입니다. 이를 초안 풀 리퀘스트(draft pull request)로 열면, 수정은 나중에 할 수 있습니다.
• 막혔던 문서를 수정합니다. 10xgraph.com의 모든 페이지에는