Analyze care flow data with an AI agent

An AI agent can answer a question about care flow data, such as how many patients completed a care flow last month, once it knows how Awell lays out that data in BigQuery. Awell publishes that knowledge as a skill for the agent to install. This page covers what the agent needs, how to install the skill, what to ask, and what happens to the data.

Before you start

• BigQuery access for the person asking, through BigQuery Studio or a read-only service account. See Get access to BigQuery.
• The project and dataset names. The skill asks for both before it writes a query. If they aren't known, email support@awellhealth.com.
• An AI agent that supports skills. Claude does, in claude.ai, the Claude desktop app and Claude Code. An agent without skill support can take the same instructions as plain context.

Install the skill from GitHub

The skill is public, at awell-health/bigquery-agent-prompt. Its README has the steps for each agent:

• claude.ai and the Claude desktop app: download bigquery-agent-prompt.zip from the repository's latest release and upload it under Customize > Skills. Skills need code execution turned on. On a Team or Enterprise plan, an owner can provision the skill for every member of the organization.
• Claude Code: clone the repository into ~/.claude/skills/bigquery-agent-prompt.
• Other agents: install it with the open-source skills command-line tool, or give the agent the repository's PROMPT.md as context.

The skill describes the tables and their columns, with worked queries. Data schema explains the model behind those tables, such as the difference between a care flow definition and a care flow.

The agent writes the query, and runs it where it can

The agent turns a question into SQL, the query language BigQuery reads. To run the query, it needs its own way into BigQuery: the bq command-line tool from Google Cloud in Claude Code, for instance, or a BigQuery connector. Without one, copy the query into BigQuery Studio and give the agent the result.

Name the project and dataset in the first question, so the agent doesn't have to ask. For example:

• "In awell-production, dataset example_clinic: how many care flows started last month, per care flow definition?"
• "How many patients completed the post-operative follow-up care flow in the last 90 days, and how long did it take them on average?"
• "Which forms do patients leave open the longest before completing them?"
• "What share of patients in the weight management care flow lost at least 5% of their first recorded weight?"

Give a date range instead of "recently", and name the care flow, so the answer doesn't span every care flow in the dataset.

Check the definitions before acting on a number

Ask the agent to show the query with its answer, and read which table and filters it used. "Active", "completed" and "enrolled" have precise meanings in Awell that may not match how a team uses them day to day. See Monthly active patients for one example.

The skill holds no data, and the agent's own terms apply

• The skill is instructions and a description of the tables. It contains no data and sends nothing to Awell.
• The agent's queries run in BigQuery with the access the organization gives it, and only the rows a query returns reach the agent.
• The skill tells the agent to read as little patient data as the question needs: counts and averages rather than patient-level rows, and no names, contact details or identifiers unless asked.
• What the agent reads goes to its model provider, under the organization's agreement with that provider, not with Awell. The provider may process it outside the region the dataset is in. Before the agent reads patient-level rows, check that the agreement covers health data and the features the agent uses.

Next steps

Next: Monthly active patients — what counts as an active patient, the definition Awell bills on.