### Start AgentOS Server

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Instructions on how to start the AgentOS server, either directly or using provided scripts. This makes the API endpoints available.

```APIDOC
## Start AgentOS Server

### Description
Follow these steps to start the AgentOS server, which exposes the API endpoints for your application.

### Usage

**Windows:**
```bash
start-agentos.bat
```

**Linux/Mac:**
```bash
chmod +x start-agentos.sh
./start-agentos.sh
```

**Alternatively, run directly:**
```bash
python 04-agno-agentos.py
```

### Expected Output
Upon successful startup, you will see:

```
🚀 Starting AgentOS for 'Should I Move?' Application
================================================================================

📋 Available Resources:
   - 👥 Agents: Cost Analyst, Sentiment Analyst, Migration Researcher
   - 🤝 Team: City Move Decision Team (coordinator)
   - 🧠 Knowledge Base: System docs, team capabilities, city data

🌐 Server Information:
   - Local URL: http://localhost:7777
   - API Docs: http://localhost:7777/docs
   - Health Check: http://localhost:7777/health
```
```

--------------------------------

### AgentOS Mode Startup - bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Starts the web-based AgentOS mode for production deployments. Linux/Mac uses bash script, Windows uses batch file. Alternatively, can be started manually with Python. Requires PostgreSQL database and Docker for full functionality.

```bash
bash start-agentos.sh           # Linux/Mac
```

```bash
python agentos_integration.py
```

--------------------------------

### Start AgentOS Server on Linux/Mac

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Makes the start script executable and runs it to launch the AgentOS server. Alternative direct execution method is also provided. Requires the script or Python file to exist.

```bash
chmod +x start-agentos.sh
./start-agentos.sh
```

```bash
python 04-agno-agentos.py
```

--------------------------------

### Start PostgreSQL Database with PgVector using Docker

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Launches a PostgreSQL container with PgVector extension enabled. Sets up user credentials and exposes the database on port 5532. Requires Docker to be installed.

```bash
docker run -d \
  --name pgvector-db \
  -e POSTGRES_USER=agno \
  -e POSTGRES_PASSWORD=agno \
  -e POSTGRES_DB=agno \
  -p 5532:5432 \
  pgvector/pgvector:pg16
```

--------------------------------

### AgentOS Mode Startup - bat

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Starts the web-based AgentOS mode for Windows production deployments. Alternative to bash script for Windows users. Requires PostgreSQL database and proper environment configuration.

```bat
start-agentos.bat               # Windows
```

--------------------------------

### GET /knowledge

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Lists all uploaded knowledge documents available to agents.

```APIDOC
## GET /knowledge

### Description
Retrieves a list of all knowledge documents in the system.

### Method
GET

### Endpoint
/knowledge

### Parameters
None.

### Request Example
No body required.

### Response
#### Success Response (200)
- **knowledge** (array) - List of knowledge entries with IDs and metadata.

#### Response Example
{
  "knowledge": [
    {
      "id": "doc_123",
      "name": "TaxGuide.pdf"
    }
  ]
}
```

--------------------------------

### Create AgentOS Instance with Agents and Teams

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Initializes an AgentOS instance with specified agents, teams, and knowledge bases. Provides methods to get a FastAPI app and serve it. Requires agent definitions and team configurations.

```python
from agno.os import AgentOS

agent_os = AgentOS(
    id="should-i-move-os",
    description="City Relocation Analysis System",
    agents=[cost_analyst, sentiment_analyst, migration_researcher],
    teams=[move_decision_team],
    knowledge=[relocation_knowledge],
)

# Get FastAPI app
app = agent_os.get_app()

# Serve with uvicorn
agent_os.serve(
    app="04-agno-agentos:app",
    host="0.0.0.0",
    port=7777,
    reload=True,
)
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/02-agno-router-approach/README.md

Installs necessary Python packages for the Agno-based city move decision application. Ensure you have a virtual environment activated before running.

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install agno openai python-dotenv firecrawl-py
```

--------------------------------

### Python Virtual Environment Setup

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Creates and activates a Python virtual environment named 'venv'. This isolates project dependencies and ensures a clean development environment.

```bash
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
```

--------------------------------

### Bash Script for Project Setup and Testing

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/data/nerd-wallet-data-generator/README.md

A collection of bash commands for setting up the project and running tests. It includes commands to create the city database, verify its functionality with the city matcher, and optionally run city validation and scraper tests. These commands are intended for command-line execution.

```bash
# Create the city database
python create_city_database.py

# Verify it works with the city matcher
python city_matcher.py

# Test the scraper with specific cities (if applicable)
python test_cost_scraper.py

# Validate cities against NerdWallet (optional)
python validate_cities.py

```

