agent-puter

---

What is Agent-Puter?

Agent-Puter is a self-contained, production-ready AI consulting agency platform. A client visits the portal, describes their project in plain English, receives an AI-generated proposal, and uses subscription credits to kick off the autonomous agent swarm. A team of specialized AI agents handles everything — research, engineering, QA — then delivers a live demo.

Client visits portal
      │
      ▼
/consult  ←── Sales Agent (live AI chat, scopes the project)
      │
      ▼
/proposal ←── Proposal (problem/solution, plan, ETA, credit cost)
      │
      ▼
Execute with credits ←── Deduct credits from subscription balance
      │
      ▼  ← Agent Swarm kicks off autonomously ──────────────────────┐
      │                                                               │
      │  CEO ──► PM ──► Engineer / Researcher ──► QA ──► CEO approves│
      │                                                               │
      ◄───────────────────────────────────────────────────────────────┘
      │
      ▼
/demo  ←── Auto-deployed sandbox delivery
      │
      ▼
/status ←── Real-time task progress tracker (auto-refreshes every 8s)

---

Architecture

Three components, one docker compose up:

┌─────────────────────────────────────────────────┐
│  frontend/          Next.js 16  (port 3000)      │
│  ├── /                Landing page               │
│  ├── /consult         AI consultation chat (SSE) │
│  ├── /dashboard       User dashboard & projects  │
│  ├── /proposal/[id]   Proposal + credit CTA      │
│  ├── /billing         Subscription & credit mgmt │
│  ├── /demo/[id]       Sandbox demo viewer        │
│  └── /status/[id]     Live progress tracker      │
│                                                  │
│  lib/api.ts           Typed REST API client      │
│  lib/auth.ts          GitHub OAuth session       │
│  lib/billing.ts       Client-side billing mock   │
└─────────────────────┬───────────────────────────┘
                      │  REST / JSON
                      ▼
