---
slug: "product-agents"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/eabait/product-agents@main/README.md"
repo: "https://github.com/eabait/product-agents"
source_file: "README.md"
branch: "main"
---
# Product Agents Monorepo [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/eabait/product-agents)

A turborepo containing multiple AI agents for product development tasks. The most complete agent today is the PRD (Product Requirements Document) agent, which includes:
- Backend HTTP API (TypeScript/Node)
- Frontend (Next.js 14)

This README covers end-to-end local setup, environment configuration, required API keys, and run commands.


## Technical Requirements
- Node.js >= 18
- npm >= 10
- macOS/Linux/WSL recommended
- Port availability: `3000` (frontend), `3001` (backend)

Included tooling (already managed via workspaces):
- Turbo (turborepo)
- TypeScript
- ESLint
- npm workspaces (pnpm/yarn not required)


## Repository Structure
```
apps/
├─ api/                    # Thin HTTP/SSE server backed by @product-agents/product-agent

frontend/
├─ product-agent/          # Next.js UI and proxy API routes

packages/
├─ product-agent/          # Deep agent orchestrator core
├─ skills/prd/             # PRD skill pack (analyzers, section writers)
├─ shared/*                # Agent core, model compatibility, PRD schemas, UI kit, etc.
└─ (other agent scaffolds)
```

### Deep Agent Architecture (high level flow)
```
┌────────────────┐      HTTPS/SSE       ┌─────────────────────────┐       Skill packs / shared libs
│  Frontend UI   │ ───────────────────▶ │        apps/api         │ ─────────────────────────────────▶ @product-agents/skills-prd
│ (Next.js 14)   │ ◀─────────────────── │  (thin controller host) │ ◀─────────────────────────────────▶ @product-agents/shared/*
└────────────────┘    streaming events  └─────────────────────────┘
                                │
                                │ invokes
                                ▼
                      ┌───────────────────────────┐
                      │ packages/product-agent    │
                      │ (planner → execute graph) │
                      └───────────────────────────┘
```
- `frontend/product-agent` only speaks to the thin API (start/run/stream).  
- `apps/api` loads `product-agent.config.ts`, registers skill packs, and proxies progress events.  
- `packages/product-agent` composes planners, skill runners, verifiers, workspace DAO, and subagents.  
- `packages/skills/prd` + `packages/shared/*` provide the analyzers, section writers, and schemas consumed by the controller.


## Environment Variables and API Keys
The project integrates with OpenRouter for AI models. You need an OpenRouter API Key.

Where to obtain: Create an account and key at openrouter.ai (do not commit your key).

Recommended local setup files:
- Backend: `apps/api/.env`
- Frontend: `frontend/product-agent/.env.local`

Required/optional variables by component:

Backend HTTP API (`apps/api/.env`)
- `OPENROUTER_API_KEY`: REQUIRED unless passed per-request in settings
- `PRODUCT_AGENT_API_HOST`: Optional, default `0.0.0.0`
- `PRODUCT_AGENT_API_PORT`: Optional, default `3001`
- `PRD_AGENT_CHANGE_WORKER_TEMPERATURE`: Optional, tuning edit worker
- Any overrides supported by `product-agent.config.ts` (model, temperature, skill packs, workspace paths, etc.)

Frontend (`frontend/product-agent/.env.local`)
- `PRD_AGENT_URL`: REQUIRED, e.g. `http://localhost:3001`
- `OPENROUTER_API_KEY`: Optional (server-side fetch for models)
- `YOUR_SITE_URL`: Optional, used as `HTTP-Referer` for OpenRouter models API
- `YOUR_SITE_NAME`: Optional, used as `X-Title` for OpenRouter models API
- `NEXT_PUBLIC_OPENROUTER_API_KEY`: Optional, if you want a client-side default (avoid exposing secrets in prod)

Security notes:
- Do not commit real API keys. `.env*` files are gitignored.
- Keys can also be supplied per-request in payloads if preferred.

## Configuration & Overrides
- **Source of truth:** `packages/product-agent/src/config/product-agent.config.ts`
- **Defaults:** `loadProductAgentConfig()` loads runtime/workspace/skills/telemetry defaults (model, retries, storage root, enabled skill packs, log level).
- **Env overrides (server-wide):**

| Scope | Environment variable | Description |
| --- | --- | --- |
| Runtime | `PRODUCT_AGENT_MODEL`, `PRODUCT_AGENT_TEMPERATURE`, `PRODUCT_AGENT_MAX_OUTPUT_TOKENS`, `PRODUCT_AGENT_ALLOW_STREAMING`, `PRODUCT_AGENT_FALLBACK_MODEL`, `PRODUCT_AGENT_RETRY_ATTEMPTS`, `PRODUCT_AGENT_RETRY_BACKOFF_MS` | Define default model + sampling + retry behaviour. |
| Workspace | `PRODUCT_AGENT_WORKSPACE_ROOT`, `PRODUCT_AGENT_WORKSPACE_PERSIST`, `PRODUCT_AGENT_WORKSPACE_RETENTION_DAYS`, `PRODUCT_AGENT_WORKSPACE_TEMP_SUBDIR` | Control filesystem storage path/retention. |
| Skills | `PRODUCT_AGENT_SKILL_PACKS`, `PRODUCT_AGENT_ALLOW_DYNAMIC_SKILLS` | Choose skill packs and whether per-run overrides are allowed. |
| Telemetry | `PRODUCT_AGENT_TELEMETRY_STREAM`, `PRODUCT_AGENT_TELEMETRY_METRICS`, `PRODUCT_AGENT_TELEMETRY_LOG_LEVEL`, `PRODUCT_AGENT_TELEMETRY_THROTTLE_MS` | Toggle streaming + metrics + logging detail. |

