Building a Tax Information Agent: Filing Guidance, Payment Plans, and Refund Status

The Tax Information Challenge

Tax agencies — whether the IRS, state revenue departments, or local property tax offices — handle an enormous volume of repetitive inquiries. "When is my refund coming?" "Do I need to file quarterly?" "Can I set up a payment plan?" "What form do I use for rental income?" These questions have clear, rule-based answers, but taxpayers struggle to find them because tax rules are scattered across publications, form instructions, and FAQ pages written in legal language.

An AI agent can serve as a knowledgeable guide that understands filing requirements, explains tax rules in plain language, helps set up payment arrangements, and provides refund status updates. Like the court agent, it must stay on the information side — it informs, it does not advise. "Here is how the home office deduction works" is information. "You should take the home office deduction" is advice.

Modeling Tax Rules and Filing Requirements

Tax filing requirements depend on filing status, income sources, and thresholds. We model these as structured data that the agent queries deterministically.

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


class FilingStatus(Enum):
    SINGLE = "single"
    MARRIED_JOINT = "married_filing_jointly"
    MARRIED_SEPARATE = "married_filing_separately"
    HEAD_OF_HOUSEHOLD = "head_of_household"
    QUALIFYING_SURVIVING_SPOUSE = "qualifying_surviving_spouse"


class IncomeSource(Enum):
    W2_EMPLOYMENT = "w2"
    SELF_EMPLOYMENT = "self_employment"
    RENTAL = "rental_income"
    INVESTMENT = "investment"
    RETIREMENT = "retirement_distribution"
    SOCIAL_SECURITY = "social_security"
    GIG_ECONOMY = "gig_1099"
    UNEMPLOYMENT = "unemployment"


@dataclass
class FilingThreshold:
    """Minimum income threshold requiring a federal tax return."""
    filing_status: FilingStatus
    age_under_65: float
    age_65_or_older: float


FILING_THRESHOLDS_2025: dict[FilingStatus, FilingThreshold] = {
    FilingStatus.SINGLE: FilingThreshold(
        FilingStatus.SINGLE, 14_600, 16_550,
    ),
    FilingStatus.MARRIED_JOINT: FilingThreshold(
        FilingStatus.MARRIED_JOINT, 29_200, 30_750,
    ),
    FilingStatus.HEAD_OF_HOUSEHOLD: FilingThreshold(
        FilingStatus.HEAD_OF_HOUSEHOLD, 21_900, 23_850,
    ),
}


@dataclass
class TaxpayerProfile:
    filing_status: FilingStatus
    age: int
    income_sources: list[IncomeSource] = field(default_factory=list)
    gross_income: float = 0.0
    self_employment_income: float = 0.0
    has_dependents: bool = False
    received_1099: bool = False
    withholding_sufficient: bool = True


def must_file_return(taxpayer: TaxpayerProfile) -> dict:
    """Determine whether a taxpayer is required to file a return."""
    threshold = FILING_THRESHOLDS_2025.get(taxpayer.filing_status)
    if not threshold:
        return {"must_file": True, "reason": "Unable to determine threshold"}

    limit = (
        threshold.age_65_or_older if taxpayer.age >= 65
        else threshold.age_under_65
    )

    must_file = taxpayer.gross_income >= limit
    reasons = []

    if must_file:
        reasons.append(
            f"Gross income ${taxpayer.gross_income:,.0f} exceeds "
            f"filing threshold ${limit:,.0f}"
        )

    # Self-employment income has a separate $400 threshold
    if taxpayer.self_employment_income >= 400:
        must_file = True
        reasons.append(
            f"Self-employment income ${taxpayer.self_employment_income:,.0f} "
            f"exceeds \$400 threshold"
        )

    # Even if not required, filing might be beneficial
    should_consider = []
    if not must_file:
        should_consider.append(
            "You may want to file anyway to claim refundable credits "
            "(Earned Income Credit, Child Tax Credit)"
        )
        if taxpayer.received_1099:
            should_consider.append(
                "You received 1099 forms, which were also reported to the IRS"
            )

    return {
        "must_file": must_file,
        "reasons": reasons,
        "filing_threshold": limit,
        "should_consider_filing": should_consider,
    }

