AgentFlow — 에이전트 코드에서 프로덕션 API까지 몇 분 안에

Source: Dev.to

같은 에이전트 인프라를 계속 재구축하지 마세요. AgentFlow는 인증, 스트리밍, 지속성, 그리고 React 프런트엔드를 즉시 제공합니다.

AgentFlow (10xscale-agentflow on PyPI)는 멀티 에이전트 AI 시스템을 구축하고 배포하기 위한 오픈‑소스 파이썬 프레임워크입니다. 에이전트 그래프를 한 번 작성하고 로컬에서 실행한 뒤, 백엔드를 다시 작성하지 않고도 프로덕션에 배포할 수 있습니다.

Built by 10xScale. MIT licensed. No vendor lock‑in.

왜 AgentFlow인가?

대부분의 에이전트 프레임워크는 프로토타입 단계에서 멈춥니다. 귀여운 데모를 얻은 뒤 인증, 속도 제한, 영속성, 프론트엔드 등을 추가하는 데 몇 주를 소비하게 됩니다. AgentFlow는 데모 이후를 위해 구축되었습니다.

하나의 프레임워크. 첫 번째 pip install부터 프로덕션 Docker 배포까지.

🔗 Links

전체 스택

agentflow            →  Core Python orchestration engine
agentflow-cli        →  FastAPI server + CLI tooling
agentflow-client     →  TypeScript/React SDK (@10xscale/agentflow-client)
agentflow-playground →  Hosted UI for testing agents

각 레이어를 단독으로 사용하거나 결합하여 완전한 AI 제품 스택을 구성할 수 있습니다 — LLM 호출부터 브라우저 UI까지 — 네 개의 다른 라이브러리를 연결할 필요 없이.

60초 안에 실행하기

pip install 10xscale-agentflow-cli

agentflow init   # scaffold a new project
agentflow api    # start the dev server
agentflow play   # open the playground UI

그게 전부입니다. 에이전트가 실행 중이며 스트리밍되고, 1분 이내에 탐색할 수 있습니다.

What You Get

Graph‑Based Agent Orchestration

AgentFlow는 StateGraph를 사용합니다 — 방향성 노드, 조건부 엣지, 그리고 실행 흐름에 대한 완전한 제어. 블랙 박스가 없습니다. 디버깅할 수 없는 마법 같은 라우팅도 없습니다.

from agentflow.graph import Agent, StateGraph, ToolNode
from agentflow.state import AgentState, Message
from agentflow.utils.constants import END

def get_weather(location: str) -> str:
    """Get weather for a location."""
    return f"The weather in {location} is sunny, 72°F"

graph = StateGraph()
graph.add_node(
    "MAIN",
    Agent(
        model="gemini/gemini-2.5-flash",
        system_prompt=[{"role": "system", "content": "You are a helpful assistant."}],
        tool_node_name="TOOL",
    ),
)
graph.add_node("TOOL", ToolNode([get_weather]))

def route(state: AgentState) -> str:
    if state.context and state.context[-1].tools_calls:
        return "TOOL"
    return END

graph.add_conditional_edges("MAIN", route, {"TOOL": "TOOL", END: END})
graph.add_edge("TOOL", "MAIN")
graph.set_entry_point("MAIN")

app = graph.compile()
result = app.invoke(
    {"messages": [Message.text_message("Weather in NYC?")]},
    config={"thread_id": "1"},
)

상태 유지형. 도구 호출. 30줄 미만.

LLM‑Agnostic

모델 문자열만 전달하면 AgentFlow가 라우팅합니다.

특정 제공자에 얽매인 추상화가 없습니다. 에이전트 로직을 건드리지 않고도 모델을 교체할 수 있습니다.

Parallel Tool Execution — Automatic

LLM이 한 번에 여러 도구를 호출하면 AgentFlow는 이를 동시에 실행합니다. 별도 설정이 필요 없습니다.

Other frameworks:  1.0s + 1.5s + 0.8s = 3.3s
AgentFlow:         max(1.0s, 1.5s, 0.8s) = 1.5s  ⚡ 2.2x faster

Production Memory — Three Layers

Working Memory    →  Current execution state (AgentState)
Session Memory    →  Redis (hot) + PostgreSQL (durable) checkpointer
Knowledge Memory  →  Qdrant vector store + Mem0 semantic recall

Redis는 뜨거운 대화 상태를 빠르게 유지합니다. PostgreSQL은 내구성을 제공하고 수평 확장이 가능합니다. 두 시스템을 함께 사용하므로 하나만 선택할 필요가 없습니다.

Streaming

stream_gen = app.astream(
    inp,
    config=config,
    response_granularity=ResponseGranularity.LOW,
)
async for chunk in stream_gen:
    print(chunk.model_dump())

세 가지 세분화 수준: 토큰‑단위 (ChatGPT 스타일), 메시지‑단위, 혹은 노드‑단위 그래프 추적. 프론트엔드가 어떤 정보를 보여줄지는 여러분이 결정합니다.

Auth and Security — Built In, Not Bolted On

대부분의 프레임워크는 인증을 독자에게 맡깁니다. AgentFlow는 기본 제공합니다.

{ "auth": "jwt" }
{ "auth": null }
{ "auth": { "method": "custom", "path": "auth.my_backend:MyAuth" } }

