Vanna 2.0 마이그레이션 — 0.x에서 에이전트 워크플로로
Vanna 2.0 마이그레이션 — 0.x에서 에이전트 워크플로로
Vanna 2.0+는 단순한 LLM 래퍼에서 유저-어웨어 에이전트 프레임워크로 구조가 바뀌었어요. 기존 0.x 코드를 쓰고 있다면 이 가이드로 옮겨가면 돼요. "직접 메서드 호출"이 "에이전트 워크플로"로 바뀐 것이 핵심 변화예요.
2.0+에서 새로 생긴 것
- 유저 인식: 정체성과 권한이 모든 레이어에 흐름.
- 웹 컴포넌트: 스트리밍 응답을 갖춘 미리 만들어진 UI.
- 툴 레지스트리: 모듈형·확장 가능한 툴 시스템.
- 풍부한 UI 컴포넌트: 표·차트·상태 카드(텍스트만이 아니라).
- 기본 스트리밍: SSE로 점진적 응답.
- 엔터프라이즈 기능: 감사 로그, 속도 제한, 관찰 가능성.
- FastAPI/Flask 서버: 프로덕션 준비 백엔드 포함.
0.x에서 바뀐 것
| 항목 | 0.x | 2.0+ |
|---|---|---|
| 사용자 컨텍스트 | 없음 | User 객체가 권한과 함께 시스템 전체에 흐름 |
| 상호작용 | 직접 호출 (vn.ask()) |
에이전트 기반 + 스트리밍 컴포넌트 |
| 도구 | 모놀리식 메서드 | 스키마를 가진 모듈형 Tool 클래스 |
| 응답 | 텍스트/DataFrame | 표·차트·코드 등 풍부한 UI 컴포넌트 |
| 학습 | vn.train() + 벡터 DB |
시스템 프롬프트·컨텍스트 인리처·RAG 툴 |
| DB 연결 | vn.connect_to_postgres() |
의존성으로 주입되는 SqlRunner 구현 |
| 웹 UI | 옛 Vanna Flask | 내장 웹 컴포넌트 + 백엔드 |
| 스트리밍 | 없음 | 기본 Server-Sent Events |
| 권한 | 없음 | 툴에 대한 그룹 기반 접근 제어 |
| 감사 로그 | 없음 | 내장 감사 로깅 시스템 |
빠른 마이그레이션
바로 못 옮긴다면 Legacy Adapter로 시작할 수 있어요. 기존 vn 객체를 감싸면 ToolRegistry와 AgentMemory 인터페이스를 자동 구현해줘요.
from vanna import Agent
from vanna.servers.fastapi import VannaFastAPIServer
from vanna.core.user import UserResolver, User, RequestContext
from vanna.legacy.adapter import LegacyVannaAdapter
from vanna.integrations.anthropic import AnthropicLlmService
# 기존 vn 객체를 어댑터로 감싸기
legacy_adapter = LegacyVannaAdapter(vn)
llm = AnthropicLlmService(model="claude-haiku-4-5")
agent = Agent(
llm_service=llm,
tool_registry=legacy_adapter,
agent_memory=legacy_adapter,
user_resolver=SimpleUserResolver()
)
server = VannaFastAPIServer(agent)
server.run(host='0.0.0.0', port=8000)
LegacyVannaAdapter는 vn.run_sql()을 run_sql 툴로 감싸고, 학습 데이터를 검색 가능한 메모리로 노출하며, 기존 DB 연결과 학습 데이터를 유지해줘요.
더 알아보기
에이전트·툴·메모리의 자세한 구성은 Configure 문서에서 이어서 볼 수 있어요.