Proposed Changes to AGENTS.md - Learnings from Zava Implementation

agents-md-proposed-changes.md

Proposed Changes to AGENTS.md

Overview

Based on learnings from the Zava business management system implementation, this document proposes updates to AGENTS.md to improve accuracy, add critical setup steps, and prevent common issues.

---

Change 1: Fix Framework Documentation (CRITICAL)

Current (INCORRECT)

### Backend (src/agent/)
- **Framework**: Flask 3.0+
- **Language**: Python 3.12+

Proposed (CORRECT)

### Backend (src/agent/)
- **Framework**: FastAPI 0.104+
- **Language**: Python 3.12+
- **ASGI Server**: Uvicorn

Rationale

• Generated code uses FastAPI, not Flask
• FastAPI better supports async Agent Framework operations
• FastAPI provides automatic OpenAPI documentation at /docs
• Prevents confusion when developers see FastAPI imports in code

---

Change 2: Add Environment Setup Section

New Section to Add (After "Project Structure")

## Environment Setup (CRITICAL - DO FIRST)

### Prerequisites
1. Azure CLI installed and authenticated: `az login`
2. Python 3.12+ with venv support
3. Node.js 18+ and pnpm 9+ installed
4. Azure subscription with necessary permissions

### Initial Setup Steps

#### 1. Provision Azure Resources
```bash
cd <project-root>
azd init
azd provision

2. Create Environment Files

# Copy Azure deployment values to local .env
cp .azure/<project-name>/.env src/agent/.env

# Verify required values exist in src/agent/.env:
# - AZURE_AI_PROJECT_ENDPOINT
# - AZURE_AI_MODEL_DEPLOYMENT
# - AZURE_STORAGE_ACCOUNT_NAME (if using Azure Storage)
# - PORT (default: 3000)
# - CORS_ORIGINS (default: *)

3. Verify Environment Loading

Ensure src/agent/app.py loads .env file:

from pathlib import Path
from dotenv import load_dotenv

# Load environment variables from .env file
env_path = Path(__file__).parent / '.env'
load_dotenv(env_path)

⚠️ Common Issue: python-dotenv must be imported and called explicitly - environment variables don't load automatically!

4. Install Dependencies

Backend:

cd src/agent
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Unix:
source .venv/bin/activate

pip install -r requirements.txt

Frontend:

cd src/web
pnpm install
pnpm run build  # Verify compilation succeeds

5. Configure VS Code Python Interpreter

Add to .vscode/settings.json:

{
  "python.defaultInterpreterPath": "${workspaceFolder}/src/agent/.venv/Scripts/python.exe"
}

Port Configuration

Default Port Assignments:

• Agent Backend: 3000 (configurable via PORT in .env)
• Web Frontend: 5173 (Vite default)

Files to Check for Port Consistency:

1. src/agent/.env - PORT=3000
2. src/web/vite.config.ts - proxy target: http://localhost:3000
3. src/web/.env.example - VITE_API_URL=http://localhost:3000

⚠️ Critical: All port references must match! Mismatched ports cause "connection refused" errors.

Best Practice: Use relative URLs in frontend components to leverage Vite proxy:

// ❌ WRONG: Bypasses proxy, causes CORS issues
const API_BASE = 'http://localhost:3000';

// ✅ CORRECT: Uses Vite proxy from vite.config.ts
const API_BASE = '';

### Rationale
- Environment setup is currently missing from AGENTS.md
- Developers need explicit instructions before writing code
- Prevents 90% of startup issues encountered during implementation
- Port configuration is scattered and needs centralization

---

## Change 3: Add Storage Initialization Requirements

### New Section to Add (After "Azure Services")
```markdown
## Storage Initialization

If using Azure Storage (Table Storage, Blob Storage, Cosmos DB), **always initialize storage resources on startup**.

### Example: Azure Table Storage
```python
async def initialize(self):
    """Initialize table clients and create tables if they don't exist"""
    try:
        await self.service_client.create_table("products")
    except Exception:
        pass  # Table already exists
    
    try:
        await self.service_client.create_table("sales")
    except Exception:
        pass  # Table already exists
    
    self.products_client = self.service_client.get_table_client("products")
    self.sales_client = self.service_client.get_table_client("sales")

Best Practices

• Create tables/containers/databases on first run
• Handle "already exists" exceptions gracefully
• Log initialization status for debugging
• Call initialization during application startup before accepting requests

⚠️ Common Issue: Forgetting to create storage resources causes 500 errors with "table/container does not exist" messages.

### Rationale
- Storage initialization is not mentioned in current AGENTS.md
- Missing tables/containers cause cryptic 500 errors
- Developers need to know this must be implemented in their code

---

## Change 4: Add Pre-Flight Validation Checklist

### New Section to Add (Before "Testing & Quality")
```markdown
## Pre-Flight Checklist

