AI Agent for Volunteer Management: Sign-Up, Scheduling, and Communication

The Volunteer Coordination Challenge

Managing volunteers is one of the most labor-intensive tasks for any nonprofit. Coordinators juggle sign-up forms, shift schedules, reminder calls, last-minute cancellations, and appreciation outreach. An AI agent can handle routine coordination while keeping a human coordinator informed of issues that require judgment.

This tutorial builds a volunteer management agent that registers volunteers, matches them to shifts based on skills and availability, sends reminders, and tracks hours for recognition programs.

Modeling Volunteers and Shifts

Start with clean data structures that capture what the agent needs to make scheduling decisions.

from dataclasses import dataclass, field
from datetime import datetime, date, time
from typing import Optional
from enum import Enum
from uuid import uuid4


class ShiftStatus(Enum):
    OPEN = "open"
    FILLED = "filled"
    IN_PROGRESS = "in_progress"
    COMPLETED = "completed"
    CANCELLED = "cancelled"


@dataclass
class Volunteer:
    volunteer_id: str = field(default_factory=lambda: str(uuid4()))
    name: str = ""
    email: str = ""
    phone: Optional[str] = None
    skills: list[str] = field(default_factory=list)
    availability: list[str] = field(default_factory=list)
    total_hours: float = 0.0
    shifts_completed: int = 0


@dataclass
class Shift:
    shift_id: str = field(default_factory=lambda: str(uuid4()))
    event_name: str = ""
    role: str = ""
    shift_date: date = field(default_factory=date.today)
    start_time: time = field(default_factory=lambda: time(9, 0))
    end_time: time = field(default_factory=lambda: time(12, 0))
    location: str = ""
    required_skills: list[str] = field(default_factory=list)
    spots_total: int = 1
    spots_filled: int = 0
    assigned_volunteers: list[str] = field(default_factory=list)
    status: ShiftStatus = ShiftStatus.OPEN

Building the Registration Tool

The agent needs to register new volunteers and capture their skills and availability.

from agents import function_tool

# In-memory store for demonstration
volunteer_db: dict[str, Volunteer] = {}


@function_tool
async def register_volunteer(
    name: str,
    email: str,
    phone: str,
    skills: list[str],
    availability: list[str],
) -> dict:
    """Register a new volunteer with their skills and availability."""
    # Check for duplicate registration
    for v in volunteer_db.values():
        if v.email == email:
            return {
                "status": "already_registered",
                "volunteer_id": v.volunteer_id,
                "message": f"{name} is already registered.",
            }

    volunteer = Volunteer(
        name=name,
        email=email,
        phone=phone,
        skills=[s.lower() for s in skills],
        availability=[d.lower() for d in availability],
    )
    volunteer_db[volunteer.volunteer_id] = volunteer

    return {
        "status": "registered",
        "volunteer_id": volunteer.volunteer_id,
        "message": f"Welcome, {name}! You are now registered.",
    }

Shift Matching and Assignment

The scheduling tool matches volunteers to shifts based on skill overlap and day-of-week availability.

shift_db: dict[str, Shift] = {}


@function_tool
async def find_matching_shifts(
    volunteer_id: str,
) -> dict:
    """Find open shifts that match a volunteer's skills and availability."""
    volunteer = volunteer_db.get(volunteer_id)
    if not volunteer:
        return {"error": "Volunteer not found"}

    matches = []
    for shift in shift_db.values():
        if shift.status != ShiftStatus.OPEN or shift.spots_filled >= shift.spots_total:
            continue

        day_name = shift.shift_date.strftime("%A").lower()
        skill_match = not shift.required_skills or any(
            s in volunteer.skills for s in shift.required_skills)

        if day_name in volunteer.availability and skill_match:
            matches.append({
                "shift_id": shift.shift_id,
                "event": shift.event_name,
                "date": str(shift.shift_date),
                "spots_left": shift.spots_total - shift.spots_filled,
            })

    return {"matches": matches, "count": len(matches)}


