Dev Hub3 months ago

Coinbase AgentKit — AI 에이전트가 직접 결제하는 지갑 아키텍처

AI 에이전트가 온체인에서 직접 자금과 결제를 제어하는 시대가 열렸지만, 개발자들은 여전히 개인키 유출 위험과 복잡한 트랜잭션 설계라는 장벽에 가로막혀 있습니다. 기존의 임시방편적인 가동 방식으로는 에이전트의 자율성과 보안성을 동시에 확보하기 어렵습니다. 코인베이스가 제시하는 에이전트 지갑 인프라와 새로운 기계 결제 표준을 통해, 에이전트가 어떻게 스스로 지갑을 가동하고 안전하게 온체인 생태계와 상호작용하는지 실전 개발 관점에서 살펴봅니다.

CDP Wallet과 AgentKit의 역할 정의

AI 에이전트 온체인 인프라의 핵심은 에이전트에게 지갑 제어권을 안전하고 유연하게 부여하는 것입니다. 코인베이스 개발자 플랫폼(CDP) 문서에 따르면, 기존에 사용되던 레거시 패키지들은 모두 사용 중단되었으며 AgentKit v0.1+ 버전과 새로운 특화 지갑 프로바이더들로 아키텍처가 전면 개편되었습니다. 개발자는 이제 @coinbase/agentkit 핵심 패키지를 기반으로 서비스 목적에 맞춘 세분화된 지갑 프로바이더를 명시적으로 선택해야 합니다.

현재 제공되는 세 가지 핵심 지갑 프로바이더는 다음과 같습니다. 먼저 CdpEvmWalletProvider는 CDP가 관리하는 키를 바탕으로 기본적인 외부 소유 계정(EOA) 지갑을 생성합니다. EVM 환경에서 표준 트랜잭션을 빠르게 구현할 때 적합합니다.

CdpSmartWalletProvider는 ERC-4337 스마트 계정 규격을 따릅니다. Base 네트워크의 가스 대납 서비스인 페이마스터와 연동되어 에이전트가 가스비 없이 트랜잭션을 자율적으로 실행할 수 있도록 돕습니다. 마지막으로 솔라나 네트워크와의 통합을 준비 중인 빌더라면 SVM 계정을 지원하는 CdpV2SolanaWalletProvider를 선택할 수 있습니다.

여기서 가장 중요한 개념은 AgentKit 자체가 자금을 보관하는 지갑이 아니라는 점입니다. AgentKit은 LLM이 온체인 액션을 파악하고 호출할 수 있도록 돕는 도구 바인딩 레이어 역할을 수행하며, 실제 트랜잭션 서명과 키 관리는 백엔드에서 격리된 지갑 프로바이더들이 처리합니다. 이 역할 구분을 정확히 인지해야 안전하고 확장성 있는 에이전트 서비스를 설계할 수 있습니다.

TypeScript 환경에서 에이전트 지갑 초기화하기

지갑 인프라를 에이전트와 결합하여 안정적으로 구동하려면 런타임 호환성을 선제적으로 확보해야 합니다. 코인베이스의 AgentKit은 내부 기능의 안정적인 동작을 위해 Node.js 22 버전 이상을 필수 요구 사항으로 강제합니다. 만약 Node.js 22 미만의 하위 버전을 사용할 경우, 에러 메시지나 예외 처리 없이 프로세스가 그냥 정지되는 무증상 실행 실패를 마주하게 되므로 반드시 최신 LTS 개발 환경을 구성해야 합니다.

TypeScript 개발 환경에서 에이전트의 온체인 지갑을 생성할 때는 다자간 연산(MPC) 기술을 바탕으로 암호화 키를 안전하게 보관하는 CdpEvmWalletProvider를 활용하는 것이 정석입니다. 이 프로바이더는 노출되기 쉬운 개인키를 직접 보유하지 않고 코인베이스 인프라를 경유해 트랜잭션에 안전하게 서명하기 때문에 프로덕션 수준의 보안 기준을 충족합니다. 지갑을 인스턴스화할 때는 configureWithWallet 메서드에 발급받은 API 키 세트를 주입하여 환경을 구성합니다.

typescript

import { AgentKit, CdpEvmWalletProvider } from "@coinbase/agentkit";

