Open WebUI의 MCP 에이전트: 도구와 ReWOO

Open WebUI에서 MCP 에이전트 구축: 기본 도구부터 플래너까지

Open WebUI에서 MCP 에이전트는 간단한 시작으로부터 출발합니다. LLM에 ClickHouse와 상호작용할 수 있는 도구 세트를 제공하고, 그 결과를 관찰하는 것입니다. 처음에는 list_databases, list_tables, run_select_queries라는 세 가지 기본 도구만 사용 가능합니다. 이들은 단순한 SQL 쿼리를 처리하지만, 작업이 복잡해지면 모델은 데이터 스키마를 이해하는 데 어려움을 겪습니다.

해결책: 구체적인 예시가 포함된 정교한 프롬프트입니다. 변수(portfolio_name, start_date, end_date)를 포함하고, LIKE 필터 지침과 Dt::date >= '{start_date}' 같은 패턴을 활용합니다. 예를 들어 포트폴리오 성과를 계산할 때 윈도우 함수를 사용합니다:

WITH log_coef as (SELECT Portfolio, Dt,
    sum(log(TWR_dod+1)) OVER (
        PARTITION BY InvestmentPortfolioID
        ORDER BY Dt ASC ROWS BETWEEN UNBOUNDED PRECEDING AND 0 FOLLOWING
    ) AS TWR_cumulative_coef
FROM Contribution.contribution_twr_1s_mcp
WHERE lowerUTF8(Portfolio) LIKE '%{portfolio_name}%'
    AND Dt::date >= {start_date}
    AND Dt::date <= {end_date}
ORDER BY Dt DESC)
SELECT Portfolio, Dt, exp(TWR_cumulative_coef) - 1 AS TWR_cumulative
FROM log_coef;

결과는 개선되지만 여전히 불안정합니다. 문법 오류와 잘못된 지표가 반복됩니다. Open WebUI의 RAG도 이를 해결하지 못합니다.

도구 킷 확장: 환상 없이 정의된 커스텀 도구

결정론적 접근으로 전환: Pydantic 스키마를 활용해 미리 정의된 도구를 구축합니다. LLM은 도구를 선택하고 매개변수를 설정할 뿐, 쿼리는 고정됩니다. 도구 클래스에는 다음과 같은 항목이 포함됩니다:

• ClickHouseClientBase: 핵심 MCP 작업을 감싸는 래퍼.
• ProfitTool: 수익률(일별 TWR, 산술/기하 평균) 계산.
• PortfolioDiscoveryTool: 포트폴리오 속성 탐색(목록, 유형, 전략).
• PortfolioCashflowTool: 자금 유입·유출 추적 및 현금 흐름 분석.

ClickHouseClientBaseParams 예시 스키마:

class ClickHouseClientBaseParams(BaseModel):
    operation: Literal['list_databases', 'list_tables', 'run_select_query'] = Field(
        description='작업 유형: list_databases, list_tables, 또는 run_select_query'
    )
    database: Optional[str] = Field(default=None, description='데이터베이스 이름')
    query: Optional[str] = Field(default=None, description='SQL 쿼리')
    like: Optional[str] = Field(default=None, description='LIKE 필터')
    not_like: Optional[str] = Field(default=None, description='NOT LIKE 필터')


def clickhouse_client_base(params: ClickHouseClientBaseParams) -> str:
    # http://clickhouse-mcp.services.kfim.int로의 HTTP 요청 로직
    # list_databases, list_tables, run_select_query 처리
    # contribution_twr_1s_mcp를 전체 테이블 이름으로 자동 교체

pydantic_to_openai_schema 함수는 이러한 스키마를 OpenAI 호환 형식으로 변환하여 환상 현상을 완전히 제거합니다. 도구는 항상 예측 가능한 JSON을 반환합니다.

이 접근 방식의 장점:

• 결정론성: 동일한 입력 → 동일한 출력.
• 확장성: 새로운 지표는 도구로 추가 가능.
• 디버깅 용이성: 쿼리 논리는 투명하며, 블랙박스 LLM 동작 없음.

단순함의 한계: 도구가 부족한 순간

사소한 에이전트는 복잡한 작업(다중 포트폴리오, 집계, JOIN 등)에서는 실패합니다. 모델은 윈도우 함수와 날짜 필터를 혼동합니다. 예시가 있어도 오류율은 30–40%에 달합니다. 포트폴리오 분석을 확장하려면 수천 건의 TWR 행과 현금 흐름 기록을 처리해야 합니다.

개선: 플래너와 실행자로 분리하기

두 번째 단계: 에이전트를 ReWOO(이해 + 행동)로 구성합니다. 플래너(별도의 LLM)는 작업을 단계별로 나누고, 실행자는 도구를 호출합니다. 이는 다음과 같은 문제를 해결합니다:

• 데이터 필터링: PortfolioDiscoveryTool을 통해 포트폴리오 전체 텍스트 검색.
• 순서 제어: 연결된 쿼리(목록 → 필터 → 집계).
• 컨텍스트 관리: UI 렌더링을 위해 테이블을 하나로 통합.

플래너는 다음 계획을 생성합니다:

• 단계 1: %name%와 일치하는 포트폴리오 목록 조회.
• 단계 2: TWR용 쿼리 실행.
• 단계 3: 집계 후 표시.

실행자는 계획을 엄격히 따르며, 즉흥적인 행동은 없습니다.

전체 텍스트 검색 실전 적용

대규모 테이블에서는 사전 필터링이 핵심입니다. 도구는 lowerUTF8(Portfolio) LIKE '%query%'를 사용해 검색하고, ID와 유형을 반환합니다. 이로 인해 run_select_query가 더 빠릅니다. 전체 스캔 대신 타겟팅된 쿼리가 실행됩니다.

예시 체인:

• PortfolioDiscoveryTool(like='stocks') → ID 목록 반환.
• ProfitTool(portfolios=ids, dates=range) → TWR 가져오기.
• Pandas/DataFrame로 병합하여 UI에 표시.

핵심 요약

• Pydantic 기반 결정론적 도구는 SQL에서 LLM 오류를 줄입니다.
• ReWOO 접근법은 복잡한 워크플로우의 계획과 실행을 분리합니다.
• 전체 텍스트 검색은 대규모 ClickHouse 데이터셋에서 필터링에 필수적입니다.
• Open WebUI 통합은 최종 테이블 렌더링을 위한 순차적 호출을 가능하게 합니다.
• 사고 과정 프롬프트는 약한 모델에서도 안정성을 높입니다.

— Editorial Team