Skip to content

LesterThomas/GitHub-AI-Agent

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

53 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

GitHub AI Agent

An AI Agent built with LanGraph ReAct pattern that can retrieve GitHub issues and automatically generates GitHub pull requests with relevant content. The agent has a configurable System Prompt and configurable set of tools (via MCP). The idea is to create multiple agent instances, each with its own GitHub profile and a different set of tools. This mechanism is an ideal way to interact asynchronously with multiple AI Assistants, whilst maintaining a strong human-in-the-loop oversight.

This work is experimental and not suitable for production use

Features

  • LanGraph ReAct Agent: Uses LanGraph's pre-built ReAct agent for intelligent issue processing
  • GitHub Integration: Polls for issues with specific labels and creates pull requests
  • Configurable: Environment-based configuration for easy deployment
  • UV Package Manager: Modern Python package management with UV
  • Type Safety: Full type hints and Pydantic-based configuration

Architecture

The agent follows LanGraph best practices and consists of:

  1. Configuration Management (config.py): Pydantic-based settings
  2. GitHub Client (github_client.py): GitHub API integration
  3. LanGraph Agent (agent.py): ReAct agent for issue processing
  4. Main Application (main.py): Orchestration and polling logic

Requirements

  • Python 3.12+
  • UV package manager
  • GitHub API token
  • OpenAI API key

Installation

  1. Install UV (if not already installed):

    pip install uv
  2. Clone and setup the project:

    git clone https://github.com/LesterThomas/GitHub-AI-Agent.git
    cd GitHub-AI-Agent
    uv sync
  3. Configure environment:

    cp .env.example .env
    # Edit .env with your actual API keys and settings
  4. Configure MCP servers (optional):

    cp mcp_config.example.json mcp_config.json
    # Edit mcp_config.json to configure your MCP servers

Configuration

Create a .env file with the following variables:

# GitHub Settings
GITHUB_TOKEN=your_github_token_here
TARGET_OWNER=LesterThomas
TARGET_REPO=SAAA
ISSUE_LABEL=AI Agent

# OpenAI Settings
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4

# Agent Settings
POLL_INTERVAL=300
MAX_ITERATIONS=10

# Logging
LOG_LEVEL=INFO

Configuration Options

Environment Variables

Variable Default Description
GITHUB_TOKEN optional GitHub personal access token for human user (used by reset script)
GITHUB_AI_AGENT_TOKEN required GitHub personal access token for AI Agent persona
TARGET_OWNER LesterThomas Owner of the target repository where files are created
TARGET_REPO SAAA Name of the target repository for file creation
ISSUE_LABEL AI Agent Label to filter issues for processing
OPENAI_API_KEY required OpenAI API key for LLM access
OPENAI_MODEL gpt-4o-mini OpenAI model to use (gpt-4, gpt-4o-mini, etc.)
POLL_INTERVAL 300 Polling interval in seconds (5 minutes)
MAX_ITERATIONS 20 Maximum ReAct agent iterations
RECURSION_LIMIT 50 Maximum LanGraph recursion limit
LOG_LEVEL INFO Logging level (DEBUG, INFO, WARNING, ERROR)

Agent Configuration

The agent can be configured for different scenarios:

# High-frequency polling for development
POLL_INTERVAL=60  # 1 minute

# Production stability settings
MAX_ITERATIONS=20
RECURSION_LIMIT=50

# Debug mode with verbose logging
LOG_LEVEL=DEBUG

API Key Setup

GitHub Tokens

The application uses two separate GitHub tokens:

AI Agent Token (Required)

  1. Go to GitHub Settings β†’ Developer settings β†’ Personal access tokens
  2. Generate a new token with repo permissions for the AI Agent persona
  3. Add to .env as GITHUB_AI_AGENT_TOKEN=your_ai_agent_token_here

Human User Token (Optional)

  1. Generate a separate token for human user operations (reset script)
  2. Add to .env as GITHUB_TOKEN=your_human_token_here

OpenAI API Key

  1. Visit https://platform.openai.com/api-keys
  2. Create a new API key
  3. Add to .env as OPENAI_API_KEY=your_key_here

Usage

Single Run

Process all current issues once:

uv run python main.py

Daemon Mode

Run continuously, polling for new issues:

uv run python main.py --daemon

Using the installed script

After installation, you can also use:

uv run github-ai-agent          # Single run
uv run github-ai-agent --daemon # Daemon mode

Example Usage Patterns

Issue Examples

The agent can process various types of file creation requests:

1. Simple File Creation

Issue: "Create a new file TEST.md and write in it 'this is a test'"

Agent Response:

[{
  "filename": "TEST.md",
  "file_content": "this is a test"
}]

2. Multiple Files

Issue: "Create README.md with project info and setup.py with basic configuration"

Agent Response:

[
  {
    "filename": "README.md",
    "file_content": "# Project\n\nProject information here..."
  },
  {
    "filename": "setup.py", 
    "file_content": "from setuptools import setup\n\nsetup(...)..."
  }
]

3. Structured Content

Issue: "Create a file describing Cardiff with sections about history, attractions, and demographics"

Agent Response: Creates a well-structured markdown file with appropriate sections and content.

Workflow Example

  1. Create Issue: Add issue with "AI Agent" label in source repository
  2. Agent Detection: Agent polls and detects new issue within 5 minutes
  3. Branch Creation: Immediately creates ai-agent/issue-123 in SAAA repository
  4. Processing: ReAct agent analyzes and creates file specification
  5. File Creation: Commits requested files to the existing branch
  6. PR Creation: Opens pull request with metadata and links
  7. Issue Update: Comments on original issue with PR link

How It Works

The agent operates across two repositories:

  1. Source Repository: Where issues are created and monitored
  2. Target Repository: SAAA repository where files are created and PRs are made

Processing Flow

  1. Issue Detection: Continuously polls the source repository for issues labeled "AI Agent"
  2. Branch Creation: Immediately creates a feature branch in the SAAA repository
  3. Content Analysis: The LanGraph ReAct agent analyzes the issue using the system prompt
  4. File Operations: Agent uses repository tools and MCP tools to create/modify files directly in GitHub
  5. Commit & Branch: Files are committed directly to the pre-created feature branch
  6. Pull Request: Opens a PR in SAAA repository linking back to the original issue
  7. Issue Update: Comments on the original issue with the PR link

Agent State Management

The agent maintains state using LanGraph's AgentState:

class AgentState(TypedDict):
    messages: Annotated[List[BaseMessage], add_messages]  # Conversation history
    issue_data: Dict[str, Any]                            # Issue metadata
    generated_content: Optional[str]                      # Generated content
    branch_name: Optional[str]                            # Feature branch name
    pr_created: bool                                      # PR creation status

Logging and Monitoring

The agent provides comprehensive logging with:

  • Color-coded output for different action types (Agent, LLM, Tool, Error)
  • State tracking at each step of the workflow
  • Tool usage logging with input/output capture
  • Error handling with detailed error messages and recovery strategies

Agent Design and Workflow

System Architecture

The agent uses LanGraph's ReAct (Reasoning and Acting) pattern with the following components:

  1. LanGraph ReAct Agent: Pre-built agent that combines reasoning with tool usage
  2. Single Tool Design: Focused on file creation using one specialized tool
  3. State Management: Typed state management with conversation persistence
  4. Enhanced Logging: Comprehensive logging with color-coded output for debugging

System Prompt

The agent uses a comprehensive system prompt that is now configured in the prompts.yaml file for easy maintenance and updates. The system prompt guides the agent's behavior and includes:

  • Role Definition: AI agent for processing GitHub issues and managing repository files
  • Capabilities: Reading repository structure, file contents, creating and editing files
  • Available Tools: Detailed descriptions of list_files_in_repo, read_file_from_repo, create_file_in_repo, and edit_file_in_repo
  • Workflow Examples: Step-by-step guidance for different types of tasks
  • Analysis Instructions: Guidelines for determining work needed and best practices

Configuration Management: All prompts (system prompt, human message templates, and tool descriptions) are now stored in prompts.yaml for:

  • Easy updates without code changes
  • Better separation of configuration from code
  • Centralized prompt management
  • Version control of prompt changes

The system prompt automatically includes the target repository information ({target_owner}/{target_repo}) when loaded.

Tool Description

The agent has access to four specialized tools for comprehensive file management:

create_files_from_request

Purpose: Create files directly in GitHub repository from a JSON array of file objects