--------------------------------

### Install Python Dependencies for AgentOS

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Activates a virtual environment and installs required packages for the AgentOS framework, including PostgreSQL driver and PgVector extension. Requires Python 3.10+.

```bash
# Activate virtual environment
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install AgentOS requirements
pip install -r requirements-agentos.txt
```

--------------------------------

### GET /memory

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Lists all stored memory entries for agents and sessions.

```APIDOC
## GET /memory

### Description
Fetches a list of all memory records in the system.

### Method
GET

### Endpoint
/memory

### Parameters
None.

### Request Example
No body required.

### Response
#### Success Response (200)
- **memories** (array) - Array of memory entries with IDs and content.

#### Response Example
{
  "memories": [
    {
      "id": "mem_123",
      "content": "Session history..."
    }
  ]
}
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Installs necessary Python packages for the Overclock Accelerator project, including agno, openai, python-dotenv, firecrawl-py, and pydantic. This is a crucial step before running the application.

```bash
pip install agno openai python-dotenv firecrawl-py pydantic
```

--------------------------------

### Add Custom Knowledge Sources

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Python code examples for extending AgentOS knowledge base with external content sources. Supports adding web content via URLs and PDF documents from file paths.

```python
# Add web content to knowledge base
relocation_knowledge.add_url(
    url="https://example.com/city-guide",
    title="City Moving Guide"
)

# Add PDF documents
relocation_knowledge.add_pdf(
    path="docs/relocation-handbook.pdf",
    title="Relocation Handbook"
)
```

--------------------------------

### Environment Variable Setup for API Key

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/brave_tools/README.md

This example shows how to set the `BRAVE_API_KEY` environment variable, which is required for the custom Brave Search tool to authenticate with the Brave Search API. The key should be added to a `.env` file in the project's root directory. This configuration is essential for the tool's operation.

```bash
BRAVE_API_KEY=BSxxxxxxxxxxxxxxxxxx
```

--------------------------------

### Create City Database

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/02-agno-router-approach/README.md

Generates a comprehensive JSON database of over 200 US cities with proper URL formats for the NerdWallet cost of living calculator. This is a one-time setup step.

```bash
cd nerdwallet-tools
python create_city_database.py
cd ..
```

--------------------------------

### Dockerfile for AgentOS Application

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

A Dockerfile used to build a container image for the AgentOS application. It specifies the base Python image, installs dependencies from requirements.txt, copies the application code, and sets the command to run the main integration script. This enables easy deployment and scaling of the application.

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements-agentos.txt .
RUN pip install -r requirements-agentos.txt

COPY . .
CMD ["python", "agentos_integration.py"]
```

--------------------------------

### Reset and Run PostgreSQL Container

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Commands to stop, remove, and then start a fresh PostgreSQL container for the agentos integration. This is useful for resetting the database state. It configures the container with specific environment variables for user, password, and database name, and maps the host port 5532 to the container's port 5432.

```bash
# Stop and remove container
docker stop agentos-postgres
docker rm agentos-postgres

# Start fresh
docker run -d --name agentos-postgres \
  -e POSTGRES_USER=agno -e POSTGRES_PASSWORD=agno \
  -e POSTGRES_DB=agno -p 5532:5432 pgvector/pgvector:pg16
```

--------------------------------

### Setup Sequential Coordination Team with Agno Framework

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Initializes a multi-agent team using the coordination pattern where agents process tasks sequentially without interaction. Uses OpenAI GPT-4o-mini model with specialized agents for cost analysis, sentiment analysis, and migration research. The team is configured for coordination mode with individual response display and output schema validation.

```python
# Sequential coordination team
move_decision_team = Team(
    name="City Move Decision Team",
    model=OpenAIChat("gpt-4o-mini"),
    members=[cost_analyst, sentiment_analyst, migration_researcher],
    delegate_task_to_all_members=False,  # ← COORDINATION MODE (default)
    show_members_responses=True,          # ← Show individual work
    add_member_tools_to_context=False,    # ← Isolate agent tools
    output_schema=FinalRecommendation,
    # ... instructions for delegation flow
)
```

--------------------------------

### Deploy AgentOS with Docker Compose

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Docker Compose configuration for deploying AgentOS with PostgreSQL database. Sets up environment variables for database connection and API keys. Requires Docker and Docker Compose installed.

