chatflow-agent
CI
PyPI version
Python 3.10+
License: MIT
Code style: ruff
Checked with mypy
무거운 의존성 체인 없이 WhatsApp, Telegram 및 Webhook을 위한 자율 에이전트 스웜(swarms)을 몇 초 만에 구축하세요.
WhatsApp, Telegram 및 Webhooks를 위해 복잡한 의존성을 다룰 필요 없이 자율 에이전트 팀을 몇 초 안에 구축합니다.
pip install chatflow-agent
English Documentation | 스페인어 가이드 | 기여하기 | PyPI 패키지 | 이슈 보고
핵심 기둥 (왜 chatflow-agent인가?)
-
초경량 코어(Ultra-Lightweight Core): 런타임 의존성이 pydantic과 httpx 단 두 가지입니다. Docker, 서버리스(serverless), 클라우드 VPS 환경에서 몇 초 만에 설치되는 매우 작은 약 72 KB의 패키지 크기를 자랑합니다.
-
옴니채널 네이티브(Omnichannel Native): WhatsApp (공식 Meta Cloud API), Telegram, Webhooks (FastAPI) 및 인터랙티브 CLI를 위한 프로덕션 준비가 된 커넥터들을 제공합니다.
-
다중 공급자 자유도(Multi-Provider Freedom): 단일 파라미터로 Google Gemini, Google Gemma (Ollama를 통한 100% 무료 로컬 사용), xAI Grok, OpenAI (GPT-4o), 그리고 Anthropic Claude 간에 전환할 수 있습니다. 공급업체 종속성(vendor lock-in)이 전혀 없습니다.
-
프로덕션 강화 보호막(Production-Hardened Shields): 네이티브 세션별 동시성 잠금(asyncio.Lock) 기능은 빠른 타이피스트로 인한 순서가 뒤바뀐 레이스 컨디션을 방지합니다. Webhook 안티-500 보호막은 LLM 다운타임 동안 Meta의 재시도 폭격(retry bombardment storms)으로부터 시스템을 보호합니다.
-
자율 피어 핸드오프(Autonomous Peer Handoffs): 에이전트들은 복잡한 상태 기계(state machines)나 그래프 빌더 없이 고객 의도에 따라 대화를 동적으로 위임합니다.
10초 만에 시작하기 (Quickstart)
English Documentation
목차
-
개요 및 아키텍처
-
API 키 및 설정
-
설치
-
단계별 퀵스타트
-
채널 커넥터
-
운영 환경 복원력 및 동시성
-
도구의 Idempotency 및 부작용 처리
-
세션 메모리 및 영속성
-
운영 환경 스타터 템플릿
-
기여하기
-
스페인어 전체 가이드
개요 및 아키텍처 (Overview & Architecture)
chatflow-agent는 단일 제공업체(single provider)에 종속되지 않으면서도 OpenAI Swarm의 다중 에이전트(multi-agent) 기능을 활용하고자 하는 개발자를 위해 설계되었으며, WhatsApp 및 Telegram과 같은 메시징 플랫폼을 위한 즉시 사용 가능한 커넥터가 결합되어 있습니다.
chatflow-agent Architecture: Input Channels (WhatsApp, Telegram, Webhook, CLI) connected to Runner and Session Memory, orchestrating a Triage Agent and a Specialist Agent with autonomous peer handoff and @agent.tool actions
API 키 및 설정 (API Keys & Configuration)
다음 3가지 방법 중 어느 것을 사용하여도 API 키를 제공할 수 있습니다:
1. Python 코드에 직접 입력 (가장 쉬움)
Runner 또는 Agent를 인스턴스화(instantiating)할 때 API 키를 직접 전달합니다:
2. .env 파일 사용
프로젝트 루트에 .env 파일을 생성합니다:
# Google Gemini (https://aistudio.google.com/에서 무료 키를 받으세요)
...
그런 다음 스크립트에서 다음과 같이 사용합니다:
from dotenv import load_dotenv
...
3. 터미널 환경 변수 이용
제공자 자격 증명 참조 테이블
| 제공자 | 키 획득 위치 | 환경 변수 | 코드 내 파라미터 | 무료 등급 사용 가능 여부 |
|---|
| Google Gemini | Google AI Studio | GEMINI_API_KEY | api_key="..." | 예 (넉넉한 무료 등급) |
| ... | | | | |
[!WARNING]
Vertex AI는 지원되지 않습니다. GeminiEngine은 Gemini Developer API(Google AI Studio)의 API 키만을 호출합니다. 애플리케이션 기본 자격 증명(ADC) 및 GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION 변수는 사용되지 않으므로, 이들에 의존했던 설정은 ProviderError("Gemini API client is not configured. ...") 오류로 실패합니다. Gemini API 키를 사용하거나, Runner(engine=...)을 통해 자체 엔진을 제공하십시오.
GeminiEngine.client는 v0.4.0에서 제거되었습니다. 이 속성은 더 이상 종속성이 아닌 google-genai 클라이언트를 보유하고 있었습니다. 여기에 가짜 값을 할당해도 더 이상 목킹(mocks)되지 않습니다. SDK를 직접 호출하려면, google-genai를 설치하고 자체 클라이언트를 생성하십시오. 테스트에서 Gemini를 목킹하거나 HTTP를 사용자 정의하려면, httpx.AsyncClient를 포함하여 GeminiEngine(http_client=...)를 전달하십시오. 이 클라이언트는 귀하의 소유로 유지되며 단일 이벤트 루프에서만 사용해야 합니다. 마이그레이션 단계는 CHANGELOG를 참조하십시오.
설치 (Installation)
필요한 것만 설치하세요:
단계별 퀵스타트 (Step-by-Step Quickstarts)
A. 클라우드 LLM 퀵스타트 (Cloud LLM Quickstart)
bot.py로 저장하고 python bot.py로 실행하세요:
B. 로컬 오프라인 퀵스타트 (Google Gemma) (Local Offline Quickstart)
Ollama를 사용하여 API 비용 제로 및 완전한 프라이버시가 보장되는 방식으로 기기에서 100% 로컬 실행하세요:
-
Ollama를 Gemma와 함께 시작합니다: ollama run gemma2:9b
-
이 스크립트를 실행합니다:
C. 핸드오프를 이용한 다중 에이전트 스웜 (Multi-Agent Swarm with Handoffs)
에이전트는 전문가에게 작업을 자율적으로 위임할 수 있습니다:
채널 커넥터 (Channel Connectors)
Meta WhatsApp Business Cloud API와 호환되는 프로덕션 웹훅 서버를 실행하세요:
from chatflow_agent import Agent, Runner
...
로컬 테스트 중인가요? ngrok과 같은 터널을 사용하거나 Cloudflare Tunnels를 사용하여 Meta에 공개 HTTPS URL(https://your-domain.ngrok-free.app/webhook)을 제공하세요.
[!참고]
개발 중인 API 문서: 보안상의 이유로, 프로덕션 환경에서는 FastAPI 대화형 문서(/docs, /redoc, 및 /openapi.json)가 기본적으로 비활성화됩니다. 로컬 개발 또는 디버깅 중에 Swagger UI와 OpenAPI 스키마를 활성화하려면 WhatsAppChannel을 인스턴스화할 때 enable_docs=True를 전달하세요:
channel = WhatsAppChannel(
...,
enable_docs=True,
...
[!팁]
프로덕션 속도 제한 및 리버스 프록시: /webhook 및 /health 엔드포인트를 플러드 공격, 서비스 거부(DoS), 그리고 인증되지 않은 요청으로 인한 CPU 고갈로부터 보호하려면, 애플리케이션 레벨에서 합법적인 Meta 웹훅 버스트를 손실할 위험 없이, 항상 Uvicorn을 리버스 프록시 뒤에 배치하세요 (예: limit_req_zone을 사용한 Nginx 또는 Cloudflare Rate Limiting):
limit_req_zone $binary_remote_addr zone=whatsapp_limit:10m rate=10r/s;
location /webhook {
limit_req zone=whatsapp_limit burst=20 nodelay;
...```
Telegram 채널
from chatflow_agent import Agent, Runner
...
대화형 터미널 (CLI)
색상 채팅 출력을 사용하여 터미널에서 스웜을 테스트하세요:
from chatflow_agent import Agent, Runner
...
프로덕션 복원력 및 동시성 (Production Resilience & Concurrency)
ChatFlow는 실제 메시징 트래픽에 맞춰 특별히 설계된 내장 안전 장치를 포함합니다:
