Building a Financial Aid Agent: FAFSA Guidance, Scholarship Search, and Aid Estimation

Financial Aid Complexity

Financial aid is one of the most confusing parts of higher education. Students and families navigate FAFSA forms, CSS profiles, institutional aid, merit scholarships, work-study, and federal loans — each with different deadlines, eligibility rules, and documentation requirements. A financial aid agent demystifies this process by providing personalized guidance at scale.

Financial Aid Data Structures

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

class AidType(Enum):
    FEDERAL_GRANT = "federal_grant"
    STATE_GRANT = "state_grant"
    INSTITUTIONAL_GRANT = "institutional_grant"
    MERIT_SCHOLARSHIP = "merit_scholarship"
    NEED_BASED_SCHOLARSHIP = "need_based_scholarship"
    FEDERAL_LOAN = "federal_loan"
    WORK_STUDY = "work_study"
    EXTERNAL_SCHOLARSHIP = "external_scholarship"

class FAFSAStatus(Enum):
    NOT_STARTED = "not_started"
    IN_PROGRESS = "in_progress"
    SUBMITTED = "submitted"
    PROCESSED = "processed"
    SELECTED_FOR_VERIFICATION = "selected_for_verification"

@dataclass
class Scholarship:
    scholarship_id: str
    name: str
    amount: float
    aid_type: AidType
    renewable: bool
    gpa_minimum: float = 0.0
    major_requirements: list[str] = field(default_factory=list)
    financial_need_required: bool = False
    essay_required: bool = False
    deadline: Optional[date] = None
    eligibility_criteria: list[str] = field(default_factory=list)
    description: str = ""

@dataclass
class StudentFinancialProfile:
    student_id: str
    name: str
    efc: Optional[float] = None  # Expected Family Contribution
    fafsa_status: FAFSAStatus = FAFSAStatus.NOT_STARTED
    gpa: float = 0.0
    major: str = ""
    enrollment_status: str = "full_time"
    state_of_residence: str = ""
    household_income: Optional[float] = None
    awarded_aid: list[dict] = field(default_factory=list)

@dataclass
class CostOfAttendance:
    tuition: float
    fees: float
    room_and_board: float
    books_supplies: float
    transportation: float
    personal_expenses: float

    @property
    def total(self) -> float:
        return (self.tuition + self.fees + self.room_and_board
                + self.books_supplies + self.transportation
                + self.personal_expenses)

Scholarship Matching Engine

The core value of a financial aid agent is matching students with scholarships they qualify for.

flowchart LR
    INPUT(["User intent"])
    PARSE["Parse plus<br/>classify"]
    PLAN["Plan and tool<br/>selection"]
    AGENT["Agent loop<br/>LLM plus tools"]
    GUARD{"Guardrails<br/>and policy"}
    EXEC["Execute and<br/>verify result"]
    OBS[("Trace and metrics")]
    OUT(["Outcome plus<br/>next action"])
    INPUT --> PARSE --> PLAN --> AGENT --> GUARD
    GUARD -->|Pass| EXEC --> OUT
    GUARD -->|Fail| AGENT
    AGENT --> OBS
    style AGENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style GUARD fill:#f59e0b,stroke:#d97706,color:#1f2937
    style OBS fill:#ede9fe,stroke:#7c3aed,color:#1e1b4b
    style OUT fill:#059669,stroke:#047857,color:#fff

SCHOLARSHIPS: list[Scholarship] = []
STUDENTS: dict[str, StudentFinancialProfile] = {}

COST_OF_ATTENDANCE = CostOfAttendance(
    tuition=42000, fees=2500, room_and_board=15000,
    books_supplies=1200, transportation=1500,
    personal_expenses=2000,
)

def match_scholarships(student_id: str) -> list[dict]:
    student = STUDENTS.get(student_id)
    if not student:
        return []

    matches = []
    today = date.today()

    for scholarship in SCHOLARSHIPS:
        # Skip expired scholarships
        if scholarship.deadline and scholarship.deadline < today:
            continue

        # Check GPA requirement
        if (scholarship.gpa_minimum > 0
                and student.gpa < scholarship.gpa_minimum):
            continue

        # Check major requirements
        if (scholarship.major_requirements
                and student.major not in
                scholarship.major_requirements):
            continue

        # Check financial need
        if (scholarship.financial_need_required
                and student.household_income
                and student.household_income > 80000):
            continue

        matches.append({
            "id": scholarship.scholarship_id,
            "name": scholarship.name,
            "amount": scholarship.amount,
            "type": scholarship.aid_type.value,
            "renewable": scholarship.renewable,
            "deadline": (
                scholarship.deadline.isoformat()
                if scholarship.deadline else "Rolling"
            ),
            "essay_required": scholarship.essay_required,
            "criteria": scholarship.eligibility_criteria,
        })

    matches.sort(key=lambda m: m["amount"], reverse=True)
    return matches

