Connect eClinicalWorks to AI Agents: Automate EHR Data Workflows

You want to connect eClinicalWorks to an AI agent so your system can independently read electronic health records, summarize patient histories, extract diagnostic reports, and automate clinical workflows based on historical context. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom, HIPAA-compliant FHIR integration from scratch.

Giving a Large Language Model (LLM) read and write access to an EHR like eClinicalWorks is a massive engineering undertaking. You either spend months building, hosting, and maintaining a custom connector that navigates complex healthcare data standards, or you utilize a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting eClinicalWorks to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting eClinicalWorks to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for eClinicalWorks, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex clinical operations workflows. For a deeper look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be - a critical consideration when handling protected health information (PHI).

Direct API tools (one tool per raw eClinicalWorks FHIR endpoint) look convenient in a prototype, but they push provider quirks directly into the LLM's context window. The model has to remember exactly how to format a FHIR R4 query string, how to resolve nested references, and how to manage opaque pagination cursors. Every one of those quirks is a hallucination waiting to happen.

Using Truto's Proxy APIs as tools collapses this complexity. Your agent sees stable functions like list_all_e_clinical_works_patients and get_single_e_clinical_works_medication_request_by_id. That gives you concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from stable function names with explicitly defined parameters. It never invents complex HL7 search queries.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit the EHR, so a broken tool call fails fast instead of returning confusing, empty payloads.
3. Framework agnosticism. Truto returns standard JSON schema tool definitions. You can pass them into LangChain's .bindTools(), Vercel AI SDK's tools object, or CrewAI agents without writing framework-specific wrappers.

The Engineering Reality of the eClinicalWorks API

Giving an LLM access to external data sounds simple. You write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production against complex healthcare systems like eClinicalWorks, this approach collapses under its own weight.

eClinicalWorks relies on the HL7 FHIR R4 specification. If you hardcode raw FHIR interactions into your agent, you will spend your sprints writing defensive parsing logic instead of improving your model's reasoning capabilities.

The FHIR Reference Trap

Standard LLMs are trained to expect flat, intuitive JSON objects. When an agent wants to find a patient's medications, it naturally attempts to look for a single endpoint that returns a list of drug names.

eClinicalWorks does not work this way. In the FHIR standard, clinical data is highly relational. A MedicationRequest resource does not always contain the string name of the medication. Instead, it contains a medicationReference pointing to a separate Medication resource, or a medicationCodeableConcept containing RxNorm codes. If you expose the raw API to an agent, the agent must figure out how to parse the reference ID, make a secondary API call to fetch the specific medication, and map the code to a human-readable string.

Truto's /tools endpoint provides pre-defined, schema-backed tools that guide the LLM on exactly what parameters are required to traverse these relationships without guessing.

Opaque Pagination and State Management

Clinical records are vast. A single patient might have hundreds of encounters and thousands of observations. eClinicalWorks handles this via pagination. If your agent is responsible for iterating through pages, it must understand how to parse the link array in a FHIR Bundle to find the next relation URL, extract the cursor, and append it to the next request.

Agents are terrible at stateful iteration over opaque strings. Truto abstracts this away. The Proxy APIs handle the underlying pagination mechanics, presenting a clean, consistent interface to the agent framework.

Strict Rate Limiting and Backoff Responsibilities

Healthcare APIs strictly throttle traffic to protect core infrastructure. A critical engineering reality to understand: Truto does not retry, throttle, or apply backoff on rate limit errors.

When the upstream eClinicalWorks API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. However, Truto normalizes the upstream rate limit information into standardized headers per the IETF specification:

• ratelimit-limit: The maximum number of requests allowed in the current window.
• ratelimit-remaining: The number of requests left in the current window.
• ratelimit-reset: The time at which the rate limit window resets.

Your agent execution loop is responsible for catching these 429s, reading the ratelimit-reset header, and pausing execution. Do not assume the integration layer will absorb these errors - if you fail to implement backoff, your agent will spiral into a loop of failed tool calls.

The Hero Tools for eClinicalWorks AI Agents

Instead of exposing the entire EHR surface area to your agent, restrict it to high-leverage clinical operations. Truto auto-generates schema-backed tools from the integration definition. Here are the core tools you should bind to your clinical agent.

list_all_e_clinical_works_patients

Searching for patients is the entry point for almost every clinical workflow. This tool allows the agent to search the practice database and returns matching FHIR R4 Patient resources containing demographics, identifiers, and active status.