```yaml
version: '3.8'
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: agno
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: agno
    volumes:
      - pgdata:/var/lib/postgresql/data
    
  agentos:
    build: .
    environment:
      AGENTOS_DB_URL: postgresql+psycopg://agno:${DB_PASSWORD}@postgres:5432/agno
      OPENAI_API_KEY: ${OPENAI_API_KEY}
    ports:
      - "7777:7777"
    depends_on:
      - postgres
```

--------------------------------

### PostgreSQL Troubleshooting - bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Commands to diagnose and fix PostgreSQL connection issues in AgentOS mode. Checks if PostgreSQL container is running, restarts the service, or recreates the container with proper pgvector extension. Requires Docker to be installed and running.

```bash
docker ps | grep agentos-postgres

docker restart agentos-postgres

docker rm agentos-postgres
docker run -d --name agentos-postgres \
  -e POSTGRES_USER=agno -e POSTGRES_PASSWORD=agno \
  -e POSTGRES_DB=agno -p 5532:5432 pgvector/pgvector:pg16
```

--------------------------------

### Session CRUD Operations - http

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Full session lifecycle management endpoints. POST creates new sessions, GET retrieves session details, PUT updates session data, and DELETE removes sessions. Sessions enable persistent conversations and user context retention.

```http
POST /sessions              # Create session
GET /sessions/{session_id}  # Get session
PUT /sessions/{session_id}  # Update session
DELETE /sessions/{id}       # Delete session
```

--------------------------------

### POST /knowledge/upload

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Uploads a document to the knowledge base for agents to reference in analyses.

```APIDOC
## POST /knowledge/upload

### Description
Adds a new document to the system's knowledge repository for use by agents.

### Method
POST

### Endpoint
/knowledge/upload

### Parameters
#### Request Body
- **document** (file) - Required - The document file to upload (e.g., PDF, text).

### Request Example
Upload as multipart/form-data with file.

### Response
#### Success Response (201)
- **id** (string) - Unique ID of the uploaded knowledge entry.

#### Response Example
{
  "id": "doc_123",
  "message": "Document uploaded"
}
```

--------------------------------

### Set Up Environment Variables

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Configures essential API keys for external services like OpenAI, Firecrawl, and Brave Search by creating a .env file. These keys are required for the application to interact with these services.

```bash
OPENAI_API_KEY=your_openai_key_here
FIRECRAWL_API_KEY=your_firecrawl_key_here
BRAVE_API_KEY=your_brave_search_key_here
```

--------------------------------

### GET /sessions/{session_id}

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Retrieves details of a specific session by its ID. Useful for checking session status and history.

```APIDOC
## GET /sessions/{session_id}

### Description
Fetches the current state and metadata of an existing session.

### Method
GET

### Endpoint
/sessions/{session_id}

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The session ID to retrieve.

### Request Example
No body required.

### Response
#### Success Response (200)
- **session** (object) - Session details including agent, user, and history.

#### Response Example
{
  "session_id": "session_abc123",
  "agent_id": "cost-analyst",
  "user_id": "user123",
  "created_at": "2023-10-01T10:00:00Z"
}
```

--------------------------------

### Initialize Vector Database with PgVector

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Sets up a vector database for storing knowledge embeddings. Requires a database URL and an embedder like OpenAIEmbedder. Creates tables for sessions, memory, and knowledge.

```python
vector_db = PgVector(
    table_name="agent_knowledge",
    db_url=DB_URL,
    embedder=OpenAIEmbedder(id="text-embedding-3-small"),
)
```

--------------------------------

### Stateless Agent vs. Stateful AgentOS Agent

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Illustrates the difference between a basic, stateless agent and a stateful agent integrated with AgentOS, highlighting the addition of database and knowledge base dependencies for persistence and context.

```python
# Before (Stateless):
# Each run is independent
team = Team(name="Move Team", members=[...])
team.print_response("Should I move?")
# No memory of previous conversations

# After (Stateful with AgentOS):
# Sessions persist across interactions
team = Team(
    name="Move Team",
    db=db,  # PostgreSQL for sessions & memory
    knowledge=knowledge_base,  # Shared knowledge
)
# Agents remember previous conversations
# Context is maintained across messages

```

--------------------------------

### Run AgentOS Application Locally

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Execute the AgentOS application in a local development environment. Requires Python environment with dependencies installed. Runs the application on localhost port 7777 by default.

```bash
python 04-agno-agentos.py
# Runs on localhost:7777
```

--------------------------------

### POST /memory

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Creates a new memory entry for storing context or data.

```APIDOC
## POST /memory

### Description
Adds a new memory record to the system.

### Method
POST

### Endpoint
/memory

### Parameters
#### Request Body
- **content** (string) - Required - The memory content to store.

### Request Example
{
  "content": "Migrated from NYC to Austin basics"
}

### Response
#### Success Response (201)
- **id** (string) - Unique ID of the created memory.

#### Response Example
{
  "id": "mem_123",
  "message": "Memory created"
}
```

