From ec292d410c5fe98fe513f488bb69245710b055f0 Mon Sep 17 00:00:00 2001 From: Jadonamite Date: Mon, 19 Jan 2026 22:17:21 +0100 Subject: [PATCH] Add Natural Language CLI tutorial with AgentKit Added a comprehensive tutorial on building a Natural Language CLI using AgentKit, LangChain, and CDP MPC Wallet, covering architecture, prerequisites, implementation steps, and common pitfalls. --- .../cookbook/natural-language-cli-agentkit.md | 273 ++++++++++++++++++ 1 file changed, 273 insertions(+) create mode 100644 docs/cookbook/natural-language-cli-agentkit.md diff --git a/docs/cookbook/natural-language-cli-agentkit.md b/docs/cookbook/natural-language-cli-agentkit.md new file mode 100644 index 00000000..d1318b3a --- /dev/null +++ b/docs/cookbook/natural-language-cli-agentkit.md @@ -0,0 +1,273 @@ +# Build a Natural Language Onchain CLI with AgentKit + +**Author:** jadonamite +**Topic:** AI Agents & Wallet Setup +**Level:** Beginner +**Prerequisites:** Node.js v18+, CDP API Key, OpenAI API Key + +Command-line tools are powerful, but they usually require strict syntax. What if you could just tell your terminal, *"Send 0.005 ETH to my other wallet"* or *"Swap all my USDC for ETH"*? + +In this tutorial, we will build a **Natural Language CLI** using **Coinbase AgentKit**, **LangChain**, and the **CDP MPC Wallet**. This agent will interpret your intent, manage the complex wallet interactions on Base Sepolia, and execute transactions automatically. + +--- + +## 1. Architecture + +* **User Interface:** A simple Node.js Read-Eval-Print Loop (REPL) for chat. +* **Reasoning Engine:** LangChain (ReAct Agent) + OpenAI (GPT-4o-mini). +* **Wallet Infrastructure:** Coinbase Developer Platform (CDP) MPC Wallet. +* *Why MPC?* It allows you to create a secure, programmatic wallet without handling raw private keys directly in your code. + + +* **Action Providers:** AgentKit tools for Swaps, Transfers, and Balance checks. + +--- + +## 2. Prerequisites + +1. **Coinbase Developer Platform (CDP) Account:** +* Navigate to [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com/). +* Create an API Key with `AgentKit` permissions. +* **Crucial:** Download your `privateKey.json` or copy the `name` and `privateKey` immediately. + + +2. **OpenAI API Key:** +* Navigate to [platform.openai.com](https://platform.openai.com/) to get your key. + + + +--- + +## 3. Implementation + +### Step 1: Initialize the Project + +We will use the official AgentKit boilerplate to ensure all dependencies are correct. + +```bash +# Create the project +npm create onchain-agent@latest agent-cli + +# Select the following options: +# ? Select your AI Framework: LangChain +# ? Select your Project Template: Empty +# ? Select your Blockchain Network: Base Sepolia +# ? Select your Wallet Provider: CDP Server Wallet + +``` + +Navigate into the folder: + +```bash +cd agent-cli + +``` + +### Step 2: Configure Environment + +Rename `.env.example` to `.env` and input your credentials. + +```env +# .env + +# CDP Keys (From Coinbase Developer Portal) +CDP_API_KEY_NAME=organizations/.../apiKeys/... +CDP_API_KEY_PRIVATE_KEY=-----BEGIN EC PRIVATE KEY-----... + +# AI Provider +OPENAI_API_KEY=sk-... + +# Network Configuration +NETWORK_ID=base-sepolia + +``` + +### Step 3: The CLI Agent (`src/index.ts`) + +We will build an interactive CLI that persists your wallet data. This ensures your agent keeps its address and balance between sessions. + +Create or overwrite `src/index.ts` with the following: + +```typescript +import { + AgentKit, + CdpWalletProvider, + wethActionProvider, + walletActionProvider, + erc20ActionProvider, + cdpApiActionProvider, + cdpWalletActionProvider, +} from "@coinbase/agentkit"; +import { getLangChainTools } from "@coinbase/agentkit-langchain"; +import { HumanMessage } from "@langchain/core/messages"; +import { MemorySaver } from "@langchain/langgraph"; +import { createReactAgent } from "@langchain/langgraph/prebuilt"; +import { ChatOpenAI } from "@langchain/openai"; +import * as dotenv from "dotenv"; +import * as fs from "fs"; +import * as readline from "readline"; + +dotenv.config(); + +// File to persist wallet data (keeps your address the same) +const WALLET_DATA_FILE = "wallet_data.txt"; + +async function main() { + console.log("Initializing AgentKit CLI..."); + + // 1. Setup LLM + const llm = new ChatOpenAI({ + model: "gpt-4o-mini", + }); + + // 2. Configure CDP Wallet Provider + // This logic checks if a wallet already exists locally. + // If yes, it loads it. If no, it creates a new MPC wallet. + let walletDataStr: string | undefined = undefined; + if (fs.existsSync(WALLET_DATA_FILE)) { + try { + walletDataStr = fs.readFileSync(WALLET_DATA_FILE, "utf8"); + } catch (error) { + console.error("Error reading wallet data:", error); + } + } + + const walletProvider = await CdpWalletProvider.configureWithWallet({ + apiKeyName: process.env.CDP_API_KEY_NAME, + apiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY?.replace(/\\n/g, "\n"), + cdpWalletData: walletDataStr || undefined, + networkId: process.env.NETWORK_ID || "base-sepolia", + }); + + // 3. Setup AgentKit with Action Providers + const agentKit = await AgentKit.from({ + walletProvider, + actionProviders: [ + wethActionProvider(), + walletActionProvider(), + erc20ActionProvider(), + cdpApiActionProvider({ + apiKeyName: process.env.CDP_API_KEY_NAME, + apiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY?.replace(/\\n/g, "\n"), + }), + cdpWalletActionProvider({ + apiKeyName: process.env.CDP_API_KEY_NAME, + apiKeyPrivateKey: process.env.CDP_API_KEY_PRIVATE_KEY?.replace(/\\n/g, "\n"), + }), + ], + }); + + const tools = await getLangChainTools(agentKit); + const memory = new MemorySaver(); + + // 4. Save Wallet Data (Persist the MPC Wallet) + const exportedWallet = await walletProvider.exportWallet(); + fs.writeFileSync(WALLET_DATA_FILE, JSON.stringify(exportedWallet)); + + const agent = createReactAgent({ + llm, + tools, + checkpointSaver: memory, + messageModifier: ` + You are a helpful agent that can interact onchain using the Coinbase Developer Platform AgentKit. + You are empowered to interact onchain using your tools. + If you ever need funds, you can request them from the faucet if you are on network ID 'base-sepolia'. + Before executing your first action, check your wallet details to see what network you're on. + If there is a 5XX (internal) HTTP error code, ask the user to try again later. + If someone asks you to do something you can't do with your currently available tools, you must say so. + `, + }); + + console.log("Agent Ready!"); + console.log(`Wallet Address: ${await walletProvider.getAddress()}`); + console.log("-------------------------------------------------"); + console.log("Enter a command (e.g., 'Swap 1 USDC for ETH') or type 'exit' to quit."); + + // 5. Interactive Chat Loop + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout, + }); + + const chatLoop = async () => { + rl.question("\n> ", async (input) => { + if (input.toLowerCase() === "exit") { + rl.close(); + return; + } + + const stream = await agent.stream( + { messages: [new HumanMessage(input)] }, + { configurable: { thread_id: "cli-agent-session" } } + ); + + for await (const chunk of stream) { + if ("agent" in chunk) { + console.log(chunk.agent.messages[0].content); + } else if ("tools" in chunk) { + console.log(chunk.tools.messages[0].content); + } + } + + chatLoop(); + }); + }; + + chatLoop(); +} + +main(); + +``` + +### Step 4: Run the CLI + +1. **Start the agent:** +```bash +npx tsx src/index.ts + +``` + + +2. **First Run (Funding):** +On the first run, your wallet will be empty. Ask the agent to fund itself. +```text +> Get my wallet details and request funds from the faucet. + +``` + + +*The agent will output its address and the transaction link for the faucet drip.* +3. **Execute a Command:** +Once funded, try a swap. +```text +> Swap 0.0001 ETH for USDC. + +``` + + +*The agent will check prices, approve the transaction, and return the Basescan link.* + +--- + +## 4. Common Pitfalls + +1. **Wallet Persistence:** +* **Gotcha:** If you delete `wallet_data.txt`, the agent will generate a brand new wallet address (with 0 funds) next time you run it. Always back up this file if you are using it for anything important. + + +2. **Model Selection:** +* **Gotcha:** Using smaller models (like `gpt-3.5-turbo`) may result in the agent failing to pick the correct tool parameters for complex swaps. `gpt-4o` or `gpt-4o-mini` is recommended for reliability. + + +3. **Permissions:** +* **Gotcha:** If you see "Unauthorized" errors, ensure your CDP API Key has the `AgentKit` permission set in the CDP Portal. + + + +--- + + +- [x] Tested "Swap ETH for USDC" command. + +```