- **API overrides (per run):** `model`, `temperature`, `maxOutputTokens`, `skillPackId`, `additionalSkillPacks`, `workspaceRoot`, `logLevel` — validated against `ProductAgentApiOverrideSchema`.
- **Backend host overrides:** `PRODUCT_AGENT_API_HOST`, `PRODUCT_AGENT_API_PORT` live in `apps/api/.env` alongside `OPENROUTER_API_KEY`.
- See `docs/deep-agent-refactor/phase5-changelog.md` for a concise summary of the API/env deltas introduced during Phase 5.

## Install
From repository root:
```
npm install
```

> ℹ️ This repo is configured for npm workspaces only. pnpm/yarn workspace commands are unsupported in this environment.


## Running Locally (recommended dev flow)
Use two terminals: one for the backend HTTP API and one for the frontend.

1) Start the Backend HTTP API
```
cd apps/api
# Create and populate .env with your keys/settings (see above)
npm run dev        # watch mode
# or npm run start # runs the built server
# => listens on http://0.0.0.0:3001 by default
```

2) Start the Frontend (Next.js)
```
cd frontend/product-agent
# Create .env.local with at least:
# PRD_AGENT_URL=http://localhost:3001
# (Optionally OPENROUTER_API_KEY, YOUR_SITE_URL, YOUR_SITE_NAME)
npm run dev
# => http://localhost:3000
```

Alternative: run dev scripts via turborepo
- From root: `npm run dev` starts all available `dev` scripts (e.g., the frontend). Start `apps/api` separately so it can stream logs clearly.


## Backend HTTP API
Default base URL: `http://localhost:3001`

Key endpoints (JSON):
- GET `/health` — agent info, defaults, capabilities
- POST `/prd` — create a PRD
- POST `/prd/edit` — edit an existing PRD
- POST `/prd/sections` — generate specific sections
- POST `/prd/section/:name` — update one section by name
- Streaming variants: `/prd/stream`, `/prd/edit/stream`, `/prd/sections/stream`, `/prd/section/:name/stream` (Server-Sent Events)

Notes:
- The backend requires an OpenRouter API key either via `OPENROUTER_API_KEY` env or in request `settings.apiKey`.
- Default model: `anthropic/claude-3-7-sonnet` (capability-filtered in frontend).

Example: Create a PRD (non-streaming)
```
curl -X POST http://localhost:3001/prd \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Create a PRD for a mobile habit tracker app",
    "settings": {
      "model": "anthropic/claude-3-7-sonnet",
      "temperature": 0.3,
      "maxTokens": 8000
      // "apiKey": "sk-or-..."  // optional override per request
    }
  }'
```


## Frontend App
Default URL: `http://localhost:3000`

- UI provides chat, settings panel, and model selection.
- Next.js API routes proxy to the backend at `PRD_AGENT_URL`.
- `/api/models` fetches model metadata from OpenRouter (requires API key server-side or `x-api-key` header).

Ensure `PRD_AGENT_URL` points to your running backend, and set `OPENROUTER_API_KEY` (optional) to list models server-side.


## Workspace Scripts
Root (turborepo):
- `npm run dev` — turbo run dev (frontend only by default)
- `npm run build` — turbo run build for all packages
- `npm run test` — turbo run test (runs every workspace’s test suite)
- `npm run lint` — turbo run lint (runs every workspace’s lint task)
- `npm run lint:fix` — turbo run lint:fix (applies auto-fixes where available)
- `npm run clean` — clean build outputs

Validating changes locally:
- Run `npm run lint` from the repo root to execute all lint jobs; use `npm run lint:fix` to apply safe fixes.
- Run `npm run test` from the repo root to execute the full workspace test matrix.
- To validate a single package, scope the turbo run: e.g. `npx turbo run lint --filter=frontend/product-agent` or `npx turbo run test --filter=packages/product-agent`.

Core workspaces:
- `apps/api`: `npm run dev`, `npm run build`, `npm run start`
- `packages/product-agent`: `npm run build`, `npm run test`
- `frontend/product-agent`: `npm run dev`, `npm run build`, `npm run start`, `npm run lint`


## Thin API Server
```
cd apps/api
npm run build
npm run start
# or npm run dev for watch mode
```


## Troubleshooting
- 404s from frontend API: Confirm `PRD_AGENT_URL` is set in `frontend/product-agent/.env.local`.
- Backend errors about missing API key: Set `OPENROUTER_API_KEY` in `apps/api/.env` or pass `settings.apiKey` in requests.
- Port conflicts: Change `PRD_AGENT_HTTP_PORT` or Next.js port (`PORT`) as needed.
- Model list empty: Ensure `OPENROUTER_API_KEY` is set for frontend server-side or provide `x-api-key` header to `/api/models`.


## Notes
- This repo uses capability filtering to show models compatible with the agent’s requirements (e.g., structured output, streaming).
- Do not expose secrets to the browser. Prefer server-side env vars or per-request headers.