Getting Started with Cascade Agent

What is Cascade Agent?

Cascade Agent is a natural language interface that sits between you and the Cascade Protocol CLI. Instead of memorizing exact commands and flags, you describe what you want in plain English and the agent figures out the right sequence of CLI calls to make it happen.

▶ Convert all FHIR files in ~/records to Cascade RDF and save them to ~/output

⚙ shell $ mkdir -p ~/output && for f in ~/records/*.json; do cascade convert ...

↳ (command succeeded — 1,201 files converted)

Done. 1,201 patient records converted and saved to ~/output as .ttl files.

The agent streams responses in real time, shows you every command it runs, and maintains conversation context so you can follow up naturally.

All health data stays on your machine

The agent only sends your text prompt to the AI provider — never your health records.
File reads are limited to 20 KB snippets, used only to help the agent understand what it is working with.
All conversion, validation, and pod management runs locally via the Cascade CLI.

1

Prerequisites

✓

Node.js 18+
Runtime

✓

Cascade CLI
See below

✓

AI API key
One provider required

If you haven't installed the CLI yet:

npm install -g @the-cascade-protocol/cli

2

Install Cascade Agent

npm install -g @the-cascade-protocol/agent

Verify the install:

cascade-agent --version

3

Configure an AI Provider

Cascade Agent supports four AI providers. You only need one.

Provider	Flag	Free tier?	Default model
Anthropic (Claude)	`-p anthropic`	No — console.anthropic.com	claude-opus-4-6
OpenAI (GPT)	`-p openai`	No — platform.openai.com	gpt-4o
Google (Gemini)	`-p google`	Yes — aistudio.google.com	gemini-2.0-flash
Ollama (local)	`-p ollama`	Yes — runs on your machine	llama3.2

Run the interactive setup to save your API key:

cascade-agent login

You can also skip login and use an environment variable instead:

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export GOOGLE_AI_API_KEY=AI...

Note: AI provider subscriptions (Claude.ai, ChatGPT Plus, Gemini Advanced) are separate from API access and cannot be used directly with this tool. You need an API key from each provider's developer console. Google AI Studio offers a free tier with generous rate limits.

4

Use the Agent

Interactive REPL

Start a conversation where the agent remembers context across requests:

cascade-agent                   # uses your configured provider
cascade-agent -p google         # override provider for this session
cascade-agent -p ollama         # use a local model

Inside the REPL:

Input	Action
any text	Send a request to the agent
clear	Reset conversation history
help	Show usage examples
exit	Quit

One-shot mode

Run a single request and exit:

cascade-agent "validate ~/health-data/patient.ttl"
cascade-agent "how many lab results are in this record?" ~/records/patient.json
cascade-agent -p openai -m gpt-4o "initialize a Pod at ~/my-pod and import patient.json"

What you can ask

The agent understands any task expressible with the Cascade CLI. Some examples:

▶ Convert all the FHIR bundles in ~/Downloads/records to Cascade RDF

▶ Validate these .ttl files and tell me which ones have errors

▶ Initialize a new Pod at ~/my-health-data and import patient.json into it

▶ How many condition records are in this Pod?

▶ Show me the medications and lab results from ~/records/provider-a.json and ~/records/provider-b.json, reconcile any duplicates

For batch jobs the agent writes a shell loop rather than making one call per file, so converting thousands of records is a single tool invocation.

Managing Providers & Models

# List configured providers
cascade-agent provider

# Switch active provider
cascade-agent provider google

# Show current model
cascade-agent model

# Switch model using a shortcut
cascade-agent model flash       # gemini-2.0-flash
cascade-agent model opus        # claude-opus-4-6
cascade-agent model sonnet      # claude-sonnet-4-6

# Use any full model ID
cascade-agent model gemini-1.5-pro

Settings are saved to ~/.config/cascade-agent/config.json. Environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_AI_API_KEY) always take precedence over saved keys.

Model shortcuts

Shortcut	Resolves to
opus	claude-opus-4-6
sonnet	claude-sonnet-4-6
haiku	claude-haiku-4-5
gpt4o	gpt-4o
o3	o3
flash	gemini-2.0-flash
pro	gemini-1.5-pro

Session Logs

Every session is logged automatically. Review past sessions with:

cascade-agent logs