# Agents Documentation

The AI Code Review system includes four specialized agents.

## Issue Agent

Handles issue triage, classification, and interaction.

### Triggers

- `issues.opened` - New issue created (handled by `run_issue_triage`)
- `issues.labeled` - Label added to issue
- `issue_comment.created` - Comment with @mention (handled by `run_issue_comment`)

### Features

**Automatic Triage:**
- Classifies issue type: bug, feature, question, documentation, support
- Assigns priority: high, medium, low
- Calculates confidence score

**Auto-Labeling:**
- Applies type labels (`type: bug`, etc.)
- Applies priority labels (`priority: high`, etc.)
- Adds `ai-reviewed` status label

**@Mention Commands:**

| Command | Description |
|---------|-------------|
| `@ai-bot summarize` | Generate concise summary |
| `@ai-bot explain` | Detailed explanation |
| `@ai-bot suggest` | Solution suggestions |

### Output

Posts a triage comment:

```markdown
## AI Issue Triage

| Field | Value |
|-------|--------|
| **Type** | Bug |
| **Priority** | High |
| **Confidence** | 85% |

### Additional Information Needed

- Steps to reproduce
- Error logs

---
*Classification based on issue content*
```

---

## PR Agent

Comprehensive pull request review with security scanning.

### Triggers

- `pull_request.opened` - New PR created
- `pull_request.synchronize` - PR updated with new commits

### Features

**AI Code Review:**
- Analyzes diff for issues
- Categorizes: Security, Correctness, Performance, Maintainability
- Assigns severity: HIGH, MEDIUM, LOW

**Inline Comments:**
- Posts comments on specific lines
- Links to file and line number
- Provides recommendations

**Security Scanning:**
- 17 OWASP-aligned rules
- Detects hardcoded secrets, SQL injection, XSS
- Fails CI on HIGH severity

**Label Management:**
- `ai-approved` - No blocking issues
- `ai-changes-required` - HIGH severity issues found

### Output

Posts summary comment:

```markdown
## AI Code Review

Review of changes in this PR.

### Summary

| Severity | Count |
|----------|-------|
| HIGH | 1 |
| MEDIUM | 2 |
| LOW | 3 |

### Security Issues

- **[HIGH]** `src/auth.py:45` - Hardcoded API key detected

### Review Findings

- **[MEDIUM]** `src/db.py:12` - SQL query uses string formatting
- **[LOW]** `src/utils.py:30` - Missing docstring

---
**Overall Severity:** `HIGH`
**AI Recommendation:** Changes Requested
```

---

## Codebase Agent

Repository-wide quality and health analysis.

### Triggers

- `schedule` - Cron schedule (default: weekly)
- `workflow_dispatch` - Manual trigger
- `@ai-bot codebase` - Comment command

### Features

**Metrics Collection:**
- Total files and lines of code
- Language distribution
- TODO/FIXME/DEPRECATED counts

**AI Analysis:**
- Overall health score (0-100)
- Architecture observations
- Technical debt identification
- Improvement recommendations

### Output

Creates/updates report issue:

```markdown
# AI Codebase Quality Report

## Health Score: 72/100

The codebase is in reasonable condition with some areas for improvement.

---

## Metrics

| Metric | Value |
|--------|-------|
| Total Files | 45 |
| Total Lines | 12,500 |
| TODO Comments | 23 |
| FIXME Comments | 8 |

### Languages

- **Python**: 35 files
- **JavaScript**: 10 files

## Issues Found

### [MEDIUM] Code Quality
Missing docstrings in 15 functions.
**Recommendation:** Add docstrings for public functions.

## Recommendations

1. Add comprehensive test coverage
2. Document API endpoints
3. Reduce TODO backlog
```

---

## Chat Agent (Bartender)

Interactive AI chat assistant with tool-calling capabilities.

### Triggers

- `issue_comment.created` - Any @ai-bot mention that isn't a specific command
- `chat` - Direct CLI invocation

### Features

**Tool Calling:**
The Chat Agent uses LLM function calling to gather information before responding:

| Tool | Description |
|------|-------------|
| `search_codebase` | Search repository files and code patterns |
| `read_file` | Read specific files from the repository |
| `search_web` | Search the web via SearXNG instance |

**Iterative Reasoning:**
- Makes up to 5 tool calls per request
- Combines information from multiple sources
- Provides comprehensive, contextual answers

**Web Search:**
- Requires SearXNG instance URL (via `SEARXNG_URL` env var or config)
- Searches for documentation, tutorials, external resources

### Configuration

```yaml
agents:
  chat:
    enabled: true
    name: "Bartender"
    max_iterations: 5
    tools:
      - search_codebase
      - read_file
      - search_web
    searxng_url: ""  # Or set SEARXNG_URL env var
```

### CLI Usage

```bash
# Simple chat
python main.py chat owner/repo "How does authentication work?"

# Chat and post response to issue
python main.py chat owner/repo "Explain this bug" --issue 123
```

### Issue Comment Usage

```
@ai-bot How do I configure rate limiting?
@ai-bot Find all files that handle user authentication
@ai-bot What does the dispatcher module do?
```

### Output

Posts a response comment:

```markdown
**Note:** This review was generated by an AI assistant...

---

Based on my analysis of the codebase, rate limiting is configured in
`tools/ai-review/config.yml` under the `enterprise.rate_limit` section:

- `requests_per_minute`: Maximum requests per minute (default: 30)
- `max_concurrent`: Maximum concurrent requests (default: 4)

The rate limiting logic is implemented in `enterprise/rate_limiter.py`...
```

---

## Agent Interface

All agents extend `BaseAgent`:

```python
from agents import BaseAgent, AgentContext, AgentResult

class CustomAgent(BaseAgent):
    def can_handle(self, event_type: str, event_data: dict) -> bool:
        # Return True if this agent handles the event
        return event_type == "custom_event"

    def execute(self, context: AgentContext) -> AgentResult:
        # Perform agent logic
        return AgentResult(
            success=True,
            message="Custom action completed",
            actions_taken=["action1", "action2"],
        )
```

Register with dispatcher:

```python
from dispatcher import get_dispatcher
from agents import CustomAgent

dispatcher = get_dispatcher()
dispatcher.register_agent(CustomAgent())
```