Agno와 Streamlit을 활용한 자가 치유(Self-Healing) LLM 에이전트 구축

LLM 에이전트는 강력하지만 실수를 저지르기도 합니다. 특히 형식이 잘못된 파라미터(parameters)로 도구(tools)를 호출할 때 더욱 그렇습니다. 만약 에이전트를 **자가 치유(self-healing)**가 가능하게 만들 수 있다면 어떨까요? 이 포스트에서는 에이전트가 스스로 오류를 감지하고, 진단하며, 자동으로 수정하는 14가지 실제 시나리오를 포함한 프로덕션급 Streamlit 애플리케이션을 구축하는 과정을 살펴보겠습니다.

문제점 (The Problem)

LLM이 잘못된 파라미터로 도구를 호출할 때 — 예를 들어 정수 대신 실수(float)를 전달하거나, 날짜 대신 "tomorrow"를, "CA" 대신 "California"를 전달하는 경우 — 대부분의 시스템은 단순히 실패합니다. 사용자는 에러를 보게 되고 처음부터 다시 시작해야 합니다. 이는 자율성이라는 환상을 깨뜨리고 사용자에게 좌절감을 줍니다.

해결책: RetryAgentRun

Agno 프레임워크는 RetryAgentRun이라는 내장 메커니즘을 제공합니다. 도구가 설명이 포함된 에러 메시지와 함께 이 예외(exception)를 발생시키면, 에이전트는 다음과 같은 과정을 거칩니다:

1. 에러를 수신합니다.
2. 수정 힌트(correction hint)를 읽습니다.
3. 파라미터를 다시 생각합니다.
4. 도구 호출을 자동으로 재시도합니다.

이 루프는 실패당 최대 한 번의 추가 LLM 라운드 트립(round-trip) 비용만 발생하며, 이는 사람이 직접 디버깅하고 다시 프롬프트를 작성해야 하는 것보다 훨씬 효율적입니다.

아키텍처 개요 (Architecture Overview)

사용자 프롬프트 (User Prompt) → Agno 에이전트 (Agno Agent) → 도구 호출 (Tool Call, 오류 가능성 있음)
                           ↓
                    도구가 파라미터 검증 (Tool validates parameters)
...

주요 구현 교훈 (Key Implementation Lessons)

1. Any 타입 어노테이션(Type Annotations) 사용하기

이것이 가장 큰 함정이었습니다. Pydantic은 함수 본문이 실행되기 전에 어노테이션된 파라미터를 검증합니다. 만약 다음과 같이 작성한다면:

def process_payment(amount: Annotated[int, ...], currency: str):
    ...

LLM이 100.5(실수)를 전달하면, 함수가 실행되기도 전에 Pydantic이 ValidationError를 발생시킵니다. 이 경우 RetryAgentRun은 작동하지 않습니다.

해결책: 모든 파라미터에 Any를 사용하고 함수 본문 내부에서 검증하십시오:

from typing import Any

def process_payment(amount: Any, currency: str):
...

2. 에이전트가 실수하도록 강제하기

자가 치유 (Self-healing)는 치유할 대상이 있어야만 작동합니다. 에이전트 서문 (Preamble)은 모델이 첫 번째 호출 시 사용자가 제공한 정확한 (exact) 값을 전달하도록 지시합니다:

CRITICAL: 사용자가 제공한 정확한 (EXACT) 파라미터 값으로 도구를 호출하십시오. 
직접 변환, 변형 또는 형식을 재구성하지 마십시오. 수정이 필요한 경우 
도구가 이를 검증하고 상세한 에러 메시지를 반환할 것입니다.

이 지시가 없다면 GPT-4 또는 Llama 3와 같은 강력한 모델들은 스스로 값을 미리 수정해 버릴 것이며, 이 경우 자가 치유 사이클이 작동하는 모습을 결코 볼 수 없습니다.

3. 타임아웃 안전 장치 (Timeout Safety)

모든 모델이 함수/도구 호출 (function/tool calling)을 지원하는 것은 아닙니다. 60초의 스레드 풀 (thread-pool) 타임아웃을 설정하여 앱이 멈추는 것을 방지합니다:

with concurrent.futures.ThreadPoolExecutor(max_workers=1) as executor:
    future = executor.submit(agent.run, prompt)
    result = future.result(timeout=60)

4. 타임라인 파싱 (Parsing the Timeline)

Agno의 Message 객체에는 tool_call_error 불리언 (boolean) 값이 포함되어 있습니다. 메시지를 스캔하고 도구 호출 인자 (tool call arguments), 에러 메시지 및 결과를 추출함으로써, 도구 호출 → 재시도 에러 → 수정된 재시도 → 성공으로 이어지는 전체 자가 치유 사이클을 시각화하는 구조화된 타임라인을 구축합니다.

14가지 실무 시나리오

이 애플리케이션은 6가지 카테고리와 14가지 구체적인 유스케이스 (use cases)를 다룹니다:

카테고리	유스케이스	치유 대상
💰 금융 (Financial)	결제 처리, 신용카드 유효성 검사	Float→int, 형식화된 카드 번호
...

결과 및 지표 (Results & Metrics)

앱은 유스케이스별 지표와 함께 실행 이력을 추적합니다:

• 도구 호출 (Tool calls): 실행당 총 호출 횟수
• 자가 치유 (Self-heals): 트리거되고 해결된 RetryAgentRun 이벤트 횟수
• 성공률 (Success rate): 성공적으로 완료된 실행의 백분율

대화형 Plotly 차트를 통해 시간에 따른 추세와 시나리오별 세부 내역을 확인할 수 있습니다.

직접 실행해보기

pip install streamlit pandas plotly agno openai httpx pydantic
streamlit run app.py

사이드바에서 Ollama, OpenAI 또는 모든 OpenAI 호환 엔드포인트(endpoint) 중 원하는 제공자(provider)를 설정하세요. Test Connection 버튼을 통해 시작하기 전에 연결 가능 여부를 확인할 수 있습니다.

자가 치유(Self-healing) 에이전트는 취약한 LLM 도구 호출(tool calls)을 견고하고 자율적인 워크플로(workflows)로 변환합니다. Agno의 RetryAgentRun, 세심한 타입 어노테이션(type annotation) 전략, 그리고 사려 깊은 프롬프트 엔지니어링(prompt engineering)의 결합은 스스로의 실수를 실시간으로 자동 감지하고 수정할 수 있는 시스템을 구축합니다.

전체 소스 코드는 즉시 실행 가능한 14가지 시나리오와 함께 제공됩니다. 여러분이 선호하는 모델로 직접 시도해 보고 에이전트가 스스로를 치유하는 과정을 지켜보세요.

코드 및 상세 정보: https://www.dailybuild.xyz/project/160-self-healing-agent