--------------------------------

### Knowledge Base Integration with AgentOS

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Demonstrates how to set up and populate a knowledge base using AgentOS, integrating vector databases for efficient querying of documents and data. This enables agents to access and utilize external information.

```python
relocation_knowledge = Knowledge(
    vector_db=PgVector(embedder=OpenAIEmbedder())
)

# Add system documentation
relocation_knowledge.add_text(SYSTEM_DOCS)

# Add data files
relocation_knowledge.add_directory(path="data", glob="*.json")

# Agents can now query this knowledge
agent = Agent(
    knowledge=relocation_knowledge,  # ← Agents have RAG access
    # ...
)

```

--------------------------------

### Debug Server Startup Problems

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Diagnostic commands for troubleshooting AgentOS server startup issues. Checks for port conflicts and validates environment variable configuration. Works on both Windows and Unix-based systems.

```bash
# Check if port 7777 is already in use
netstat -ano | findstr :7777  # Windows
lsof -i :7777                  # Linux/Mac

# Check environment variables
python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.getenv('AGENTOS_DB_URL'))"
```

--------------------------------

### Verify Knowledge Base Loading

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Commands to diagnose knowledge base loading issues in AgentOS. Checks data directory existence, file permissions, and tests manual knowledge loading functionality.

```bash
# Verify data directory exists
ls -la data/

# Check file permissions
chmod 644 data/*.json

# Test manual knowledge loading
python -c "
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector
kb = Knowledge(vector_db=PgVector(...))
kb.add_directory('data', glob='*.json')
"
```

--------------------------------

### Build and Run AgentOS Docker Container

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Commands to build a Docker image for the 'should-i-move-agentos' project and then run it as a container. It maps port 7777 on the host to the container's port 7777 and utilizes environment variables from a `.env` file for configuration. This facilitates the deployment of the application in a containerized environment.

```bash
docker build -t should-i-move-agentos .
docker run -p 7777:7777 --env-file .env should-i-move-agentos
```

--------------------------------

### Run analysis scripts in Bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/COMPARISON.md

Command-line instructions to execute coordination and cooperation analysis modes. The coordination mode provides quick results while cooperation mode includes detailed debate information.

```bash
# Quick coordination analysis
python 01-agno-coordination.py

# In-depth cooperation analysis with priority
python 03-agno-cooperation.py
```

--------------------------------

### Visualize AgentOS system architecture diagram

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/ARCHITECTURE.md

ASCII diagram showing the complete AgentOS system architecture with user browser, control plane, agent server, and PostgreSQL database components. Illustrates the flow of HTTPS/WebSocket connections and data storage components.

```text
┌─────────────────────────────────────────────────────────────────┐
│                         USER'S BROWSER                          │
│                   https://app.agno.com                          │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTPS + WebSocket
                         │
┌────────────────────────▼────────────────────────────────────────┐
│                  AGENTOS CONTROL PLANE                          │
│                   (Hosted by Agno)                              │
│                                                                 │
│  • Chat UI  • Knowledge Manager  • Session Browser             │
│  • Memory Browser  • Performance Metrics                        │
│  🔒 NO DATA STORED - Direct browser connection                  │
└────────────────────────┬────────────────────────────────────────┘
                         │ HTTP/WebSocket (from browser)
                         │
┌────────────────────────▼────────────────────────────────────────┐
│               YOUR AGENTOS SERVER                               │
│           (Your Infrastructure - Port 7777)                     │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                    REST API                              │  │
│  │  /agents/{id}/runs  /teams/{id}/runs  /sessions        │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │              AGENTS & TEAMS                              │  │
│  │  Cost Analyst  │  Sentiment  │  Migration Researcher    │  │
│  │                    Team Coordinator                      │  │
│  └─────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │                 CUSTOM TOOLS                             │  │
│  │  NerdWallet Scraper  │  Brave Reddit Search             │  │
│  └─────────────────────────────────────────────────────────┘  │
└────────────────────────┬────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────────┐
│                    POSTGRESQL + pgvector                        │
│  agent_sessions  │  agent_memory  │  agent_knowledge            │
└─────────────────────────────────────────────────────────────────┘
```

--------------------------------

### Python: Integrate Brave Search Tool with Agent

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/brave_tools/README.md

This Python code demonstrates how to integrate the `search_reddit_discussions` tool into a custom agent, specifically the 'Migration Researcher' agent. It shows the tool being added to the agent's list of available tools for use in its decision-making process. This setup requires the agent framework to be defined elsewhere.