Before running `azd app run` or starting services locally, verify:

### Backend (src/agent/)
- [ ] `.env` file exists with all required values
- [ ] `load_dotenv()` is called at top of `app.py`
- [ ] Virtual environment activated: `.venv/Scripts/activate`
- [ ] All packages installed: `pip install -r requirements.txt`
- [ ] Python interpreter configured in VS Code
- [ ] Storage initialization code exists (if using Azure Storage)
- [ ] Port in `.env` matches other configs (default: 3000)

### Frontend (src/web/)
- [ ] All packages installed: `pnpm install`
- [ ] TypeScript compiles: `pnpm run build`
- [ ] shadcn/ui components installed (if used)
- [ ] Vite proxy target matches agent port
- [ ] Components use relative URLs, not hardcoded absolute URLs

### Configuration Consistency
- [ ] Agent port in `src/agent/.env`
- [ ] Vite proxy target in `src/web/vite.config.ts`
- [ ] API URL in `src/web/.env.example`
- [ ] All three match (default: 3000 for agent)

### Validation Commands
```bash
# Test agent endpoint
curl http://localhost:3000/health

# Check TypeScript compilation
cd src/web && pnpm run build

# Verify Python imports
cd src/agent && .venv/Scripts/python -c "import fastapi; import azure.ai.client; print('OK')"

Common Issues

• "AZURE_AI_PROJECT_ENDPOINT environment variable required": .env not loaded
• "Connection refused": Port mismatch between agent and web config
• "Table does not exist": Storage resources not initialized
• shadcn/ui errors: Components not installed or wrong baseColor
• CORS errors: Using absolute URLs instead of Vite proxy

### Rationale
- Provides actionable checklist before starting services
- Prevents common startup failures
- Reduces debugging time from hours to minutes
- Catches configuration issues early

---

## Change 5: Update Package Management Section

### Current
```markdown
### Python
- ✅ **Use pip with virtual environment** (no Poetry)
- Create venv: `python -m venv .venv`
- Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (Unix)
- Install: `pip install -r requirements.txt`
- Add packages: Edit `requirements.txt`, then `pip install -r requirements.txt`

Proposed (Enhanced)

### Python
- ✅ **Use pip with virtual environment** (no Poetry)
- Create venv: `python -m venv .venv`
- Activate: `.venv\Scripts\activate` (Windows) or `source .venv/bin/activate` (Unix)
- Install: `pip install -r requirements.txt`
- Add packages: Edit `requirements.txt`, then `pip install -r requirements.txt`

**Important**: Always activate the virtual environment before running Python commands!

**Common Issues**:
- Packages installed globally instead of in venv → wrong Python interpreter
- Missing `python-dotenv` import → environment variables not loaded
- Outdated packages → run `pip install --upgrade -r requirements.txt`

**Verify Installation**:
```bash
cd src/agent
.venv/Scripts/python -c "import fastapi, azure.ai.client, dotenv; print('All packages OK')"

### Rationale
- Adds common pitfalls and solutions
- Includes verification command
- Reminds developers to activate venv (frequently forgotten)

---

## Change 6: Add Vite Proxy Configuration Guidance

### New Section to Add (After "Frontend (src/web/)")
```markdown
### Vite Development Server Configuration

The Vite dev server includes a proxy to forward API requests to the agent backend, avoiding CORS issues.

**Configuration** (`src/web/vite.config.ts`):
```typescript
export default defineConfig({
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: process.env.VITE_AGENT_URL || 'http://localhost:3000',
        changeOrigin: true,
        secure: false,
      },
      '/health': {
        target: process.env.VITE_AGENT_URL || 'http://localhost:3000',
        changeOrigin: true,
        secure: false,
      }
    }
  }
})

Usage in Components:

// ✅ CORRECT: Use relative URLs to leverage proxy
const response = await fetch('/api/products');

// ❌ WRONG: Absolute URLs bypass proxy and cause CORS errors
const response = await fetch('http://localhost:3000/api/products');

Benefits:

• No CORS configuration needed in development
• Same-origin requests from browser perspective
• Easy to switch between local and deployed backends
• Matches production behavior (same origin)

⚠️ Critical: Always use relative URLs in frontend code to use the proxy!

### Rationale
- Vite proxy is critical but not documented
- Prevents CORS issues that waste development time
- Explains why relative URLs are required

---

## Change 7: Add Troubleshooting Section

### New Section to Add (End of Document)
```markdown
## Troubleshooting

