Build real agentic apps using CUGA: two dozen working examples on a lightweight harness

🖼️ 인포그래픽

Build real agentic apps using CUGA: two dozen working examples on a lightweight harness 내용을 설명하는 본문 이미지

🖼️ 4컷 인포그래픽

💡 한 줄 요약

CUGA는 에이전트 앱에서 반복되는 계획·실행·도구 호출·상태 관리·정책 처리를 하네스가 맡고, 개발자는 도구 목록과 프롬프트에 집중하도록 해 주는 IBM의 오픈소스 에이전트 하네스입니다.

📌 핵심 요약

글은 에이전트 앱 개발에서 실제 가치보다 먼저 많은 배관 작업이 필요하다는 문제의식에서 출발해, CUGA가 모델 클라이언트 연결, 도구 호출, 실행 루프, 상태 관리, 재계획 같은 공통 작업을 대신 처리한다고 설명합니다.
CUGA는 프레임워크라기보다 설정 가능한 하네스로 제시되며, 개발자는 CugaAgent에 모델, 도구 목록, 지시문, 상태 폴더를 넘기고 agent.invoke를 호출하는 작은 API만 다루면 됩니다.
IBM Cloud 아키텍처 어드바이저 예시는 하나의 FastAPI 파일 안에서 로컬 카탈로그 검색 도구와 MCP 기반 웹 도구, 명시적 프롬프트를 조합해 실제 IBM Cloud 서비스 추천 에이전트를 만드는 흐름을 보여줍니다.
글은 안정적인 에이전트 실행을 위해 모든 인라인 도구가 성공과 실패를 같은 형태의 JSON 봉투로 반환해야 한다고 강조하며, 선언된 실패는 재계획으로 회복할 수 있지만 예외가 그대로 터지면 실행이 무너진다고 설명합니다.
cuga-apps는 24개 안팎의 단일 파일 예제를 통해 연구, 생산성, 문서·미디어 RAG, 운영 모니터링, 기업 문서, 다중 에이전트, 브라우저 자동화 등 다양한 시작점을 제공하며, 위험한 작업에는 CUGA의 정책 시스템으로 경계를 둘 수 있다고 소개합니다.

🧩 주요 포인트

글은 에이전트 앱 개발에서 실제 가치보다 먼저 많은 배관 작업이 필요하다는 문제의식에서 출발해, CUGA가 모델 클라이언트 연결, 도구 호출, 실행 루프, 상태 관리, 재계획 같은 공통 작업을 대신 처리한다고 설명합니다.
CUGA는 프레임워크라기보다 설정 가능한 하네스로 제시되며, 개발자는 CugaAgent에 모델, 도구 목록, 지시문, 상태 폴더를 넘기고 agent.invoke를 호출하는 작은 API만 다루면 됩니다.
IBM Cloud 아키텍처 어드바이저 예시는 하나의 FastAPI 파일 안에서 로컬 카탈로그 검색 도구와 MCP 기반 웹 도구, 명시적 프롬프트를 조합해 실제 IBM Cloud 서비스 추천 에이전트를 만드는 흐름을 보여줍니다.
글은 안정적인 에이전트 실행을 위해 모든 인라인 도구가 성공과 실패를 같은 형태의 JSON 봉투로 반환해야 한다고 강조하며, 선언된 실패는 재계획으로 회복할 수 있지만 예외가 그대로 터지면 실행이 무너진다고 설명합니다.
cuga-apps는 24개 안팎의 단일 파일 예제를 통해 연구, 생산성, 문서·미디어 RAG, 운영 모니터링, 기업 문서, 다중 에이전트, 브라우저 자동화 등 다양한 시작점을 제공하며, 위험한 작업에는 CUGA의 정책 시스템으로 경계를 둘 수 있다고 소개합니다.

🧠 상세 정리

1. 에이전트 개발의 반복 배관 문제

글은 대부분의 에이전트형 앱이 유용한 행동을 하기 전부터 모델 클라이언트 선택, 도구 어댑터 작성, UI에 상태를 스트리밍하는 장치, 실행 루프 같은 배관 작업에 시간을 쓰게 된다고 지적합니다. 개발자가 실제로 고민해야 할 것은 에이전트가 어떤 도구를 사용할 수 있고 무엇을 수행해야 하는지인데, 그 흥미로운 부분이 오히려 가장 늦게 도착한다는 문제의식입니다. CUGA는 이 순서를 뒤집기 위한 하네스로 소개됩니다. 계획, 실행 루프, 도구 호출, 상태 배관을 하네스가 맡아 개발자가 도구 목록과 프롬프트라는 앱 고유의 부분에 집중하게 만드는 것이 핵심입니다.