Input Format:

[
  {
    "filename": "test.md", 
    "file_content": "# Test File\n\nThis is a test file content."
  },
  {
    "filename": "readme.txt",
    "file_content": "This is a readme file."
  }
]

Output: JSON status report of the file creation operation

{
  "success": true,
  "files_created": ["test.md", "readme.txt"],
  "files_count": 2,
  "errors": null
}

list_files_in_repo

Purpose: Browse repository structure by listing files and directories

Usage: list_files_in_repo(path="", branch="main")

  • path: Directory path to list (empty string for root)
  • branch: Branch name (defaults to 'main')

Output: JSON with repository contents

{
  "success": true,
  "path": "",
  "contents": [
    {"name": "README.md", "type": "file", "size": 2048},
    {"name": "src", "type": "dir", "size": null}
  ]
}

read_file_from_repo

Purpose: Read the content of specific files from the repository

Usage: read_file_from_repo(file_path, branch="main")

  • file_path: Path to the file in the repository
  • branch: Branch name (defaults to 'main')

Output: JSON with file content

{
  "success": true,
  "file_path": "README.md",
  "content": "# Project\n\nDescription here...",
  "length": 156
}

edit_file_in_repo

Purpose: Edit existing files or create new ones with custom commit messages

Usage: edit_file_in_repo(file_path, file_content, commit_message="", branch="")

  • file_path: Path to the file in the repository
  • file_content: New content for the file
  • commit_message: Optional commit message
  • branch: Branch name (defaults to current working branch)

Output: JSON status report

{
  "success": true,
  "file_path": "config.json",
  "commit_message": "Update configuration",
  "content_length": 245
}

These tools enable the agent to:

  • Explore repository structure before making changes
  • Read existing files to understand current codebase
  • Create new files with specified content
  • Edit existing files with proper version control

Complete Workflow

The agent follows this detailed workflow from GitHub issue polling to PR creation:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚   1. POLLING    β”‚ -> β”‚  2. ISSUE FETCH  β”‚ -> β”‚ 3. BRANCH       β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚    CREATION     β”‚
β”‚ β€’ Poll GitHub   β”‚    β”‚ β€’ Get issue data β”‚    β”‚                 β”‚
β”‚   repository    β”‚    β”‚ β€’ Extract title  β”‚    β”‚ β€’ Create        β”‚
β”‚ β€’ Filter by     β”‚    β”‚ β€’ Extract body   β”‚    β”‚   feature       β”‚
β”‚   "AI Agent"    β”‚    β”‚ β€’ Get metadata   β”‚    β”‚   branch        β”‚
β”‚   label         β”‚    β”‚                  β”‚    β”‚ β€’ ai-agent/     β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚   issue-{num}   β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         |                       |                       |
         v                       v                       v
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ 4. AGENT SETUP  β”‚ -> β”‚ 5. REACT AGENT   β”‚ -> β”‚ 6. TOOL         β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚    EXECUTION    β”‚
β”‚ β€’ Create system β”‚    β”‚ β€’ LLM reasoning  β”‚    β”‚                 β”‚
β”‚   message       β”‚    β”‚ β€’ Plan actions   β”‚    β”‚ β€’ Execute       β”‚
β”‚ β€’ Create human  β”‚    β”‚ β€’ Generate tool  β”‚    β”‚   create_files_ β”‚
β”‚   message       β”‚    β”‚   calls          β”‚    β”‚   from_request  β”‚
β”‚ β€’ Set up state  β”‚    β”‚                  β”‚    β”‚ β€’ Validate JSON β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚ β€’ Return resultsβ”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         |                       |                       |
         v                       v                       v
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ 6. TOOL         β”‚ -> β”‚ 7. STATUS CHECK  β”‚ -> β”‚ 8. PULL REQUEST β”‚
β”‚    EXECUTION    β”‚    β”‚                  β”‚    β”‚                 β”‚
β”‚                 β”‚    β”‚ β€’ Check tool     β”‚    β”‚ β€’ Create PR     β”‚
β”‚ β€’ Execute       β”‚    β”‚   results        β”‚    β”‚   in SAAA repo  β”‚
β”‚   create_files_ β”‚    β”‚ β€’ Verify files   β”‚    β”‚ β€’ Link to issue β”‚
β”‚   from_request  β”‚    β”‚   created        β”‚    β”‚ β€’ Add metadata  β”‚
β”‚ β€’ Create files  β”‚    β”‚ β€’ Fallback if    β”‚    β”‚                 β”‚
β”‚   directly in   β”‚    β”‚   needed         β”‚    β”‚                 β”‚
β”‚   GitHub        β”‚    β”‚                  β”‚    β”‚                 β”‚
β”‚ β€’ Return status β”‚    β”‚                  β”‚    β”‚                 β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
         |                       |                       |
         v                       v                       v
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚ 9. ISSUE        β”‚ -> β”‚ 10. LOGGING &    β”‚ -> β”‚ 11. COMPLETION  β”‚
β”‚    COMMENT      β”‚    β”‚     TRACKING     β”‚    β”‚                 β”‚
β”‚                 β”‚    β”‚                  β”‚    β”‚ β€’ Mark issue    |
β”‚ β€’ Add comment   β”‚    β”‚ β€’ Color-coded    β”‚    β”‚   as processed  |
β”‚   with PR link  β”‚    β”‚   console logs   β”‚    β”‚ β€’ Return        |
β”‚ β€’ Close or      β”‚    β”‚ β€’ State tracking β”‚    β”‚   success       |
β”‚   reference     β”‚    β”‚ β€’ Error handling β”‚    β”‚   status        |
β”‚   issue         β”‚    β”‚                  β”‚    β”‚                 |
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Detailed Step Breakdown

