issue-core/examples/agents/README.md

Agent Examples

This directory contains working examples of autonomous agents using the Issue Core for coordination.

Prerequisites

1. Install issue-core:

   cd ../..
   pip install -e .
   

2. Configure backend (one-time setup):

   export GITEA_API_TOKEN="your-token"
   issue backend add myproject gitea
   # Enter: URL, owner, repo when prompted
   issue backend set-default myproject
   

3. Set environment variables for scripts:

   export GITEA_URL=https://gitea.example.com
   export GITEA_TOKEN=your-token
   export GITEA_OWNER=your-org
   export GITEA_REPO=your-repo
   

Examples

1. Simple Task Executor (simple_task_executor.py)

What it does:

• Finds open issues labeled ready
• Claims them by assigning to itself
• Simulates work
• Closes with completion comment

Usage:

# Run once
python simple_task_executor.py --once

# Run continuously
python simple_task_executor.py

# Run for N iterations
python simple_task_executor.py --max-iterations 5

Setup test data:

# Create some test issues
issue create "Test task 1" --label=ready
issue create "Test task 2" --label=ready
issue create "Test task 3" --label=ready

2. Multi-Agent Pipeline (multi_agent_pipeline.py)

What it does: Simulates a CI/CD pipeline with specialized agents:

• Coder: Implements features (needs-implementation → needs-review)
• Reviewer: Reviews code (needs-review → needs-testing)
• Tester: Runs tests (needs-testing → needs-deployment)
• Deployer: Deploys to staging (needs-deployment → deployed + closed)

Usage:

# Run all agents in round-robin (one process)
python multi_agent_pipeline.py --mode=roundrobin

# Or run each agent separately (in different terminals)
python multi_agent_pipeline.py --agent=coder
python multi_agent_pipeline.py --agent=reviewer
python multi_agent_pipeline.py --agent=tester
python multi_agent_pipeline.py --agent=deployer

Setup test data:

issue create "Feature: Add user profile" --label=feature --label=needs-implementation
issue create "Feature: Export data to CSV" --label=feature --label=needs-implementation

Watch the pipeline:

# In another terminal, watch progress
watch -n 2 'issue list --format=json | jq -r ".[] | [.number, .state, (.labels | map(.name) | join(\",\"))] | @tsv"'

3. Human-in-the-Loop (human_in_loop.py)

What it does:

• Finds large features labeled needs-breakdown
• Proposes breaking them into subtasks
• Waits for human approval via comments
• Creates subtasks only after approval

Usage:

# Run once
python human_in_loop.py --once

# Run continuously
python human_in_loop.py

Setup test data:

issue create "Feature: Implement complete authentication system" \
  --label=feature \
  --label=needs-breakdown \
  --description="Large feature that should be broken down into smaller tasks"

Approve the agent's proposal:

# Agent will post a proposal comment. You reply with:
issue comment <issue-number> "APPROVED"

# Or reject:
issue comment <issue-number> "REJECTED: Not the right approach"

# Or request modifications:
issue comment <issue-number> "MODIFY: Please add security audit as a subtask"

4. Monitoring Agent (monitoring_agent.py)

What it does:

• Monitors issue tracker health
• Detects stale issues (not updated in N days)
• Finds blocked issues
• Identifies unassigned priority issues
• Analyzes project velocity
• Creates alert issues when problems found

Usage:

# Run once (no alerts)
python monitoring_agent.py --once --no-alerts

# Run continuously with hourly checks
python monitoring_agent.py --check-interval=3600

# Run with custom stale threshold
python monitoring_agent.py --stale-days=14 --once

View monitoring output: The agent will create issues tagged with monitoring and alert when it detects problems.

Agent Coordination Patterns

Pattern 1: Label-Based Roles

Agents claim issues based on label matching:

AGENT_ROLES = {
    'agent:coder': ['feature', 'bug', 'refactor'],
    'agent:tester': ['needs-testing', 'test-failure'],
    'agent:reviewer': ['needs-review']
}

issues = backend.list_issues(IssueFilter(
    state='open',
    labels=[agent_type, 'feature']
))

Pattern 2: State Machine

Issues flow through states:

open → in_progress → needs_review → closed
  ↓         ↓             ↓
blocked   blocked      blocked

Pattern 3: Comment-Based Communication

Agents communicate via structured comments:

# Agent posts JSON in comment
comment.body = "```agent-message\n" + json.dumps({
    'type': 'implementation_complete',
    'agent': 'agent-coder',
    'data': {'files_changed': ['auth.py'], 'tests_passing': True}
}) + "\n```"

# Other agents parse it
for comment in comments:
    if '```agent-message' in comment.body:
        msg = json.loads(extract_json(comment.body))
        if msg['type'] == 'implementation_complete':
            # React to completion

Troubleshooting

"Backend not configured"

issue backend list
# If empty:
issue backend add myproject gitea

"Authentication failed"

# Check token is valid
curl -H "Authorization: token $GITEA_TOKEN" $GITEA_URL/api/v1/user

"No issues found"

# Verify you have issues
issue list

# Create test data
issue create "Test" --label=ready

Agent stuck/not processing

# Check what agent sees
issue list --state=open --label=needs-implementation --format=json

# Verify labels match what agent expects
issue show 42 --format=json | jq '.labels'

Tips for Development

1. Use --once flag during development to run single iterations
2. Use --no-alerts for monitoring agent to avoid cluttering tracker
3. Run agents in separate terminals to see concurrent execution
4. Use JSON format for debugging: issue list --format=json | jq
5. Clean up test data: issue list --label=agent-generated --format=json | jq -r '.[].number' | xargs -I {} issue close {}

Next Steps

• Modify these examples for your use case
• Add error handling and retry logic
• Implement actual work instead of time.sleep()
• Add logging and metrics
• Deploy as services with proper process management

See AGENT_INTEGRATION.md for more patterns and strategies.