Creating expert AI agents with SWML and Datasphere

The SignalWire AI Agent allows you to develop custom digital assistants that are compliant with the regulations of specific industries. SignalWire Markup Language (SWML) creates AI-powered call flows, while Datasphere (SignalWire’s RAG API) can be used to build knowledge bases for AI agents to become experts in specific topics.

In this post, we’ll walk through an example of a HIPAA-compliant AI agent for a nursing home that automates routine weekly check-ins with residents. This AI assistant transforms a repetitive, hands-on process into a fully automated workflow, ensuring vital information promptly reaches caregivers without missing a beat.

We’ll show you exactly how to set up the call flow with SWML and demonstrate how to leverage SignalWire AI Gateway (SWAIG) functions, like verify_patient and store_summary, to connect to a local database. This will confirm each patient’s identity and log their assessment results in real-time.

To access the full code, view the SignalWire in Seconds GitHub repository.

How the AI nursing home digital assistant works

1. Patient verification: The AI agent calls a patient, asks for their name, and verifies it against a local database.

2. Health assessment: The AI collects key information about well-being, pain, appetite, and sleep quality.

3. Datasphere queries: If the patient needs more information about a symptom, the AI can fetch relevant paragraphs from a stored document (such as a PDF of best practices or medical guidelines).

4. Summarization and notification: After the call, the AI saves a conversation summary in the database and texts the caregiver with a conversation summary.

SWML: The conversation blueprint

SWML is a JSON or YAML based markup language used to define call flows, IVRs, AI interactions, and other telephony logic in a flexible, declarative format. In this example, it orchestrates how the AI agent interacts with the patient. Below is an abridged snippet from our SWML prompt that highlights the conversation flow:

SWAIG functions

Below is a quick look at how verify_patient is defined in SWML as a SWAIG function and how it corresponds to a Flask endpoint.

With meta_data_token = "patient_meta", each SWML function referencing the same token can read or update the meta_data object. This avoids repetition of fetching basic details (like phone numbers or IDs) every time. Instead, store_summary or send_message simply uses "${meta_data.patient_id}".

/verify_patient endpoint response

Datasphere: Retrieving paragraph-level information

Datasphere processes text documents like PDFs, splits them into smaller, searchable sections, and stores them as vectors for quick retrieval. This enables the AI agent to fetch knowledge on the fly for accurate, fact-based answers.

For this example, we uploaded a PDF to SignalWire’s Datasphere API using the “paragraph” chunking strategy, meaning the PDF document was formatted into clear paragraph sections.

Chunking strategy

1. Paragraph splitting: Breaks the document into paragraphs.

2. Upload to Datasphere: Use the Datasphere API or dashboard UI to store the chunked document, receiving a document_id.

3. Query in SWML: The get_data function then references that document_id:

If a patient were to ask, “I’ve been having trouble sleeping. What can I do?” the AI calls get_data, sending the question to Datasphere. The best paragraph about sleep or insomnia is returned and read back to the user, removing guesswork from the AI’s response.

Example call flow

Start dialer

From the CRM interface, a staff member clicks “call patients,” triggering the /start_dialer endpoint in Flask. This spawns the dialer.py script, which uses SignalWire RELAY consumer to read each patient’s phone number from nursing_home.db. It then dials those numbers using the from_number configured in the environment.

Once the call successfully connects to a patient, the script bridges that call to the AI agent phone number, where SWML (via /ai_prompt) is set up to handle the conversation logic.

AI introduction

After the dialer script has handed off the call to your digital_assistant number, the SWML "answer" directive takes over. The AI greets the patient and asks for their first and last name, preparing to verify them against your database.

Verify

The AI calls verify_patient (Flask), sending those names. In return, the endpoint provides the patient’s ID and caregiver phone. SWML then stores this in meta_data so it can be used in later steps.

Health questions

The AI proceeds to ask weekly check-in questions like, “How do you feel overall?” “Any pain or discomfort?” “How’s your sleep?”

Further details

If the patient wants more info or has specific concerns, get_data is triggered. This calls Datasphere to retrieve relevant paragraphs from a stored document (like a PDF of health guidelines).

Summarize and send SMS

Finally, the AI calls store_summary to save the call details in the database, and then send_message to text a short summary to the caregiver’s phone number—no extra verification needed.

Get started with SignalWire AI Agents and Datasphere

Using the SignalWire Datasphere with our AI Agent allows smart applications to deliver targeted, helpful answers, improving user experiences and efficiency.

To dive deeper into the code and see how it all fits together, check out the full project in our GitHub repository. Fork the code, experiment, adapt the logic for your own use case, and continue exploring the power of the SignalWire AI Agent.

Need help as you get started? Start building for free today by signing up for a SignalWire Space, exploring our developer documentation, and bringing your questions to our community on Discord.