1-3. Polling, Issue Detection & Branch Creation

  • Frequency: Every 5 minutes (configurable via POLL_INTERVAL)
  • Filter: Issues with "AI Agent" label in the configured repository
  • State: Tracks processed issues to avoid duplication
  • Early Branch: Creates feature branch immediately upon issue detection

4-6. Agent Initialization, Reasoning & Tool Execution

  • LLM Model: GPT-4o-mini (configurable via OPENAI_MODEL)
  • ReAct Pattern: Uses LanGraph's built-in ReAct agent with MemorySaver checkpointing
  • Reasoning: Analyzes issue requirements and plans file operations
  • Repository Tools: 5 comprehensive tools for repository management:
    • create_file_in_repo: Create new files in the target repository
    • edit_file_in_repo: Modify existing files
    • read_file_from_repo: Read file contents for context
    • list_files_in_repo: Explore repository structure
    • delete_file_from_repo: Remove files when needed
  • MCP Tools: Additional tools from configured MCP servers (filesystem, GitHub, etc.)
  • Tool Integration: MCP tools are seamlessly integrated alongside repository tools
  • Direct Creation: Files are created immediately in GitHub with proper commit messages

7-8. Status Check & Pull Request Creation

  • Target Repository: SAAA repository (separate from issue source)
  • Branch Strategy: Uses pre-created feature branch ai-agent/issue-{number}
  • File Creation: Tool creates files directly via GitHub API with proper commit messages
  • PR Creation: Automated pull request with detailed metadata
  • Error Handling: Comprehensive error handling with fallbacks

9-11. Issue Management & Completion

  • Issue Linking: Comments on original issue with PR link
  • Status Tracking: Maintains processed issue list
  • Logging: Comprehensive state logging for debugging and monitoring

Development

Running Tests

uv run pytest

Code Formatting

uv run black .
uv run isort .

Type Checking

uv run mypy github_ai_agent

Project Structure

