Building a Community Resource Directory Agent: Service Finder for Housing, Food, and Health

Connecting People to the Services They Need

Every community has dozens of organizations offering housing assistance, food programs, healthcare clinics, job training, and legal aid. But people who need these services the most — those facing homelessness, food insecurity, or health crises — often do not know what is available or how to access it. The information is scattered across websites, 211 directories, and word of mouth.

An AI resource directory agent serves as a single point of access. A person describes their situation, and the agent identifies relevant services, checks eligibility criteria, provides contact details, and tracks referrals to ensure people actually connect with help.

Resource and Referral Data Models

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

class ServiceCategory(Enum):
    HOUSING = "housing"
    FOOD = "food"
    HEALTHCARE = "healthcare"
    EMPLOYMENT = "employment"
    LEGAL_AID = "legal_aid"
    UTILITIES = "utilities"

@dataclass
class CommunityResource:
    resource_id: str = field(default_factory=lambda: str(uuid4()))
    name: str = ""
    category: ServiceCategory = ServiceCategory.FOOD
    address: str = ""
    city: str = ""
    state: str = ""
    phone: str = ""
    hours: str = ""
    accepts_walkins: bool = False
    wait_time_days: int = 0
    is_active: bool = True

@dataclass
class Referral:
    referral_id: str = field(default_factory=lambda: str(uuid4()))
    client_name: str = ""
    client_phone: str = ""
    resource_name: str = ""
    category: ServiceCategory = ServiceCategory.FOOD
    follow_up_date: Optional[date] = None

Resource Search with Eligibility Filtering

The search tool matches a person's needs and circumstances against available resources.

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

from agents import function_tool

resources_db: list[CommunityResource] = []
referrals_db: list[Referral] = []

@function_tool
async def search_resources(
    category: str,
    city: str = "",
    state: str = "",
    eligibility_factors: list[str] = [],
    language: str = "English",
    needs_walkin: bool = False,
) -> dict:
    """Search community resources by category, location,
    and eligibility factors."""
    cat = ServiceCategory(category)
    results = []

    for resource in resources_db:
        if not resource.is_active or resource.category != cat:
            continue
        if city and resource.city.lower() != city.lower():
            continue
        if state and resource.state.lower() != state.lower():
            continue
        if needs_walkin and not resource.accepts_walkins:
            continue

        results.append({
            "name": resource.name,
            "address": resource.address,
            "phone": resource.phone,
            "hours": resource.hours,
            "walk_ins": resource.accepts_walkins,
            "wait_time": f"{resource.wait_time_days} days"
                if resource.wait_time_days > 0 else "No wait",
        })

    return {"resources": results, "total_found": len(results)}

Multi-Need Assessment

People in crisis rarely have just one need. The agent can assess multiple needs from a single description.

@function_tool
async def assess_needs(caller_description: str) -> dict:
    """Analyze a caller's description to identify multiple
    service needs and relevant eligibility factors."""
    text = caller_description.lower()

    needs = []
    factors = []

    need_map = {
        "housing": ["housing", "rent", "eviction", "shelter", "homeless"],
        "food": ["food", "hungry", "groceries", "meals", "food bank"],
        "healthcare": ["doctor", "medical", "clinic", "prescription"],
        "employment": ["job", "work", "unemployed", "resume"],
        "legal_aid": ["lawyer", "legal", "court", "custody"],
        "utilities": ["electric", "gas bill", "utility", "disconnected"],
    }

    for cat, keywords in need_map.items():
        if any(kw in text for kw in keywords):
            needs.append(cat)

    factor_map = {
        "veteran": ["veteran", "military"],
        "senior": ["senior", "elderly", "retired"],
        "family_with_children": ["kids", "children", "baby", "pregnant"],
        "homeless": ["homeless", "no place", "shelter"],
    }

    for factor, keywords in factor_map.items():
        if any(kw in text for kw in keywords):
            factors.append(factor)

    return {
        "identified_needs": needs,
        "eligibility_factors": factors,
        "needs_count": len(needs),
        "recommendation": "Search for resources in each identified "
            "category, filtered by eligibility factors.",
    }

@function_tool
async def create_referral(
    client_name: str,
    client_phone: str,
    resource_name: str,
    category: str,
) -> dict:
    """Create a referral record and schedule follow-up."""
    follow_up = date.today() + timedelta(days=14)
    referral = Referral(
        client_name=client_name,
        client_phone=client_phone,
        resource_name=resource_name,
        category=ServiceCategory(category),
        follow_up_date=follow_up,
    )
    referrals_db.append(referral)
    return {"referral_id": referral.referral_id,
            "resource": resource_name, "follow_up": str(follow_up)}

Assembling the Resource Directory Agent

from agents import Agent, Runner

resource_agent = Agent(
    name="Community Resource Directory Agent",
    instructions="""You are a community resource navigator. Your
role is to connect people with the services they need.

YOUR APPROACH:
1. Listen to the person's situation without judgment
2. Assess their needs — people often have multiple needs
3. Search for resources matching each identified need
4. Explain eligibility requirements clearly
5. Create referrals and schedule follow-ups
6. Prioritize resources that accept walk-ins for urgent needs
7. Always provide phone numbers so people can call directly
8. Mention language availability for non-English speakers
9. Note wait times so people can plan accordingly
10. If no local resources match, suggest 211 as a backup

TONE: Helpful, respectful, and practical. Avoid jargon.
Remember that asking for help takes courage.""",
    tools=[
        assess_needs,
        search_resources,
        create_referral,
    ],
)

result = Runner.run_sync(
    resource_agent,
    "I am a single mom with two kids. I just got an eviction notice "
    "and we need somewhere to stay. We also need help with groceries "
    "this week. I am in Portland, Oregon.",
)
print(result.final_output)

FAQ

How do you keep the resource database accurate?

Resource information goes stale quickly — organizations change hours, lose funding, or move locations. Implement a verification schedule that contacts each resource monthly to confirm details. Track the last_verified date and flag resources not verified within 90 days. The agent can deprioritize unverified resources in search results and note the last verification date to the caller.

How does the referral follow-up work?

The agent creates a referral record with a follow-up date (typically 2-4 weeks after the referral). A scheduled job queries for referrals due for follow-up, and the agent or a case worker contacts the client to check whether they connected with the resource. Outcomes are tracked (connected, could not reach, waitlisted, not eligible) to measure the referral pipeline's effectiveness.

Can the agent handle crisis situations?

The resource agent is designed for non-emergency service navigation. If the agent detects crisis language (suicidal ideation, domestic violence in progress, child abuse), it should immediately provide emergency numbers (911, 988, NDVH) and transfer to a crisis-trained agent or counselor. The resource agent does not attempt crisis intervention.

#CommunityResources #SocialServices #ResourceDirectory #AgenticAI #Python #LearnAI #AIEngineering