# Analyze care flow data with an AI agent
URL: https://docs.awellhealth.com/docs/data/analyze-data-with-an-ai-agent

> For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt).



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 [#before-you-start]

* **BigQuery access** for the person asking, through BigQuery Studio or a read-only service account. See
  [Get access to BigQuery](/docs/data/getting-access).
* **The project and dataset names.** The skill asks for both before it writes a query. If they aren't
  known, email [support@awellhealth.com](mailto: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 [#install-the-skill-from-github]

The skill is public, at
[awell-health/bigquery-agent-prompt](https://github.com/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](/docs/data/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-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 [#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](/docs/data/monthly-active-patients) for one example.

## The skill holds no data, and the agent's own terms apply [#the-skill-holds-no-data-and-the-agents-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-steps]

**Next:** [Monthly active patients](/docs/data/monthly-active-patients) — what counts as an active
patient, the definition Awell bills on.