GitHub-AI-Agent/
β”œβ”€β”€ github_ai_agent/           # Main package
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ agent.py              # LanGraph ReAct agent implementation
β”‚   β”‚                         # - GitHubIssueAgent class (1,152 lines)
β”‚   β”‚                         # - AgentState and IssueProcessingResult data classes
β”‚   β”‚                         # - 5 repository management tools
β”‚   β”‚                         # - Comprehensive error handling and logging
β”‚   β”‚                         # - MCP client integration for external tools
β”‚   β”œβ”€β”€ mcp_client.py         # MCP client implementation (580+ lines)
β”‚   β”‚                         # - MCPClient, MCPServerConfig, MCPTool classes
β”‚   β”‚                         # - MCP server process management
β”‚   β”‚                         # - Tool discovery and LangChain integration
β”‚   β”‚                         # - Mock implementations for filesystem/GitHub servers
β”‚   β”œβ”€β”€ config.py             # Pydantic settings management (120 lines)
β”‚   β”‚                         # - Environment-based configuration
β”‚   β”‚                         # - YAML prompt loading and templating
β”‚   β”‚                         # - Type-safe settings validation
β”‚   β”œβ”€β”€ github_client.py      # GitHub API integration (1,000+ lines)
β”‚   β”‚                         # - Multi-authentication support (tokens, GitHub App)
β”‚   β”‚                         # - Full CRUD operations for repositories
β”‚   β”‚                         # - Advanced PR and issue management
β”‚   β”œβ”€β”€ logging_utils.py      # Enhanced logging utilities (247 lines)
β”‚   β”‚                         # - ANSI color coding for different log types
β”‚   β”‚                         # - Structured logging for debugging
β”‚   β”‚                         # - Pretty JSON formatting
β”‚   └── main.py               # Application orchestration (500+ lines)
β”‚                             # - GitHubAIAgentApp class
β”‚                             # - Polling and issue detection logic
β”‚                             # - Daemon and single-run modes
β”œβ”€β”€ tests/                    # Test suite
β”‚   β”œβ”€β”€ __init__.py
β”‚   β”œβ”€β”€ test_basic.py         # Basic functionality tests
β”‚   β”œβ”€β”€ test_mcp_client.py    # MCP client functionality tests
β”‚   β”œβ”€β”€ test_pr_comments.py   # PR comment processing tests
β”‚   └── test_prompt_config.py # Configuration and prompt tests
β”œβ”€β”€ main.py                   # CLI entry point
β”œβ”€β”€ prompts.yaml              # YAML configuration for all prompts
β”œβ”€β”€ mcp_config.json           # MCP server configuration (user-created)
β”œβ”€β”€ mcp_config.example.json   # Example MCP configuration
β”œβ”€β”€ pyproject.toml            # Project configuration & dependencies
β”œβ”€β”€ uv.lock                   # Dependency lock file
β”œβ”€β”€ .env.example              # Environment template
β”œβ”€β”€ README.md                 # This file
└── LICENSE                   # Apache 2.0 license

Key Files

  • agent.py: Contains the GitHubIssueAgent class with comprehensive ReAct implementation
    • Well-documented classes: AgentState, IssueProcessingResult, GitHubIssueAgent
    • Comprehensive tool management with 5 repository operation tools + MCP integration
    • MCP client for external tool integration with automatic discovery
    • Robust error handling and state management
    • Streaming execution support with fallback to invoke mode
  • github_client.py: Handles all GitHub API operations (issues, PRs, files, authentication)
    • Supports multiple authentication methods (Personal tokens, GitHub App)
    • Comprehensive CRUD operations for repository management
    • Advanced features like PR comment monitoring and issue processing state tracking
  • config.py: Pydantic-based configuration with environment variable loading
    • Type-safe settings management with validation
    • YAML-based prompt configuration system
    • Template rendering for system and human messages
  • main.py: Application entry point with daemon and single-run modes
    • Comprehensive polling and issue detection logic
    • Color-coded logging and monitoring
    • PR follow-up comment processing
  • logging_utils.py: Enhanced logging utilities with color support
    • ANSI color codes for different log types
    • Structured logging for agent actions, LLM interactions, and tool usage
    • Pretty JSON formatting and timestamps
  • prompts.yaml:
    • System, HumanMessage and tool prompts in an easy to read YAML configuration file.

LanGraph Implementation Details

This implementation follows LanGraph best practices:

1. ReAct Agent Pattern

  • Uses LanGraph's pre-built create_react_agent for reasoning and acting
  • Single-tool design for focused file creation capabilities
  • Memory persistence with MemorySaver for conversation context

2. State Management

class AgentState(TypedDict):
    messages: Annotated[List[BaseMessage], add_messages]
    issue_data: Dict[str, Any]
    generated_content: Optional[str]
    branch_name: Optional[str]
    pr_created: bool

3. Tool Definition

The agent uses five comprehensive tools for repository management:

# Repository exploration tools
Tool(name="list_files_in_repo", description="List files and directories...")
Tool(name="read_file_from_repo", description="Read file contents...")