Net Cost Estimator

def estimate_net_cost(student_id: str) -> dict:
    student = STUDENTS.get(student_id)
    if not student:
        return {"error": "Student not found"}

    total_cost = COST_OF_ATTENDANCE.total
    total_aid = sum(
        award.get("amount", 0) for award in student.awarded_aid
    )
    total_grants = sum(
        award.get("amount", 0) for award in student.awarded_aid
        if award.get("type") in ("federal_grant", "state_grant",
                                  "institutional_grant")
    )
    total_scholarships = sum(
        award.get("amount", 0) for award in student.awarded_aid
        if "scholarship" in award.get("type", "")
    )
    total_loans = sum(
        award.get("amount", 0) for award in student.awarded_aid
        if award.get("type") == "federal_loan"
    )

    return {
        "cost_of_attendance": total_cost,
        "breakdown": {
            "tuition": COST_OF_ATTENDANCE.tuition,
            "fees": COST_OF_ATTENDANCE.fees,
            "room_and_board": COST_OF_ATTENDANCE.room_and_board,
            "books_supplies": COST_OF_ATTENDANCE.books_supplies,
            "other": (COST_OF_ATTENDANCE.transportation
                      + COST_OF_ATTENDANCE.personal_expenses),
        },
        "total_aid": total_aid,
        "grants_scholarships": total_grants + total_scholarships,
        "loans": total_loans,
        "net_cost": total_cost - total_aid,
        "unmet_need": max(0, total_cost - total_aid),
    }

Agent Assembly

from agents import Agent, function_tool, Runner
import json

@function_tool
def check_fafsa_status(student_id: str) -> str:
    """Check a student FAFSA filing status and next steps."""
    student = STUDENTS.get(student_id)
    if not student:
        return "Student not found."

    next_steps = {
        FAFSAStatus.NOT_STARTED: "Visit studentaid.gov to begin.",
        FAFSAStatus.IN_PROGRESS: "Complete remaining sections.",
        FAFSAStatus.SUBMITTED: "Wait 3-5 days for processing.",
        FAFSAStatus.PROCESSED: "Review your SAR for accuracy.",
        FAFSAStatus.SELECTED_FOR_VERIFICATION:
            "Submit verification documents to financial aid office.",
    }

    return json.dumps({
        "student": student.name,
        "status": student.fafsa_status.value,
        "efc": student.efc,
        "next_step": next_steps.get(student.fafsa_status, ""),
    })

@function_tool
def search_scholarships(student_id: str) -> str:
    """Find scholarships the student qualifies for."""
    matches = match_scholarships(student_id)
    return json.dumps(matches) if matches else "No matching scholarships."

@function_tool
def estimate_costs(student_id: str) -> str:
    """Estimate the student net cost of attendance after aid."""
    return json.dumps(estimate_net_cost(student_id))

aid_agent = Agent(
    name="Financial Aid Advisor",
    instructions="""You are a university financial aid advisor agent.
    Help students understand FAFSA requirements, find scholarships,
    and estimate costs. Be empathetic and encouraging. Never
    guarantee aid amounts. Always clarify the difference between
    grants (free money) and loans (must be repaid). If a student
    is selected for verification, explain the process calmly.""",
    tools=[check_fafsa_status, search_scholarships, estimate_costs],
)

FAQ

How does the agent handle students selected for FAFSA verification?

When the FAFSA status is SELECTED_FOR_VERIFICATION, the agent explains that this is a routine process affecting roughly one-third of applicants. It lists the typically required documents (tax transcripts, W-2s, verification worksheet) and provides the deadline. It reassures the student that verification does not mean they did something wrong.

Can the agent provide accurate scholarship matching without income data?

The agent can match on non-financial criteria (GPA, major, demographics, extracurriculars) but should flag that need-based scholarships require financial information for accurate matching. It can prompt the student to complete their FAFSA or provide household income range to improve results.

How do you keep scholarship data current?

Integrate with scholarship aggregator APIs (Fastweb, Scholarships.com) and schedule nightly syncs. For institutional scholarships, pull from the university financial aid database. Each scholarship record includes a last_verified date, and the agent notes when data may be outdated.

#AIAgents #EdTech #FinancialAid #Python #FAFSA #AgenticAI #LearnAI #AIEngineering