Form Selection Engine

Taxpayers often do not know which forms they need. The agent maps income sources and situations to the correct tax forms.

@dataclass
class TaxForm:
    form_number: str
    form_name: str
    description: str
    triggers: list[str]
    due_date: str
    instructions_url: str


TAX_FORMS: list[TaxForm] = [
    TaxForm(
        form_number="1040",
        form_name="U.S. Individual Income Tax Return",
        description="The main federal income tax form for individuals",
        triggers=["all_individual_filers"],
        due_date="April 15",
        instructions_url="https://www.irs.gov/forms-pubs/about-form-1040",
    ),
    TaxForm(
        form_number="Schedule C",
        form_name="Profit or Loss From Business",
        description="Report income and expenses from self-employment",
        triggers=["self_employment", "gig_1099", "freelance"],
        due_date="Filed with 1040",
        instructions_url="https://www.irs.gov/forms-pubs/about-schedule-c-form-1040",
    ),
    TaxForm(
        form_number="Schedule E",
        form_name="Supplemental Income and Loss",
        description="Report rental income, royalties, partnerships, S corps",
        triggers=["rental_income", "royalty_income", "partnership"],
        due_date="Filed with 1040",
        instructions_url="https://www.irs.gov/forms-pubs/about-schedule-e-form-1040",
    ),
    TaxForm(
        form_number="1040-ES",
        form_name="Estimated Tax for Individuals",
        description="Pay estimated taxes quarterly if you expect to owe $1,000+",
        triggers=["self_employment", "no_withholding", "investment"],
        due_date="Quarterly: Apr 15, Jun 15, Sep 15, Jan 15",
        instructions_url="https://www.irs.gov/forms-pubs/about-form-1040-es",
    ),
    TaxForm(
        form_number="4868",
        form_name="Application for Extension of Time to File",
        description="Request a 6-month extension to file (not to pay)",
        triggers=["extension_request"],
        due_date="April 15 (original due date)",
        instructions_url="https://www.irs.gov/forms-pubs/about-form-4868",
    ),
]


def recommend_forms(taxpayer: TaxpayerProfile) -> list[dict]:
    """Determine which tax forms a taxpayer likely needs."""
    trigger_map = {
        IncomeSource.SELF_EMPLOYMENT: ["self_employment"],
        IncomeSource.GIG_ECONOMY: ["gig_1099", "self_employment"],
        IncomeSource.RENTAL: ["rental_income"],
        IncomeSource.INVESTMENT: ["investment"],
    }

    active_triggers = {"all_individual_filers"}
    for source in taxpayer.income_sources:
        triggers = trigger_map.get(source, [])
        active_triggers.update(triggers)

    recommended = []
    for form in TAX_FORMS:
        if any(t in active_triggers for t in form.triggers):
            recommended.append({
                "form": form.form_number,
                "name": form.form_name,
                "why": form.description,
                "due_date": form.due_date,
                "instructions": form.instructions_url,
            })

    return recommended

Payment Plan Calculator

When taxpayers owe money they cannot pay in full, the agent helps them understand installment agreement options.

from math import ceil


@dataclass
class PaymentPlan:
    plan_type: str
    monthly_payment: float
    total_months: int
    setup_fee: float
    interest_rate: float
    total_cost: float
    qualifies: bool
    requirements: list[str]


