git clone https://github.com/marc-shade/agent-runtime-mcp
cd agent-runtime-mcp
pip install -r requirements.txt

git clone https://github.com/marc-shade/agent-runtime-mcp
cd agent-runtime-mcp
uv pip install -r requirements.txt

pip install anthropic-mcp

{
  "mcpServers": {
    "agent-runtime": {
      "command": "python3",
      "args": [
        "/absolute/path/to/agent-runtime-mcp/server.py"
      ]
    }
  }
}

# Create goal
goal = mcp__agent-runtime__create_goal({
    "name": "Build REST API",
    "description": "Create RESTful API for user authentication with JWT tokens",
    "metadata": {"priority": "high", "project": "auth-service"}
})
# Returns: {"id": 1, "name": "Build REST API", "status": "active", ...}

# Decompose goal into tasks (sequential strategy)
result = mcp__agent-runtime__decompose_goal({
    "goal_id": 1,
    "strategy": "sequential"
})
# Returns: {
#   "goal_id": 1,
#   "strategy": "sequential",
#   "tasks_created": [101, 102, 103, 104, 105],
#   "count": 5
# }
# Tasks: Research → Plan → Implement → Test → Document (with dependencies)

# Decompose for parallel execution
result = mcp__agent-runtime__decompose_goal({
    "goal_id": 1,
    "strategy": "parallel"
})
# Creates: Backend, Frontend, Testing tasks (no dependencies, run simultaneously)

# Decompose into phases
result = mcp__agent-runtime__decompose_goal({
    "goal_id": 1,
    "strategy": "hierarchical"
})
# Creates: Phase 1 (Foundation) → Phase 2 (Core) → Phase 3 (Integration) → Phase 4 (Optimization)

# Get next ready task
task = mcp__agent-runtime__get_next_task()
# Returns: Highest priority task with all dependencies met
# {"id": 101, "title": "Research requirements...", "priority": 10, ...}

# Start work
mcp__agent-runtime__update_task_status({
    "task_id": 101,
    "status": "in_progress"
})

# Complete task
mcp__agent-runtime__update_task_status({
    "task_id": 101,
    "status": "completed",
    "result": "Requirements documented in docs/api-spec.md"
})

# Get next (automatically handles dependencies)
next_task = mcp__agent-runtime__get_next_task()
# Returns: Task 102 (Plan approach) since Research (101) is complete

# Create task with explicit dependencies
mcp__agent-runtime__create_task({
    "goal_id": 1,
    "title": "Deploy to production",
    "description": "Deploy authentication service",
    "priority": 7,
    "dependencies": [103, 104]  # Wait for Implementation and Testing
})

# Create relay pipeline for complex workflow
pipeline = mcp__agent-runtime__create_relay_pipeline({
    "name": "Research Paper Analysis",
    "goal": "Extract insights from 10 AGI papers",
    "agent_types": [
        "researcher",      # Gather papers
        "analyzer",        # Extract key points
        "synthesizer",     # Find patterns
        "validator",       # Check quality
        "formatter"        # Create report
    ],
    "token_budget": 100000
})
# Returns: {"pipeline_id": "rp_abc123", "agent_count": 5, ...}

# Check pipeline status
status = mcp__agent-runtime__get_relay_status({
    "pipeline_id": "rp_abc123"
})
# Returns: {
#   "current_step": 2,
#   "total_steps": 5,
#   "status": "in_progress",
#   "quality_scores": [0.92, 0.88, ...],
#   "tokens_used": 24531
# }

# Get current baton (context for next agent)
baton = mcp__agent-runtime__get_relay_baton({
    "pipeline_id": "rp_abc123"
})
# Returns: {
#   "baton": {...},
#   "prompt": "You are the Synthesizer. Previous output: ..."
# }

# Advance to next step
mcp__agent-runtime__advance_relay({
    "pipeline_id": "rp_abc123",
    "quality_score": 0.88,
    "l_score": 0.85,
    "output_entity_id": 456,
    "tokens_used": 8234,
    "output_summary": "Found 3 key patterns across papers"
})

# Retry failed step
mcp__agent-runtime__retry_relay_step({
    "pipeline_id": "rp_abc123",
    "step_index": 2
})

# Check agent circuit breaker status
status = mcp__agent-runtime__circuit_breaker_status({
    "agent_id": "researcher_agent"
})
# Returns: {
#   "agent_id": "researcher_agent",
#   "state": "CLOSED",
#   "failure_count": 0,
#   "success_count": 42
# }

# Record failure
mcp__agent-runtime__circuit_breaker_record_failure({
    "agent_id": "researcher_agent",
    "failure_type": "timeout",
    "error_message": "API request timed out after 30s"
})

# List all circuit breakers
breakers = mcp__agent-runtime__circuit_breaker_list()
# Returns: {
#   "total_breakers": 10,
#   "open_circuits": ["failing_agent_1", "failing_agent_2"],
#   "half_open_circuits": ["recovering_agent"],
#   "breakers": [...]
# }

# Configure thresholds
mcp__agent-runtime__circuit_breaker_configure({
    "agent_id": "researcher_agent",
    "failure_threshold": 5,
    "window_seconds": 60,
    "cooldown_seconds": 300,
    "fallback_agent": "generalist"
})

# Manually trip (emergency stop)
mcp__agent-runtime__circuit_breaker_trip({
    "agent_id": "researcher_agent",
    "reason": "Manual intervention - debugging required"
})

# Reset after fix
mcp__agent-runtime__circuit_breaker_reset({
    "agent_id": "researcher_agent"
})

# Session 1: Create goal and start work
goal = mcp__agent-runtime__create_goal({"name": "Big Project", ...})
mcp__agent-runtime__decompose_goal({"goal_id": goal["id"]})
task1 = mcp__agent-runtime__get_next_task()
mcp__agent-runtime__update_task_status({"task_id": task1["id"], "status": "in_progress"})

# [Close Claude Code, restart later]

# Session 2: Resume exactly where left off
pending = mcp__agent-runtime__list_tasks({"status": "in_progress"})
# Returns: [task1] - still marked as in_progress
task1_updated = mcp__agent-runtime__update_task_status({
    "task_id": task1["id"],
    "status": "completed"
})
next_task = mcp__agent-runtime__get_next_task()
# Automatically gets task2 (next in dependency chain)

Task 1 → Task 2 → Task 3 → Task 4 → Task 5

Task 1 (Backend)  ─┐
Task 2 (Frontend) ─┼─→ All run simultaneously
Task 3 (Testing)  ─┘

Phase 1 (Foundation)
  ↓
Phase 2 (Core Implementation)
  ↓
Phase 3 (Integration)
  ↓
Phase 4 (Optimization)

# Run test suite
python3 test_agent_runtime.py

# Test relay protocol
python3 test_relay_protocol.py

# Test circuit breaker
python3 test_circuit_breaker.py