CUGA를 활용한 에이전트형 애플리케이션 구축: 경량 하네스로 작동하는 24개의 예제

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

맥락·배경: 엔터프라이즈 환경에서 에이전트가 여러 도구를 조합해 복잡한 태스크를 수행하도록 만드는 것이 일반적이지만, 구성 부가가 많아 초기 접근이 어렵다. 본 글의 주된 아이디어는 CUGA 하네스를 통해 도구 목록과 프롬프트만으로도 엔터프라이즈 에이전트를 쉽게 구성하고 생산 환경으로 운용 가능한 상태로 만드는 것이다. 핵심 전개: CUGA는 계획-실행 루프를 가지되, 실행 전에 계획을 수립하고 중간 상태를 추적하며 필요 시 재계획하는 반성(reflection) 메커니즘으로 안정성을 확보한다. 이 구조는 'Inline 도구 + MCP' 패턴으로 구현되며, 24개의 단일 파일 앱(cuga-apps)을 통해 다양한 도메인에 재사용 가능하다는 점이 입증된다. 또한 거버넌스와 안전성은 내재된 정책 체계(Intent Guard, Tool Approval 등)로 확보되며, 생산 환경에서의 운영은 Sovereign Core의 경계 격리 모델로 가능하다. 핵심 수치·근거: AppWorld와 WebArena 벤치마크에서 상위 성과를 기록했고, 1개의 파일(main.py)로 에이전트를 시작하고 도구를 조합하는 구조를 제시한다. 의미: 이 패턴은 엔터프라이즈에서도 반복 가능한 방법으로 에이전트 개발의 진입 장벽을 낮추고, 거버넌스 포함 생산 운영의 신뢰성을 높이는 방향으로 나아간다.

섹션별 상세

대부분의 에이전트는 긴 작업에서 중간 결과를 잃고 잘못된 방향으로 가는 경향이 있다. CUGA는 상태를 유지하고 반성 단계를 통해 실행 전에 재계획하며, 잘못된 호출을 포착해 재계산한다. 이 접근은 20단계의 작업에서도 안정적으로 작동하며 벤치마크에서 상향 곡선을 보인다(AppWorld, WebArena).

python

def make_agent():
    from cuga import CugaAgent
    from _llm import create_llm
    return CugaAgent(
        model=create_llm(
            provider=os.getenv("LLM_PROVIDER"),
            model=os.getenv("LLM_MODEL"),
        ),
        tools=_make_tools(),
        special_instructions=_SYSTEM,
        cuga_folder=str(_DIR / ".cuga"),
    )

# Pattern: inline tool + MCP tools
@tool
def search_ibm_catalog(query: str) -> str:  # 
    """Search the IBM Cloud Global Catalog for real IBM Cloud services. Always call this before recommending services to verify they exist."""
    ...

# hits the catalog API, returns JSON from _mcp_bridge
web_tools = load_tools(["web"])
return [search_ibm_catalog, *web_tools]

에이전트의 메인 팩토리와 inline 도구 정의를 보여주는 핵심 예시 코드 블록이다

ibm_cloud_advisor 예제의 main.py 구성 및 inline 도구 흐름을 시각화한 다이어그램 — DiagramInline 도구와 MCP의 결합 흐름, 프레이밍/실행 흐름, UI와의 인터랙션 흐름을 시각적으로 제시한다.

근거

CUGA는 상태를 유지하고 반성 단계를 통해 잘못된 호출을 포착해 재계획한다. — The pattern here holds across every app: the harness plans before acting and uses reflection to catch bad calls and re-plan.
이번 글의 엔드투엔드 예시는 하나의 파일(main.py)로 에이전트를 구성하는 방법을 보여준다. — One app, start to finish: The whole thing fits in one file: a main.py with the agent factory, the tools, and the prompt, plus a small UI.

하나의 파일로 작동하는 24개의 단일 파일 앱(cuga-apps)을 통해 패턴이 실제로 재현되고, 영화 추천부터 IBM Cloud 아키텍처 자문에 이르기까지 다양한 도메인에서 같은 구조를 활용한다. 라이브 갤러리와 MCP 도구 탐색기를 통해 즉시 검증 가능하다.

거버넌스와 안전성은 내재된 정책 시스템으로 확보되며, Intent Guard, Tool Approval, Tool Guide, Playbook, Output Formatter, CustomPolicy의 여섯 가지 정책 유형이 핵심 역할을 한다.

근거

6가지 정책 유형이 내재된 거버넌스 시스템의 핵심이다. — A policy system, and you attach policies to the same agent object: Intent Guard, Tool Approval, Tool Guide, Playbook, Output Formatter, CustomPolicy.

생산 환경에서의 운영은 Sovereign Core의 경계 격리(Boundary Isolation)로 가능하며, 오프라인 모델(gpt-oss-120b) 및 도구별 접근 제어로 외부로의 데이터 흔적이 최소화된다.

근거

Sovereign Core의 경계 격리는 생산 운영의 안전성과 거버넌스를 강화한다. — Sovereign Core runs CUGA agents under what we call Boundary Isolation: data, control plane, and execution engine inside the same boundary, with models running in fully air-gapped infrastructure.

다중 에이전트 형태로의 확장도 용이하다. Ouroboros 같은 seven-agent lead-gen 구조가 제시되며, 각 전문가는 독립적으로 동작하고 상호작용은 supervisor를 통해 관리된다. ALTK-Evolve를 통해 스킬의 자동 개선도 가능하다.

근거

Ouroboros는 7에이전트 리드제너레이션 구조로 다중 에이전트 패턴의 실전 예시를 제시한다. — Ouroboros — a seven-agent lead-gen app that attaches three policies (an intent guard, a tool guide, and an output formatter) to its supervisor.

클론과 시작은 간단하다. GitHub의 cuga-apps를 클론하고 Docker Compose로 빌드한 뒤 로컬에서 실행하면 바로 에이전트를 체험할 수 있으며, 코드 한 줄로 모델 교체가 가능하다.

근거

클론 후 Quick Start Guide를 따라 도커로 실행하면 즉시 체험 가능하다. — Next steps: Clone the repo and run an app. Docker Compose up --build; open http://localhost:8080; then read main.py end to end.

용어 해설

MCP: — MCP 서버군은 도구·서비스를 중앙에서 연결해 공유하는 러너 역할을 하며, 도구 탐색과 외부 서비스 호출을 관리한다(브리징 및 재사용 가능성을 높이는 중개 계층으로 작동).
CodeAct: — CodeAct는 계획-실행 루프에서 코드 생성과 도구 호출을 결합해 에이전트가 실제 작업을 수행하는 방식을 정의하는 요소다.
FastAPI: — Python으로 작성된 경량 웹 프레임워크로, 에이전트의 라우트를 빠르게 노출하고 UI와 연동하는 데 사용된다.
Ouroboros: — Ouroboros는 7-에이전트 리드제너레이션 시스템으로, 각 전문가는 독립된 에이전트로 동작하고 상호작용은 supervisor를 통해 조정된다.
경계 격리(Boundary Isolation): — Boundary Isolation은 데이터/제어/실행 엔진을 같은 경계 안에 두고 외부로의 노출을 차단해 보안성과 거버넌스를 강화한다.
ALTK-Evolve: — ALTK-Evolve는 에이전트가 실행 중에 습득한 스킬을 현업 운영에서 점진적으로 개선하는 온-더-잡 학습 프레임워크이다.