openrabbit/docs/agents.md

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:

## 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:

## 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:

# 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

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

# 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:

**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:

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:

from dispatcher import get_dispatcher
from agents import CustomAgent

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