### Agent Won't Start

**Error: "AZURE_AI_PROJECT_ENDPOINT environment variable required"**
- **Cause**: `.env` file not loaded
- **Solution**: Add to top of `app.py`:
  ```python
  from pathlib import Path
  from dotenv import load_dotenv
  
  env_path = Path(__file__).parent / '.env'
  load_dotenv(env_path)

Error: "error while attempting to bind on address ('0.0.0.0', 3000)"

• Cause: Port already in use
• Solution:

  # Windows
  netstat -ano | findstr :3000
  Stop-Process -Id <PID> -Force
  
  # Change port in src/agent/.env if needed
  PORT=3001

Web App Can't Connect to Agent

Error: "ERR_CONNECTION_REFUSED" or "Failed to fetch"

• Cause: Port mismatch or agent not running
• Check:
  1. Agent is running: curl http://localhost:3000/health
  2. Ports match in .env and vite.config.ts
  3. Using relative URLs in components (not absolute URLs)

Error: CORS errors in browser console

• Cause: Using absolute URLs instead of Vite proxy
• Solution: Change to relative URLs:

  const API_BASE = '';  // Not 'http://localhost:3000'

Storage Errors

Error: "The table specified does not exist" (500 error)

• Cause: Azure Table Storage tables not created
• Solution: Add table creation to initialization:

  async def initialize(self):
      try:
          await self.service_client.create_table("your_table")
      except Exception:
          pass  # Already exists

shadcn/ui Component Errors

Error: "baseColor 'sky' is not a valid color"

• Cause: Invalid baseColor in components.json
• Solution: Change to valid color: "slate", "gray", "zinc", "neutral", or "stone"

Error: "Cannot find module '@/components/ui/tabs'"

• Cause: Components not installed
• Solution: pnpm dlx shadcn@latest add tabs table label

TypeScript Compilation Errors

Error: "Cannot find module" after adding packages

• Cause: Vite dependency cache stale
• Solution:

  cd src/web
  rm -rf node_modules/.vite
  pnpm install

Azure Authentication Errors

Error: "DefaultAzureCredential failed to retrieve token"

• Cause: Not logged into Azure CLI
• Solution: az login and az account set --subscription <id>

### Rationale
- Provides quick solutions to common errors
- Reduces time spent debugging
- Based on actual issues encountered during implementation

---

## Change 8: Update Key Guidelines

### Current
```markdown
## Key Guidelines

- ✅ Always use Agent Framework for AI features
- ✅ Use pnpm for Node.js packages
- ✅ Use pip + venv for Python packages (no Poetry)
- ✅ Write tests before marking features complete
- ✅ Update docs when requirements change
- ✅ Handle errors gracefully
- ✅ Follow existing code patterns

Proposed (Enhanced)

## Key Guidelines

### Development Process
- ✅ **Setup first**: Create `.env` files and install dependencies BEFORE writing code
- ✅ **Verify configuration**: Check port consistency across all config files
- ✅ **Test incrementally**: Verify agent works before starting web app
- ✅ **Use relative URLs**: Let Vite proxy handle API routing (avoid hardcoded URLs)

### Technology Choices
- ✅ **Always use Agent Framework** for AI features (never raw OpenAI SDK)
- ✅ **Always use pnpm** for Node.js packages (never npm or yarn)
- ✅ **Always use pip + venv** for Python packages (no Poetry)
- ✅ **Always use FastAPI** for backend (not Flask, despite legacy docs)
- ✅ **Always use DefaultAzureCredential** for Azure authentication

### Code Quality
- ✅ Write tests before marking features complete
- ✅ Update docs when requirements change
- ✅ Handle errors gracefully with meaningful messages
- ✅ Follow existing code patterns
- ✅ Use type hints (Python) and proper types (TypeScript)

