AgentOS

AgentOS is an operating system for onchain AI agents. Users connect a Sepolia wallet and deploy a real AI agent that gets a human-readable ENS name like trade.agentos.eth, a user-owned smart wallet, machine-readable capability records, and a full execution pipeline backed by Uniswap and KeeperHub.

The platform features:

• ENS subname deployment under agentos.eth — every agent gets a real persistent identity
• User-owned AgentSmartWallet deployed through AgentWalletFactory — the server never holds user keys
• ENS text records as machine-readable capability manifests — specialty, fee, preferred token, endpoint, reputation
• ERC-8004 onchain identity, reputation, and validation registries
• OpenAI tool-calling runtime with ENS discovery, Uniswap quote, and KeeperHub history tools
• Uniswap Trading API integration — /check_approval, /quote, /swap with generatePermitAsTransaction
• KeeperHub Direct Execution for reliable onchain settlement with retry logic and audit trails
• Agent-to-agent discovery: any app resolves *.agentos.eth and reads capability records without a central database
• Execution proof written back to ENS — latest swap transaction hash and KeeperHub run ID stored as text records
• Frontend on Vercel, backend on Render, and six Solidity contracts deployed on Sepolia

Users describe what they want in plain English, like "swap 1 USDC to WETH". The agent quotes via Uniswap, explains the route, and on confirmation routes the required transactions through KeeperHub Direct Execution from the user-owned agent smart wallet.

How It's Made

AgentOS uses a TypeScript monorepo with three packages: contracts (Hardhat + Solidity), backend (Express + TypeScript on Render), and frontend (Next.js 15 + RainbowKit on Vercel).

Frontend — Next.js 15 + RainbowKit

• RainbowKit + wagmi for wallet connection and transaction signing
• viem getLogs with the AgentSubnameRegistered event filter to scan recent Sepolia blocks and load user-owned agents without a backend call
• viem decodeEventLog on AgentSmartWallet.Executed to label wallet activity in human-readable form, including USDC approval, Permit2 approval, and Universal Router swap activity
• Secure Next.js API proxy at /api/backend/* forwards requests to Render with a server-side secret header so execution routes are not exposed directly to the browser
• ENS write-back flow: after a confirmed swap, the frontend calls setText on the public resolver to store agentos.lastExecutionTx, agentos.lastKeeperHubRun, and updated reputation back into the agent ENS name

Backend — Express + TypeScript on Render

• OpenAI tool-calling loop with tools for ENS discovery, Uniswap quote/swap preparation, and KeeperHub execution
• ENS adapter using viem getEnsAddress and getEnsText to resolve agent identities and read capability records
• Uniswap adapter calling /check_approval, /quote with generatePermitAsTransaction: true, and /swap to produce Universal Router calldata
• KeeperHub adapter that decodes raw transaction data with known ABIs (erc20, permit2, universalRouter, agentSmartWallet) and posts structured contract-call execution requests with decoded functionName, functionArgs, and abi
• Status polling loop against /execute/{id}/status until the KeeperHub run completes or fails

Blockchain Integration

• Solidity contracts deployed on Sepolia: AgentWalletFactory, AgentSmartWallet, AgentSubnameRegistrar, AgentIdentityRegistry8004, AgentReputationRegistry8004, AgentValidationRegistry8004, and AgentRegistry
• AgentSubnameRegistrar calls setSubnodeRecord on the ENS registry, setAddr on the public resolver, and writes capability keys from a TextRecord[] array in one transaction
• AgentSmartWallet has an owner (the user wallet), a scoped executor (KeeperHub wallet), and an explicit allowlist of permitted call targets such as USDC, Permit2, and the Uniswap Universal Router

AI / Agent Layer

• OpenAI gpt-4.1-mini for agent reasoning and tool orchestration
• Quote confirmation flow: the agent caches the last Uniswap quote per agent and wallet, detects confirmation messages like "yes", "proceed", or "swap", and gates execution behind explicit user confirmation
• Agent runtime refuses to claim execution success unless a tool result contains a confirmed transaction hash

Hacky / Notable Solutions

• Wrapped Uniswap transactions inside AgentSmartWallet.execute(target, value, data) before sending to KeeperHub. This lets the KeeperHub wallet call the agent smart wallet, while the smart wallet only forwards calls to allowlisted targets. The server executor never needs the user's private key or unlimited contract access.
• Used generatePermitAsTransaction: true in Uniswap /quote to avoid browser EIP-712 Permit2 signatures, making the flow compatible with execution services and smart-wallet wrappers.
• Built an ABI-decode-then-restructure pattern in keeperhub.ts: raw transaction calldata is decoded with known ABIs and converted into KeeperHub's functionName, functionArgs, and abi JSON format.
• Frontend agent scanner uses chunked getLogs windows to stay within RPC limits while still loading user-created agents across sessions.

The most challenging part was getting the Uniswap smart-wallet execution path to work end-to-end through KeeperHub. The key insight was that the swapper address in every Uniswap API call must be the agent smart wallet, not the connected EOA. That means USDC approval to Permit2 must also come from the smart wallet before the swap can execute. Once the approval sequence was ordered correctly, KeeperHub ran the full path, with successful Sepolia approval and swap transactions.