AgentKit 사용법: AI 에이전트 구축을 위한 실용적인 엔드투엔드 가이드
업데이트 날짜: 2025년 9월 23일
7 분
"AgentKit" 사용법: AI 에이전트 구축을 위한 실용적인 엔드 투 엔드 가이드
만약 "AgentKit"에 대한 이야기는 들어봤지만 실제로 어떻게 활용하는지 궁금했다면 제대로 찾아오셨습니다. 여기서 주의할 점은 AgentKit은 단일 제품이 아니라는 것입니다. 이 이름은 여러 에코시스템에서 사용됩니다. 가장 주목할 만한 것은 온체인/Web3 작업을 위한 Coinbase의 AgentKit, 에이전트 네트워크 오케스트레이션을 위한 Inngest의 AgentKit, 그리고 Coinbase의 키트와 함께 OpenAI Agents SDK를 사용하는 다양한 튜토리얼입니다. 이 가이드에서는 각 AgentKit이 무엇인지, 왜 다른 AgentKit보다 특정 AgentKit을 선택해야 하는지, 그리고 재사용할 수 있는 프로 팁과 실제 패턴을 통해 단계별로 설정하는 방법을 자세히 설명합니다.
실용적이고 솔루션 지향적인 접근 방식을 취할 것입니다: 빠른 비교, 명확한 설정, 실행 가능한 예제, 그리고 피해야 할 문제점.
어떤 "AgentKit"에 대해 이야기하는 건가요?
- Coinbase AgentKit (CDP/온체인): AI 에이전트가 지갑을 관리하고, 온체인 트랜잭션을 보내고, 토큰을 배포하는 등 지원되는 네트워크에서 더 많은 작업을 수행할 수 있습니다. Web3 네이티브 에이전트 (예: 팁 봇, 토큰 배포자, NFT 배포자)를 구축하는 데 이상적입니다. 퀵스타트 가이드 및 워크숍을 널리 이용할 수 있습니다.
- Inngest AgentKit: 확장 가능하고 이벤트 중심적인 실행에 중점을 둔 에이전트, 도구를 정의하고 네트워크 내에서 실행하는 프레임워크입니다. 여러 에이전트, 재시도 로직 및 백그라운드 워크플로우를 오케스트레이션하는 데 적합합니다.
- Safe/Protocol Kits (컨텍스트): 에이전트가 스마트 계정 제어 (멀티시그, 정책, 일괄 호출)가 필요한 경우, 안전한 실행을 위해 Safe의 Protocol Kit이 온체인 에이전트와 함께 사용되는 경우가 많습니다.
온체인 AI 에이전트를 빠르게 구축하는 것이 목표라면 Coinbase AgentKit부터 시작하세요. 강력한 멀티 에이전트 아키텍처 및 스케줄링이 필요한 경우 Inngest AgentKit이 적합합니다. 많은 팀에서 OpenAI Agents를 추론에, Coinbase AgentKit을 온체인 작업에, Inngest를 오케스트레이션에 사용하는 방식으로 조합합니다.
: 빠른 의사 결정 가이드
- 자금을 이동하거나, 토큰을 배포하거나, dApp과 상호 작용할 수 있는 Web3 에이전트가 필요한 경우 → Coinbase AgentKit을 사용하세요.
- 재시도 및 상태 유지를 통해 여러 에이전트/도구를 오케스트레이션하는 내구성 있는 이벤트 중심 시스템이 필요한 경우 → Inngest AgentKit을 사용하세요.
- 에이전트에 대한 엔터프라이즈급 지갑 보안 또는 멀티시그 거버넌스가 필요한 경우 → 에이전트와 함께 Safe의 Protocol Kit을 통합하세요.
파트 1: Coinbase AgentKit 사용법 (온체인 에이전트)
Coinbase AgentKit을 사용하는 이유
- 즉시 사용 가능한 온체인 작업 (지갑 작업, 전송, 토큰 관리)을 위해 구축되었습니다.
- 깔끔한 개발자 경험과 빠른 시작 도구
- 소셜 (예: X)에서 사용자와 상호 작용하고 온체인에서 작업을 처리하는 봇/에이전트에 적합합니다.
설정 개요
- CLI 및 SDK를 설치하고 (빠른 시작 참조) 네트워크, 키 및 RPC 엔드포인트에 대한 환경 변수를 구성합니다.
- 프로젝트를 초기화하고 필요한 온체인 기능을 선택합니다.
- 도구 (예: 지갑 작업, 토큰 배포)를 에이전트에 바인딩합니다.
- 에이전트를 추론 모델 (OpenAI 또는 유사한 모델)에 연결하여 도구를 호출할 시기를 결정합니다.
공식 빠른 시작을 따라 몇 분 안에 실행하십시오. 지갑을 관리하고 Twitter/X에서 상호 작용하는 Web3 AI 에이전트 구축에 대한 실습 튜토리얼은 QuickNode 연습 및 AgentKit Twitter 봇 생성에 대한 비디오 데모를 참조하십시오.
예제 아키텍처
- 추론 레이어: 함수/도구 호출이 있는 LLM
- 액션 레이어: Coinbase AgentKit 도구 (전송, 토큰 배포)
- 영속성: 데이터베이스에 에이전트 메모리/목표 저장
- 프런트 엔드: 사용자 프롬프트를 위한 채팅 UI 또는 소셜 봇 (X)
모범 사례
- 최소 권한 원칙: 에이전트 키를 필요한 범위와 작은 잔액으로 제한합니다.
- 정책 프롬프트: 온체인 작업이 허용되는 시기에 대한 명시적 규칙을 정의합니다.
- 가드레일: 트랜잭션 미리보기/확인, 시간 창당 제한을 구현합니다.
- 관찰 가능성: 감사 가능성을 위해 도구 호출, 트랜잭션 및 모델 출력을 기록합니다.
일반적인 함정
- 허술한 키 관리: 비밀을 하드 코딩하지 말고 볼트를 사용하십시오.
- 무제한 작업: 대량 가치 전송에 대한 확인이 필요합니다.
- 누락된 비율 제한: RPC 엔드포인트 및 소셜 API를 보호합니다.
파트 2: Inngest AgentKit 사용법 (에이전트 네트워크 및 오케스트레이션)
Inngest AgentKit을 사용하는 이유
- 목표 및 도구 세트가 있는 일급, 상태 비저장 작업자로서의 에이전트
- 복잡한 워크플로우를 위해 여러 에이전트를 조정하는 네트워크
- 재시도 및 내구성 있는 실행을 통한 이벤트 중심 설계
빠른 시작으로 첫 번째 에이전트를 시작하고 네트워크 내에서 실행하십시오. 비즈니스 로직을 연결하기 전에 핵심 개념 (에이전트, 도구, 네트워크)을 읽으십시오.
설정 단계
- 에이전트 목표 및 사용 가능한 도구 (API, 내부 서비스, 온체인 키트)를 정의합니다.
- 네트워크를 만들고 에이전트를 등록합니다.
- 이벤트를 내보내 에이전트를 트리거합니다. 복원력을 위해 재시도 및 백오프를 사용합니다.
- 관찰 가능성 추가: 로그, 추적, 결과.
오케스트레이션 패턴
- 감독자-작업자: 플래너 에이전트는 작업자를 전문 에이전트에 위임합니다.
- 이벤트 소싱: 상태 변경은 에이전트가 반응하도록 트리거합니다 (예: payment_received → fulfillment_agent).
- Human-in-the-loop: 위험한 작업에 대한 승인, 일시 중지/재개
팁
- 에이전트를 상태 비저장으로 유지하십시오. 이벤트/상태 저장소를 통해 컨텍스트를 전달하십시오.
- 시간 경과에 따른 성능을 추적하기 위해 도구 및 프롬프트 버전을 지정합니다.
- 실패 모드를 시뮬레이션합니다. 외부 호출에 대한 멱등성을 확인합니다.
파트 3: Safe를 사용한 보안 실행 (선택 사항이지만 권장됨)
에이전트가 자금을 관리하거나 관리 작업을 실행하는 경우 거버넌스를 통해 스마트 계정을 통합하십시오. Safe의 Protocol Kit은 스마트 계정 및 멀티시그 흐름에 대한 생성, 구성 및 실행을 제공합니다.
- 사용 사례: 온체인 에이전트가 트랜잭션을 제출하는 동안 소유자 (사람 또는 감독자 에이전트)가 공동 서명합니다.
- 이점: 정책 제어, 지출 제한 및 안전한 복구
- 패턴: 에이전트가 트랜잭션을 제안합니다. 정책 엔진 (또는 사람)이 서명하고 실행합니다.
단계별: 최소 온체인 에이전트 구축
다음은 적용할 수 있는 개념적 흐름입니다 (언어 불가지론적, 의사 코드 스타일). 작동 코드 및 CLI 명령은 Coinbase 빠른 시작을 참조하십시오.
- 프로젝트 초기화 및 종속성 설치
- 프로젝트 디렉토리를 만들고 AgentKit SDK 및 LLM 클라이언트를 설치하십시오.
- 환경 변수 설정: RPC URL, 개인 키 또는 관리형 지갑, 네트워크
- 도구 및 기능 정의
- 지갑:
get_balance,transfer(to, amount)
- 토큰:
deploy_erc20(name, symbol, supply)
- 필요에 따라 계약 호출 읽기/쓰기
- 추론 모델 연결
- 목표 및 제약 조건을 정의하는 시스템 프롬프트를 제공하십시오.
- 안전한 함수 호출을 위해 스키마를 사용하여 도구를 등록하십시오.
- 안전 및 정책 추가
- 임계값 이상의 전송에 대한 확인을 적용하십시오.
- 일일 지출을 제한하고 생산에 대한 수신인 주소를 허용 목록에 추가하십시오.
- 기본 인터페이스 제공
- CLI:
agent ask "0.01 ETH를 0x...로 보내기"
- 웹/채팅: 작업을 제출하고 영수증을 표시하는 최소 UI
- 먼저 테스트넷에서 테스트하십시오.
- 수도꼭지 자금; 작업 로그 및 트랜잭션 해시를 확인하십시오.
- 관찰 가능성으로 생산으로 이동하십시오.
- 원격 측정, 실패한 트랜잭션에 대한 경고 및 모델 동작의 드리프트를 캡처하십시오.
프로덕션에서 작동하는 패턴
- 계획 후 실행: 모델을 사용하여 도구를 호출하기 전에 단계를 설명합니다.
- 드라이 런 모드: 트랜잭션을 미리보고 승인을 요청합니다.
- 예산 봉투: 각 작업에 지출 한도 및 도구 시간 초과를 제공합니다.
- 합성 모니터링: 예약된 작업은 에이전트의 상태 및 RPC 연결을 확인합니다.
실제 예제 시나리오
- 커뮤니티 팁 봇: 사용자가 X에서 봇을 언급합니다. 에이전트는 확인된 지갑을 온체인에서 팁합니다.
- 고객 보상: 에이전트는 온체인 작업을 추적하고 매주 보상 토큰을 보냅니다.
- DAO 작업: 에이전트는 제안에 대한 Safe 트랜잭션을 초안합니다. 멀티시그는 검토 후 서명합니다.
- 마켓플레이스 어시스턴트: 에이전트는 NFT를 나열하고 사용자 질문에 응답하며 확인 후 거래를 실행합니다.
안내식 Web3 에이전트 빌드의 경우 QuickNode 튜토리얼 및 Agents SDK + AgentKit 통합을 통해 Coinbase의 워크숍을 참조하십시오.
문제 해결: 빠른 수정
- 내 에이전트가 트랜잭션을 보낼 수 없습니다. 네트워크, 가스 설정 및 키 권한을 확인하십시오. 먼저 테스트넷을 사용해보십시오.
- 도구 호출이 불규칙합니다. 도구 스키마 및 유효성 검사를 강화하십시오. 사전 검사 프롬프트를 추가하십시오.
- 실행이 불안정합니다. 백오프로 재시도를 추가하십시오. RPC 비율 제한 및 상태 코드를 모니터링하십시오.
- 보안 문제: 키를 회전하고, 자금을 격리하고, Safe 기반 승인으로 이동하십시오.
참고: Sider.AI로 워크플로우 가속화
주목할 가치가 있음—프롬프트, 접착제 코드 및 문서를 반복하는 경우 사이드킥이 도움이 될 수 있습니다. Sider.AI를 사용하면 편집기와 함께 연구, 코드 스니펫 및 실험 로그를 체계적으로 유지하여 에이전트에 대한 빌드-측정-학습 루프를 가속화할 수 있습니다. 여기에서 탐색하십시오:
주요 내용
- "AgentKit"은 일반적으로 온체인 도구 키트인 Coinbase와 오케스트레이션 키트인 Inngest를 나타냅니다. 온체인 작업과 다중 에이전트 조정의 필요성에 따라 선택하십시오.
- 작게 시작하십시오. 테스트넷, 최소 도구, 엄격한 정책. 기능을 점진적으로 추가하십시오.
- 재정 또는 관리 권한의 경우 거버넌스 및 보안을 위해 Safe를 통합하십시오.
- 에이전트를 프로덕션 소프트웨어처럼 취급하십시오. 로깅, 경고, 제한 및 사람의 승인.
추가 학습
- Coinbase AgentKit 빠른 시작 및 CLI
- 워크숍: Coinbase AgentKit을 사용한 OpenAI Agents SDK
- Web3 AI 에이전트 연습 (QuickNode)
- Inngest AgentKit 빠른 시작 및 개념
- 안전한 스마트 계정을 위한 Safe Protocol Kit
FAQ
Q1: AgentKit은 무엇이며 어떤 것을 사용해야 합니까? AgentKit은 일반적으로 온체인 작업을 위한 Coinbase AgentKit과 에이전트 오케스트레이션을 위한 Inngest AgentKit을 의미합니다. Web3 작업(지갑, 토큰)에는 Coinbase를 선택하고 다중 에이전트, 이벤트 중심 워크플로우에는 Inngest를 선택하십시오.
Q2: AI 에이전트가 온체인에서 자금을 안전하게 이동하도록 하려면 어떻게 해야 합니까? 작은 잔액, 엄격한 도구 스키마 및 위험한 작업에 대한 확인 프롬프트를 사용하십시오. 프로덕션의 경우 Safe 스마트 계정을 통합하고 멀티시그 또는 정책 승인을 요구하십시오.
Q3: OpenAI Agents와 Coinbase AgentKit을 결합할 수 있습니까? 예. 추론 레이어(OpenAI Agents/함수 호출)를 Coinbase AgentKit 도구에 연결하십시오. 많은 개발자가 오케스트레이션 및 재시도를 위해 Inngest도 추가합니다.
Q4: AgentKit을 사용할 때 일반적인 함정은 무엇입니까? 키를 하드 코딩하고, 테스트넷을 건너뛰고, 무제한 작업을 허용하는 것이 가장 큰 문제입니다. 안전을 유지하려면 비율 제한, 지출 한도 및 강력한 관찰 가능성을 추가하십시오.
Q5: Web3 AI 에이전트를 구축하기 위한 빠른 시작은 어디에서 찾을 수 있습니까? 설정 및 예제는 Coinbase의 AgentKit 빠른 시작으로 시작하고, QuickNode의 튜토리얼과 엔드 투 엔드 지침은 워크숍 비디오를 참조하십시오.
