AGENTS.md

Setup commands

Quick start

• Install deps: ./scripts/setup.sh
• Start dev servers: ./start-dev.sh
• Run tests: ./test.sh

Manual setup

• Backend deps: cd backend && uv pip install -e .
• Frontend deps: cd frontend && npm install
• Backend dev server: cd backend && app-dev (with auto-reload) or cd backend && app (production)
• Frontend dev server: cd frontend && npm run dev

Project overview

This is a modern AI Agent application built with:

• Backend: Python 3.12 + Agno framework + FastAPI
• Frontend: TypeScript + Next.js 16 + React 19 + Tailwind CSS 4 + CopilotKit
• Communication: AG-UI Protocol for real-time agent interactions via CopilotKit
• Architecture: Monorepo with backend and frontend integration

Code style

Backend (Python)

• Use Python 3.12+ with strict type hints
• Follow PEP 8 style guide
• Use uv for package management
• Docstrings follow Google style
• Async/await for I/O operations
• Environment variables for configuration

Frontend (TypeScript)

• TypeScript strict mode enabled
• Next.js 16 App Router architecture
• Use functional React components with hooks
• Tailwind CSS 4 for styling
• CopilotKit for AI agent integration
• AG-UI protocol via @ag-ui/agno adapter
• Server components by default, client components when needed

General

• Conventional commits for git messages
• Write tests for all new features
• Use descriptive variable and function names
• Keep components small and focused
• Error boundaries for graceful failure handling

Dev environment tips

Backend development

• Use uv venv --python 3.12 for virtual environments
• Run uv pip install -e . for editable installs
• Check .env.example for required environment variables
• Use app-dev for development server (auto-reload) or app for production server
• Logs are structured JSON for easy parsing

Frontend development

• Use npm as the package manager
• Run npm run lint for linting with ESLint
• Hot reload enabled on file changes (Next.js Fast Refresh)
• CopilotKit runtime handles AG-UI protocol connections
• API routes in app/api/copilotkit/route.ts for backend integration

Testing

• Backend tests: cd backend && python -m pytest tests/ -v
• Frontend: Testing setup pending (to be configured)
• Integration tests: ./test.sh
• Coverage reports generated automatically

Common workflows

• Add new agent: Create in backend/src/agents/ (see backend/AGENTS.md)
• Add new tool: Create in backend/src/tools/ (see backend/AGENTS.md)
• Add new page: Create in frontend/app/
• Add API route: Create in frontend/app/api/
• Update CopilotKit integration: Modify frontend/app/api/copilotkit/route.ts

Testing instructions

Prerequisites

• Backend: cd backend && source .venv/bin/activate
• Frontend: Node.js 20+ and npm installed

Running tests

• Backend only: cd backend && python -m pytest tests/ -v
• Frontend: Testing framework to be configured
• Integration tests: Manual testing via running both servers

Test coverage

• Backend: Generates HTML coverage report in backend/htmlcov/
• Frontend: To be configured

Test patterns

• Unit tests for individual functions/classes
• Integration tests for API endpoints
• Agent integration tests for AG-UI protocol communication

Security considerations

API security

• All API endpoints validate input with Pydantic models
• Rate limiting implemented on chat endpoints
• CORS configured for frontend domain only
• Environment variables for all secrets (no hardcoded keys)

Frontend security

• Next.js built-in security features enabled
• XSS protection through React's built-in escaping
• API keys stored in environment variables, not client code
• CopilotKit runtime handles secure agent communication
• Server-side API routes for backend integration

Data protection

• No sensitive data logged in production
• User conversations stored encrypted
• Regular security audits of dependencies
• GDPR compliance for user data handling

Performance considerations

Backend optimization

• Async request handling with FastAPI
• Connection pooling for database operations
• Caching for frequently accessed knowledge
• Streaming responses for real-time chat

Frontend optimization

• Automatic code splitting with Next.js App Router
• Server components for reduced client bundle size
• Lazy loading for large components
• React.memo for expensive renders
• Image optimization with next/image
• Font optimization with next/font

Monitoring

• Response time tracking for all API calls
• Memory usage monitoring for agent instances
• Frontend bundle size analysis
• Database query performance logging

Common workflows

• Add new agent: Create in backend/src/agents/ (see backend/AGENTS.md)
• Add new tool: Create in backend/src/tools/ (see backend/AGENTS.md)
• Add new page: Create in frontend/app/ (see frontend/AGENTS.md)
• Add API route: Create in frontend/app/api/ (see frontend/AGENTS.md)
• Update CopilotKit integration: Modify frontend/app/api/copilotkit/route.ts

Sub-Level Documentation Standards

Backend Documentation (backend/AGENTS.md)

The backend follows these additional guidelines:

• Use uv for package management (not pip)
• Server commands: app-dev (development), app (production)
• Python 3.12+ with strict type hints
• Qwen models require role mapping fix
• Tool development standards in backend/src/tools/AGENTS.md
• Agent development standards in backend/src/agents/AGENTS.md

Frontend Documentation (frontend/AGENTS.md)

The frontend follows these additional guidelines:

• Use npm as package manager
• Next.js 16 App Router architecture
• TypeScript strict mode enabled
• Server Components by default, Client Components when needed
• CopilotKit for AI agent integration
• AG-UI protocol via @ag-ui/agno adapter

Agent Development (backend/src/agents/AGENTS.md)

When creating agents:

• Use folder-based structure: agent_name/__init__.py, agent.py, README.md
• Choose model based on complexity: qwen-plus (simple), qwen-max (complex)
• Include detailed instructions with domain knowledge
• Document HITL (Human-in-the-Loop) requirements
• Follow naming conventions and import order

Tool Development (backend/src/tools/AGENTS.md)

When creating tools:

• Separate core logic (core.py) from tool wrapper (__init__.py)
• Use complete type hints and Google-style docstrings
• Test core functions directly, not via .entrypoint
• Document HITL requirements clearly
• Use @tool decorator with detailed instructions

Resources

• Backend details: See backend/AGENTS.md
• Frontend details: See frontend/AGENTS.md
• Agent development: See backend/src/agents/AGENTS.md
• Tool development: See backend/src/tools/AGENTS.md
• Agno documentation
• AG-UI protocol documentation
• Next.js documentation
• CopilotKit documentation