```python
from brave_tools.brave_search_tool import search_reddit_discussions

migration_researcher = Agent(
    name="Migration Researcher",
    tools=[search_reddit_discussions],
    # ... agent configuration
)
```

--------------------------------

### Create Collaborative Debate Team for City Move Analysis

Source: https://context7.com/overclock-accelerator/should-i-move/llms.txt

This Python code sets up a 'Team' for collaborative, parallel analysis of city move decisions, emphasizing user priorities. It introduces extended Pydantic schemas (`CostAnalysis`, `DebateSummary`, `FinalRecommendation`) to capture debate specifics. Key configurations include `delegate_task_to_all_members=True` for parallel execution and debate, and detailed instructions guiding agents to debate, prioritize user input, and document consensus with a focus on the user's most important factor.

```python
from agno.team.team import Team
from agno.agent.agent import Agent
from agno.tools.local_file_system import LocalFileSystemTools
from agno.llms.openai import OpenAIChat
from pydantic import BaseModel, Field
from typing import List

# Extended schemas for cooperation mode
class CostAnalysis(BaseModel):
    overall_cost_difference: str
    housing_comparison: str
    food_comparison: str
    transportation_comparison: str
    taxes_comparison: str
    key_insights: List[str]
    perspective_on_user_priority: str  # NEW: relates cost to user's priority

class DebateSummary(BaseModel):
    debate_rounds: int
    key_points_of_agreement: List[str]
    key_points_of_disagreement: List[str]
    how_user_priority_influenced_debate: str
    consensus_reached: str
    debate_highlights: List[str]

class FinalRecommendation(BaseModel):
    # ... standard fields ...
    debate_summary: DebateSummary  # NEW: full debate documentation
    alignment_with_user_priority: str  # NEW: explicit priority alignment

# Assume cost_analyst, sentiment_analyst, migration_researcher are defined elsewhere
# Assume get_cost_of_living_comparison is a tool defined elsewhere

# Create cooperation team (parallel + debate)
move_decision_team = Team(
    name="City Move Decision Team",
    model=OpenAIChat("gpt-4o-mini"),
    members=[cost_analyst, sentiment_analyst, migration_researcher],
    delegate_task_to_all_members=True,  # KEY: parallel execution + debate
    show_members_responses=True,         # Show the debate process
    tools=[
        LocalFileSystemTools(target_directory="./reports")
    ],
    instructions=[
        "Step 1 - Gather Info + Priority:",
        "Collect: cities, finances, preferences",
        "CRITICAL: Ask 'What's your MOST IMPORTANT factor?' (cost, career, culture, etc.)",
        "",
        "Step 2 - Collaborative Debate:",
        "Delegate task to ALL members simultaneously",
        "Agents present findings and debate perspectives",
        "Focus debate on user's stated priority",
        "Guide team to consensus respecting user priority",
        "",
        "Step 3 - Document Debate:",
        "Include full DebateSummary in final recommendation",
        "Show how priority influenced the debate",
        "Explain consensus and any disagreements",
        "",
        "Step 4 - Save Report:",
        "Filename: '{current_city}_to_{desired_city}_cooperation_analysis.md'",
        "Include subtitle: 'Collaborative Analysis with Priority: [User Factor]'",
        "Add sections: User's Most Important Factor, Debate Summary, How This Aligns with Your Priority"
    ],
    output_schema=FinalRecommendation,
    markdown=True
)

# Agent instructions emphasize collaboration
cost_analyst_coop = Agent(
    name="Cost Analyst",
    model=OpenAIChat("gpt-4o-mini"),
    instructions=[
        "You are in a COLLABORATIVE DEBATE",
        "CRITICAL: Consider user's MOST IMPORTANT FACTOR",
        "If cost data suggests X, but user prioritizes career, adjust perspective",
        "Be willing to reframe analysis based on user priority",
        "Work toward consensus with other agents",
        "Document your perspective on the user's priority"
    ],
    tools=[get_cost_of_living_comparison],
    output_schema=CostAnalysis
)

# Note: Similar Agent configurations would be needed for sentiment_analyst and migration_researcher
# The actual execution (running the team) would follow a similar pattern to the sequential example.
```

--------------------------------

### Illustrate AgentOS request flow process

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/ARCHITECTURE.md

ASCII diagram showing the complete request flow from user input through the AgentOS system. Demonstrates how user queries traverse the control plane, agent server, and various specialized agents before returning synthesized responses.