@function_tool
async def assign_volunteer_to_shift(
    volunteer_id: str,
    shift_id: str,
) -> dict:
    """Assign a volunteer to a specific shift."""
    volunteer = volunteer_db.get(volunteer_id)
    shift = shift_db.get(shift_id)

    if not volunteer:
        return {"error": "Volunteer not found"}
    if not shift:
        return {"error": "Shift not found"}
    if volunteer_id in shift.assigned_volunteers:
        return {"error": "Already assigned to this shift"}
    if shift.spots_filled >= shift.spots_total:
        return {"error": "Shift is full"}

    shift.assigned_volunteers.append(volunteer_id)
    shift.spots_filled += 1
    if shift.spots_filled >= shift.spots_total:
        shift.status = ShiftStatus.FILLED

    return {
        "status": "assigned",
        "volunteer": volunteer.name,
        "shift": shift.event_name,
        "date": str(shift.shift_date),
        "role": shift.role,
    }

Reminders and Appreciation

Automated reminders reduce no-shows, and post-shift appreciation messages improve retention.

@function_tool
async def send_shift_reminder(
    volunteer_id: str,
    shift_id: str,
) -> dict:
    """Send a reminder to a volunteer about an upcoming shift."""
    volunteer = volunteer_db.get(volunteer_id)
    shift = shift_db.get(shift_id)
    if not volunteer or not shift:
        return {"error": "Volunteer or shift not found"}

    return {
        "status": "sent",
        "recipient": volunteer.email,
        "shift": shift.event_name,
        "date": str(shift.shift_date),
    }


@function_tool
async def log_hours_and_thank(
    volunteer_id: str,
    shift_id: str,
    hours_worked: float,
) -> dict:
    """Log volunteer hours and send an appreciation message."""
    volunteer = volunteer_db.get(volunteer_id)
    if not volunteer:
        return {"error": "Volunteer not found"}

    volunteer.total_hours += hours_worked
    volunteer.shifts_completed += 1

    milestone = ""
    if volunteer.total_hours >= 100:
        milestone = " You have reached 100+ hours — Gold level!"
    elif volunteer.total_hours >= 50:
        milestone = " You have reached 50+ hours — Silver level!"

    return {
        "status": "logged",
        "total_hours": volunteer.total_hours,
        "shifts_completed": volunteer.shifts_completed,
        "milestone": milestone,
    }

Assembling the Agent

from agents import Agent, Runner

volunteer_agent = Agent(
    name="Volunteer Coordinator Agent",
    instructions="""You are a volunteer coordinator agent.
Your responsibilities:

1. Register new volunteers with their skills and availability
2. Find shifts that match a volunteer's profile
3. Assign volunteers to shifts they are interested in
4. Send reminders 24 hours before shifts
5. Log hours after shifts and send appreciation
6. Track milestones (50 hours = Silver, 100 = Gold)
7. If no shifts match, suggest the volunteer broaden availability
8. Always confirm assignment details before finalizing""",
    tools=[
        register_volunteer,
        find_matching_shifts,
        assign_volunteer_to_shift,
        send_shift_reminder,
        log_hours_and_thank,
    ],
)

result = Runner.run_sync(
    volunteer_agent,
    "Maria Garcia wants to volunteer. Her email is maria@example.com, "
    "phone 555-0199. She has skills in cooking and event setup, and is "
    "available on Saturdays and Sundays. Please register her and find "
    "matching shifts.",
)
print(result.final_output)

FAQ

How does the agent handle last-minute cancellations?

Add a cancel_assignment tool that removes the volunteer from the shift, reopens the spot, and triggers a notification to the waitlist. The agent can then proactively reach out to other qualified volunteers to fill the gap, prioritizing those who have expressed interest in similar shifts.

Can the agent handle background check requirements?

Yes. Add a background_check_status field to the Volunteer model. The assignment tool checks this field before confirming shifts that require clearance (such as working with children). If the check is pending, the agent informs the volunteer and places them on a conditional waitlist.

How do you prevent double-booking a volunteer?

The assign_volunteer_to_shift tool should check the volunteer's existing assignments for time conflicts before confirming. Query all shifts where the volunteer is assigned, compare the date and time ranges, and reject the assignment if there is any overlap.

---

#VolunteerManagement #NonprofitAI #Scheduling #AgenticAI #Python #LearnAI #AIEngineering