Usage Note: Ensure your agent prompts extract specific identifiers (like name or telecom) to avoid returning massive, unfilterable datasets.

"Find the patient record for John Doe, born on 1980-05-15, and return their active patient ID."

list_all_e_clinical_works_encounters

Encounters represent visits, admissions, or interactions between the patient and the healthcare provider. This tool is vital for agents tasked with summarizing recent clinical history or prepping a provider for an upcoming appointment.

Usage Note: This tool requires a patient parameter. The agent must first use the patient search tool to acquire the correct FHIR ID.

"Retrieve all recent encounters for patient ID 98765 and summarize the primary reason for their last three visits."

list_all_e_clinical_works_conditions

Conditions encompass the patient's problems, encounter diagnoses, or health concerns. Agents use this to construct problem lists or screen patients for specific chronic diseases.

Usage Note: Filter by category to differentiate between chronic problems and acute encounter diagnoses. Requires the patient ID.

"List all active conditions for patient ID 98765, focusing specifically on chronic health concerns."

list_all_e_clinical_works_medication_requests

This tool retrieves all active and historical medication orders for a patient. It is essential for medication reconciliation workflows or checking for contraindications.

Usage Note: The output will contain FHIR MedicationRequest resources. The agent will need to parse medicationCodeableConcept or use the reference ID to fetch specific drug details.

"Fetch the current medication requests for patient ID 98765 to prepare a medication reconciliation summary."

list_all_e_clinical_works_observations

Observations are the lifeblood of clinical data, encompassing vitals, lab results, and social history. Agents use this tool to track health metrics over time.

Usage Note: Because observations are so broad, instruct your agent to filter by category (e.g., vitals vs labs) to prevent context window overflow.

"Pull the most recent laboratory observations for patient ID 98765, specifically looking for HbA1c and lipid panel results."

list_all_e_clinical_works_diagnostic_reports

This tool retrieves diagnostic reports, which often include narrative clinical notes, pathology reports, and finalized lab result groupings. It is critical for deep-dive summarization tasks.

Usage Note: Returns FHIR R4 DiagnosticReport resources. Requires the patient ID.

"Get all diagnostic reports for patient ID 98765 from the last six months and summarize the findings of their recent cardiology workup."

To view the complete inventory of available eClinicalWorks tools, including precise JSON schemas for creating, updating, and specialized querying, visit the eClinicalWorks integration page.

Workflows in Action

Providing individual tools is just the foundation. The real value emerges when agents autonomously chain these tools together to execute complex clinical workflows.

Scenario 1: Pre-Visit Clinical Summary Prep

Medical assistants and clinicians spend hours reviewing charts before a patient arrives. An AI agent can automate this intake preparation.

"Prepare a comprehensive pre-visit summary for Jane Smith. I need to know her active conditions, her last three encounters, and any recent lab observations."

Execution Sequence:

1. Agent Action: Calls list_all_e_clinical_works_patients searching for "Jane Smith" to retrieve the patient's FHIR ID.
2. Agent Action: Calls list_all_e_clinical_works_conditions using the retrieved ID to compile the active problem list.
3. Agent Action: Calls list_all_e_clinical_works_encounters (sorting/filtering by date) to extract the context of her most recent visits.
4. Agent Action: Calls list_all_e_clinical_works_observations categorized by 'laboratory' to fetch recent test results.
5. Final Output: The agent synthesizes this data into a formatted, chronological Markdown summary, saving the clinician 15 minutes of chart review.

Scenario 2: Clinical Trial Cohort Screening

Research coordinators need to scan entire patient panels to find individuals meeting strict inclusion criteria for clinical trials.

"Find patients in the system who have an active diagnosis of Type 2 Diabetes and check their recent lab observations to see if their last HbA1c was above 8.0."

Execution Sequence:

1. Agent Action: Calls list_all_e_clinical_works_patients to generate a base cohort (or iterates through an existing panel list).
2. Agent Action: Loops through the patient IDs, calling list_all_e_clinical_works_conditions for each, filtering for Type 2 Diabetes SNOMED/ICD-10 codes.
3. Agent Action: For patients matching the condition, the agent calls list_all_e_clinical_works_observations looking for the specific HbA1c LOINC code.
4. Final Output: The agent returns a highly targeted list of eligible patient IDs and contact info, completely automating the manual chart abstraction process.