```text
USER TYPES: "Should I move from Seattle to Austin?"
    ↓
Browser → Control Plane (app.agno.com)
    ↓
Control Plane → Your Server (localhost:7777)
    POST /teams/move-decision-team/runs
    ↓
AgentOS Server:
    ├─ Load session from PostgreSQL (if exists)
    ├─ Load user memories
    └─ Delegate to Team Coordinator
    ↓
Team Coordinator delegates to agents:
    ├─ Cost Analyst → scrapes NerdWallet
    ├─ Sentiment Analyst → analyzes city culture  
    └─ Migration Researcher → searches Reddit via Brave
    ↓
Agents return analyses → Team synthesizes
    ↓
Save to PostgreSQL:
    ├─ Conversation → agent_sessions
    ├─ Memories → agent_memory
    └─ Knowledge vectors → agent_knowledge
    ↓
Response streams back through Control Plane → Browser
    ↓
USER SEES: Complete recommendation with all analyses
```

--------------------------------

### Execute agent tool for cost comparison

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/ARCHITECTURE.md

Process flow for agent tool execution when performing cost of living comparisons. Shows the sequence of city matching, URL construction, web scraping, and data analysis steps used by AgentOS agents.

```text
Agent: "I need cost data"
    ↓
Call: get_cost_of_living_comparison("Seattle", "Austin")
    ↓
    ├─ find_best_city_match("Seattle")
    │  └─ Returns: "seattle-wa"
    │
    ├─ find_best_city_match("Austin")
    │  └─ Returns: "austin-tx"
    │
    └─ Build URL: nerdwallet.com/...compare/seattle-wa-vs-austin-tx
       ↓
       Firecrawl scrapes page
       ↓
       Returns: Structured cost data
       ↓
       Agent analyzes → CostAnalysis model
```

--------------------------------

### CLI Mode Execution Commands - bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Executes analysis in CLI mode using different coordination strategies. Sequential analysis processes tasks in order, single specialist mode uses one agent, and collaborative debate enables agent cooperation. All commands require Python 3.7+ and project dependencies.

```bash
python 01-agno-coordination.py  # Sequential analysis
python 02-agno-router.py        # Single specialist
python 03-agno-cooperation.py   # Collaborative debate
```

--------------------------------

### Set Environment Variables for API Keys and Database

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Defines necessary environment variables including API keys for OpenAI, Firecrawl, and Brave Search, as well as the database URL. Stored in a .env file for secure configuration.

```bash
# OpenAI
OPENAI_API_KEY=your_openai_key_here

# Data sources
FIRECRAWL_API_KEY=your_firecrawl_key_here
BRAVE_API_KEY=your_brave_search_key_here

# Database (or use default)
AGENTOS_DB_URL=postgresql+psycopg://agno:agno@localhost:5532/agno
```

--------------------------------

### POST /sessions

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Creates a new session for persistent agent interactions. Associates an agent with a user for maintaining context across multiple runs.

```APIDOC
## POST /sessions

### Description
Initializes a new session linking an agent and a user for ongoing conversations.

### Method
POST

### Endpoint
/sessions

### Parameters
#### Request Body
- **agent_id** (string) - Required - Agent to associate with the session.
- **user_id** (string) - Required - User ID for the session.

### Request Example
{
  "agent_id": "cost-analyst",
  "user_id": "user123"
}

### Response
#### Success Response (201)
- **session_id** (string) - Unique ID of the created session.

#### Response Example
{
  "session_id": "session_abc123"
}
```

--------------------------------

### Add API Key Authentication to AgentOS App

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Configuration snippet for adding API key authentication to an AgentOS application. It shows how to set the API key in a `.env` file and then use it when creating the AgentOS app. This enhances the security of the application by requiring a valid API key for access.

```bash
# In .env
AGENTOS_API_KEY=your_secure_key_here
```

```python
app = create_agentos_app(
    agents=[...],
    teams=[...],
    api_key=os.getenv("AGENTOS_API_KEY"),
)
```

--------------------------------

### Configure Team Leader Agent Instructions

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Defines production-grade instructions for Team Leader agent including role definition, conversational approach guidelines, and memory/knowledge base usage reminders. Ensures consistent, empathetic interaction with users.

```python
instructions=[
    "🤝 YOUR ROLE:",
    "- Engage in natural, helpful conversations",
    "- Ask clarifying questions when needed",
    "- Coordinate specialists to provide analysis",
    
    "💬 CONVERSATIONAL APPROACH:",
    "- Be warm and empathetic",
    "- Remember context from earlier messages",  # ← Memory!
    "- Explain what your team will do",
    
    "🧠 REMEMBER:",
    "- You have access to a knowledge base",      # ← RAG!
    "- You maintain conversation memory",         # ← Sessions!
]
```

