FHIR Agent Tools

LLM-agent-ready extraction functions for FHIR JSON resources. Parse FHIR API responses and extract structured data for use in AI agents.

Installation

pip install fhir-agent-tools

Quick Start

from fhir_agent_tools import get_patient_summary, get_bundle_entries

# Parse a Patient resource
patient_json = '{"resourceType":"Patient","id":"123","name":[{"family":"Smith","given":["John"]}],"birthDate":"1990-01-15"}'
result = get_patient_summary(patient_json)
# result: {"success": True, "data": {"id": "123", "name": "Smith, John", "birthDate": "1990-01-15", ...}}

# Parse a Bundle (search results)
bundle_json = '{"resourceType":"Bundle","type":"searchset","entry":[{"resource":{...}}]}'
entries = get_bundle_entries(bundle_json)
# entries: {"success": True, "data": [<list of resources>]}

Error Handling

All extractors return a structured result—they never raise by default:

# Success
{"success": True, "data": {...}}

# Error (invalid JSON, wrong resource type, validation failure)
{"success": False, "error": {"type": "parse_error", "message": "...", "details": ...}}

For programmatic use with exceptions:

from fhir_agent_tools import get_patient_summary, FhirExtractError

try:
    data = get_patient_summary(patient_json, raise_on_error=True)
except FhirExtractError as e:
    print(e.error)

Agent Integration

OpenAI Function Calling

from openai import OpenAI
from fhir_agent_tools import get_tools, get_extractor_functions

client = OpenAI()

# Get tool definitions for the API
tools = get_tools()

# When the model calls a tool, execute it:
functions = {name: fn for name, fn in get_extractor_functions()}
# For extract_resources_by_type, the function expects (fhir_json, resource_type)

LangChain

from langchain.tools import StructuredTool
from fhir_agent_tools import get_tools, get_extractor_functions

# Convert to LangChain tools
lc_tools = []
for name, fn in get_extractor_functions():
    if name == "extract_resources_by_type":
        lc_tools.append(StructuredTool.from_function(
            func=lambda j, rt: fn(j, rt),
            name=name,
            description=next(t["function"]["description"] for t in get_tools() if t["function"]["name"] == name),
        ))
    else:
        lc_tools.append(StructuredTool.from_function(
            func=fn,
            name=name,
            description=next(t["function"]["description"] for t in get_tools() if t["function"]["name"] == name),
        ))

Supported Resources

FHIR Version

Uses FHIR R4B (4.3.0) via fhir.resources. Compatible with R4.0.1 API responses.

License

MIT