Building Multi-Step Workflows

To build these autonomous loops, you must fetch the tool schemas from Truto and bind them to your LLM. Because Truto acts as the unified proxy, the integration code remains agnostic to the specific agent framework you choose.

Here is how you architect the agent loop using TypeScript and LangChain. Note the explicit handling of HTTP 429 rate limit errors - a requirement when working with Truto's transparent error passing.

flowchart TD
    A["User Prompt<br>Request patient summary"] --> B["Agent Framework<br>LangChain / CrewAI"]
    B -->|"Selects Tool"| C["TrutoToolManager<br>Invokes Proxy API"]
    C -->|"REST HTTP Request"| D["Truto Unified Proxy<br>Handles Auth & Normalization"]
    D -->|"FHIR API Request"| E["eClinicalWorks API<br>Raw EHR Data"]
    E -->|"HTTP 429 Too Many Requests"| D
    D -->|"ratelimit-reset Header"| C
    C -->|"Throw Error / Backoff"| B
    B -->|"Wait & Retry"| C
    E -->|"200 OK FHIR JSON"| D
    D -->|"Normalized JSON"| C
    C -->|"Tool Result"| B
    B -->|"Final Synthesis"| F["Formatted Clinical Summary"]

1. Fetching Tools and Initializing the Agent

First, we instantiate the TrutoToolManager from the truto-langchainjs-toolset. This fetches the OpenAPI descriptions for the eClinicalWorks Proxy APIs and converts them into LangChain-compatible DynamicStructuredTool objects.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
async function initializeClinicalAgent(trutoToken: string, accountId: string) {
  // Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });
 
  // Fetch eClinicalWorks tools for the specific connected account
  const toolManager = new TrutoToolManager({
    token: trutoToken,
    accountId: accountId,
  });
 
  // We can filter tools to only include read operations for safety
  const tools = await toolManager.getTools({ methods: ["read"] });
 
  // Create a strict system prompt to guide clinical behavior
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a clinical AI assistant. Use the provided tools to query eClinicalWorks. Always search for a patient ID first before querying conditions or encounters. If a tool fails due to a rate limit, acknowledge it and wait."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // Bind tools to the agent
  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });
 
  return new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });
}

2. Handling Rate Limits in the Execution Loop

Because Truto passes upstream eClinicalWorks rate limits directly to the caller, your system must respect the normalized ratelimit-* headers. If you are building custom tool executors (or modifying the SDK), you must intercept 429s.

async function executeWithBackoff(executor: AgentExecutor, input: string) {
  try {
    console.log(`Executing prompt: ${input}`);
    const result = await executor.invoke({ input });
    return result.output;
    
  } catch (error: any) {
    // Check if the error is a 429 passed through Truto
    if (error.response && error.response.status === 429) {
      const resetTime = error.response.headers['ratelimit-reset'];
      
      if (resetTime) {
        const resetDate = new Date(parseInt(resetTime) * 1000);
        const waitMs = resetDate.getTime() - Date.now();
        
        console.warn(`Rate limit hit. Waiting ${waitMs}ms until ${resetDate.toISOString()} before retrying.`);
        
        // Implement wait logic here, then retry or return message to user
        await new Promise(resolve => setTimeout(resolve, waitMs));
        return executeWithBackoff(executor, input); // Recursive retry
      }
    }
    
    console.error("Agent execution failed:", error);
    throw error;
  }
}
 
// Usage:
// const executor = await initializeClinicalAgent(process.env.TRUTO_TOKEN, "ecw-account-123");
// const summary = await executeWithBackoff(executor, "Summarize recent encounters for John Doe.");
// console.log(summary);

By handling rate limits explicitly based on the standardized headers Truto provides, you ensure your agent remains robust and compliant with the EHR's traffic policies, preventing account lockouts.

Moving Forward with EHR Automation

Building autonomous agents that interact with eClinicalWorks requires strict attention to data schemas, reliable pagination, and explicit rate limit handling. Bypassing the raw FHIR R4 complexity and utilizing Truto's Proxy API tools allows your engineering team to focus on prompt engineering, reasoning loops, and clinical accuracy, rather than decoding HL7 payload structures.

Whether you are building pre-visit summarization bots, automated trial matching systems, or intelligent patient intake workflows, the architectural principles remain the same: give your LLM a constrained, stable set of tools, handle upstream state gracefully, and ensure strict input validation.