def calculate_payment_plans(
    amount_owed: float,
    can_pay_monthly_max: float,
) -> list[PaymentPlan]:
    """Calculate available IRS payment plan options."""
    plans = []

    # Short-term plan (180 days or less, no setup fee online)
    if amount_owed <= 100_000:
        months_needed = ceil(amount_owed / can_pay_monthly_max)
        if months_needed <= 6:
            plans.append(PaymentPlan(
                plan_type="Short-term (up to 180 days)",
                monthly_payment=round(amount_owed / min(months_needed, 6), 2),
                total_months=min(months_needed, 6),
                setup_fee=0,
                interest_rate=0.08,  # failure-to-pay penalty + interest
                total_cost=round(amount_owed * 1.04, 2),  # approximate
                qualifies=True,
                requirements=[
                    "Owe \$100,000 or less (including penalties and interest)",
                    "Filed all required tax returns",
                ],
            ))

    # Long-term installment agreement
    if amount_owed <= 50_000:
        monthly = max(amount_owed / 72, 25)  # 72-month max, $25 minimum
        total_months = ceil(amount_owed / monthly)
        setup_fee = 31 if True else 107  # online vs. phone/mail

        plans.append(PaymentPlan(
            plan_type="Long-term installment agreement (monthly)",
            monthly_payment=round(monthly, 2),
            total_months=total_months,
            setup_fee=setup_fee,
            interest_rate=0.08,
            total_cost=round(monthly * total_months + setup_fee, 2),
            qualifies=True,
            requirements=[
                "Owe \$50,000 or less (including penalties and interest)",
                "Filed all required tax returns",
                "Set up direct debit for lowest setup fee",
            ],
        ))

    # Offer in Compromise hint
    if amount_owed > can_pay_monthly_max * 120:
        plans.append(PaymentPlan(
            plan_type="Offer in Compromise (settle for less)",
            monthly_payment=0,
            total_months=0,
            setup_fee=205,
            interest_rate=0,
            total_cost=0,  # varies based on offer accepted
            qualifies=False,  # requires detailed financial review
            requirements=[
                "Must demonstrate inability to pay full amount",
                "All tax returns must be filed",
                "Current on estimated tax payments",
                "Not in open bankruptcy",
                "Complete Form 656 and financial statements",
            ],
        ))

    return plans

Refund Status Tracking

The refund status check is the single highest-volume inquiry tax agencies receive. The agent provides clear, specific status information.

def check_refund_status(ssn_last_4: str, tax_year: int, expected_amount: float) -> dict:
    """Check the status of a tax refund.
    In production, this queries the agency's refund tracking system."""

    # Simulated response structure
    return {
        "tax_year": tax_year,
        "status": "approved",
        "status_detail": "Your refund has been approved and is scheduled for direct deposit.",
        "expected_date": "2026-03-21",
        "amount": expected_amount,
        "delivery_method": "direct_deposit",
        "delays": [],
        "action_required": None,
    }

FAQ

How does the agent handle state-specific tax questions when rules vary by state?

The agent maintains a state tax configuration that maps each state to its income tax structure (flat rate, graduated brackets, or no income tax), standard deduction amounts, and unique credits or deductions. When a user specifies their state, the agent loads the corresponding rules and provides state-specific guidance alongside federal information. For states with no income tax (like Texas or Florida), the agent proactively mentions that no state return is needed. The configuration is updated annually when states publish new tax year parameters.

What safeguards prevent the agent from giving tax advice instead of information?

The agent uses the same information-vs-advice framework as the court agent. It describes how tax rules work but never recommends specific actions. Instead of "you should itemize your deductions," it says "if your itemizable expenses exceed the standard deduction of $14,600, itemizing would result in a larger deduction." The agent presents the rule and the math, letting the taxpayer (or their tax professional) make the decision. All responses include a disclaimer that the information is general guidance, not personalized tax advice.

Can the agent help with estimated tax payments for self-employed individuals?

Yes. The agent calculates estimated quarterly payments using the safe harbor rules: either 100% of the prior year tax liability (110% for high earners) or 90% of the current year expected liability, whichever is applicable. It generates a payment schedule showing the four quarterly due dates and amounts, provides the Form 1040-ES voucher numbers, and explains the penalty calculation for underpayment. It also reminds self-employed taxpayers that estimated payments cover both income tax and self-employment tax (Social Security and Medicare).

---

#GovernmentAI #TaxServices #FilingGuidance #PaymentPlans #PublicSector #AgenticAI #LearnAI #AIEngineering