# Agent Guidelines System - Detailed Design

## 1. Overview

The **Agent Guidelines system** enables trainers to influence agent
behavior dynamically using natural language instructions.

Key principles: - Guidelines are **natural language (NL) only** -
Guidelines are **agent-specific** - No strict schema or intent mapping
(LLM interprets relevance) - Applied at runtime via **prompt injection**

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

## 2. High-Level Flow

1.  Trainer adds guideline via UI
2.  Guideline stored in `agent_guidelines` table
3.  On agent execution:
    -   Fetch guidelines by `agent_type`
    -   Sort by priority
    -   Inject into prompt
4.  LLM decides which guidelines to apply

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

## 3. Database Design

### Table: `agent_guidelines`

  Field        Type        Description
  ------------ ----------- -----------------------------
  id           UUID        Unique identifier
  agent_type   ENUM        UI / DATA / RTI / USER_PREF
  content      TEXT        Natural language guideline
  priority     INT         Higher = more important
  status       ENUM        active / inactive
  version      INT         Version tracking
  created_by   STRING      Trainer ID
  created_at   TIMESTAMP   Created time

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

## 4. Trainer Workflow

### Input Requirements:

-   Select **Agent Type** (mandatory)
-   Enter **Guideline (NL text)**

### Example:

-   UI Agent → "Use line charts for trends"
-   Data Agent → "Avoid archived data unless requested"

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

## 5. Runtime Implementation

### Step 1: Fetch Guidelines

``` python
def get_guidelines(agent_type):
    return db.query(
        '''
        SELECT content 
        FROM agent_guidelines 
        WHERE agent_type = %s AND status = 'active'
        ORDER BY priority DESC
        LIMIT 5
        ''',
        [agent_type]
    )
```

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

### Step 2: Prompt Builder

``` python
def build_prompt(base_prompt, guidelines, context, user_query):
    guidelines_text = "\n".join([f"- {g}" for g in guidelines])

    return f'''
You are a {context["agent_name"]}.

Base Responsibilities:
{base_prompt}

Agent Guidelines:
Below are guidelines provided by trainers.
Apply them only when relevant to the current task.

{guidelines_text}

User Query:
{user_query}

Context:
{context}

Instructions:
- Apply guidelines only if relevant
- If guidelines conflict, choose the most appropriate one
- Do not blindly follow all guidelines
'''
```

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

## 6. Agent Integration

Each agent should: 1. Fetch its guidelines 2. Build prompt using
template 3. Execute LLM call

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

## 7. Priority Handling

-   Sort by `priority DESC`
-   Higher priority appears first in prompt
-   LLM naturally biases toward earlier instructions

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

## 8. Edge Cases & Handling

### 1. Conflicting Guidelines

Example: - "Use bar chart" - "Use line chart"

**Handling:** - Let LLM decide based on context - Add instruction:
"choose most appropriate"

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

### 2. Too Many Guidelines

Problem: - Prompt becomes noisy

Solution: - Limit to top 5 guidelines - (Future) Add summarization layer

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

### 3. Irrelevant Guidelines

Problem: - Guidelines unrelated to query

Solution: - Prompt instruction: "apply only when relevant"

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

### 4. Vague Guidelines

Example: - "Make output better"

Problem: - Low signal

Solution: - Add validation in UI (future) - Or allow but expect weak
effect

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

### 5. Duplicate Guidelines

Solution: - Deduplicate at insertion or fetch stage

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

### 6. Empty Guidelines

Solution: - Skip injection - Use base prompt only

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

### 7. Overpowering Guidelines

Problem: - Guidelines override core logic incorrectly

Solution: - Keep base prompt strong - Add instruction: "Do not violate
core responsibilities"

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

### 8. Latency Impact

Problem: - DB fetch per agent call

Solution: - Cache guidelines per agent (Redis / in-memory)

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

## 9. Future Enhancements

-   Add tags (intent, domain)
-   Add embeddings for semantic filtering
-   Add guideline summarization layer
-   Add conflict detection system
-   Add explainability ("which guideline was used")

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

## 10. Summary

This system provides: - Flexible behavioral control - No schema
dependency - Fast iteration for trainers

Trade-offs: - Less deterministic - Relies on LLM reasoning

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

## 11. Key Design Principle

> "Let the LLM decide relevance, not the system"

This keeps the system simple and scalable for early-stage development.