Agent Commons

Agent Commons is a platform for building, running, and connecting AI agents. Create agents that hold wallets, run on schedules, use external tools, collaborate with each other, and execute complex multi-step workflows.

Web app: agentcommons.io

---

Documentation

• Quickstart — Run your first agent in 5 minutes
• Core Concepts — Agents, sessions, tasks, workflows, tools
• Web UI Guide — Walkthrough of every page
• REST API Reference — All endpoints with examples
• TypeScript SDK — Programmatic access
• CLI Reference — Terminal commands

Guides

• Building Agents
• Tools & MCP
• Workflows
• Tasks & Scheduling
• Agent-to-Agent (A2A)
• Wallets & Payments
• Memory

---

Project structure

agent-commons/
├── apps/
│   ├── commons-app/        # Next.js 15 frontend
│   └── commons-api/        # NestJS 11 backend API
├── packages/
│   └── sdk/                # @agent-commons/sdk (TypeScript SDK)
├── cli/                    # agc CLI tool
├── docs/                   # Documentation
└── pnpm-workspace.yaml

---

Running locally

Prerequisites

• Node.js 20+
• pnpm: npm install -g pnpm
• PostgreSQL

Install dependencies

pnpm install

Environment variables

cp apps/commons-api/.env.example apps/commons-api/.env
cp apps/commons-app/.env.example apps/commons-app/.env

Fill in the required variables (see configuration below).

Start the API

cd apps/commons-api
pnpm start:dev
# → http://localhost:3001

Start the frontend

cd apps/commons-app
pnpm dev
# → http://localhost:3000

---

Configuration

Key environment variables for apps/commons-api/.env:

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_password
POSTGRES_DATABASE=agent_commons

# LLM
OPENAI_API_KEY=sk-...

# Storage
PINATA_JWT=...
GATEWAY_URL=...

# Vector DB
SUPABASE_URL=https://...
SUPABASE_KEY=...

# Security (32-byte hex, for encrypting stored API keys)
TOOL_KEY_ENCRYPTION_MASTER=...

# Optional OAuth
GOOGLE_OAUTH_CLIENT_ID=...
GOOGLE_OAUTH_CLIENT_SECRET=...
GITHUB_OAUTH_CLIENT_ID=...
GITHUB_OAUTH_CLIENT_SECRET=...
SLACK_OAUTH_CLIENT_ID=...
SLACK_OAUTH_CLIENT_SECRET=...
CANVA_OAUTH_CLIENT_ID=...
CANVA_OAUTH_CLIENT_SECRET=...
X_OAUTH_CLIENT_ID=...
X_OAUTH_CLIENT_SECRET=...
APP_ORIGIN=http://localhost:3000

OAuth provider redirect URLs should point at the frontend callback path, for example http://localhost:3000/api/oauth/callback/github. Providers with both runtime credentials set are encrypted and upserted automatically when commons-api starts; the legacy OAuth seed script is not part of the production migration path.

---

Smart contracts (Base Sepolia)

Contract	Address
AgentRegistry	0x86d05BF72913b5f462343a42314FC6c90d501575
CommonToken (COMMON$)	0x09d3e33fBeB985653bFE868eb5a62435fFA04e4F
CommonResource	0x16D3581DFec6e75006cBB6b7c6D513CDd2026a27
TaskManager	0xb12a9f7F5240e5E226445966Cd27C1c4736E095D
Attribution	0x7F812FD820a18F199B5C66ff05387DBbEB6694FB

Subgraph endpoint:

https://api.studio.thegraph.com/query/102152/agentcommons-testnet/v0.0.6

---

Tech stack

Layer	Technology
Frontend	Next.js 15, React 19, TailwindCSS, Privy auth
Backend	NestJS 11, TypeScript, Drizzle ORM
Database	PostgreSQL, Supabase (vectors)
AI	LangGraph, OpenAI / Anthropic / Google / Groq / Mistral
Storage	IPFS via Pinata
Blockchain	Solidity, Hardhat, Base Sepolia, The Graph
Real-time	Socket.io, WebRTC

---

Contributing

git checkout -b feature/your-feature
# make changes
git commit -m "feat: description"
# open a pull request

---

License

MIT