Skip to content

AGENTS.md

Latest commit

 

History

History
1346 lines (1017 loc) · 48 KB

AGENTS.md

File metadata and controls

1346 lines (1017 loc) · 48 KB
Raw

🤖 AI Agent Knowledge Base - Liquid AI Docker

Last Updated: December 24, 2025 — V4 Agent Architecture v4.0.0 (Stable)

This file serves as the persistent knowledge base for AI assistants working on this project. Read this FIRST to minimize tool calls and maximize development efficiency.

🆕 V4 AGENT ARCHITECTURE: Lazy loading, biomimetic memory, hybrid retrieval, complete tracing. 📚 Complete V4 Documentation

📚 Table of Contents

🤖 GitHub Copilot Custom Agents (NEW)

Based on GitHub's analysis of 2,500+ repositories

This project now includes specialized agents for GitHub Copilot following the AGENTS.md specification.

Available Agents

Agent Command Description
test-agent @test-agent QA engineer for E2E and integration tests
api-agent @api-agent Backend engineer for Express/TypeScript APIs
frontend-agent @frontend-agent Frontend engineer for React/TypeScript UI
database-agent @database-agent Database engineer for PostgreSQL migrations
docs-agent @docs-agent Technical writer for documentation
langchain-agent @langchain-agent AI/ML engineer for LangChain agents and tools

Usage

In GitHub Copilot Chat, mention the agent by name:

@test-agent Write tests for the new task creation feature
@api-agent Create a new endpoint for user preferences
@database-agent Create a migration for the preferences table

Agent Files Location

All custom agents are located in .github/agents/:

.github/agents/
├── README.md           # Index and usage guide
├── test-agent.md       # Testing specialist
├── api-agent.md        # Backend API specialist
├── frontend-agent.md   # React/UI specialist
├── database-agent.md   # PostgreSQL specialist
├── docs-agent.md       # Documentation specialist
└── langchain-agent.md  # AI/ML specialist

Permission Boundaries (Three-Tier System)

Each agent follows a clear permission structure:

  • ✅ Always Do: Actions the agent should take without asking
  • ⚠️ Ask First: Actions that require human approval
  • 🚫 Never Do: Hard stops (e.g., "Never commit secrets")

📖 Full documentation: .github/agents/README.md

⚠️ MANDATORY: Documentation LLM/Gemini for Creating Agents

⚠️ ATTENTION: Before creating any new agent, ALWAYS consult the LLM (Gemini) usage documentation.

Mandatory Documentation

📚 GEMINI_3_PRO_GUIDE.md - ⭐⭐⭐⭐⭐ READ FIRST

This guide contains everything you need to know about:

  • ✅ When to use Gemini 3.0 Pro vs Gemini 2.5 Flash (System 1 vs System 2)
  • ✅ Correct model configuration in TypeScript code
  • ✅ Advanced features (thinking, grounding, vision, tool use)
  • ✅ Recommended use cases for each model
  • ✅ Cost and performance optimization
  • ✅ Complete troubleshooting

Why consult before creating agents?

  • Avoids model configuration errors
  • Ensures correct use (3.0 Pro for deep reasoning, 2.5 Flash for speed)
  • Optimizes costs and latency
  • Leverages advanced Gemini features

Other related guides:

  • GEMINI_QUICK_REFERENCE.md - Quick reference
  • GEMINI_FILE_SEARCH.md - File search with Gemini
  • docs/GEMINI_IMAGE_GENERATION_GUIDE.md - Image generation
  • docs/GEMINI_MODELS_GUIDE.md - Model guide

📋 See also: Section "⚠️ MANDATORY: Consult Gemini/LLM Documentation Before Creating Agents" below for complete checklist.

📁 Project Structure

liquid-ai-docker/
├── backend/                      # Node.js + TypeScript + Express
│   ├── src/
│   │   ├── routes/              # API endpoints
│   │   ├── services/
│   │   │   ├── langchain/       # LangChain agents & tools
│   │   │   │   ├── agents/      # 26+ specialized agents
│   │   │   │   ├── tools/       # 50+ integrated tools
│   │   │   │   ├── base-agent.ts
│   │   │   │   ├── unified-master-agent.ts
│   │   │   │   └── config.ts
│   │   │   ├── airbyte/         # Data sync integration
│   │   │   ├── julep/           # Serverless workflows
│   │   │   ├── nylas/           # Email & calendar
│   │   │   └── openmanus/       # Document generation
│   │   ├── middleware/          # Auth, validation, rate limiting
│   │   └── db/                  # Database client (PostgreSQL)
│   └── package.json
├── src/                         # React + Vite + TypeScript frontend
│   ├── components/
│   ├── pages/
│   ├── services/
│   └── lib/
├── migrations/                  # Database migrations (62 files)
├── cypress/                     # E2E tests
├── .env.example                 # Environment variables template
├── docker-compose.yml           # Local development
├── Makefile                     # Build commands
└── fly.*.toml                   # Fly.io production configs

Last Updated: December 24, 2025 — stable release v4.0.0 applied (V4 Architecture + Cyberpunk UI). See RELEASE_v4.0.0_STABLE.md for details.