### Storage
- ✅ **Initialize storage on startup**: Create tables/containers if they don't exist
- ✅ **Handle "already exists" exceptions**: Use try/except gracefully
- ✅ **Test storage access**: Verify connectivity before processing requests

### Configuration
- ✅ **Load .env explicitly**: Import and call `load_dotenv()` in Python
- ✅ **Keep ports consistent**: Document and verify across all config files
- ✅ **Validate before running**: Use pre-flight checklist before `azd app run`

Rationale

• Organizes guidelines by category
• Adds critical setup and configuration guidance
• Makes it easier to find relevant guidelines
• Emphasizes configuration validation

---

Summary of Changes

Change	Priority	Impact
Fix Framework Documentation (Flask→FastAPI)	🔴 Critical	Prevents confusion about tech stack
Add Environment Setup Section	🔴 Critical	Prevents 90% of startup failures
Add Storage Initialization Requirements	🟡 High	Prevents 500 errors from missing tables
Add Pre-Flight Validation Checklist	🟡 High	Catches issues before they become problems
Update Package Management Section	🟢 Medium	Reduces common venv mistakes
Add Vite Proxy Configuration Guidance	🟡 High	Prevents CORS issues
Add Troubleshooting Section	🟡 High	Reduces debugging time significantly
Update Key Guidelines	🟢 Medium	Better organization and clarity

---

Implementation Priority

Phase 1 (Critical - Implement Immediately)

1. Fix Flask→FastAPI documentation
2. Add Environment Setup section
3. Add Pre-Flight Checklist

Phase 2 (High Priority - Next Update)

1. Add Storage Initialization requirements
2. Add Vite Proxy configuration guidance
3. Add Troubleshooting section

Phase 3 (Nice to Have - Future Improvement)

1. Update Package Management section
2. Reorganize Key Guidelines

---

Additional Recommendations

1. Add Example .env Files to Template

Create src/agent/.env.example:

# Agent Configuration
PORT=3000

# Azure AI Foundry
AZURE_AI_PROJECT_ENDPOINT=https://your-endpoint.ai.azure.com/api/projects/your-project
AZURE_AI_MODEL_DEPLOYMENT=gpt-4o-mini

# Azure Storage (if using)
AZURE_STORAGE_ACCOUNT_NAME=your-storage-account

# CORS Configuration
CORS_ORIGINS=*

# Debug
DEBUG=True

Create src/web/.env.example:

# API Configuration
VITE_API_URL=http://localhost:3000

2. Add Validation Script

Create scripts/validate-setup.sh or scripts/validate-setup.ps1:

# Check .env exists
if (!(Test-Path "src/agent/.env")) {
    Write-Error ".env file missing in src/agent/"
    exit 1
}

# Check port consistency
$agentPort = (Get-Content src/agent/.env | Select-String "PORT=").Line.Split("=")[1]
$viteConfig = Get-Content src/web/vite.config.ts -Raw
if ($viteConfig -notmatch "localhost:$agentPort") {
    Write-Warning "Port mismatch detected!"
}

# Check dependencies
Push-Location src/agent
& .venv/Scripts/python -c "import fastapi, azure.ai.client, dotenv"
if ($LASTEXITCODE -ne 0) {
    Write-Error "Missing Python dependencies"
    exit 1
}
Pop-Location

Write-Host "✅ Setup validation passed!" -ForegroundColor Green

3. Update README.md

Add "Quick Start" section referencing AGENTS.md:

## Quick Start

1. **Read AGENTS.md first** - Contains critical setup instructions
2. Follow the Environment Setup section carefully
3. Use the Pre-Flight Checklist before running services
4. Refer to Troubleshooting if you encounter issues

---

Testing the Changes

Validation Approach

1. Create new project from template
2. Follow updated AGENTS.md exactly
3. Measure time to first successful run
4. Note any remaining pain points
5. Iterate on documentation

Success Criteria

• New developer can get app running in < 30 minutes
• Zero "connection refused" errors with correct setup
• Zero "environment variable required" errors
• Zero "table does not exist" errors
• All troubleshooting steps resolve issues within 5 minutes

---

Conclusion

These changes address the major pain points discovered during Zava implementation:

1. Environment configuration (most critical)
2. Port consistency (frequent source of errors)
3. Storage initialization (causes cryptic 500 errors)
4. Framework documentation (Flask vs FastAPI confusion)
5. Proxy usage (CORS issues)

Implementing these changes will significantly improve developer experience and reduce time-to-first-success for new projects.