cuga-project/cuga-agent

개요

CUGA(Configurable Generalist Agent)는 오케스트레이션 플러밍을 처음부터 작성하지 않고 도메인별 AI 에이전트를 구축하기 위한 오픈소스 Python 프레임워크입니다. 실제 API 및 웹 브라우징 작업에서 최고의 벤치마크 결과(AppWorld 및 WebArena에서 1위)를 주장합니다.

존재 이유

엔터프라이즈 에이전트를 구축하려면 일반적으로 에이전트/도구 오케스트레이션, 계획 로직, 안전 정책, 평가, 비용/성능 튜닝을 직접 조립해야 합니다. CUGA는 이를 구성 가능한 코어로 제공합니다. API, MCP 서버, 정책을 연결하기만 하면 빈 상태가 아닌 강력한 범용 에이전트로 시작할 수 있습니다.

작동 방식(핵심 개념)

• AGENT_ORCHESTRATION — 확립된 에이전트 패턴(플래너 실행기, 코드 액트)과 구조화된 계획 및 변수 관리를 결합하여 복잡한 다단계 작업을 처리합니다.
• TOOL_INTEGRATION — 도구는 OpenAPI 사양, MCP 서버, LangChain 또는 일반 Python 함수를 통해 연결되므로 REST API 및 사용자 정의 프로토콜을 쉽게 연결할 수 있습니다.
• POLICIES — 5가지 정책 유형(의도 가드, 플레이북, 도구 승인, 도구 가이드, 출력 포맷터)이 동작을 관리하며, 위험한 작업에 대한 인간 개입 승인 게이트를 포함합니다.
• KNOWLEDGE (RAG) — 문서(PDF, Office, HTML, Markdown via Docling)에 대한 내장 검색으로, 에이전트 수준(공유) 또는 세션 수준(대화별)으로 범위를 지정합니다.
• AGENT_SKILLS — 도메인 워크플로를 SKILL.md 파일로 패키징합니다. 에이전트는 시스템 프롬프트를 비대화하지 않고 load_skill 도구를 통해 온디맨드로 전체 지침을 로드합니다.
• MULTI_AGENT — 슈퍼바이저 모드(CugaSupervisor)는 멀티 에이전트 협업을 지원합니다. 또한 다른 에이전트에 도구로 노출할 수 있습니다.
• EVENT_DRIVEN — 선택적 두 번째 서비스는 이벤트 기반 트리거를 추가합니다: 웹훅, cron/poll/push, Slack/Discord/Telegram 채널, 자연어로 무장된 상시 작동 플로우(사람이 확인).

눈에 띄는 주요 기능

• 단일 작업에서 API 호출과 브라우저 상호 작용을 혼합하는 하이브리드 모드
• 코드 생성 프로필(빠름 / 균형 / 정확)
• 리플렉션, 도구 호출 예산, 버전 관리 구성 게시(초안 → 게시)
• Helm 차트를 통한 Kubernetes 자체 호스팅
• Langflow를 통한 로우 코드 통합
• 광범위한 LLM 공급자 지원: OpenAI, Azure, Groq, OpenRouter, IBM watsonx, Groq, RITS, watsonx Orchestrate, LiteLLM

시작하기

Python 3.12+ 및 uv 패키지 관리자가 필요합니다. 클론하고, venv를 만들고, uv sync를 실행하고, .env에 API 키를 설정한 다음, cuga start demo_crm --read-only를 실행하면 로컬 웹 채팅(localhost:7860)이 열립니다. cuga viz는 에이전트 궤적을 검사하는 대시보드를 시작합니다.