🚀 Dev environment tips

According to agents.md

  • Use make (Linux/Mac) or ./start.ps1 (Windows) to start all services instead of manually running docker-compose commands.
  • Use docker-compose up to start all services directly if you prefer Docker Compose.
  • Frontend runs on http://localhost:3000, backend on http://localhost:5000.
  • Use make frontend or make backend to start individual services instead of starting everything.
  • Use docker-compose logs -f backend or make logs to view logs instead of checking Docker Desktop.
  • Use docker-compose restart backend to restart a service instead of stopping and starting manually.
  • ⚠️ NEVER use docker-compose down -v - this deletes volumes and data. Use docker-compose down (without -v) or docker-compose stop.
  • Check .env.example for required environment variables before starting services.
  • Use docker exec -it liquid-ai-buddy-postgres psql -U postgres -d liquid_ai_buddy to access the database directly.
  • Use ./apply-migrations-direct.ps1 to apply database migrations in production (Fly.io).

🧪 Testing instructions

According to agents.md

  • Find E2E tests in the ./cypress/e2e/ folder.
  • Run ./run-e2e-tests.sh to run the full E2E test suite.
  • Run npm run test to run Cypress tests from the root directory.
  • Run ./test-agents-tools-online.sh to test agents and tools functionality.
  • Run ./test-chat-e2e.sh to test chat functionality specifically.
  • Run ./test-flyio-production.sh to validate production deployment.
  • Test user credentials:
    • Email: test-1763664269@liquidai.test
    • Password: Test@123456
  • Mandatory for AI agents: test-user lifecycle
    • Prefer the existing test user above when possible.
    • If you create any additional test user (via API, seed scripts, or direct DB writes), you MUST delete that user after the tests finish (best-effort cleanup even on failures).
    • Production safety: never leave test users in production. Only create them if explicitly requested, and delete immediately after validating the scenario.
  • The commit should pass all tests before you merge. Fix any test or type errors until the whole suite is green.
  • After moving files or changing imports, run npm run lint to ensure ESLint and TypeScript rules still pass.
  • Add or update tests for the code you change, even if nobody asked.

📝 PR instructions

According to agents.md

  • Title format: [Area/Feature] Description
    • Examples:
      • [Backend] Add new agent tool for weather
      • [Frontend] Fix chat UI responsiveness
      • [Docs] Update AGENTS.md with standard sections
      • [Fix] Resolve tool calling timeout issue
  • Always run npm run lint and npm run test before committing.
  • Update relevant documentation files:
    • AGENTS.md - If changing project structure, tools, or workflows
    • ARCHITECTURE.md - If changing system architecture
    • CHANGELOG.md - For significant changes
    • README.md - If changing setup or deployment instructions
  • Check TypeScript errors: npm run type-check (if available) or tsc --noEmit
  • Ensure Docker services are running before testing locally.
  • Verify migrations are applied if database schema changed.

🔧 Tech Stack

Frontend

  • Framework: React 18 + Vite + TypeScript
  • UI: TailwindCSS + shadcn/ui
  • State: React Query (@tanstack/react-query) + Zustand
  • Forms: react-hook-form + Zod validation
  • Icons: lucide-react
  • Routing: React Router v6
  • Server: Nginx (production SPA routing)
  • Port: 3000 (dev), 80 (prod)

Backend

  • Runtime: Node.js 20 + Express + TypeScript
  • AI Framework: LangChain 1.1.5 (35+ specialized agents)
  • AI Models:
    • Gemini 3.0 Pro (standard for deep reasoning)
    • Gemini 3.0 Flash (fast for routing and default chat)
    • Gemini 2.5 Flash-Lite (ultra-fast for simple routing)
  • Vector Search: PostgreSQL 15 + pgvector + Supermemory RAG
  • Database Client: pg (native PostgreSQL client)
  • Validation: Zod
  • Auth: JWT (jsonwebtoken)
  • Port: 5000 (dev), 8000 (prod)

Infrastructure

  • Local: Docker Compose
  • Production: Fly.io (2 separate apps: frontend + backend)
  • Database: Fly.io PostgreSQL Machines
  • Monitoring: Health checks + automated backups

Key Dependencies

{
  "frontend": [
    "react@18",
    "vite",
    "@tanstack/react-query",
    "zustand",
    "tailwindcss",
    "shadcn/ui",
    "framer-motion",
    "lucide-react",
    "pdfjs-dist"
  ],
  "backend": [
    "express",
    "@langchain/core",
    "@langchain/community",
    "@google/generative-ai",
    "pg",
    "zod",
    "jsonwebtoken"
  ]
}

🧪 Testing Conventions

Test File Naming

  • E2E tests: *.test.js, *.test.mjs, *.test.ts
  • Unit tests: *.spec.ts
  • Test scripts: test-*.sh, test-*.ps1, test-*.cjs

Test Locations

  • E2E Tests: ./cypress/e2e/
  • Test Scripts: Root directory (./test-*.sh)
  • Agent Tests: ./test-agents-tools-online.sh, ./test-agents-tools-online.html

Run Commands

# E2E Tests
./run-e2e-tests.sh                    # Full E2E suite
npm run test                          # Cypress tests