2. CUGA가 지향하는 하네스의 역할

본문은 CUGA를 새로운 거대한 프레임워크라기보다 모델 주변의 오케스트레이션을 대신 조립해 주는 하네스로 설명합니다. CUGA는 행동하기 전에 계획하고, 도구 호출과 생성된 코드 실행을 섞어 작업을 수행하며, 긴 작업 중간에 생기는 결과를 추적합니다. 특히 여러 단계가 이어지는 작업에서 에이전트가 중간 결과를 잃어버리거나 잘못 다시 계산하는 문제가 생기는데, CUGA는 상태를 보존하고 반성 단계를 통해 잘못된 호출을 감지한 뒤 재계획할 수 있게 합니다. 글은 이러한 장치가 AppWorld와 WebArena 같은 벤치마크에서 성과를 낸 배경이라고 설명합니다.

3. 설정으로 조절하는 실행 방식과 작은 API

CUGA의 중요한 특징은 비용과 지연 시간의 균형을 코드 변경이 아니라 설정으로 조정한다는 점입니다. 글은 Fast, Balanced, Accurate라는 reasoning 모드와 로컬, Docker 또는 Podman, E2B 클라우드 같은 코드 실행 샌드박스를 언급하면서 같은 에이전트 정의에 다른 실행 다이얼을 적용할 수 있다고 설명합니다. 또한 CUGA는 계획, 반성, 변수 추적 같은 부담을 모델이 아니라 하네스 쪽에서 상당 부분 떠안기 때문에 더 작은 오픈 웨이트 모델로도 버틸 수 있다는 주장을 펼칩니다. 개발자가 직접 만지는 API는 CugaAgent를 도구 목록과 프롬프트로 만들고 invoke를 호출하는 수준으로 작게 유지됩니다.

4. 사전 조립된 기능과 구성 가능성

본문은 CUGA의 개별 구성요소들이 완전히 새로운 발명이라기보다, 중요한 점은 이들이 미리 조립되어 있어 개발자가 직접 연결하지 않아도 된다는 데 있다고 말합니다. OpenAPI, MCP, LangChain 함수형 도구를 같은 방식으로 바인딩할 수 있고, 장기 계획에는 변수 관리와 자기 수정이 포함됩니다. 여기에 선언적 가드레일, A2A를 통한 다중 에이전트 위임, Docling 기반 RAG, 환경변수 하나로 바꾸는 모델 제공자 전환도 언급됩니다. 이름의 첫 단어인 Configurable이 강조되는 이유도 여기에 있습니다. 어려운 부분을 하네스가 처리하고, 개발자는 과제 정의에 집중하도록 하는 구조입니다.

5. IBM Cloud 어드바이저 예제로 본 앱 구조

글은 IBM Cloud 아키텍처 어드바이저를 대표 예제로 들며, 하나의 main.py 파일 안에 에이전트 팩토리, 도구, 프롬프트, 작은 UI가 모두 들어간다고 설명합니다. make_agent 함수는 CugaAgent를 만들면서 모델, 도구 목록, special_instructions, cuga_folder 네 가지를 넘깁니다. 모델은 create_llm이라는 작은 팩토리를 통해 환경변수에 따라 OpenAI, Anthropic, watsonx, LiteLLM, Ollama 등으로 바뀌며, 앱 코드는 뒤에 어떤 모델이 있는지 알 필요가 없습니다. 실제 앱의 성격을 결정하는 것은 결국 도구 목록과 시스템 지시문이라는 점이 강조됩니다.

6. 도구 구성과 프롬프트의 실무적 규칙

