agentx402-ai/agentkv

Habilidade AgentKV

AgentKV é um armazenamento chave-valor nativo para agentes. Você mantém uma conta AgentKV, de duas formas possíveis (detectadas automaticamente pelo cliente) — mesmos dados, mesmos créditos, mesma criptografia de conhecimento zero:

• Carteira como chave (padrão): uma carteira que pode assinar é a conta. Seu endereço é o namespace e sua chave deriva a chave AES. O AgentKV provisiona uma automaticamente no primeiro uso — sem contas, sem chaves de API, sem cadastro.
• Chave de conta: para uma carteira gerenciada que não pode assinar (ex.: awal), um token portador opaco ak_… é a identidade + namespace e uma chave de criptografia local criptografa — desacoplada da carteira pagante, permitindo que qualquer carteira que possa assinar funde a conta.

Os valores são criptografados no lado do cliente (AES-256-GCM) antes de chegar ao servidor, portanto o servidor tem conhecimento zero. O armazenamento custa USDC real na Base (mainnet) ou Base Sepolia (testnet), cobrado por operação via o protocolo x402.

Pré-requisito: @agentkv/cli deve estar publicado no npm e ser resolvível via npx @agentkv/cli. No momento, o pacote ainda não foi publicado — este plugin é o artefato que depende dessa etapa de publicação.

---

Quando usar o AgentKV

Use o AgentKV quando precisar de:

• Memória persistente entre sessões — fatos, preferências, resumos ou estado de tarefas que devem sobreviver ao fim da sessão atual.
• Armazenamento e uso de segredos — chaves de API, tokens ou credenciais. O servidor só vê texto cifrado (conhecimento zero). ⚠️ As operações comuns agentkv_set/agentkv_get roteiam o valor através do contexto do modelo deste agente; para segredos reais, use as ferramentas seguras (agentkv_set_from_env/_from_file para armazenar, agentkv_get_to_file/agentkv_run_with_secret para usar) para que o texto claro nunca entre em uma iteração do modelo. Veja Segredos abaixo.
• Estado compartilhado de frota — múltiplas instâncias de agente que compartilham uma única carteira podem coordenar através de um namespace comum (ex.: uma fila de trabalhos, um bloqueio, um contador compartilhado).
• Estado temporário com TTL — valores temporários (ex.: um nonce, um rascunho) com expiração automática, eliminando a necessidade de limpeza manual.

NÃO use o AgentKV para:

• Blobs binários grandes (o tamanho máximo do valor é 256 KB).
• Operações gratuitas em um contexto sensível a orçamento — cada set e get custa USDC; verifique o limite de gastos primeiro.
• Substituir um banco de dados adequado em uma aplicação voltada ao usuário (é projetado para cargas de trabalho de agentes, não para aplicativos web de alta taxa).

---

Ferramentas MCP Disponíveis

O servidor MCP agentkv expõe doze ferramentas — oito principais, mais quatro ferramentas seguras cujo texto claro nunca entra no contexto do modelo (veja Segredos abaixo):

Ferramenta	Descrição	Custo
agentkv_set	Escreve um valor criptografado sob uma chave. Aceita um TTL opcional (dias).	~$0,005 USDC
agentkv_get	Lê e descriptografa um valor por chave. O TTL deslizante redefine a expiração por padrão.	~$0,003 USDC
agentkv_delete	Exclui uma chave imediatamente.	Grátis
agentkv_deposit	Deposita créditos USDC no namespace da carteira para pré-financiar operações. Recusado no modo account-key (uma conta gerenciada não tem carteira — funde-a via <endpoint>/account/deposit).	Compra de USDC
agentkv_balance	Verifica o saldo atual de créditos USDC para o namespace da carteira.	Grátis
agentkv_wallet_address	Retorna o endereço da carteira (identificador do namespace). Informativo.	Grátis
agentkv_fund	Retorna uma URL de integração cartão→USDC que entrega USDC à carteira na Base. Apenas constrói a URL — nenhum pagamento é feito. Recusado no modo account-key (nenhuma carteira para comprar USDC).	Grátis
agentkv_list_keys	Lista as chaves armazenadas desta carteira — os NOMES reais das chaves, descriptografados localmente; o servidor vê apenas hashes opacos. Paginado.	Grátis
agentkv_set_from_env	Armazena um segredo lido de uma variável de ambiente local (passe o NOME). O valor nunca entra no contexto do modelo.	~$0,005 USDC
agentkv_set_from_file	Armazena um segredo lido de um arquivo local (passe o CAMINHO). O conteúdo nunca entra no contexto do modelo.	~$0,005 USDC
agentkv_get_to_file	Descriptografa um valor para um arquivo local; retorna { found, path, bytes } — nunca o valor.	~$0,003 USDC
agentkv_run_with_secret	Executa um comando com o segredo injetado no ambiente do processo filho apenas; retorna a saída do comando, nunca o segredo.	~$0,003 USDC