agentflow.json에 한 줄만 추가하면 됩니다. 그래프 코드를 건드리지 않고 개발용 인증에서 프로덕션 인증으로 전환할 수 있습니다.

포함된 보안 기능:

• 구성 가능한 비밀키를 사용하는 JWT 인증
• OAuth2, API 키, 세션 등을 위한 커스텀 인증 백엔드
• 역할 기반 접근 제어 (RBAC)
• 메모리 또는 Redis 백엔드를 활용한 슬라이딩 윈도우 레이트 리밋
• 요청 크기 제한 설정 (DoS 방어, 기본 10 MB)
• 로그에서 토큰 및 비밀 자동 마스킹
• 시작 시 검증 — 보안에 취약한 CORS 설정이나 디버그 모드가 있으면 배포 전에 경고

Lifecycle Callbacks

실행의 모든 레이어에 훅을 달 수 있습니다 — 각 LLM 호출, 도구 호출, 혹은 MCP 호출 전후, 그리고 그래프 자체의 시작, 종료, 체크포인트, 인터럽트, 재개, 오류 이벤트 등. 로깅, 트레이싱, 커스텀 메트릭, 동적 그래프 수정 등에 활용하세요.

Quick Start Recap

pip install 10xscale-agentflow-cli
agentflow init
agentflow api
agentflow play

이제 프로덕션 준비가 완료된, 인증 보호된, 스트리밍이 활성화된, 다중 에이전트 AI 스택을 배포할 준비가 되었습니다.

AgentFlow 개요

AgentFlow는 그래프 기반 DSL, 자동 영속성, 병렬 도구 실행 및 풀 스택 CLI를 사용하여 프로덕션 수준의 LLM 에이전트를 구축할 수 있게 해줍니다. 보일러플레이트 없이, 맞춤형 상태 관리도 필요 없습니다.

CLI

agentflow init                 # Scaffold project + config
agentflow api                  # Dev server with auto‑reload
agentflow play                 # Open playground against local backend
agentflow build --docker-compose  # Generate Dockerfile + compose

자동 생성된 FastAPI 엔드포인트

에이전트 그래프가 프로덕션 API가 됩니다—FastAPI 보일러플레이트가 필요 없습니다.

Dependency Injection with InjectQ

from agentflow.utils import tool

@tool(tags=["weather"])
async def get_weather(
    location: str,
    user_id: str = Inject(UserService)
) -> str:
    """Get weather for a location."""
    return f"Weather for user {user_id} in {location}: sunny"

• 깔끔하고 테스트 가능한 도구들.
• 전역 상태 없이 요청당 컨텍스트 제공.

Human‑in‑the‑Loop

• 그래프 중간에서 실행을 일시 중지합니다.
• 인간의 결정을 삽입합니다.
• 전체 상태를 그대로 유지하면서 재개합니다—이전 단계들을 다시 실행하지 않습니다.

Use cases: 승인 워크플로, 검열 게이트, 인터랙티브 디버깅.

이벤트 퍼블리싱

React/TypeScript Client SDK

@10xscale/agentflow-client는 React 훅(useAgent, useStream, useThreads), ChatGPT‑스타일 UI를 위한 토큰‑레벨 스트리밍, 그리고 클라이언트‑사이드 도구 실행을 제공합니다. 프런트엔드는 사용자 정의 통합 코드를 작성하지 않고도 AgentFlow API와 통신합니다.

기능 비교

설치

# Core library
pip install 10xscale-agentflow

# Full CLI + API server
pip install 10xscale-agentflow-cli

선택적 추가 기능

pip install 10xscale-agentflow[pg_checkpoint]   # PostgreSQL + Redis persistence
pip install 10xscale-agentflow[mcp]             # Model Context Protocol
pip install 10xscale-agentflow[google-genai]    # Google GenAI adapter
pip install 10xscale-agentflow[kafka]           # Kafka event publishing
pip install 10xscale-agentflow[redis]           # Redis publisher + rate limiting

Current Version

v0.7.x에 추가된 내용: 멀티모달 지원(이미지, 오디오, 비디오), 확장된 추론 / 체인‑오브‑생각, 3‑계층 메모리, 콜백 및 라이프사이클 훅, 에이전트 스킬, Vertex AI 지원, 구조화된 Pydantic 출력.

Roadmap

• ✅ 노드, 엣지 및 조건부 라우팅을 지원하는 그래프 엔진
• ✅ Redis + PostgreSQL 상태 체크포인팅
• ✅ 도구 통합 — 로컬 Python, MCP, 선택적 어댑터
• ✅ 병렬 도구 실행
• ✅ 라이프사이클 콜백 및 그래프 훅
• ✅ 스트리밍 + 이벤트 퍼블리싱
• ✅ 인간‑인‑루프
• ✅ 멀티모달 에이전트
• 🚧 분산 처리를 위한 원격 노드 실행
• 🚧 OpenTelemetry 추적
• 🚧 더 많은 영속성 백엔드 (DynamoDB 등)
• 🚧 시각적 그래프 편집기

개인정보 및 라이선스

• MIT License – 상업적 사용이 무료입니다.
• No data collection – 대화는 귀하의 인프라에 보관됩니다.
• No per‑call billing – LLM API와 인프라 비용만 지불합니다.
• Deploy anywhere – Docker, Kubernetes, AWS ECS, Cloud Run, Azure, Heroku.

링크

Built by 10xScale와 커뮤니티가 제작했습니다. MIT 라이선스.