자율형 Web3 AI 에이전트를 위한 Python 프레임워크를 구축하며 배운 점

DeFi를 위한 봇, 스크립트, 자동화 도구를 몇 달 동안 구축하면서, 저는 지갑 관리, RPC 연결, 스왑 실행, 가스 추정(gas estimation), 에러 처리(error handling) 등 동일한 보일러플레이트(boilerplate) 코드를 계속해서 다시 작성하고 있다는 사실을 깨달았습니다.

그래서 저는 **Web3 Agent Kit**를 구축했습니다. 이는 단 5줄의 코드로 자율형 블록체인 에이전트를 실행할 수 있게 해주는 오픈 소스 Python 프레임워크입니다.

pip install web3-agent-kit

문제점

대부분의 Web3 자동화 도구는 다음과 같은 문제 중 하나 이상을 겪고 있습니다:

• 폐쇄형 소스 (Closed-source) — 내부에서 어떤 일이 일어나고 있는지 알 수 없습니다.
• 특정 체인 종속적 (Chain-specific) — Ethereum 전용이거나 Solana 전용으로 구축되어 있습니다.
• 저수준 (Low-level) — 깊은 Solidity/스마트 컨트랙트(smart contract) 지식이 필요합니다.
• AI 추론 부재 (No AI reasoning) — 순수하게 규칙 기반(rule-based) 자동화이며, 적응력이 없습니다.

저는 LLM의 강력한 기능과 온체인(on-chain) 실행 능력을 결합하여, Python을 통해 여러 체인에 걸쳐 작동하는 무언가를 원했습니다.

주요 기능

1. DeFi 운영 (Uniswap V2 스왑)

from web3_agent_kit import Agent, UniswapSwap, SpendGovernor