# File management tools  
Tool(name="create_file_in_repo", description="Create new files...")
Tool(name="edit_file_in_repo", description="Modify existing files...")
Tool(name="delete_file_in_repo", description="Remove files...")

Each tool includes:

  • Pydantic input validation with structured schemas
  • Comprehensive error handling with JSON responses
  • Contextual commit messages tied to issue numbers
  • Branch-aware operations with proper state management

4. Error Handling & Streaming

  • Comprehensive error handling with fallback strategies
  • Stream execution with multiple modes: ["values", "updates", "debug"]
  • State logging at each execution step

5. LLM Integration

  • Custom OpenAI integration with enhanced request/response logging
  • Configurable models (default: GPT-4o-mini for cost efficiency)
  • Temperature set to 0.1 for consistent, predictable outputs
  • Comprehensive message handling for different LangChain message types

Code Quality and Best Practices

Documentation Standards

  • Comprehensive Docstrings: All classes and methods follow Google/Sphinx documentation style
  • Type Annotations: Complete type hints throughout the codebase using modern Python typing
  • Module Documentation: Each module includes detailed purpose and usage information
  • Inline Comments: Strategic commenting for complex logic and business rules

Architecture Patterns

  • Separation of Concerns: Clean module boundaries with specific responsibilities
  • Configuration Management: Centralized settings using Pydantic with environment variable support
  • Error Handling: Robust exception handling with comprehensive logging
  • State Management: Immutable state patterns using TypedDict and LangGraph reducers

Code Organization

  • Import Structure: Well-organized imports following PEP 8 guidelines
  • Class Design: Single responsibility principle with clear inheritance patterns
  • Method Structure: Logical grouping with clear public/private interfaces
  • Data Classes: Proper use of dataclasses and TypedDict for structured data

Testing and Quality Assurance

  • Test Coverage: Basic test suite with mock-based unit tests
  • Development Tools: Black, isort, mypy configured for code quality
  • Type Safety: MyPy configuration for strict type checking
  • Modern Python: Requires Python 3.12+ with modern language features

Debugging and Monitoring

Log Output Format

The agent provides comprehensive color-coded logging for easy monitoring:

  • πŸ€– AGENT: Agent actions and state changes (cyan)
  • 🧠 LLM: LLM requests and responses with structured formatting (green)
  • οΏ½ TOOL: Tool executions with input/output details (pink/magenta)
  • οΏ½ GITHUB: GitHub API operations and authentication (orange)
  • βœ… SUCCESS: Successful operations (bright green)
  • ❌ ERROR: Error conditions and exceptions (red)
  • ⚠️ WARNING: Warning messages (orange)
  • ℹ️ INFO: General information (light blue)

Enhanced Logging Features

  • Structured JSON Output: Pretty-printed JSON for complex data structures
  • Message Truncation: Long messages are intelligently truncated for readability
  • Contextual Icons: Different icons for different types of operations
  • Timestamp Precision: HH:MM:SS format for easy chronological tracking
  • Visual Separators: Clean separation between different log sections

Debug Mode

Enable debug logging for detailed execution tracking:

# Set in .env file
LOG_LEVEL=DEBUG

# Run with enhanced logging
uv run python main.py

Debug mode provides:

  • Complete message history with conversation flow
  • State transitions at each step with detailed context
  • Tool execution details including input validation and error handling
  • LLM token usage and response timing
  • GitHub API call logs with request/response details
  • Branch and file operation tracking

Monitoring Checklist

For production deployment, monitor:

  1. Issue Processing Rate: Number of issues processed per hour
  2. Error Rates: Failed processing attempts and their causes
  3. API Limits: GitHub and OpenAI API usage and rate limits
  4. Branch Creation: Successful feature branch creation in target repo
  5. PR Success: Pull request creation and merge rates

Common Issues and Solutions

Issue Cause Solution
Authentication errors Invalid GitHub token or insufficient permissions Regenerate token with full repo permissions
Rate limiting Too frequent API calls or quota exceeded Increase POLL_INTERVAL or check API limits
OpenAI errors Invalid API key, quota, or model access Check API key, billing, and model availability
Branch creation failed Permission issues or branch already exists Ensure token has write access, check existing branches
File creation failed Path issues, permission problems, or content errors Validate file paths, check repository permissions
Tool execution failed Network issues or API timeouts Check network connectivity and GitHub status
Agent timeout Complex reasoning or infinite loops Adjust recursion_limit and max_iterations