Preços e depósitos: o pagamento por uso é de ~$0,005 por agentkv_set e ~$0,003 por agentkv_get. Créditos pré-pagos custam aproximadamente 1/10 disso (≈ $0,0005 por set, ≈ $0,0003 por get). agentkv_deposit exige um mínimo de $1,00 e credita o namespace à taxa de crédito com desconto.

---

Segredos — mantenha o valor fora do contexto do modelo

agentkv_set e agentkv_get roteiam o valor através do contexto do modelo deste agente (é um argumento da ferramenta na escrita, um resultado na leitura). A criptografia no lado do cliente torna os valores de conhecimento zero para o servidor — ela não os oculta do agente. Portanto, set/get comuns são adequados para memória não secreta (planos, resumos, preferências), mas para credenciais reais use as ferramentas seguras para que o texto claro nunca entre em uma iteração do modelo:

• Armazenar: agentkv_set_from_env (passe o NOME de uma variável de ambiente) ou agentkv_set_from_file (passe o CAMINHO). O servidor lê o valor localmente, criptografa e armazena.
• Usar: agentkv_run_with_secret (executa um comando com o segredo apenas no ambiente do processo filho e retorna a saída do comando) ou agentkv_get_to_file (escreve o valor descriptografado em um arquivo local e retorna o caminho — exclua-o quando terminar).

Residual: o segredo se materializa brevemente em um arquivo local ou ambiente de processo filho — local e efêmero, nunca enviado a um provedor de modelo ou registrado no histórico da conversa. agentkv_run_with_secret (sem arquivo em disco) é o mais restrito.

---

Configuração Única

Instale o plugin pelo marketplace do Claude Code — os comandos exatos /plugin marketplace add e /plugin install estão no README.md do plugin (plugin/README.md). Após a instalação:

1. Credenciais (inseridas na instalação, não via variáveis de ambiente do shell)

Quando o plugin for instalado, o Claude Code solicita estas informações e as insere no servidor MCP para você (a chave privada é mascarada e armazenada no chaveiro do sistema operacional — nunca gravada em disco):

Config	Obrigatório	Descrição
Chave privada da carteira	Não	Opcional — deixe em branco e o AgentKV criará e gerenciará uma carteira local no primeiro uso (em seguida, funde e faça backup dela). Para usar a sua própria: uma chave privada EVM (hex), a carteira que paga e possui o namespace.
Endpoint AgentKV	Não	A API AgentKV hospedada; o padrão é https://api.agentx402.ai.
Rede	Não	eip155:8453 (Base mainnet, padrão) ou eip155:84532 (Base Sepolia testnet).
Chave de criptografia	Não	Substitui a chave AES derivada (avançado; o padrão é HKDF a partir da chave privada).
Gasto máximo por operação (USD)	Não	Recusa qualquer operação única que custe mais que este valor; vazio = sem limite por operação.
Gasto máximo da sessão (USD)	Não	Recusa operações quando o gasto acumulado da sessão excede este valor; vazio = sem limite.

Execute /plugin novamente para alterar estes valores depois. Verifique se o servidor foi carregado com /mcp (você deve ver o servidor agentkv e suas doze ferramentas).

