AgentOS

Demo

About

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

## 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.