Target Repository

This agent is designed to monitor the LesterThomas/SAAA repository for issues labeled "AI Agent" and automatically generate helpful responses.

Example Execution output

uv run python main.py
════════════════════════════════════════════════════════════════════════════════
πŸ€– GITHUB AI AGENT - Automated Issue Processing
════════════════════════════════════════════════════════════════════════════════
════════════════════════════════════════════════════════════
🎯 GITHUB AI AGENT INITIALIZATION
────────────────────────────────────────────────────────────
[23:04:18] ℹ️ Target: LesterThomas/SAAA
[23:04:18] ℹ️ Label filter: 'AI Agent'
[23:04:18] ℹ️ AI Model: gpt-4o-mini
[23:04:18] ℹ️ Max iterations: 20
[23:04:18] πŸ™ Authenticated via AI Agent Token
[23:04:19] πŸ€– Initializing GitHub Issue Agent
[23:04:19] πŸ€– Model: gpt-4o-mini, Max iterations: 20
[23:04:19] πŸ€– Recursion limit: 50
[23:04:19] πŸ€– Target SAAA repository: LesterThomas/SAAA
[23:04:19] πŸ€– Created 1 tools: ['create_files_from_request']
[23:04:19] πŸ€– ReAct agent created successfully
────────────────────────────────────────────────────────────────────────────────
════════════════════════════════════════════════════════════
🎯 SINGLE RUN MODE
────────────────────────────────────────────────────────────
════════════════════════════════════════════════════════════
🎯 SCANNING FOR ISSUES
────────────────────────────────────────────────────────────
[23:04:19] ℹ️ Looking for issues labeled 'AI Agent'
[23:04:19] ℹ️ Discovered 1 unprocessed issues
────────────────────────────────────────────────────────────────────────────────
════════════════════════════════════════════════════════════
🎯 PROCESSING ISSUE #91 TITLE: CREATE TEST.MD
────────────────────────────────────────────────────────────
[23:04:19] πŸ™ Creating branch 'ai-agent/issue-91'
[23:04:19] πŸ™ Creating branch 'ai-agent/issue-91' in LesterThomas/SAAA from 'main'
[23:04:21] πŸ™ Successfully created branch 'ai-agent/issue-91' in LesterThomas/SAAA
[23:04:21] πŸ™ Branch 'ai-agent/issue-91' created successfully
[23:04:21] πŸ€– Starting to process issue #91
[23:04:21] πŸ€– Fetching issue #91 from GitHub
[23:04:21] πŸ€– Successfully fetched issue #91: Create TEST.md
[23:04:21] πŸ€– Issue data prepared - Title: Create TEST.md, User: LesterThomas, Labels: ['AI Agent']
[23:04:21] πŸ€– Creating system and human messages
[23:04:21] πŸ€– Messages created, preparing to invoke agent
[23:04:21] πŸ€– Invoking ReAct agent with thread_id: issue-91, recursion_limit: 50
[23:04:21] 🧠 values (HumanMessage)
    Process this GitHub issue:

    Issue #91: Create TEST.md

    Description: Create a TEST.md markdown file and in the content of the file make up a poem about clouds.

    Analyze the issue and use create_files_from_request with a JSON array to create the requested files.

    Example format:
    [
      {
        "filename": "example.md",
        "file_content": "# Example\n\nThis is example content."
      }
    ]

    Use the create_files_from_request tool with proper JSON formatting.
──────────────────────────────────────────────────
[23:04:25] 🧠 values (AIMessage)
    Tool Calls:
      1. **create_files_from_request**
         Args: {
      "__arg1": "[{\"filename\": \"TEST.md\", \"file_content\": \"# Clouds\n\nIn the sky so high and bright,  \nFluffy clouds take their flight.  \nWhispers of white, drifting slow,  \nPainting the blue with a gentle glow.  \n\nSome are like cotton, soft and sweet,  \nOthers like shadows, a cool retreat.  \nThey dance and twirl, a graceful ballet,  \nChanging their shapes throughout the day.  \n\nWhen the sun sets, they catch the light,  \nA canvas of colors, a breathtaking sight.  \nOh, how they wander, free and proud,  \nA beautiful mystery, the ever-changing cloud.\"}]}"
    }