IBM Cloud 어드바이저의 도구 구성은 로컬 함수와 호스팅된 도구를 섞는 패턴을 보여줍니다. search_ibm_catalog는 실제 IBM Cloud 글로벌 카탈로그를 검색해 서비스 존재 여부를 확인하는 앱 고유의 인라인 도구이고, web 도구는 MCP 서버에서 가져옵니다. 글은 모든 앱에서 일반적이고 상태 없는 기능은 공유 MCP 서버에서 빌려오고, 앱에 특화된 기능은 평범한 Python 함수로 직접 정의하는 식의 분리가 반복된다고 설명합니다. 또한 프롬프트는 서비스를 추천하기 전 반드시 카탈로그를 검색하고, 3개에서 7개의 서비스를 추천하며, 존재하지 않는 서비스 이름을 지어내지 말라고 명시합니다. 페르소나식 프롬프트보다 절차와 금지 규칙이 분명한 프롬프트가 더 잘 작동한다는 논지입니다.

7. 상태 표시 UI와 도구 반환 형식의 중요성

예제의 FastAPI 라우트는 평범한 웹 코드로 설명됩니다. 브라우저가 /ask로 질문을 보내고, 라이브 패널은 /session/{thread_id} 엔드포인트를 폴링해 상태를 보여줍니다. 별도 데이터베이스는 없으며 상태는 thread_id별 Python 딕셔너리로 유지되고, 에이전트가 도구를 통해 그 상태를 변경하면 UI가 이를 화면에 반영합니다. 글은 특히 모든 인라인 도구가 성공 시 ok와 data를, 실패 시 ok와 code, error를 담은 같은 작은 봉투를 반환하는 관례가 중요하다고 강조합니다. 선언된 실패는 CUGA의 플래너가 우회하거나 재계획할 수 있지만, 원시 예외가 그대로 올라오면 실행 중 계획이 탈선할 수 있기 때문입니다.

8. cuga-apps 예제 라이브러리와 확장 패턴

cuga-apps가 단순 데모가 아니라 시작점의 카탈로그라는 설명도 이어집니다. 클라우드 어드바이저를 이해하면 영화 추천기, 웹 리서처 등 다른 앱도 같은 골격으로 읽을 수 있으며, 아이디어에 가까운 앱을 골라 도구 목록과 프롬프트를 바꾸는 방식으로 출발할 수 있습니다. 예제들은 연구, 일상 생산성, PDF·오디오·비디오 기반 RAG, 실시간 지표를 보는 운영 도구, IBM 제품 문서 기반 기업 예제 등 여러 계열로 나뉩니다. Ouroboros는 7개 에이전트로 구성된 리드 생성 시스템의 형태를 보여주고, Meetup Finder는 Playwright로 헤드리스 Chromium을 제어해 공개 검색 API가 사라진 서비스에서 구조화된 이벤트를 추출하는 브라우저 자동화 사례로 소개됩니다.

9. 위험한 작업을 위한 정책 경계

글의 후반부는 카탈로그를 검색하는 낮은 위험의 데모와 달리, 파일을 쓰거나 셸 명령을 실행하거나 프로덕션에 닿는 에이전트에서는 경계 설정이 중요하다고 전환합니다. CUGA는 이를 외부 래퍼가 아니라 런타임의 정책 시스템으로 다루며, 같은 에이전트 객체에 정책을 붙일 수 있다고 설명합니다. 예시로는 --force나 --no-verify 같은 파괴적 git 플래그를 막는 Intent Guard가 제시됩니다. 정책 유형에는 요청 자체를 거부하는 Intent Guard, 위험한 도구 실행 전 사람 승인을 요구하는 Tool Approval, 특정 도구 사용법을 유도하는 Tool Guide, 반복 작업의 절차를 고정하는 Playbook, 최종 응답 형식을 강제하는 Output Formatter, 예외적 요구를 위한 CustomPolicy가 포함됩니다.

🧾 핵심 주장 / 시사점

이 글의 핵심은 에이전트 품질을 단지 더 강한 모델 선택 문제로 보지 않고, 계획·상태·반성·도구 실패 처리를 하네스가 얼마나 안정적으로 떠안느냐의 문제로 본다는 점입니다.
실무적으로 가장 재사용 가능한 교훈은 도구를 만들 때 예외를 그대로 던지지 말고 성공과 실패를 명시적 구조로 반환해야 한다는 점입니다. 이는 작아 보이지만 긴 실행에서 재계획 가능성을 좌우합니다.
cuga-apps의 가치는 개별 데모의 화려함보다 모든 앱이 비슷한 골격을 공유한다는 데 있습니다. 반복 가능한 구조는 사람이 배우기 쉽고, 코딩 보조 도구가 새 앱을 생성하기에도 좋은 기반이 됩니다.