agent = Agent(
...

지출 관리자(spend governor)가 매우 중요합니다. 이는 에이전트가 통제를 벗어나 지갑의 자금을 모두 소진하는 것을 방지하는 상한선(hard cap) 역할을 합니다. 모든 트랜잭션은 실행 전 트랜잭션당 제한 및 일일 제한 사항을 기준으로 검사됩니다.

2. 리스크 평가를 포함한 토큰 스나이핑 (Token Sniping)

토큰 스나이퍼(token sniper)는 Uniswap V2의 PairCreated 이벤트를 실시간으로 모니터링하고 각 새로운 토큰을 평가합니다:

from web3_agent_kit.sniper import TokenSniper

sniper = TokenSniper(
...

리스크 평가에는 다음 항목이 포함됩니다:

• 허니팟 탐지 (Honeypot detection) — 실제로 판매가 가능한가?
• 유동성 분석 (Liquidity analysis) — 충분한 깊이(depth)가 있는가?
• 컨트랙트 검증 (Contract verification) — 소스 코드가 공개되어 있는가?
• 소유권 분석 (Owner analysis) — 소유권 포기(renounced ownership)가 되었는가?

3. 크로스 체인 브릿징 (Cross-Chain Bridging)

브릿지 간의 경로를 수동으로 비교하는 대신, 에이전트가 최적의 경로를 찾아냅니다:

from web3_agent_kit.bridge import BridgeAgent

bridge = BridgeAgent(private_key="0x...")
...

이것은 Li.Fi와 Socket 애그리게이터(Aggregator) 모두를 쿼리하여 수수료가 가장 낮은 경로를 선택합니다.

4. LLM 기반 추론 (LLM-Powered Reasoning)

이 부분이 흥미로운 지점입니다. 에이전트는 단순히 실행만 하는 것이 아니라, _생각_을 합니다:

from web3_agent_kit.llm import LLMClient

llm = LLMClient()  # 환경 변수에서 API 키를 자동 감지합니다
...

LLM 클라이언트는 자동 캐스케이드(Cascade) 기능을 갖춘 6개의 제공업체를 지원합니다:

1. Anthropic (Claude) — 최고의 추론 능력
2. Kimi (Moonshot) — 긴 컨텍스트 (Long context)
3. OpenRouter — 멀티 모델 폴백 (Multi-model fallback)
4. DeepSeek — 저렴한 비용
5. Groq — 빠른 추론 (Fast inference)
6. OpenAI — 폴백 (Fallback)

한 제공업체가 속도 제한(Rate limits)에 걸리거나 오류가 발생하면, 자동으로 다음 제공업체로 폴백합니다.

5. 포트폴리오 추적 (Portfolio Tracking)

여러 토큰에 걸친 실시간 포트폴리오 대시보드:

from web3_agent_kit.portfolio import Portfolio

portfolio = Portfolio(w3=w3, address="0x...")
...

아키텍처 결정 사항 (Architecture Decisions)

왜 Python인가?

대부분의 DeFi 도구는 JavaScript/TypeScript (ethers.js, viem)로 작성되어 있습니다. 제가 Python을 선택한 이유는 다음과 같습니다:

• 더 나은 AI/ML 생태계 (LangChain, transformers 등)
• 모니터링 루프를 위한 더 깔끔한 비동기 (Async) 패턴
• 제가 타겟팅하는 대상(AI 엔지니어)이 주로 Python을 사용함

왜 멀티 제공업체 LLM 캐스케이드인가?

LLM API는 신뢰할 수 없습니다. 속도 제한, 서비스 중단, 가격 변동 등이 발생합니다. 단일 제공업체 설정은 단일 장애점 (Single point of failure)이 됩니다. 캐스케이드 패턴은 에이전트가 결코 생각을 멈추지 않음을 의미합니다.

왜 지출 거버너(Spend Governor)인가?

이것은 자율형 에이전트에게 타협할 수 없는 요소입니다. 하드 캡(Hard caps)이 없다면, 버그나 적대적 프롬프트(Adversarial prompt)가 지갑을 털어갈 수 있습니다. 거버너는 LLM 레벨이 아닌 도구(Tool) 레벨에서 강제되므로, 프롬프트 인젝션(Prompt injection)에 의해 우회될 수 없습니다.

내가 배운 점

1. 보안이 전부다 (Security is everything) — 자율형 에이전트(Autonomous agent)의 버그 하나는 실제 금전적 손실로 이어질 수 있습니다. 지출 관리자(Spend governor)는 개발 과정에서 저를 여러 번 구해냈습니다.

2. 가스 추정(Gas estimation)은 예술이다 — 모든 트랜잭션이 가스를 정확하게 추정하는 것은 아닙니다. 폴백(Fallback) 메커니즘과 과다 추정 버퍼(Overestimation buffers)가 필요합니다.

3. LLM은 수학에 약하다 — LLM이 토큰 양을 계산하게 두지 마세요. 견적(Quotes)을 낼 때는 항상 온체인(On-chain)의 getAmountsOut()을 사용해야 합니다.

4. 멀티체인(Multi-chain)은 복잡하다 — 모든 체인은 서로 다른 RPC 특성, 가스 모델, 컨트랙트 주소를 가지고 있습니다. 초기에 추상화(Abstract)를 진행하세요.

5. 실제 돈으로 테스트하는 것은 공포스럽다 — 테스트넷(Testnets)을 사용하되, 테스트넷은 메인넷과 동일하게 동작하지 않으므로 아주 적은 금액($0.01)으로 메인넷(Mainnet)에서도 테스트를 진행하세요.

직접 시도해보기

pip install web3-agent-kit

GitHub: github.com/ulsreall/web3-agent-kit

PyPI: pypi.org/project/web3-agent-kit

이 저장소(Repo)에는 스왑(Swaps), 스나이핑(Sniping), 포트폴리오 추적(Portfolio tracking), 브릿징(Bridging), 그리고 LLM 통합(LLM integration)을 다루는 10가지 즉시 사용 가능한 예제가 포함되어 있습니다. MIT 라이선스가 적용되어 있으므로 원하는 대로 사용하세요.

기여(Contributions), 이슈(Issues), 기능 요청(Feature requests)은 언제나 환영합니다. 이 도구로 멋진 것을 만드신다면 꼭 알려주세요.

이 내용이 유용했다면 GitHub 저장소에 스타(Star)를 눌러주세요. 이는 가시성을 높이는 데 도움이 되며, 제가 계속해서 개발을 이어 나갈 수 있는 동기부여가 됩니다.