──────────────────────────────────────────────────
[23:04:25] πŸ”§ TOOL create_files_from_request [{"filename": "TEST.md", "file_content": "# Clouds

In the sky so high and bright,
Fluffy cloud...
[23:04:25] ❌ TOOL create_files_from_request Invalid JSON format: Invalid control character at: line 1 column 51 (char 50)
[23:04:25] 🧠 values (ToolMessage)
    {"success": false, "error": "Invalid JSON format: Invalid control character at: line 1 column 51 (char 50)", "files_created": []}
──────────────────────────────────────────────────
[23:04:28] 🧠 values (AIMessage)
    Tool Calls:
      1. **create_files_from_request**
         Args: {
      "__arg1": "[{\"filename\": \"TEST.md\", \"file_content\": \"# Clouds\\n\\nIn the sky so high and bright,  \\nFluffy clouds take their flight.  \\nWhispers of white, drifting slow,  \\nPainting the blue with a gentle glow.  \\n\\nSome are like cotton, soft and sweet,  \\nOthers like shadows, a cool retreat.  \\nThey dance and twirl, a graceful ballet,  \\nChanging their shapes throughout the day.  \\n\\nWhen the sun sets, they catch the light,  \\nA canvas of colors, a breathtaking sight.  \\nOh, how they wander, free and proud,  \\nA beautiful mystery, the ever-changing cloud.\"}]"
    }
──────────────────────────────────────────────────
[23:04:28] πŸ”§ TOOL create_files_from_request [{"filename": "TEST.md", "file_content": "# Clouds\n\nIn the sky so high and bright,  \nFluffy cloud...
[23:04:28] πŸ€– Creating file TEST.md in SAAA repository on branch ai-agent/issue-91
[23:04:28] πŸ™ Creating/updating file 'TEST.md' in LesterThomas/SAAA on branch 'ai-agent/issue-91'
[23:04:29] πŸ™ Created file 'TEST.md' in LesterThomas/SAAA
[23:04:29] πŸ€– Successfully created file: TEST.md
[23:04:29] πŸ”§ TOOL create_files_from_request Created 1 files directly in GitHub
[23:04:29] 🧠 values (ToolMessage)
    {
      "success": true,
      "files_created": [
        "TEST.md"
      ],
      "files_count": 1,
      "errors": null
    }
──────────────────────────────────────────────────
[23:04:30] 🧠 values (AIMessage)
    Created the file **TEST.md** with a poem about clouds.
──────────────────────────────────────────────────
[23:04:30] πŸ€– Agent execution completed after 6 steps
[23:04:30] πŸ€– Generated content length: 54 characters
[23:04:30] πŸ€– Total files created by tool: 1
[23:04:30] πŸ€– Files created successfully: ['TEST.md']
[23:04:30] πŸ€– Describing file: TEST.md
[23:04:30] πŸ€– File description for TEST.md: Test markdown file with example content
[23:04:30] πŸ€– Creating pull request to SAAA repository: Create TEST.md as requested in issue #91
[23:04:30] πŸ™ Creating pull request in LesterThomas/SAAA: 'Create TEST.md as requested in issue #91'
[23:04:30] πŸ™ PR details - Head: ai-agent/issue-91, Base: main, Draft: False
[23:04:31] πŸ™ Successfully created pull request #92 in LesterThomas/SAAA: Create TEST.md as requested in issue #91
[23:04:31] πŸ™ Pull request URL: https://github.com/LesterThomas/SAAA/pull/92
[23:04:31] πŸ€– Successfully created pull request #92 in SAAA repository
[23:04:31] πŸ€– Pull request URL: https://github.com/LesterThomas/SAAA/pull/92
[23:04:31] πŸ€– Adding comment to issue #91
[23:04:33] πŸ™ Added comment to issue #91
[23:04:33] πŸ€– Issue #91 processed successfully - created PR in SAAA repository
[23:04:33] πŸ™ Issue completed! Created PR #92
────────────────────────────────────────────────────────────────────────────────
[23:04:33] ℹ️ Single run completed

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages