AgentKV 스킬
AgentKV는 에이전트 네이티브 키-값 저장소입니다. 하나의 AgentKV 계정을 보유하며, 클라이언트가 자동 감지하는 두 가지 방식 중 하나로 관리됩니다 — 동일한 데이터, 동일한 크레딧, 동일한 제로-지식 암호화:
- 지갑-키(기본값): 서명 가능한 지갑이 곧 계정입니다. 해당 주소가 네임스페이스이고 키는 AES 키를 파생합니다. AgentKV는 첫 사용 시 자동으로 프로비저닝합니다 — 계정, API 키, 가입이 필요 없습니다.
- 계정-키: 서명할 수 없는 관리형 지갑(예: awal)의 경우, 불투명한
ak_…베어러 토큰이 식별자 + 네임스페이스가 되고 로컬 암호화 키가 암호화합니다 — 지불 지갑과 분리되므로 모든 서명 지갑이 계정에 자금을 조달할 수 있습니다.
값은 서버에 도달하기 전에 클라이언트 측에서 암호화(AES-256-GCM)되므로 서버는 제로-지식입니다. 저장 비용은 x402 프로토콜을 통해 Base(메인넷) 또는 Base Sepolia(테스트넷)에서 실제 USDC로 청구되며, 작업당 지불됩니다.
전제 조건:
@agentkv/cli가 npm에 게시되고npx @agentkv/cli로 확인 가능해야 합니다. 현재 이 패키지는 아직 게시되지 않았습니다 — 이 플러그인은 해당 게시 단계를 기다리는 아티팩트입니다.
AgentKV를 사용해야 하는 경우
다음이 필요할 때 AgentKV를 사용하세요:
- 지속적인 교차 세션 메모리 — 현재 세션이 종료되어도 유지되어야 하는 사실, 선호도, 요약 또는 작업 상태.
- 비밀 저장 및 사용 — API 키, 토큰 또는 자격 증명. 서버는 암호문만 볼 수 있습니다(제로-지식). ⚠️ 일반
agentkv_set/agentkv_get은 값을 이 에이전트의 모델 컨텍스트를 통해 라우팅합니다. 실제 비밀은 비밀-안전 도구(agentkv_set_from_env/_from_file로 저장,agentkv_get_to_file/agentkv_run_with_secret로 사용)를 사용하여 일반 텍스트가 모델 턴에 들어가지 않도록 하세요. 비밀 섹션을 참조하세요. - 공유 플릿 상태 — 단일 지갑을 공유하는 여러 에이전트 인스턴스가 공통 네임스페이스를 통해 조정할 수 있습니다(예: 작업 큐, 잠금, 공유 카운터).
- TTL 제한 임시 상태 — 자동 만료되는 임시 값(예: nonce, 초안)으로 수동 정리가 필요 없습니다.
다음의 경우에는 AgentKV를 사용하지 마세요:
- 대용량 바이너리 블롭(최대 값 크기는 256KB).
- 예산에 민감한 맥락에서 무료, 제로 비용 작업 — 모든
set및get은 USDC가 소요됩니다. 먼저 지출 한도를 확인하세요. - 사용자 대면 애플리케이션의 적절한 데이터베이스를 대체(에이전트 워크로드용으로 설계되었으며, 고처리량 웹 앱용이 아님).
사용 가능한 MCP 도구
agentkv MCP 서버는 12개의 도구를 제공합니다 — 8개의 핵심 도구와 4개의 비밀-안전 도구(모델 컨텍스트에 일반 텍스트가 절대 들어가지 않음, 아래 비밀 섹션 참조):
| 도구 | 설명 | 비용 |
|---|---|---|
agentkv_set | 키 아래에 암호화된 값을 씁니다. 선택적 TTL(일)을 허용합니다. | ~$0.005 USDC |
agentkv_get | 키로 값을 읽고 복호화합니다. 슬라이딩 TTL은 기본적으로 만료를 재설정합니다. | ~$0.003 USDC |
agentkv_delete | 키를 즉시 삭제합니다. | 무료 |
agentkv_deposit | 지갑의 네임스페이스에 USDC 크레딧을 입금하여 작업을 선불로 자금 조달합니다. 계정-키 모드에서는 거부됨(관리형 계정에는 지갑이 없음 — <endpoint>/account/deposit을 통해 자금 조달). | USDC 구매 |
agentkv_balance | 지갑 네임스페이스의 현재 USDC 크레딧 잔액을 확인합니다. | 무료 |
agentkv_wallet_address | 지갑 주소(네임스페이스 식별자)를 반환합니다. 정보용입니다. | 무료 |
agentkv_fund | 카드→USDC 온램프 URL을 반환하여 Base의 지갑에 USDC를 전달합니다. URL만 생성 — 결제는 이루어지지 않습니다. 계정-키 모드에서는 거부됨(USDC를 구매할 지갑이 없음). | 무료 |
agentkv_list_keys | 이 지갑의 저장된 키를 나열합니다 — 실제 키 이름, 로컬에서 복호화됨; 서버는 불투명한 다이제스트만 봅니다. 페이지네이션 지원. | 무료 |
agentkv_set_from_env | 로컬 env var에서 읽은 비밀을 저장합니다(NAME 전달). 값이 모델 컨텍스트에 절대 들어가지 않습니다. | ~$0.005 USDC |
agentkv_set_from_file | 로컬 파일에서 읽은 비밀을 저장합니다(PATH 전달). 내용이 모델 컨텍스트에 절대 들어가지 않습니다. | ~$0.005 USDC |
agentkv_get_to_file | 값을 로컬 파일로 복호화합니다. { found, path, bytes }를 반환 — 값 자체는 반환하지 않습니다. | ~$0.003 USDC |
agentkv_run_with_secret | 비밀을 자식 프로세스 env에만 주입하여 명령을 실행합니다; 명령의 출력을 반환하며, 비밀은 절대 반환하지 않습니다. | ~$0.003 USDC |
가격 및 입금: 종량제는
agentkv_set당 ~$0.005,agentkv_get당 ~$0.003입니다. 선불 크레딧은 약 1/10 비용(약 $0.0005 per set, 약 $0.0003 per get)입니다.agentkv_deposit은 최소 $1.00이 필요하며 할인된 크레딧 요율로 네임스페이스에 자금을 조달합니다.
비밀 — 모델 컨텍스트 외부에 값 유지
agentkv_set 및 agentkv_get은 값을 이 에이전트의 자체 모델 컨텍스트를 통해 라우팅합니다(쓰기 시 도구 인수, 읽기 시 도구 결과). 클라이언트 측 암호화는 값을 서버에 대해 제로-지식으로 만듭니다 — 에이전트로부터 숨기지 않습니다. 따라서 일반 set/get은 비밀이 아닌 메모리(계획, 요약, 선호도)에 적합하지만, 실제 자격 증명의 경우 비밀-안전 도구를 사용하여 일반 텍스트가 모델 턴에 절대 들어가지 않도록 하세요:
- 저장:
agentkv_set_from_env(env var NAME 전달) 또는agentkv_set_from_file(PATH 전달). 서버가 값을 로컬에서 읽고, 암호화한 다음 저장합니다. - 사용:
agentkv_run_with_secret(자식 프로세스의 env에만 비밀을 넣어 명령을 실행하고 명령의 출력을 반환) 또는agentkv_get_to_file(복호화된 값을 로컬 파일에 쓰고 경로를 반환 — 사용 후 삭제).
잔여: 비밀이 로컬 파일이나 자식 프로세스 env에 잠시 구체화됩니다 — 로컬 및 일시적이며, 모델 제공자에게 전송되거나 대화 기록에 기록되지 않습니다. agentkv_run_with_secret(디스크에 파일 없음)이 가장 안전합니다.
일회성 설정
Claude Code의 마켓플레이스에서 플러그인을 설치합니다 — 정확한 /plugin marketplace add 및 /plugin install 명령은 플러그인의 README.md(plugin/README.md)에 있습니다. 설치 후:
1. 자격 증명(설치 시 입력, 셸 환경 변수 아님)
플러그인이 설치되면 Claude Code가 입력을 요청하여 MCP 서버에 전달합니다(개인 키는 마스킹되어 OS 키체인에 저장 — 디스크에 기록되지 않음):
| 설정 | 필수 | 설명 |
|---|---|---|
| 지갑 개인 키 | 아니요 | 선택 사항 — 비워 두면 AgentKV가 첫 사용 시 로컬 지갑을 생성 및 관리합니다(그런 다음 자금 조달 및 백업). 자신의 것을 사용하려면: EVM 개인 키(hex), 네임스페이스를 소유하고 비용을 지불하는 지갑. |
| AgentKV 엔드포인트 | 아니요 | 호스팅된 AgentKV API; 기본값은 https://api.agentx402.ai. |
| 네트워크 | 아니요 | eip155:8453(Base 메인넷, 기본값) 또는 eip155:84532(Base Sepolia 테스트넷). |
| 암호화 키 | 아니요 | 파생된 AES 키를 재정의(고급; 기본값은 개인 키의 HKDF). |
| 최대 작업당 지출(USD) | 아니요 | 이 금액을 초과하는 단일 작업을 거부; 비어 있음 = 작업당 상한 없음. |
| 최대 세션 지출(USD) | 아니요 | 누적 세션 지출이 이 금액을 초과하면 작업을 거부; 비어 있음 = 상한 없음. |
나중에 변경하려면 /plugin을 다시 실행하세요. 서버가 로드되었는지 /mcp로 확인하세요(agentkv 서버와 12개 도구가 보여야 함).
기존 USDC 잔액 대신 카드로 자금을 조달하려면 agentkv_fund 도구가 Coinbase 온램프 URL을 반환합니다 — 서버에서 AGENTKV_ONRAMP_APP_ID(공개 CDP 프로젝트 ID)를 설정하고 선택적으로 AGENTKV_ONRAMP_PROVIDER로 제공자를 변경하여 구성하세요.
2. 네임스페이스 자금 조달
agentkv_wallet_address로 지갑 주소를 읽고, Base의 해당 주소로 USDC를 보낸 다음(또는 agentkv_fund를 호출하여 카드→USDC 온램프 URL 획득), agentkv_deposit을 호출하여 금액(최소 $1)을 네임스페이스에 입금합니다. 그러면 읽기 및 쓰기가 자동으로 크레딧에서 지불됩니다.
계정-키 모드 (관리형 지갑 / awal)
서명할 수 없는 관리형 지갑은 지갑 대신 계정-키 모드를 사용합니다. 플러그인 외부에서 CLI가 계정을 생성하고 자금을 조달합니다:
agentkv account new # ak_… + 로컬 암호화 키 생성(0600 권한으로 저장) — 백업 필수, 복구 불가능
# 서명 가능한 지갑에서 자금 조달(실제 ≥$1 입금이 첫 입금 시 계정을 생성):
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'
그런 다음 AGENTKV_ACCOUNT_KEY=ak_…와 AGENTKV_ENCRYPTION_KEY=0x…(로컬 AES 키 — 계정 모드에서는 필수, 파생할 지갑이 없음)를 설정하세요. 계정이 네임스페이스이며; 기본적으로 읽기/쓰기는 베어러만 전달하고 선불 크레딧을 차감합니다 — 작업당 서명이 필요 없습니다. 어떤 방식으로든 서버에 대해 제로-지식 상태를 유지합니다. 모든 서명 지갑이 동일한 계정을 충전할 수 있습니다.
AGENTKV_TOPOFF=awal도 설정하면 크레딧 부족 시 자동으로 자체 복구됩니다 — 추가 조치 불필요, CLI/MCP 세션이 awal을 통해 자체 충전을 지불하고 계속합니다. 설정하지 않은 경우, 크레딧 부족 오류가 발생하면 awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}'를 실행하고 재시도하세요. 또는 AGENTKV_INLINE=awal을 설정하여 작업당 인라인 지불을 사용할 수 있습니다: 각 요청이 베어러와 함께 지불 서명을 전달하고 즉시 온체인에서 결제되므로 선불 크레딧이 전혀 필요하지 않습니다.
지출 상한 인식
모든 agentkv_set, agentkv_get 및 agentkv_deposit 호출은 실제 USDC가 소요됩니다(agentkv_delete, agentkv_balance, agentkv_wallet_address, agentkv_fund, agentkv_list_keys는 무료). 루프나 대량 작업을 시작하기 전에:
agentkv_balance를 호출하여 충분한 크레딧이 있는지 확인하세요.- 플러그인 설정에서 최대 작업당 지출(USD) 및/또는 최대 세션 지출(USD) 상한을 설정하세요(
/plugin실행). - 도구 호출이 402 Payment Required 오류를 반환하고 지출 예산이 남아 있지 않으면, 맹목적으로 재시도하지 말고 일시 중지하고 사용자에게 보고하세요.
서버는 크레딧이 소진되면 PAYMENT-REQUIRED 챌린지를 반환합니다. CLI는 지출 상한 내에서 x402 지불을 자동으로 처리합니다.
공유 플릿 상태 패턴
여러 에이전트가 단일 AGENTKV_PRIVATE_KEY를 공유하는 경우(동일한 지갑 = 동일한 네임스페이스), 잘 알려진 키를 통해 조정할 수 있습니다:
fleet:lock:<task-id> # 분산 잠금(짧은 TTL로 설정)
fleet:queue # 직렬화된 작업 목록
fleet:result:<task-id> # 완료된 하위 작업의 출력
잠금에 짧은 TTL을 사용하여 에이전트 충돌 시 오래된 보류를 방지하세요.
키 명명 규칙
- 구분자로
:사용:session:<id>:summary,secret:github-token,prefs:language.secret:*키는 비밀-안전 도구(agentkv_set_from_env/_from_file,agentkv_get_to_file/run_with_secret)로 저장/읽기 — 일반set/get은 절대 사용하지 마세요. 자격 증명이 모델 컨텍스트에 들어가지 않도록 합니다. - 사용자별 데이터는 안정적인 식별자로 접두사 지정:
user:<handle>:.... - 공유 플릿 상태를 쓰기 전에
agentkv_wallet_address를 사용하여 작업 중인 네임스페이스를 확인하세요.