--------------------------------

### Chat with Team via API - bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Initiates a conversation with the move-decision-team to analyze relocation questions. Requires the team API endpoint and accepts a message payload. Returns collaborative analysis from the team specialists.

```bash
curl -X POST "http://localhost:7777/teams/move-decision-team/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Should I move from NYC to Austin?"
  }'
```

--------------------------------

### Create Cooperation Mode Team

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/COMPARISON.md

Creates a team using cooperation mode where all agents work together with debate. Key parameters include delegate_task_to_all_members=True and show_members_responses=True.

```python
move_decision_team = Team(
    name="City Move Decision Team",
    members=[cost_analyst, sentiment_analyst, migration_researcher],
    delegate_task_to_all_members=True,  # ← KEY DIFFERENCE
    show_members_responses=True,        # ← Shows debate
    instructions=[
        "Initiate collaborative debate",
        "Ensure user's priority is central",
        "Guide team to consensus",
        "Document debate in report"
    ]
)
```

--------------------------------

### Query Agent Sessions and Memory in PostgreSQL

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Provides Docker commands to inspect AgentOS PostgreSQL database tables for sessions, memory entries, and knowledge embeddings. Essential for debugging, monitoring production deployments, and verifying data persistence.

```bash
# Check sessions
docker exec -it pgvector-db psql -U agno -d agno \
  -c "SELECT id, created_at FROM agent_sessions ORDER BY created_at DESC LIMIT 5;"
```

```bash
# Check memory entries
docker exec -it pgvector-db psql -U agno -d agno \
  -c "SELECT session_id, created_at FROM agent_memory ORDER BY created_at DESC LIMIT 5;"
```

```bash
# Check knowledge embeddings
docker exec -it pgvector-db psql -U agno -d agno \
  -c "SELECT COUNT(*) FROM agent_knowledge;"
```

--------------------------------

### Create City Database using Python

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/data/nerd-wallet-data-generator/README.md

Generates a comprehensive database of over 200 US cities with proper NerdWallet URL formats. It handles special cases like NYC boroughs and outputs the data to '../data/nerdwallet_cities_comprehensive.json'. This script requires no external dependencies beyond standard Python libraries.

```python
import json

# Sample data structure (replace with actual data source)
US_CITIES = [
    {"name": "New York", "state": "NY", "aliases": ["NYC", "New York City"]},
    {"name": "Los Angeles", "state": "CA", "aliases": ["LA", "L.A."]},
    # ... more cities
]

NYC_BOROUGHS = {
    "Brooklyn": "brooklyn",
    "Manhattan": "manhattan",
    "Queens": "queens",
    "Bronx": "bronx",
    "Staten Island": "staten-island"
}

def format_nerdwallet_url(city_data):
    city_name_parts = city_data['name'].lower().split(' ')
    formatted_name = '-'.join(city_name_parts)
    
    # Handle NYC boroughs specifically
    if city_data['name'] == "New York" and "borough" in city_data:
        formatted_name = f"new-york-{NYC_BOROUGHS[city_data['borough']]}"
        
    return f"{formatted_name}-{city_data['state'].lower()}"

def create_city_database(output_file='../data/nerdwallet_cities_comprehensive.json'):
    city_database = []
    for city in US_CITIES:
        if city['name'] == "New York":
            for borough, borough_slug in NYC_BOROUGHS.items():
                city_database.append({
                    "name": f"New York - {borough}",
                    "state": city['state'],
                    "url_name": format_nerdwallet_url({"name": borough, "state": city['state'], "borough": borough})
                })
        else:
            city_database.append({
                "name": city['name'],
                "state": city['state'],
                "url_name": format_nerdwallet_url(city)
            })
            
    with open(output_file, 'w') as f:
        json.dump(city_database, f, indent=2)
    print(f"City database created at {output_file}")

if __name__ == "__main__":
    # This is a placeholder. In a real scenario, US_CITIES would be loaded from a source
    # and the script would execute create_city_database()
    print("Simulating city database creation...")
    # create_city_database()

```

--------------------------------

### PostgreSQL Database Configuration for AgentOS

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Shows how to configure the PostgreSQL database connection for AgentOS, specifying the database URL and table names for session and memory storage. This is crucial for enabling persistence.

```python
DB_URL = "postgresql+psycopg://agno:agno@localhost:5532/agno"

# Session and memory storage
db = PostgresDb(
    db_url=DB_URL,
    session_table="agent_sessions",
    memory_table="agent_memory",
)

```

--------------------------------

### Knowledge & Memory Management - http

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