async function initializeAgent() {
  const walletProvider = await CdpEvmWalletProvider.configureWithWallet({
    apiKeyId: process.env.CDP_API_KEY_ID,
    apiKeySecret: process.env.CDP_API_KEY_SECRET,
    walletSecret: process.env.CDP_WALLET_SECRET,
    networkId: "base-mainnet",
  });

  const address = await walletProvider.getAddress();
  console.log(`에이전트 활성 지갑: ${address}`);

  return await AgentKit.from({
    walletProvider,
    actionProviders: [],
  });
}

자율 에이전트가 중단 없이 서비스를 이어가게 만들려면 지갑 데이터를 영구 보존하는 지속성 패턴이 필수입니다. 최초 연동이 성공하면 exportWallet 메서드를 호출해 해당 지갑의 주소 등 식별 정보를 추출한 다음, 이를 암호화하여 안전한 데이터베이스나 보안 스토리지에 백업합니다. 이후 에이전트 시스템이 재실행될 때 보관해 둔 지갑 주소를 address 옵션에 다시 제공하면 기존의 온체인 상태와 신원 정보, 보유 자산을 매번 새 지갑 생성 없이 그대로 이어받아 거래를 수행할 수 있습니다.

Model Context Protocol 활용과 LLM 도구 바인딩

생성된 온체인 지갑과 지갑의 기능들은 모델 컨텍스트 프로토콜(MCP) 서버를 통해 AI 에이전트에게 바로 연결할 수 있습니다. 기존에는 에이전트에게 온체인 액션을 수행시키기 위해 각 기능마다 API 스키마를 수동으로 작성하고 LLM의 도구 호출에 맞춰 조율하는 번거로운 과정이 필요했습니다. 코인베이스의 MCP 패키지는 지갑이 지원하는 모든 블록체인 동작을 표준 스키마 도구 목록으로 자동 변환해 줍니다.

이를 위해 @coinbase/agentkit-model-context-protocol 라이브러리의 getMcpTools 함수를 활용합니다. AgentKit 인스턴스를 해당 함수에 전달하면, 잔액 조회, 토큰 스왑, 컨트랙트 배포 등 30개 이상의 온체인 액션들이 표준화된 MCP 도구 형태와 핸들러로 반환됩니다.

다음은 AgentKit 지갑을 MCP 도구로 묶어 서버에 등록하는 핵심 구현 코드입니다.

typescript

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
import { getMcpTools } from "@coinbase/agentkit-model-context-protocol";
import { AgentKit } from "@coinbase/agentkit";

const agentKit = await AgentKit.from({ walletProvider });
const { tools, toolHandler } = await getMcpTools(agentKit);

