first commit
This commit is contained in:
298
docs/agents.md
Normal file
298
docs/agents.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# 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())
|
||||
```
|
||||
Reference in New Issue
Block a user