Para financiar com cartão em vez de um saldo USDC existente, a ferramenta agentkv_fund retorna uma URL de integração Coinbase — configure-a definindo AGENTKV_ONRAMP_APP_ID (um ID de projeto público do CDP) no servidor e, opcionalmente, AGENTKV_ONRAMP_PROVIDER para trocar de provedor.

2. Funde o namespace

Leia o endereço da sua carteira com agentkv_wallet_address, envie USDC para ele na Base (ou chame agentkv_fund para uma URL de integração cartão→USDC que entrega USDC para aquele endereço), depois chame agentkv_deposit com um valor (mínimo $1) para creditar o namespace. Leituras e escritas são então pagas automaticamente a partir dos créditos.

Modo account-key (carteiras gerenciadas / awal)

Uma carteira gerenciada que não pode assinar usa o modo account-key em vez de uma carteira. Fora do plugin, a CLI cria e funde uma conta:

agentkv account new        # cria ak_… + uma chave de criptografia local (salva 0600) — FAÇA BACKUP, irrecuperável
# Funde-a de QUALQUER carteira que possa assinar (um depósito real de ≥$1 cria a conta no primeiro depósito):
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'

Em seguida, defina AGENTKV_ACCOUNT_KEY=ak_… e AGENTKV_ENCRYPTION_KEY=0x… (a chave AES local — obrigatória no modo account, pois não há carteira para derivar uma). A conta é o namespace; por padrão, leituras/escritas carregam apenas o token portador e debitam créditos pré-pagos — nenhuma assinatura por operação. De qualquer forma, tudo permanece com conhecimento zero para o servidor. Qualquer carteira que possa assinar pode recarregar a mesma conta.

Com AGENTKV_TOPOFF=awal também definido, créditos insuficientes se auto-curam — nenhuma ação necessária, a sessão CLI/MCP paga sua própria recarga via awal e continua. Sem isso, em caso de erro de créditos insuficientes, execute awal x402 pay <endpoint>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' e tente novamente. Alternativamente, defina AGENTKV_INLINE=awal para pagar por operação inline: cada requisição carrega uma assinatura de pagamento junto com o token portador e é liquidada on-chain imediatamente, portanto nenhum crédito pré-pago é necessário.

---

Consciência de Limite de Gastos

Cada chamada a agentkv_set, agentkv_get e agentkv_deposit custa USDC real (agentkv_delete, agentkv_balance, agentkv_wallet_address, agentkv_fund e agentkv_list_keys são gratuitas). Antes de iniciar um loop ou operação em lote:

1. Chame agentkv_balance para confirmar créditos suficientes.
2. Defina um teto de Gasto máximo por operação (USD) e/ou Gasto máximo da sessão (USD) na configuração do plugin (execute /plugin para editar).
3. Se uma chamada de ferramenta retornar um erro 402 Payment Required e não houver orçamento de gasto restante, pause e informe ao usuário em vez de tentar novamente cegamente.

O servidor retorna um desafio PAYMENT-REQUIRED quando os créditos são esgotados; a CLI lida com o pagamento x402 automaticamente dentro do limite de gastos.

---

Padrão de Estado Compartilhado de Frota

Quando múltiplos agentes compartilham uma única AGENTKV_PRIVATE_KEY (mesma carteira = mesmo namespace), eles podem coordenar através de chaves conhecidas:

fleet:lock:<task-id>     # bloqueio distribuído (definido com TTL curto)
fleet:queue              # lista de trabalhos serializada
fleet:result:<task-id>   # saída de uma subtarefa concluída

Use TTLs curtos em bloqueios para evitar retenções obsoletas se um agente falhar.

---

Convenções de Nomenclatura de Chaves

• Use : como separador: session:<id>:summary, secret:github-token, prefs:language. Armazene/leia chaves secret:* com as ferramentas seguras (agentkv_set_from_env/_from_file, agentkv_get_to_file/run_with_secret) — nunca com set/get comuns — para que a credencial nunca entre no contexto do modelo.
• Prefixe dados específicos do usuário com um identificador estável: user:<handle>:....
• Use agentkv_wallet_address para confirmar em qual namespace você está operando antes de escrever estado compartilhado de frota.