API endpoints for managing uploaded documents and stored memories. Knowledge endpoints handle document upload, listing, and deletion. Memory endpoints provide persistent storage for analysis context and user preferences.

```http
POST /knowledge/upload      # Upload document
GET /knowledge              # List knowledge
DELETE /knowledge/{id}      # Delete document

GET /memory                 # List memories
POST /memory                # Create memory
DELETE /memory/{id}         # Delete memory
```

--------------------------------

### Verify PostgreSQL Database Connection

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Executes a command inside the running PostgreSQL container to verify the database connection and version. Requires the container to be running.

```bash
docker exec -it pgvector-db psql -U agno -d agno -c "SELECT version();"
```

--------------------------------

### Troubleshoot Database Connection Issues

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Commands to diagnose and fix database connection problems in AgentOS deployment. Includes testing database connectivity, enabling PgVector extension, and verifying table structures.

```bash
# Test database connection
docker exec -it pgvector-db psql -U agno -d agno -c "SELECT 1;"

# Check if PgVector extension is enabled
docker exec -it pgvector-db psql -U agno -d agno -c "CREATE EXTENSION IF NOT EXISTS vector;"

# Verify tables exist
docker exec -it pgvector-db psql -U agno -d agno -c "\dt"
```

--------------------------------

### Build City List for Matching

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/02-agno-router-approach/README.md

Executes a series of scripts to create and validate a city database for fuzzy matching user input to NerdWallet city formats, handling aliases and variations.

```bash
cd nerdwallet-tools

# Step 1: Create the city database
python create_city_database.py

# Step 2: Test the city matcher
python city_matcher.py

# Step 3 (Optional): Validate cities against NerdWallet
python validate_cities.py

cd ..
```

--------------------------------

### Configure Enhanced Agent with Knowledge Access

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/README.md

Configures an agent with capabilities including memory, knowledge access via RAG, session context awareness, and a unique ID for API routing. Depends on a database and knowledge base being available.

```python
cost_analyst = Agent(
    name="Cost Analyst",
    id="cost-analyst",  # ← Unique ID for routing
    db=db,              # ← Enable session storage
    knowledge=relocation_knowledge,  # ← Access to knowledge base
    # ... rest of configuration
)
```

--------------------------------

### View PostgreSQL Container Logs

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

A command to view the logs of the running PostgreSQL container named 'agentos-postgres'. This is essential for diagnosing any issues or monitoring the database's activity.

```bash
docker logs agentos-postgres
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/02-agno-router-approach/README.md

Sets up API keys for OpenAI and Firecrawl in a .env file. This file is automatically loaded by the application to access external services.

```bash
OPENAI_API_KEY=your_api_key_here
FIRECRAWL_API_KEY=your_firecrawl_key_here
```

--------------------------------

### Agent & Team API Endpoints - http

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

REST API endpoints for running individual agents or teams. POST /agents/{agent_id}/runs processes messages with optional session persistence. POST /teams/{team_id}/runs enables collaborative analysis. Both endpoints support streaming responses.

```http
POST /agents/{agent_id}/runs
Content-Type: application/json

{
  "message": "Compare Seattle vs Portland",
  "session_id": "optional-session-id",
  "stream": false
}
```

```http
POST /teams/{team_id}/runs
Content-Type: application/json

{
  "message": "Should I move to Austin?",
  "session_id": "optional-session-id",
  "stream": false
}
```

--------------------------------

### Test City Matching

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Executes the 'city_matcher.py' script within the 'nerdwallet-tools' directory to test the city matching logic, which handles aliases, specific boroughs, and fuzzy matching.

```bash
cd nerdwallet-tools
python city_matcher.py
cd ..
```

--------------------------------

### Run Overclock Accelerator Application

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/01-agno-coordination-approach/README.md

Executes the main application script '01-agno-coordination.py'. It can be run in normal mode or debug mode for detailed agent communication logs.

```bash
# Normal mode
python 01-agno-coordination.py

# Debug mode (shows detailed agent communication)
python 01-agno-coordination.py --debug
```

--------------------------------

### Session Management via API - bash

Source: https://github.com/overclock-accelerator/should-i-move/blob/main/04-agno-agentos-approach/GETTING_STARTED.md

Creates and manages user sessions for persistent analysis. The create session endpoint requires agent_id and user_id. The continue session endpoint allows ongoing conversations with a specific session identifier.

```bash
curl -X POST "http://localhost:7777/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "cost-analyst",
    "user_id": "user123"
  }'
```

```bash
curl -X POST "http://localhost:7777/agents/cost-analyst/runs" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What about taxes?",
    "session_id": "session_abc123"
  }'
```