const server = new Server(
  { name: "agentkit-mcp", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
server.setRequestHandler(CallToolRequestSchema, async (req) => 
  toolHandler(req.params.name, req.params.arguments)
);

이 코드를 실행해 구동한 MCP 서버를 클로드 데스크톱과 같은 에이전트 호스트에 연동하면, 복잡한 커스텀 바인딩 코드 없이도 에이전트가 주어진 작업을 분석해 직접 가스비를 내고 스왑이나 결제 트랜잭션을 실행하는 자율 루프가 동작합니다.

x402 프로토콜: API 키 없는 HTTP 네이티브 기계 결제

AI 에이전트가 다른 유료 서비스를 이용할 때 매번 신용카드를 등록하거나 사전에 API 키를 충전하는 방식은 자율적인 작업을 방해하는 거대한 장벽입니다. 이를 해결하기 위해 등장한 x402 프로토콜은 그동안 예약 상태로 방치되어 있던 HTTP 402 결제 필요 상태 코드를 활성화하여, 에이전트가 가입이나 로그인 없이 즉시 서비스를 이용할 수 있는 기계 결제 환경을 구축합니다. 이 표준은 별도의 회원가입 없이 에이전트의 온체인 지갑과 웹 서버 간의 HTTP 네이티브 핸드셰이크만으로 결제를 매끄럽게 조율합니다.

이 프로토콜의 구체적인 무상태 핸드셰이크 흐름은 다음과 같습니다.

최초 요청: 에이전트가 인증 없이 특정 API 서버에 리소스를 요청합니다.
HTTP 402 응답: 서버는 HTTP 402 상태 코드와 함께 결제 요구 사항(체인, 토큰 주소, 금액, 수취인 등)이 Base64 형식으로 기재된 PAYMENT-REQUIRED 헤더를 담아 반환합니다.
결제 서명: 에이전트는 결제 요건을 파악한 뒤, 자신의 지갑에서 가스비 대납을 지원하는 EIP-3009 오프체인 가스리스 서명 증명을 생성합니다.
재요청 및 검증: 에이전트는 서명 데이터를 PAYMENT-SIGNATURE 헤더에 실어 동일한 API 요청을 재전송합니다.
HTTP 200 응답: 서버는 온체인 검증 및 정산을 대행하는 퍼실리테이터(Facilitator)를 거쳐 서명의 유효성을 확인한 뒤, 트랜잭션을 실행합니다. 정산이 성공하면 HTTP 200 정상 응답 코드와 함께 PAYMENT-RESPONSE 정산 증명 헤더를 담아 최종 리소스를 에이전트에게 전송합니다.

이러한 구조 덕분에 에이전트는 온체인 가스비 충전이나 트랜잭션 전파 지연 시간 같은 사용자 경험 저하 없이, 단 한 번의 서명 제출만으로 전 세계 모든 유료 웹 서비스를 즉시 구매하고 사용할 수 있는 자율적인 경제적 능력을 얻게 됩니다.

보안 경계 설계: TEE 격리와 한도 통제

AI 에이전트에게 온체인 결제 권한을 넘길 때 가장 우려되는 점은 에이전트의 오작동이나 자금 탈취 사고입니다. 코인베이스는 하드웨어 수준의 격리 기술과 실시간 정책 통제를 결합해 이 문제를 해결합니다.

지갑의 안전한 구동을 위해 개발자는 에이전틱 지갑 CLI인 awal 또는 페이먼트 MCP 도구를 활용할 수 있습니다. 아래 명령어로 에이전트에게 안전한 지갑 환경을 신속하게 부여할 수 있습니다.

bash

# 에이전틱 지갑 기능 추가
npx skills add coinbase/agentic-wallet-skills

# 또는 페이먼트 MCP 패키지 사용
npx @coinbase/payments-mcp

이 아키텍처는 사용자가 이메일 일회용 비밀번호인 OTP 인증을 거쳐 코인베이스의 신뢰 실행 환경(TEE)에 격리된 비수탁형 지갑을 생성하도록 유도합니다. 에이전트가 동작하는 로컬 서버가 침해당하더라도, 실제 트랜잭션 서명 열쇠는 TEE 영역 내부에 완전히 감춰져 있으므로 보안 위협으로부터 안전합니다.

에이전트가 실행하는 모든 결제는 사전에 합의된 보안 경계를 넘을 수 없습니다. 사용자는 별도의 컴패니언 인터페이스(npx awal show)를 통해 호출당 지출 한도와 세션당 최대 한도를 엄격하게 통제합니다. 이 규칙은 에이전트 스스로 수정할 수 없습니다. 또한 지갑 내부에 내장된 OFAC 준수 필터링 및 거래 분석 스크리닝 기능이 작동하여 자금 세탁 위험이 높은 주소로의 송금을 서명 전 단계에서 자동으로 차단합니다.

개발자가 마주할 자율 온체인 결제의 방향성

코인베이스의 에이전트 인프라와 x402 표준의 결합은 기계 간 자율 결제라는 새로운 경제 계층을 현실로 만들고 있습니다. 개발자는 더 이상 복잡한 API 키 발급이나 사용자 인증 처리에 시간을 낭비하지 않고, 에이전트가 필요한 서비스를 즉시 이용하도록 결제 흐름을 매끄럽게 연결할 수 있습니다.

보안이 격리된 신뢰 실행 환경과 실시간 한도 통제를 통해 에이전트 오작동이나 자금 유출 위험을 원천적으로 제어하는 안전 장치도 확보되었습니다. 이제 개발자는 가치 전달에 수반되는 인프라 관리의 부담을 내려놓고 에이전트 본연의 비즈니스 로직과 자율 행동 정책을 정교화하는 데 집중하면 됩니다.

새로운 기술을 이해하는 가장 확실한 방법은 직접 코드를 실행해 보는 것입니다. 가스비 걱정 없는 Base 네트워크 위에서 스스로 자금을 관리하고 다른 API 서비스를 호출하며 실시간으로 정산하는 자율형 에이전트를 지금 바로 빌드해 보세요.

참고 링크