# Agent Tests
./test-agents-tools-online.sh         # Agent/tool testing
./test-chat-e2e.sh                    # Chat functionality

# Production Tests
./test-flyio-production.sh            # Fly.io production tests

Test User Credentials

Email: test-1763664269@liquidai.test
Password: Test@123456

📝 Code Standards

Cyberpunk icons (frontend)

Use the shared Lucide-based icon system and avoid hard-coded palette colors:

TypeScript Configuration

  • Strict mode: Enabled
  • Target: ES2020
  • Module: ESNext
  • Path aliases: @/ → src/

Import Style

// ✅ Correct
import { Something } from "@/components/ui/something";
import { apiClient } from "@/lib/api";

// ❌ Avoid
import Something from "../../../components/ui/something";

Validation Pattern

// Always use Zod for validation
import { z } from "zod";

const schema = z.object({
  field: z.string().min(1),
});

📅 Date Formatting (IMPORTANT!)

⚠️ ALWAYS use the centralized date utility!

The default timezone is Brasília (GMT-3 / America/Sao_Paulo).

// ✅ CORRECT - Always use date-utils
import {
  formatDateTime,
  formatDate,
  formatTime,
  formatRelative,
} from "@/lib/date-utils";

formatDateTime("2025-12-11T17:30:00Z"); // "11/12/2025, 14:30"
formatDate("2025-12-11T17:30:00Z"); // "11/12/2025"
formatTime("2025-12-11T17:30:00Z"); // "14:30"
formatRelative("2025-12-11T17:30:00Z"); // "5 minutes ago"

// ❌ NEVER do this - causes timezone issues
new Date(date).toLocaleString("pt-BR");
new Date(date).toLocaleDateString("pt-BR");

File: src/lib/date-utils.ts

Why? Without specifying timeZone: 'America/Sao_Paulo', the browser uses the user's local timezone, causing incorrect times for users in other timezones.

Database Queries

// ✅ Always use parameterized queries
const result = await db.query("SELECT * FROM users WHERE id = $1", [userId]);

// ❌ Never use string interpolation
const result = await db.query(`SELECT * FROM users WHERE id = ${userId}`);

Error Handling

// Standard response format
return {
  success: true,
  data: {
    /* result */
  },
};

// Error format
return {
  success: false,
  error: {
    code: "ERROR_CODE",
    message: "User-friendly message",
    details: {},
  },
};

Type Safety

// ✅ Handle string | undefined safely
if (!value) {
  throw new Error("Value is required");
}
someFunction(value); // Now value is string

// ❌ Don't pass undefined to functions expecting string
someFunction(value); // Error if value is string | undefined

🚀 Run Commands

Development (Local)

# Start all services
./start.ps1                          # PowerShell (Windows)
make                                 # Linux/Mac
docker-compose up                    # Docker Compose direct

# Individual services
make frontend                        # Frontend only
make backend                         # Backend only

# View logs
./logs.ps1                          # PowerShell
make logs                           # Makefile
docker-compose logs -f              # Docker direct

# Restart services
docker-compose restart backend
docker-compose restart frontend

# Stop services (SAFE - preserves volumes)
docker-compose stop
docker-compose down                 # WITHOUT -v flag

Production (Fly.io)

# ⚠️ IMPORTANT: 2 separate apps
# - liquid-ai-frontend-new (frontend)
# - liquid-ai-backend (backend)

# Frontend deployment
fly deploy --config fly.frontend.toml

# Backend deployment
fly deploy --config fly.backend.toml

# Check status
fly status -a liquid-ai-backend
fly status -a liquid-ai-frontend-new

# View logs
fly logs -a liquid-ai-backend

# Database operations
fly postgres connect -a liquid-ai-db
fly mpg proxy -a liquid-ai-db

Database Migrations

# Local
docker exec -it liquid-ai-buddy-postgres psql -U postgres -d liquid_ai_buddy

# Production (Fly.io)
./apply-migrations-direct.ps1       # Recommended
fly mpg connect -a liquid-ai-db     # Direct connection

Testing

# E2E Tests
./run-e2e-tests.sh                  # Full suite
./test-chat-e2e.sh                  # Chat tests

# Agent Tests
./test-agents-tools-online.sh       # Agent/tool validation

# Production Tests
./test-flyio-production.sh          # Production validation

🛠️ Critical Files & Locations

Agent Development (V4 Architecture)

🆕 V4 Services:

  • Agent Factory V4: /backend/src/services/langchain/agent-factory-v4.ts
  • Memory Types V4: /backend/src/services/memory/memory-types-v4.service.ts
  • Hybrid Retrieval V4: /backend/src/services/memory/hybrid-retrieval-v4.service.ts
  • Span Service V4: /backend/src/services/tracing/span-service-v4.ts
  • Workflow Capture V4: /backend/src/services/workflow/workflow-capture-v4.service.ts
  • Structured Planning V4: /backend/src/services/planning/structured-planning-v4.service.ts
  • Reasoning Modes V4: /backend/src/services/reasoning/reasoning-modes-v4.service.ts
  • Control Plane V4: /backend/src/routes/v4-control-plane.ts

