Skip to main content

Overview

Build an autonomous agent that connects to GitHub, analyzes repository data — issues, pull requests, commit activity — and generates structured reports in your workspace.

Prerequisites

Environment Variables

# .env
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
ANTHROPIC_API_KEY=your-anthropic-key-here

Installation

# With uv (recommended)
uv pip install upsonic python-dotenv

# With pip
pip install upsonic python-dotenv

Example: Repository Issue Analysis

The agent fetches open issues from a data science repository, categorizes them by label, and writes a summary report to the workspace.
import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

github_handler = MCPHandler(
    command="npx -y @modelcontextprotocol/server-github",
    env={
        "GITHUB_PERSONAL_ACCESS_TOKEN": os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN")
    },
    timeout_seconds=60,
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./reports",
)

task = Task(
    description="""
    Fetch the open issues from 'pandas-dev/pandas' repository (per_page=10).
    Categorize each issue by label (bug, enhancement, etc.) and write
    a short summary report to 'pandas_issues_report.md'.
    """,
    tools=[github_handler],
)

agent.print_do(task)
Generated output in ./reports/pandas_issues_report.md:
# Pandas Open Issues Report

## Issue Summary
Total issues analyzed: 10

## By Category
| Label       | Count |
|-------------|-------|
| Bug         | 4     |
| Enhancement | 3     |
| Docs        | 2     |
| Regression  | 1     |

## Issue Details
| #     | Title                          | Labels      |
|-------|--------------------------------|-------------|
| 12345 | DataFrame.merge produces ...   | Bug         |
| ...   | ...                            | ...         |

Example: Compare Contributor Activity

The agent fetches recent commits from a repository and summarizes contributor activity.
import os
from dotenv import load_dotenv
from upsonic import AutonomousAgent, Task
from upsonic.tools.mcp import MCPHandler

load_dotenv()

github_handler = MCPHandler(
    command="npx -y @modelcontextprotocol/server-github",
    env={
        "GITHUB_PERSONAL_ACCESS_TOKEN": os.getenv("GITHUB_PERSONAL_ACCESS_TOKEN")
    },
    timeout_seconds=60,
)

agent = AutonomousAgent(
    model="anthropic/claude-sonnet-4-6",
    workspace="./reports",
)

task = Task(
    description="""
    Fetch the last 30 commits from 'scikit-learn/scikit-learn' and write
    a contributor activity summary to 'sklearn_contributors.md' with
    a table of authors ranked by commit count.
    """,
    tools=[github_handler],
)

agent.print_do(task)

Available Tools

The GitHub MCP server exposes tools including:
ToolDescription
list_issuesList issues in a repository
create_issueCreate a new issue
get_pull_requestGet PR details and diff
search_repositoriesSearch for repositories
get_file_contentsRead file contents from a repo
list_commitsList recent commits

Security Notes

  • Use a fine-grained personal access token with only the permissions your agent needs.
  • Store your token in .env — never hardcode it.
  • For production, use GitHub Apps with scoped installation tokens instead of personal access tokens.