O Manual Ausente para Meu Agente Solana Alimentado por Ollama

Um colega de equipe poderia reconstruir esta pilha de agentes usando apenas o que eu escrevi? Honestamente, há uma semana, não. Em cinco dias, eu montei algo genuinamente sofisticado: um loop de agente local rodando no Ollama em vez de uma API em nuvem, uma ferramenta de transferência com um limite de gastos codificado, um servidor MCP que transforma essas ferramentas em algo que qualquer cliente de IA pode descobrir, um motor de políticas que separa "o modelo decidiu" de "o código permitido" e uma execução autônoma onde tudo isso buscou um objetivo por conta própria em várias rodadas. Cada decisão de design que faz isso funcionar viveu em um só lugar: minha cabeça. Este post é essa decisão sendo escrita.

Fazer inventário

Desenhar o fluxo

seu objetivo, em inglês simples
        |
        v
+----------------------+
|  Ollama (LLM local)  |  decide qual ferramenta chamar a seguir
+----------------------+
        |
        v  chamada de ferramenta, ex. transfer_sol / send_sol
+----------------------+
|  servidor MCP ou     |  expõe ferramentas a qualquer cliente
|  loop de ferramenta do agente |  (Dia 92-93 chamava ferramentas diretamente;
+----------------------+   Dia 94 moveu isso para trás do MCP)
        |
        v
+----------------------+
|  policy.mjs          |  negar por padrão; cada gasto verificado
+----------------------+
        |  permitido
        v
+----------------------+
|  Solana devnet       |  transação enviada e confirmada
+----------------------+ 

A chave privada nunca entra no Ollama em nenhum ponto desta cadeia. O modelo só vê nomes de ferramentas, descrições e resultados; o par de chaves da carteira permanece dentro do processo Node.js o tempo todo.

Referência da ferramenta

Ferramenta: get_balance / get_wallet_balance

• Entradas: nenhuma (lê a carteira configurada do agente)
• Retornos: { balance_sol: number }, ou uma string formatada "<endereço> tem X SOL" via MCP
• Efeitos colaterais: nenhum
• Protegido por política: não aplicável, somente leitura

Ferramenta: send_sol (versão de chamada direta da ferramenta, Dia 93)

• Entradas: destinatário (string), quantidade_sol (número)
• Retornos: { assinatura, explorador } em caso de sucesso, ou { erro }
• Efeitos colaterais: gasta SOL da carteira do agente
• Protegido por política: sim, uma verificação codificada MAX_SOL_PER_SEND = 0.1 dentro da ferramenta neste estágio (a verificação não foi movida para um módulo separado até o Dia 95)

Ferramenta: initialize_vault (versão MCP, Dia 94)

• Entradas: amountSol (número)
• Retornos: um bloco de texto confirmando que o cofre foi criado com uma assinatura de transação, um aviso de "já existe" ou uma rejeição
• Efeitos colaterais: deposita SOL em uma conta de cofre derivada de programa via uma instrução deposit do Anchor
• Protegido por política: sim, uma verificação MAX_SOL = 0.1 dentro do manipulador da ferramenta MCP, mesma forma que o teto do Dia 93, apenas movido para trás da fronteira do protocolo

Ferramenta: transfer_sol (versão do fluxo de trabalho autônomo, Dia 96)

• Entradas: para (endereço), lamports (inteiro)
• Retornos: { status: "confirmado", assinatura, quantidadeSol } ou { status: "negado", razão }
• Efeitos colaterais: gasta SOL da carteira operacional
• Protegido por política: sim, roteado através do policy.mjs's checkTransferPolicy antes que qualquer coisa seja assinada

Documentar a camada de políticas

Esta é a parte da pilha que realmente a torna segura, então é escrita regra por regra. policy.mjs executa uma sequência fixa de verificações antes que qualquer transferência seja permitida:

1. O destinatário está na lista de permitidos? O endereço é analisado como um PublicKey primeiro; um endereço malformado é rejeitado antes que qualquer outra coisa seja executada. Em seguida, é verificado contra um Set codificado de destinatários permitidos. Qualquer coisa que não esteja na lista é negada, ponto final, independentemente do valor.
2. O valor é um número inteiro positivo de lamports? Valores zero, negativos ou não inteiros são rejeitados.
3. A transferência está dentro do teto por transação? No policy.mjs original, esse teto era 0.1 SOL. Quando a execução autônoma aconteceu no Dia 96, o teto operacional foi apertado para 0.05 SOL, e cada log abaixo reflete esse número mais apertado, não o original 0.1.
4. O total da sessão em execução ainda está dentro do teto da sessão (0.25 SOL na política original)? Uma transferência que é individualmente pequena o suficiente ainda pode ser negada se ultrapassar o limite cumulativo de gastos da sessão.
5. Se nenhuma das acima rejeitar, aprovar e registrar o gasto.

O padrão quando nenhuma regra aprova explicitamente um pedido é negar. Não há um caminho através desse código onde uma transferência é bem-sucedida porque uma verificação foi silenciosamente ignorada.

A invariância central, declarada de forma simples: o prompt pode mudar, o modelo pode mudar, a sequência exata de chamadas de ferramentas pode mudar, mas nenhuma transação move fundos sem passar primeiro pelo checkTransferPolicy. Uma negação dessa camada parece idêntica ao modelo, quer o modelo tenha pedido para enviar demais, ou se um texto injetado tentou convencê-lo a enviar demais. A política não pergunta por que o pedido foi feito; ela apenas verifica se o pedido é permitido.

Anotar uma execução real

Esta é uma execução real do fluxo de trabalho autônomo do Dia 96 (agent-workflow-ollama.mjs), lendo duas carteiras e movendo SOL entre elas por conta própria:

turn 1
tool_call { index: 0