V2/V3 (Legacy):

  • Router LLM: /backend/src/services/langchain/intelligent-router.ts
  • Agent Factory: /backend/src/services/langchain/specialized-agent-factory.ts
  • Master Agent V2: /backend/src/services/langchain/unified-master-agent-v2.ts (with V4 support)
  • Master Agent V3: /backend/src/services/langchain/unified-master-agent-v3.ts
  • Base Agent: /backend/src/services/langchain/base-agent.ts
  • Tools Index: /backend/src/services/langchain/tools/index.ts
  • AI Config: /backend/src/services/ai-config.service.ts

API Routes

  • Auth: /backend/src/routes/auth.ts
  • Chat: /backend/src/routes/unified-chat.ts
  • Tasks: /backend/src/routes/tasks.ts
  • Goals: /backend/src/routes/goals.ts

Database

  • Client: /backend/src/db/index.ts
  • Migrations: /migrations/
  • Schema: PostgreSQL 15 + pgvector extension

Configuration

  • Environment: .env.example (template)
  • Docker: docker-compose.yml
  • Fly.io Frontend: fly.frontend.toml
  • Fly.io Backend: fly.backend.toml
  • TypeScript: tsconfig.json

🔑 Environment Variables

Required Variables

# Backend
GOOGLE_AI_API_KEY=              # Google Gemini API key
DATABASE_URL=                   # PostgreSQL connection string
JWT_SECRET=                     # JWT signing secret
PORT=5000                       # Backend port

# Frontend
VITE_API_URL=                   # Backend API URL
VITE_ENABLE_DEV_TOOLS=          # Dev tools flag
VITE_USE_POSTGRES=              # Database flag

Production (Fly.io)

  • API Keys: Stored in Fly.io secrets
  • Database: Auto-configured via Fly.io attachment
  • No hardcoded secrets

⚠️ Common Error Patterns

Issue: "Cannot read properties of undefined"

Solution: Check userId injection in tools File: /backend/src/services/langchain/tools/tool-forcing-wrapper.ts

Issue: CORS errors

Solution: Verify CORS middleware configuration File: /backend/src/middleware/cors.ts

Issue: Migration failed

Solution: Use direct migration script Command: ./apply-migrations-direct.ps1

Issue: Docker volumes deleted

Prevention: NEVER use docker-compose down -v Safe: docker-compose down (without -v) or docker-compose restart

Issue: Frontend 404 on /dashboard

Solution: Ensure Nginx SPA routing is configured File: nginx.frontend.conf

Issue: LangChain import errors

Solution: Check imports from @langchain/core vs @langchain/community Reference: BUILD-FIXES-2025-11-21.md

🤖 V4 Architecture - Extreme Performance + Biomimetic Memory (December 2025)

IMPORTANT: V4 architecture is the most recent and advanced, implemented on 19/12/2025. V2/V3 are still in use but V4 is available via feature flag.

📚 Complete V4 Documentation 📊 V4 Migration Status

V4 Overview

V4 architecture implements significant improvements inspired by open source leading solutions:

┌─────────────────────────────────────────────────────────────────────┐
│ V4 ARCHITECTURE - EXTREME PERFORMANCE + BIOMIMETIC MEMORY          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│ 1. AGENT FACTORY V4 (Lazy Loading)                                 │
│    - Instantiation < 10ms (20× faster)                             │
│    - LRU cache with 5-minute TTL                                    │
│    - Agent pool for frequent cases                                  │
│                                                                     │
│ 2. MEMORY TYPES V4 (Biomimetic)                                    │
│    - world_fact: Facts about the world                             │
│    - experience: Agent experiences                                 │
│    - opinion: Beliefs with confidence scores                        │
│    - observation: Observed patterns                                │
│                                                                     │
│ 3. HYBRID RETRIEVAL V4 (4 Parallel Strategies)                     │
│    - Semantic: Vector search (pgvector)                            │
│    - Lexical: Full-text search (BM25)                              │
│    - Graph: Relationship navigation                                │
│    - Temporal: Date filters                                        │
│                                                                     │
│ 4. SPAN SERVICE V4 (Complete Tracing)                              │
│    - Spans for each execution                                      │
│    - Performance metrics per agent                                 │
│    - Easy debugging with trace IDs                                 │
│                                                                     │
│ 5. WORKFLOW CAPTURE V4 (Intelligent Reuse)                         │
│    - Automatic capture of successful workflows                     │
│    - Reuse (30-50% latency reduction)                              │
│                                                                     │
│ 6. STRUCTURED PLANNING V4                                          │
│    - Planning before executing                                     │
│    - Dependency validation                                         │
│                                                                     │
│ 7. REASONING MODES V4                                              │
│    - Fast: < 1s (fast heuristics)                                   │
│    - Balanced: 2-3s (default)                                       │
│    - Accurate: 5-10s (deep reasoning)                              │
└─────────────────────────────────────────────────────────────────────┘

V4 vs V2/V3 Improvements

