대부분의 AI 에이전트 튜토리얼은 채팅 인터페이스와 RAG (Retrieval-Augmented Generation) 파이프라인 단계에서 멈춥니다. 이 가이드는 그렇지 않습니다.

이 가이드는 LangChain의 에이전트 프레임워크, ethers.js, 그리고 직접 처음부터 작성할 커스텀 도구 세트를 사용하여 온체인 (on-chain) 데이터를 읽고, 스마트 컨트랙트 (smart contracts)와 상호작용하며, DeFi (Decentralized Finance) 작업을 실행할 수 있는 프로덕션급 AI 에이전트를 구축하는 과정을 안내합니다.

이 과정을 마치면 여러분은 다음과 같은 기능을 가진 에이전트를 갖게 됩니다:

• 지갑 잔액 및 토큰 보유량 조회
• ABI를 통해 모든 스마트 컨트랙트의 상태 읽기
• DEX (Decentralized Exchange)에서 토큰 스왑 시뮬레이션 및 실행
• 온체인 이벤트를 모니터링하고 자율적으로 작업 트리거

스택 (Stack)

• LangChain (TypeScript) — 에이전트 프레임워크
• ethers.js v6 — 블록체인 상호작용
• OpenAI GPT-4o — LLM (Large Language Model) 백본
• Alchemy — RPC (Remote Procedure Call) 제공자
• Hardhat — 안전한 테스트를 위한 로컬 포크 (local fork)

1. 프로젝트 설정 (Project Setup)

mkdir ai-blockchain-agent && cd ai-blockchain-agent
npm init -y
npm install langchain @langchain/openai @langchain/core ethers dotenv
...

.env:

OPENAI_API_KEY=your_openai_key
ALCHEMY_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your_key
PRIVATE_KEY=your_wallet_private_key

2. 프로바이더 (Provider) 및 시그너 (Signer) 초기화

// src/provider.ts
import { ethers } from "ethers";
import * as dotenv from "dotenv";
...

3. 커스텀 블록체인 도구 구축

LangChain 에이전트는 그들이 가진 도구만큼 강력합니다. 모든 온체인 작업은 에이전트가 호출할 수 있는 도구가 됩니다. 각 도구에는 이름, 설명 (LLM이 언제 사용할지 결정하기 위해 이를 읽습니다), 그리고 함수 (func)가 필요합니다.

도구 1 — ETH 잔액 가져오기 (Get ETH Balance)

// src/tools/getBalance.ts
import { DynamicTool } from "@langchain/core/tools";
import { provider } from "../provider";
...

도구 2 — ERC-20 토큰 잔액 읽기 (Read ERC-20 Token Balance)

// src/tools/getTokenBalance.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
...

도구 3 — 임의의 컨트랙트 상태 읽기 (Read Arbitrary Contract State)

이 부분이 강력해지는 지점입니다. ABI를 제공하면 에이전트가 어떤 컨트랙트든 쿼리할 수 있습니다.

// src/tools/readContract.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
...

Tool 4 — Gas 가격 조회 및 추정 (Get Gas Price and Estimate)

// src/tools/getGasPrice.ts
import { DynamicTool } from "@langchain/core/tools";
import { provider } from "../provider";
...

Tool 5 — Uniswap V3 스왑 시뮬레이션 (견적만) (Simulate a Uniswap V3 Swap (Quote Only))

// src/tools/getSwapQuote.ts
import { DynamicStructuredTool } from "@langchain/core/tools";
import { z } from "zod";
...

4. 에이전트 조립 (Assembling the Agent)

이제 모든 도구들을 메모리와 행동을 정의하는 시스템 프롬프트와 함께 LangChain 에이전트에 연결합니다.

// src/agent.ts
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIFunctionsAgent } from "langchain/agents";
...

5. 에이전트 실행 (Running the Agent)

// src/index.ts
import { createBlockchainAgent } from "./agent";
import * as dotenv from "dotenv";
...

실행 방법:
npx ts-node src/index.ts

6. Hardhat 메인넷 포크를 사용한 안전한 테스트 (Testing Safely With a Hardhat Mainnet Fork)

메인넷에서 쓰기 작업을 직접 테스트하지 마십시오. 로컬에서 포킹(Fork)하세요:
npm install -D hardhat @nomicfoundation/hardhat-toolbox npx hardhat node --fork https://eth-mainnet.g.alchemy.com/v2/your_key
그런 다음 .env 파일에서 ALCHEMY_RPC_URL을 http://127.0.0.1:8545로 지정하여 로컬 테스트를 진행합니다. 에이전트는 실제 자금을 위험에 빠뜨릴 염려 없이 실제 상태 스냅샷과 상호작용하게 됩니다.

7. 다음 단계 (Where to Take This Further)

이 에이전트는 기초입니다. 프로덕션 확장 기능에는 다음이 포함됩니다:

• 이벤트 리스너(Event listeners) — 온체인 이벤트(청산, 대규모 스왑 등)를 감지하고 에이전트 액션을 자율적으로 트리거합니다.
• 다중 에이전트 아키텍처(Multi-agent architecture) — 하나의 에이전트는 모니터링하고, 다른 에이전트는 실행하며, 세 번째 에이전트는 검증합니다.
• 쓰기 작업(Write operations) — 도구를 확장하여 트랜잭션에 서명하고 브로드캐스트합니다 (먼저 Hardhat 포크를 사용해 테스트하세요).
• 크로스체인 지원(Cross-chain support) — 체인별로 프로바이더를 교체할 수 있으며, 에이전트 아키텍처는 동일하게 유지됩니다.
• 온체인 메모리(On-chain memory) — 에이전트 상태를 인메모리 버퍼 대신 스마트 컨트랙트에 저장합니다.

맺음말

AI 에이전트와 블록체인 인프라 사이의 간극이 빠르게 좁혀지고 있습니다. LangChain의 도구 추상화 (Tool abstraction)를 활용하면 모든 온체인 (On-chain) 작업을 호출 가능한 함수로 간단하게 노출할 수 있으며, 에이전트는 그 위에서 추론 (Reasoning), 시퀀싱 (Sequencing), 의사결정을 처리합니다.

위에서 설명한 아키텍처는 설계상 최소한의 구성입니다. 실제 운영 환경 (Production systems)에서의 진정한 복잡성은 도구를 연결하는 것이 아닙니다. 안전한 실행 경계 (Execution boundaries)를 설계하고, RPC 실패를 유연하게 처리하며, 에이전트가 프롬프트 (Prompt) 공격을 통해 승인해서는 안 될 항목에 서명하지 않도록 보장하는 것이 핵심입니다.

기능을 구축하기 전에 가드레일 (Guardrails)을 먼저 구축하십시오.

저는 Fahad Arif입니다 — Blockchain Developer, 스마트 컨트랙트 감사인 (Smart Contract Auditor), 그리고 DeFi 컨설턴트입니다. 저는 EVM 체인과 Solana 전반에 걸쳐 운영 중인 Web3 시스템을 구축하고 보안을 강화합니다. 더 자세한 내용은 제 웹사이트에서 확인하실 수 있습니다.