┌─────────────────────────────────────────────────┐
│  src/agent_puter/swarm/   Starlette  (port 9999) │
│                                                  │
│  ── Client API ──────────────────────────────── │
│  GET  /api/auth/github                           │
│  GET  /api/auth/callback                         │
│  GET  /api/auth/me                               │
│  POST /api/auth/logout                           │
│  POST /api/consult/start                         │
│  POST /api/consult/{id}/message                  │
│  POST /api/consult/{id}/stream      (SSE)        │
│  GET  /api/consult/{id}                          │
│  POST /api/consult/{id}/complete                 │
│  GET  /api/projects                              │
│  GET  /api/projects/{id}                         │
│  GET  /api/projects/{id}/proposal                │
│  POST /api/projects/{id}/demo-url                │
│  GET  /api/projects/{id}/demo                    │
│  GET  /api/projects/{id}/usage                   │
│  POST /api/projects/{id}/push-github             │
│  POST /api/payments/deposit                      │
│  POST /api/payments/final                        │
│  POST /api/payments/webhook                      │
│  GET  /api/payments/{id}/status                  │
│  GET  /api/admin/*   (X-Admin-Key required)      │
│                                                  │
│  ── Agent A2A Endpoints ─────────────────────── │
│  /              CEO Agent (root)                 │
│  /sales/*       Sales Agent                      │
│  /pm/*          Project Manager                  │
│  /product-manager/* Product Manager Agent        │
│  /researcher/*  Researcher                       │
│  /engineer/*    Engineer                         │
│  /qa/*          QA Agent                         │
│  /deliveries/*  Static sandbox files             │
└─────────────────────────────────────────────────┘

---

The Agent Swarm

Seven specialized agents, each a self-contained A2A ASGI app:

All inter-agent calls use the A2A protocol (HTTP via fasta2a.A2AClient). No direct Python .run() calls between agents — every agent is addressed only by its mounted HTTP URL.

---

Subscription & Credit Model

Project execution is billed in credits drawn from a subscription balance. All billing state is managed client-side via localStorage (frontend mock — no backend billing calls).

Plans

Credits roll over; they do not expire. Monthly grants accumulate on top of your existing balance.

Credit Packs (paid plans only)

Top-up credits are available on Starter, Pro, and Business plans. The Free tier cannot purchase packs.

Per-Million Token Pricing

Credits are calculated from the proposal's estimated hours using the same per-million-token structure as LLM providers:

Formula: totalCredits = (inputTokens / 1M × 3) + (outputTokens / 1M × 15)

---

Quick Start

Prerequisites

• uv — Python package manager
• Node.js 20+ and npm
• A Puter.js account for free LLM inference (or any OpenAI-compatible API)
• A Stripe account (test keys work fine)
• A GitHub OAuth App (optional — required for the login button and GitHub delivery features)

1. Clone and configure

git clone https://github.com/vizionik25/agent-puter.git
cd agent-puter
cp .env.example .env
# Edit .env: fill in PUTER_AUTH_TOKEN, PUTER_MODEL, PUTER_API_BASE,
#             Stripe keys, and (optional) GitHub OAuth vars

GitHub login (optional): Create an OAuth App at github.com/settings/developers. Set the callback URL to http://localhost:3000/api/auth/callback. Copy the client ID and secret into GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env. Set SESSION_SECRET to any strong random string.

2. Start the backend

uv sync
uv run agent-puter
# → http://localhost:9999
# → http://localhost:9999/health   (swarm status)
# → http://localhost:9999/docs     (CEO agent interactive docs)

Or install from PyPI and run globally:

uv tool install agent-puter
agent-puter

3. Start the frontend

cd frontend
npm install
npm run dev
# → http://localhost:3000

4. (Optional) Stripe webhook for local testing

stripe listen --forward-to localhost:9999/api/payments/webhook

Docker — full stack

cp .env.example .env   # fill in secrets
docker compose up --build -d
# Frontend: http://localhost:3000
# Backend:  http://localhost:9999

---

Environment Variables

---

Project Structure

agent-puter/
├── src/agent_puter/
│   ├── __init__.py
│   ├── agent-logic-example.py       Single-agent reference example
│   └── swarm/
│       ├── main.py                  Starlette app — mounts agents + API
│       ├── server.py                uvicorn launcher
│       ├── agency.py                Agency orchestrator (business loop)
│       ├── models.py                Pydantic data models
│       ├── base_agent.py            LiteLLMModel factory
│       ├── middleware.py            Multi-tenancy (X-Agency-Key)
│       ├── notifications.py         SMTP email notifications
│       ├── ceo_agent.py
│       ├── sales_agent.py
│       ├── pm_agent.py
│       ├── product_manager_agent.py
│       ├── researcher_agent.py
│       ├── engineer_agent.py
│       ├── qa_agent.py
│       └── api/
│           ├── __init__.py          Aggregates all API routes
│           ├── _store.py            Legacy alias (delegates to store.py)
│           ├── store.py             Pluggable storage backends
│           ├── auth.py              /api/auth/* routes (GitHub OAuth)
│           ├── consultation.py      /api/consult/* routes
│           ├── github_delivery.py   Push deliverables to GitHub repo
│           ├── projects.py          /api/projects/* routes
│           ├── payments.py          /api/payments/* routes
│           └── admin.py             /api/admin/* routes
│
├── frontend/
│   ├── app/
│   │   ├── layout.tsx               Root layout + nav + UserMenu
│   │   ├── page.tsx                 Landing page
│   │   ├── consult/page.tsx         Consultation chat (SSE streaming)
│   │   ├── dashboard/page.tsx       User dashboard & project management
│   │   ├── proposal/[id]/page.tsx   Proposal + credit execution CTA
│   │   ├── billing/page.tsx         Subscription & credit management
│   │   ├── demo/[id]/page.tsx       Sandbox demo viewer
│   │   └── status/[id]/page.tsx     Real-time task progress
│   ├── components/
│   │   ├── UserMenu.tsx             GitHub auth nav menu + dropdown
│   │   └── MockStripeModal.tsx      Simulated payment modal
│   ├── lib/
│   │   ├── api.ts                   Typed REST client
│   │   ├── auth.ts                  GitHub OAuth session helpers
│   │   └── billing.ts               Client-side billing (localStorage)
│   └── next.config.ts               Standalone output mode
│
├── Dockerfile                       Backend multi-stage build
├── frontend/Dockerfile              Frontend multi-stage build (Node 22)
├── docker-compose.yml               Full stack
├── docker-compose.backend.yml       Backend only
├── pyproject.toml
└── .env.example

---

Docs

• Architecture — system design, agent communication, data flow, storage
• API Reference — every endpoint with request/response tables
• Getting Started — local dev setup, first consultation walkthrough
• Deployment — Docker Compose, environment reference, Stripe production

---

License

MIT © 2026 Charles Nichols — vizionikmedia.com