Aspect V2/V3 V4 Improvement
Instantiation ~200ms < 10ms 20×
Memory Recall ~70% 85%+ +15%
Tracing ❌ No ✅ Yes New
Memory Types ❌ No ✅ 4 types New
Hybrid Retrieval ❌ No ✅ 4 strategies New
Workflow Reuse ❌ No ✅ Yes New

Open Source Learned Lessons Applied

  • ✅ Agno: Lazy loading and extreme performance
  • ✅ Hindsight: Biomimetic memory and hybrid retrieval
  • ✅ Agent Lightning: Tracing and quality evaluation
  • ✅ CUGA: Workflow reuse and structured planning

📚 Complete V4 Documentation

🤖 V2 Architecture - Intelligent Routing + Gemini 3.0 Pro (Historical)

IMPORTANT: V2 architecture with Gemini 3.0 Pro was the standard since 11/12/2025. V4 is available as evolution.

Overview

V2 architecture uses a 2-stage system with optimized models:

┌─────────────────────────────────────────────────────────────────────┐
│  STAGE 1: Router LLM (Fast Classification)                          │
│  - Model: Gemini 2.5 Flash ⚡ (speed)                               │
│  - Function: Classifies user intent with AI semantics              │
│  - Output: { agent, confidence, reasoning }                         │
│  - Time: ~1.5s                                                     │
│  - Cost: Minimum ($0.0001 per 1K tokens)                            │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│  STAGE 2: Specialized Agent (Execution with Reasoning)             │
│  - Model: Gemini 3.0 Pro 🧠 (deep reasoning) - DEFAULT              │
│  - Fallback: Gemini 2.5 Flash ⚡ (if very fast needed)               │
│  - Agent: Selected by Router (ex: content_creator)                 │
│  - Tools: Only necessary ones (1-5 focused tools)                  │
│  - Prompt: Optimized and domain-focused                            │
│  - Memory: Context via Supermemory RAG                             │
│  - Time: 2-5s (depends on reasoning needed)                        │
│  - Cost: Moderate ($0.002 per 1K input, $0.012 output)             │
└─────────────────────────────────────────────────────────────────────┘

Why Gemini 3.0 Pro?

Aspect Gemini 2.5 Flash Gemini 3.0 Pro
Speed Ultra-fast (System 1) Moderate (System 2) ✅
Reasoning Basic Deep with explicit thinking ✅
Analysis Superficial Deep with multiple perspectives ✅
Cost Minimum Moderate
Best for Simple chat, routing Analysis, strategy, creativity

Decision: Use Gemini 3.0 Pro for agent execution (better response quality) and Gemini 2.5 Flash for routing (lower latency and cost).

Specialized Agents V2

Agent Tools (source) Description
conversational 0 Simple chat, greetings, general questions
task_manager 5 Create, list, update, delete tasks
goal_manager 3 Goals, OKRs, objectives
content_creator 2 PDFs, presentations, documents
memory_manager 5 Memories, notes, recollections
contact_manager 3 Contacts, leads, CRM
research 4 Web research, analysis
calendar 3 Meetings, events, agenda
automation 2 Workflows, automations
weather 1 Weather, temperature
image_generator 3 AI image generation with Gemini 2.0 Flash (1024x1024, multiple styles)
simplification_thinking 4 NEW! Radical simplification with first principles (Shortcut: /simple)
consulting 10+ Strategic consulting with documents + external validation via research
autonomous_researcher 10+ Deep web research/autonomous with multiple tools
catequista 10+ Catholic catechesis (content + materials + memory)
gary_vee_viral 5 Viral post creation (research + text + image)
general 8 General agent (multi-action: research + create + save)
browser 6 Browser automation (navigate/click/extract/structured scraping)
personal_finance 14 Personal finance & crypto planner with risk profiling before global investment advice
sales 8 Commercial agent for sales, marketing, proposals, and B2B strategies
vitamin_supplement 10 NEW! Vitamins, minerals, supplements expert with research access
command_center 10 Interprets context and transforms into actions (tasks/goals/memory)

Note: numbers above are historical and may vary. The source of truth for tools per agent is AGENT_CONFIGS[agent].toolNames in backend/src/services/langchain/intelligent-router.ts.

Chat Shortcuts (Slash Commands)

Shortcuts are direct commands to skip AI routing and choose a specific agent.

Implementation (backend): backend/src/middleware/slash-commands.ts (function parseSlashCommand)

Implementation (frontend): src/lib/commandSystem.ts (chat command parser; some commands call dedicated routes)

  • /help → lists shortcuts
  • /chat → conversational
  • /tasks → task_manager
  • /goals → goal_manager
  • /contacts → contact_manager
  • /notes → memory_manager
  • /automation → automation
  • /research → research
  • /consulting (or /consult) → consulting
  • /calendar → calendar
  • /weather → weather
  • /image → image_generator
  • /presentation → content_creator
  • /church → catequista
  • /investment → personal_finance
  • /sales → sales
  • /simple → simplification_thinking

