Habilidad AgentKV
AgentKV es un almacén de clave-valor nativo para agentes. Tienes una cuenta AgentKV, administrada de una de dos maneras (detección automática por el cliente): los mismos datos, los mismos créditos, el mismo cifrado de conocimiento cero:
- Cartera como clave (por defecto): una cartera firmable es la cuenta. Su dirección es el espacio de nombres y su clave deriva la clave AES. AgentKV autoaprovisiona una al primer uso: sin cuentas, sin claves API, sin registro.
- Clave de cuenta: para una cartera gestionada que no puede firmar (p. ej. awal), un token portador opaco
ak_…es la identidad + espacio de nombres y una clave de cifrado local cifra — desacoplada de la cartera pagadora, por lo que cualquier cartera firmante puede financiar la cuenta.
Los valores se cifran del lado del cliente (AES-256-GCM) antes de llegar al servidor, por lo que el servidor tiene conocimiento cero. El almacenamiento cuesta USDC real en Base (mainnet) o Base Sepolia (testnet), cobrado por operación a través del protocolo x402.
Requisito previo:
@agentkv/clidebe estar publicado en npm y ser resoluble mediantenpx @agentkv/cli. Al momento de escribir esto, el paquete aún no está publicado — este plugin es el artefacto pendiente de ese paso de publicación.
Cuándo usar AgentKV
Usa AgentKV cuando necesites:
- Memoria persistente entre sesiones — hechos, preferencias, resúmenes o estado de tareas que deben sobrevivir al finalizar la sesión actual.
- Almacenamiento y uso de secretos — claves API, tokens o credenciales. El servidor solo ve texto cifrado (conocimiento cero). ⚠️ Los comandos simples
agentkv_set/agentkv_getenrutan el valor a través del contexto del modelo de este agente; para secretos reales usa las herramientas seguras (agentkv_set_from_env/_from_filepara almacenar,agentkv_get_to_file/agentkv_run_with_secretpara usar) para que el texto plano nunca entre en un turno del modelo. Consulta Secretos más abajo. - Estado compartido de flota — múltiples instancias de agente que comparten una sola cartera pueden coordinarse a través de un espacio de nombres común (p. ej., una cola de trabajos, un bloqueo, un contador compartido).
- Estado temporal con TTL — valores temporales (p. ej., un nonce, un borrador) con vencimiento automático para no tener que limpiar manualmente.
NO uses AgentKV para:
- Grandes blobs binarios (el tamaño máximo de valor es 256 KB).
- Operaciones gratuitas y sin costo en un contexto con presupuesto sensible — cada
setygetcuesta USDC; verifica primero el límite de gasto. - Reemplazar una base de datos adecuada en una aplicación orientada al usuario (está diseñado para cargas de trabajo de agentes, no para aplicaciones web de alto rendimiento).
Herramientas MCP Disponibles
El servidor MCP agentkv expone doce herramientas — ocho principales, más cuatro herramientas seguras para secretos cuyo texto plano nunca entra en el contexto del modelo (consulta Secretos más abajo):
| Herramienta | Descripción | Costo |
|---|---|---|
agentkv_set | Escribe un valor cifrado bajo una clave. Acepta un TTL opcional (días). | ~$0.005 USDC |
agentkv_get | Lee y descifra un valor por clave. El TTL deslizante restablece el vencimiento por defecto. | ~$0.003 USDC |
agentkv_delete | Elimina una clave de inmediato. | Gratis |
agentkv_deposit | Deposita créditos USDC en el espacio de nombres de la cartera para prefondear operaciones. Rechazado en modo clave de cuenta (una cuenta gestionada no tiene cartera — fíнансíala mediante <endpoint>/account/deposit). | Compra de USDC |
agentkv_balance | Verifica el saldo actual de créditos USDC para el espacio de nombres de la cartera. | Gratis |
agentkv_wallet_address | Devuelve la dirección de la cartera (identificador del espacio de nombres). Informativo. | Gratis |
agentkv_fund | Devuelve una URL de onramp de tarjeta→USDC que entrega USDC a la cartera en Base. Solo construye una URL — no se realiza ningún pago. Rechazado en modo clave de cuenta (no hay cartera para comprar USDC). | Gratis |
agentkv_list_keys | Lista las claves almacenadas de esta cartera — los NOMBRES de clave reales, descifrados localmente; el servidor solo ve resúmenes opacos. Paginado. | Gratis |
agentkv_set_from_env | Almacena un secreto leído de una variable de entorno local (pasa el NOMBRE). El valor nunca entra en el contexto del modelo. | ~$0.005 USDC |
agentkv_set_from_file | Almacena un secreto leído de un archivo local (pasa la RUTA). El contenido nunca entra en el contexto del modelo. | ~$0.005 USDC |
agentkv_get_to_file | Descifra un valor en un archivo local; devuelve { encontrado, ruta, bytes } — nunca el valor. | ~$0.003 USDC |
agentkv_run_with_secret | Ejecuta un comando con el secreto inyectado en el entorno del proceso hijo únicamente; devuelve la salida del comando, nunca el secreto. | ~$0.003 USDC |
Precios y depósitos: el pago por uso es de ~$0.005 por
agentkv_sety ~$0.003 poragentkv_get. Los créditos prepagados cuestan aproximadamente 1/10 de eso (≈ $0.0005 por set, ≈ $0.0003 por get).agentkv_depositrequiere un mínimo de $1.00 y financia el espacio de nombres a la tasa de crédito con descuento.
Secretos — mantén el valor fuera del contexto del modelo
agentkv_set y agentkv_get enrutan el valor a través del contexto del modelo de este agente (es un argumento de herramienta al escribir, un resultado de herramienta al leer). El cifrado del lado del cliente hace que los valores tengan conocimiento cero para el servidor — no los oculta del agente. Por lo tanto, los set/get simples son adecuados para memoria no secreta (planes, resúmenes, preferencias), pero para credenciales reales usa las herramientas seguras para que el texto plano nunca entre en un turno del modelo:
- Almacenar:
agentkv_set_from_env(pasa un NOMBRE de variable de entorno) oagentkv_set_from_file(pasa una RUTA). El servidor lee el valor localmente, lo cifra y lo almacena. - Usar:
agentkv_run_with_secret(ejecuta un comando con el secreto solo en el entorno del proceso hijo y devuelve la salida del comando) oagentkv_get_to_file(escribe el valor descifrado en un archivo local y devuelve la ruta — elimínalo cuando termines).
Residual: el secreto se materializa brevemente en un archivo local o en el entorno de un proceso hijo — local y efímero, nunca enviado a un proveedor de modelos ni escrito en el historial de conversación. agentkv_run_with_secret (sin archivo en disco) es el más estricto.
Configuración Única
Instala el plugin desde el mercado de Claude Code — los comandos exactos /plugin marketplace add y /plugin install están en el README.md del plugin (plugin/README.md). Después de la instalación:
1. Credenciales (ingresadas en la instalación, no mediante entorno de shell)
Cuando se instala el plugin, Claude Code solicita estos valores y los enhebra en el servidor MCP por ti (la clave privada se enmascara y se almacena en el llavero de tu SO — nunca se escribe en disco):
| Configuración | Requerida | Descripción |
|---|---|---|
| Clave privada de cartera | No | Opcional — déjala en blanco y AgentKV acuña + gestiona una cartera local en el primer uso (luego finánciala y respáldala). Para usar la tuya: una clave privada EVM (hex), la cartera que paga y posee el espacio de nombres. |
| Endpoint de AgentKV | No | La API de AgentKV alojada; por defecto https://api.agentx402.ai. |
| Red | No | eip155:8453 (Base mainnet, predeterminada) o eip155:84532 (Base Sepolia testnet). |
| Clave de cifrado | No | Sobrescribe la clave AES derivada (avanzado; por defecto HKDF a partir de la clave privada). |
| Gasto máximo por operación (USD) | No | Rechaza cualquier operación única que costaría más de esto; vacío = sin límite por operación. |
| Gasto máximo de sesión (USD) | No | Rechaza operaciones una vez que el gasto acumulado de la sesión excede esto; vacío = sin límite. |
Ejecuta /plugin nuevamente para cambiar estos valores más tarde. Verifica que el servidor se haya cargado con /mcp (deberías ver el servidor agentkv y sus doce herramientas).
Para financiar con tarjeta en lugar de un saldo USDC existente, la herramienta agentkv_fund devuelve una URL de onramp de Coinbase — configúrala estableciendo AGENTKV_ONRAMP_APP_ID (un ID de proyecto CDP público) en el servidor, y opcionalmente AGENTKV_ONRAMP_PROVIDER para cambiar de proveedor.
2. Financia el espacio de nombres
Lee la dirección de tu cartera con agentkv_wallet_address, envía USDC a ella en Base (o llama a agentkv_fund para obtener una URL de onramp de tarjeta→USDC que entrega USDC a esa dirección), luego llama a agentkv_deposit con una cantidad (mínimo $1) para acreditar el espacio de nombres. Las lecturas y escrituras se pagan automáticamente de los créditos.
Modo clave de cuenta (carteras gestionadas / awal)
Una cartera gestionada que no puede firmar usa el modo clave de cuenta en lugar de una cartera. Fuera del plugin, la CLI acuña y financia una cuenta:
agentkv account new # acuña ak_… + una clave de cifrado local (guardada 0600) — HAZ COPIA DE SEGURIDAD, irrecuperable
# Fínánciala desde CUALQUIER cartera firmante (un depósito real de ≥$1 crea la cuenta en el primer depósito):
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'
Luego establece AGENTKV_ACCOUNT_KEY=ak_… y AGENTKV_ENCRYPTION_KEY=0x… (la clave AES local — requerida en modo cuenta, no hay cartera de la cual derivar una). La cuenta es el espacio de nombres; por defecto las lecturas/escrituras llevan solo el portador y debitan créditos prepagados — sin firma por operación. De cualquier manera, se mantiene con conocimiento cero para el servidor. Cualquier cartera firmante puede recargar la misma cuenta.
Con AGENTKV_TOPOFF=awal también establecido, los créditos insuficientes se autocuran — no se requiere acción, la CLI/sesión MCP paga su propia recarga a través de awal y continúa. Sin ello, en un error de créditos insuficientes ejecuta awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' y reintenta. Alternativamente, establece AGENTKV_INLINE=awal para pagar por operación en línea: cada solicitud lleva una firma de pago junto con el portador y se liquida en cadena de inmediato, por lo que no se requieren créditos prepagados.
Conciencia del Límite de Gasto
Cada llamada a agentkv_set, agentkv_get, y agentkv_deposit cuesta USDC real (agentkv_delete, agentkv_balance, agentkv_wallet_address, agentkv_fund y agentkv_list_keys son gratuitas). Antes de iniciar un bucle u operación masiva:
- Llama a
agentkv_balancepara confirmar créditos suficientes. - Establece un límite de Gasto máximo por operación (USD) y/o Gasto máximo de sesión (USD) en la configuración del plugin (ejecuta
/pluginpara editar). - Si una llamada de herramienta devuelve un error 402 Payment Required y no queda presupuesto de gasto, pausa e informa al usuario en lugar de reintentar ciegamente.
El servidor devuelve un desafío PAYMENT-REQUIRED cuando los créditos se agotan; la CLI maneja el pago x402 automáticamente dentro del límite de gasto.
Patrón de Estado Compartido de Flota
Cuando múltiples agentes comparten una sola AGENTKV_PRIVATE_KEY (misma cartera = mismo espacio de nombres), pueden coordinarse a través de claves bien conocidas:
fleet:lock:<id-tarea> # bloqueo distribuido (establecer con TTL corto)
fleet:queue # lista de trabajos serializada
fleet:result:<id-tarea> # salida de una subtarea completada
Usa TTL cortos en los bloqueos para evitar retenciones obsoletas si un agente falla.
Convenciones de Nomenclatura de Claves
- Usa
:como separador:session:<id>:resumen,secret:github-token,prefs:idioma. Almacena/lee las clavessecret:*con las herramientas seguras para secretos (agentkv_set_from_env/_from_file,agentkv_get_to_file/run_with_secret) — nunca conset/getsimples — para que la credencial nunca entre en el contexto del modelo. - Prefija los datos específicos del usuario con un identificador estable:
user:<handle>:.... - Usa
agentkv_wallet_addresspara confirmar en qué espacio de nombres estás operando antes de escribir estado compartido de flota.