Additional shortcuts (dedicated routes / outside V2 Router):

  • /imdb → IMDb Agent (dedicated API: POST /api/imdb)
  • /soccer → Soccer Agent (dedicated API: POST /api/soccer)
  • /case → Business Cases Agent (dedicated API: POST /api/case)
  • Advisory Board Agent: Dedicated API in POST /api/agents/advisory-board/chat (aliases exist in backend like /advisory//advisors)

Important: these agents do not belong to the AgentType in Router in intelligent-router.ts. In backend, unified-chat ignores invalid forceAgent to avoid crashes.

Main V2 Files

backend/src/services/langchain/
├── intelligent-router.ts        # LLM Router - Semantic classification
├── specialized-agent-factory.ts # Specialized agent factory
├── unified-master-agent-v2.ts   # V2 Orchestrator (MAIN)
├── base-agent.ts                # Base agent class
└── tools/index.ts               # All tools registry

Performance Metrics

Metric Value
Routing Accuracy 95-99%
Routing Time ~1.5s
Execution Time ~2-3s
Total Time ~4-5s

Diagnostic Endpoints

# V2 Stats
GET /api/unified-chat/v2-stats

# Isolated test
POST /api/unified-chat/v2-test

🚀 Google ADK Integration (02/12/2025)

NEW: Google ADK is integrated for high-performance automations. Chat system continues using LangChain V2 (zero breaking changes).

Overview

Google ADK (Agent Development Kit) offers parallel and optimized execution for automations:

┌─────────────────────────────────────────────────────────────────────┐
│  DUAL ARCHITECTURE: LangChain (Chat) + ADK (Automations)            │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  CHAT (LangChain V2)           │  AUTOMATIONS (Google ADK)           │
│  ─────────────────────────     │  ─────────────────────────         │
│  • Intelligent Router          │  • Parallel Research               │
│  • Specialized Agents          │  • Research Pipeline               │
│  • 55+ Tools                   │  • Task Creation Workflow          │
│  • Streaming Response          │  • Master Coordinator              │
│                                │                                    │
│  USE CASE: Human interaction   │  USE CASE: Batch processing        │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Available ADK Workflows

Workflow Description Speedup
coordinator Intelligent automatic routing 15-25%
parallel_research Research in multiple sources simultaneously 3-5x
research_pipeline Research → Analysis → Document 30-40%
task_creation Research → Task → Memory 25-35%

Main ADK Files

backend/src/services/
├── adk-automation-adapter.ts    # ADK automations adapter
├── adk-bridge.ts                # TypeScript ↔ ADK bridge
└── routes/automations.ts        # ADK endpoints

ADK Endpoints

# ADK Status
GET /api/automations/adk/status

# Available workflows
GET /api/automations/adk/available-workflows

# Optimization analysis
GET /api/automations/:id/adk-analysis

Configuration

# Enable ADK (Fly.io)
fly secrets set USE_ADK=true -a liquid-ai-backend

# Verify status
curl https://liquid-ai-backend.fly.dev/api/automations/adk/status

🖥️ ADK Web UI (Visual Debugging)

ADK Web UI offers visual debugging for agents, allowing step-by-step execution inspection.

Start UI

Linux/Mac:

cd backend
./scripts/start-adk-ui.sh

Windows (PowerShell):

cd backend
.\scripts\start-adk-ui.ps1

Python direct:

cd backend
python adk_ui_server.py

Access: http://localhost:8080

UI Features

  1. Visual Flow 🎯

    • See real-time agent execution flow
    • Visualize transfers between agents
    • Track tool calls

  2. Step-by-Step Inspection 🔍

    • Inspect input/output of each step
    • See parameters and tool call results
    • Analyze intermediate reasoning

  3. Session Rewind 🔄

    • Go back to previous steps
    • Test alternative paths
    • Debug failures without restarting

  4. Performance Metrics 📊

    • Latency per step
    • Total execution time
    • Tool call performance

Usage Example

  1. Start UI:

    cd backend && ./scripts/start-adk-ui.sh

  2. Enter query:

    "Create a task to study Python"

  3. Observe flow:

    • Router → task_manager agent
    • Tool call: create_task
    • Response generation

  4. Inspect details:

    • Click any step for details
    • See parameters passed to tools
    • Analyze intermediate responses

  5. Test alternatives:

    • Use "Rewind" to go back
    • Modify query
    • Compare results

Troubleshooting

Error: "Google ADK not installed"

pip install google-adk

Error: "GOOGLE_AI_API_KEY not found"

# Add to .env
echo "GOOGLE_AI_API_KEY=your-key" >> .env

Port 8080 already in use:

# Use alternative port
adk ui --port 8081

Database Fields (Migration 69)

Table Column Type Description
automations execution_engine VARCHAR(20) langchain/adk/hybrid
automations adk_config JSONB ADK configuration
automation_executions execution_engine VARCHAR(20) Used engine
automation_executions adk_metadata JSONB Execution metadata

Analytics View

SELECT * FROM automation_adk_analytics;
-- Compares LangChain vs ADK performance per automation

🧠 Agent Quality & Memory V2 (December 2025)

NEW: Biomimetic memory system and agent quality evaluation.

Hindsight Memory System (Biomimetic)

Memory system inspired by human functioning, with hybrid retrieval:

  • World Facts: Factual knowledge about the world (World Bank)
  • Agent Opinions: Beliefs and opinions formed by agents
  • Agent Observations: Observed patterns in interactions
  • Entity Graph: Relationship graph between entities
  • Reflection Logs: Reflection and memory consolidation process

Hybrid Retrieval:

  • Semantic: Vector search (pgvector) for similar concepts
  • Lexical: Full-text search (BM25) for exact terms
  • Graph: Relationship navigation between entities

Agent Quality Framework

Continuous quality evaluation system for agent responses:

  • Metrics: Accuracy, Relevance, Completeness, Clarity, Helpfulness, Safety
  • Evaluators: Support for automatic evaluation, LLM-as-a-Judge and Human
  • Feedback Loop: Results stored for prompt fine-tuning

🛠️ Available Tools (55+)

Categories

  • Database Tools: Tasks, Goals, Automations, Contacts, Documents CRUD
  • OpenManus Tools: Presentations, Documents, Reports, Ebooks, Code
  • Image Generation: AI images via Gemini 2.0 Flash (1024x1024, multiple styles)
  • OCR Tools: Text extraction, document analysis
  • Integrations: Airbyte, Apify, Julep, Nylas, Supermemory
  • Gemini File Search (RAG): Document indexing and semantic search with citations
  • Unified Web Search: Unified web search (Jina AI, DuckDuckGo, Brave, Firecrawl)
  • Unified Memory Search: Unified memory search (Supermemory, notes, documents)

Tools Location: /backend/src/services/langchain/tools/ Index: /backend/src/services/langchain/tools/index.ts File Search Docs: /GEMINI_FILE_SEARCH.md Image Generation Docs: /docs/GEMINI_IMAGE_GENERATION_GUIDE.md ✨ NEW

🔐 Security Rules

Docker Safety

# ✅ SAFE - Preserves data
docker-compose stop
docker-compose restart
docker-compose down              # WITHOUT -v flag

# ❌ DANGEROUS - Deletes volumes
docker-compose down -v           # NEVER USE
docker volume prune             # NEVER USE

Database Safety

  • Always use parameterized queries
  • Never use string interpolation in SQL
  • Enable row-level security (planned)
  • User isolation via WHERE user_id = $1

API Security

  • JWT authentication on all protected routes
  • Rate limiting per endpoint type
  • CORS configured for allowed origins
  • Input validation via Zod schemas

📚 Essential Documentation

Development

  • Architecture: ARCHITECTURE.md (492 lines)
  • Tools Reference: TOOLS.md
  • Agent Guide: .cursorrules
  • Deploy Guide: DEPLOY.md + DEPLOY-REFERENCE.md
  • Agent Skills: skills.md

🧠 LLM/Gemini Documentation (MANDATORY for Creating Agents)

  • 📖 GEMINI_3_PRO_GUIDE.md - ⭐⭐⭐⭐⭐ READ FIRST

    • Complete guide on using Gemini 3.0 Pro and Gemini 2.5 Flash
    • Model configuration in TypeScript code
    • Advanced features (thinking, grounding, vision, tool use)
    • Recommended use cases for each model
    • Cost and performance optimization
    • Complete troubleshooting

  • 📋 Other Gemini Guides:

    • GEMINI_QUICK_REFERENCE.md - Quick reference
    • GEMINI_FILE_SEARCH.md - File search with Gemini
    • docs/GEMINI_IMAGE_GENERATION_GUIDE.md - Image generation
    • docs/GEMINI_MODELS_GUIDE.md - Model guide

⚠️ IMPORTANT: Always consult GEMINI_3_PRO_GUIDE.md before creating new agents to ensure correct model use.

Quick References

  • PRD: PRD.md (product requirements)
  • Changelog: CHANGELOG.md
  • Release Notes: RELEASE_NOTES.md
  • Migrations: DATABASE-MIGRATIONS.md

🎯 Development Workflow

Before Starting Any Task

  1. ✅ Read this file (AGENTS.md)
  2. ✅ Check if functionality already exists
  3. ✅ Review relevant documentation
  4. ✅ Verify tech stack and patterns
  5. ✅ Check .cursorrules for rules

⚠️ MANDATORY: Consult Gemini/LLM Documentation Before Creating Agents

BEFORE creating any new agent, ALWAYS consult the LLM (Gemini) usage documentation:

  1. 📚 GEMINI_3_PRO_GUIDE.md - MANDATORY

    • Complete guide on using Gemini 3.0 Pro and Gemini 2.5 Flash
    • When to use each model (System 1 vs System 2)
    • Model configuration in code
    • Advanced features (thinking, grounding, vision, tool use)
    • Recommended use cases
    • Cost optimization
    • Troubleshooting

  2. 📋 Other Gemini Guides:

    • GEMINI_QUICK_REFERENCE.md - Quick reference
    • GEMINI_FILE_SEARCH.md - File search with Gemini
    • docs/GEMINI_IMAGE_GENERATION_GUIDE.md - Image generation
    • docs/GEMINI_MODELS_GUIDE.md - Model guide

Why?

  • Ensures correct model use (Gemini 3.0 Pro vs 2.5 Flash)
  • Avoids configuration errors
  • Optimizes costs and performance
  • Leverages advanced features (thinking, grounding, etc)

Checklist before creating agent:

  • Read the GEMINI_3_PRO_GUIDE.md
  • Understood which model to use (3.0 Pro vs 2.5 Flash)
  • Configured model correctly in code
  • Checked recommended use cases
  • Considered cost optimization

Creating New Features

  1. ⚠️ CONSULT GEMINI_3_PRO_GUIDE.md FIRST (see section above)
  2. Check /backend/src/services/langchain/tools/ for existing tools
  3. Follow existing patterns in similar files
  4. Use TypeScript strict mode
  5. Add Zod validation
  6. Update tool index if adding new tools
  7. Test locally before deploying

Deploying Changes

  1. ⚠️ Check DEPLOY-REFERENCE.md FIRST
  2. Identify correct Fly.io app (frontend vs backend)
  3. Use correct fly.*.toml config file
  4. Never cross-deploy (backend code to frontend app)
  5. Monitor logs after deployment

⚠️ Workflow pós-feature (OBRIGATÓRIO)

Após implementar uma feature, SEMPRE:

  1. Deploy no Fly.io – subir as alterações para produção (frontend e/ou backend conforme o que mudou).
  2. Testar em produção – validar a feature no ambiente real (https://liquid-ai-frontend-new.fly.dev e https://liquid-ai-backend.fly.dev).

Não considerar a feature concluída até que deploy e testes em produção tenham sido feitos.

📊 Performance Best Practices

Frontend

  • Use React Query for server state
  • IndexedDB persistence with throttling
  • Lazy load components
  • Optimize bundle size (Vite)

Backend

  • Connection pooling (50 connections)
  • HNSW indexes for vector search
  • Caching for similar queries
  • Streaming responses (SSE)

Database

  • Parameterized queries only
  • B-tree indexes on user_id
  • GIN indexes on JSONB
  • HNSW indexes on vector columns

🌐 Production URLs

📝 Notes for AI Assistants

Tool Call Optimization

Reading this file FIRST reduces tool calls by ~50%:

  • No need to scan directory structure
  • No need to infer test conventions
  • No need to check commit history for patterns
  • Direct access to run commands

Key Principles

  1. Reuse before creating - Check existing tools/agents
  2. Follow patterns - Match existing code style
  3. Document changes - Update relevant docs
  4. Test integrations - Verify tools work together
  5. Maintain compatibility - Don't break existing features

When in Doubt

  • Check .cursorrules for project rules
  • Refer to ARCHITECTURE.md for system design
  • Consult DEPLOY-REFERENCE.md before deploying
  • Review recent *.md files for context

🚀 Gemini 3.0 Pro - Complete Documentation

For detailed documentation on:

  • ✅ Gemini 3.0 Pro model (deep reasoning)
  • ✅ Explicit thinking (thinking)
  • ✅ Grounding (citations with sources)
  • ✅ Computer vision (vision)
  • ✅ Cost-benefit strategy
  • ✅ Complete troubleshooting

Consult: GEMINI_3_PRO_GUIDE.md (official guide from 11/12/2025)

🛠️ Tools, Agents & LangChain - Advanced Documentation

For complete documentation on:

  • ✅ 30+ Tools (database, image, content, research, etc)
  • ✅ 35+ Specialized agents
  • ✅ LangChain 1.1.5 architecture
  • ✅ Implementation patterns
  • ✅ Best practices and examples

Consult: TOOLS_AGENTS_LANGCHAIN.md (official guide from 11/12/2025)

📚 Analysis of Google ADK Samples - Improvements and Learnings

For complete analysis of official Google ADK Samples and practical improvement recommendations:

  • ✅ Structure patterns for agents
  • ✅ Systematic evaluation framework (YAML test sets)
  • ✅ Multi-agent workflows (Sequential, Parallel, Loop)
  • ✅ Developer tools (ADK Web UI)
  • ✅ Safety plugins and validations
  • ✅ Documentation per agent

Consult: docs/ANALISE_ADK_SAMPLES_MELHORIAS.md (complete analysis from 15/12/2025)

Last Updated: December 24, 2025 Version: 4.0.0 Status: ✅ Production Ready (V4 Agent Architecture + LangChain V2 + Gemini 3.0 Pro + Google ADK)

🆕 V4 Features:

  • ✅ Lazy loading of agents (20× faster)
  • ✅ Biomimetic memory (4 types)
  • ✅ Hybrid retrieval (4 strategies)
  • ✅ Complete tracing (spans)
  • ✅ Workflow reuse (30-50% latency reduction)
  • ✅ Structured planning
  • ✅ Configurable reasoning modes

📝 IMPORTANT NOTICE: ENGLISH DOCUMENTATION POLICY

All future documentation in this project MUST be written in English.

This policy ensures:

  • Consistency: Uniform language across all project files
  • Accessibility: Broader reach for international contributors
  • Standards: Alignment with industry best practices
  • AI Compatibility: Better integration with AI tools and assistants

For AI agents and developers:

  • Always create new documentation in English
  • When updating existing docs, translate to English
  • Maintain technical accuracy during translations
  • Preserve code examples, links, and formatting

Exception: User-facing content (UI strings, error messages) may remain in Portuguese if targeting Brazilian users.