Ionworks Agent

Chat with the Ionworks battery-modelling agent directly inside Studio — run simulations, fit models, and explore data without leaving the app.

The Ionworks Agent is a battery-modelling analyst built into Ionworks Studio. It runs real electrochemical simulations, fits models, and explores the data in your project — all inside a chat panel that stays anchored to whatever page you are on.

The Agent is hosted for you. There is nothing to install and no API key to configure — just open the chat and start asking. If you would rather work in your own coding agent, see Bring your own agent.

When to use it

Reach for the in-app Agent when you want to:

• Explore what you have — “What cell specifications and measurements do I have in this project?”
• Run a simulation on the fly — “Run a 1C discharge on one of my parameterized models and plot voltage vs time.”
• Fit a model to a measurement — “Fit an ECM to one of my cells and show the voltage overlay.”
• Get context-aware help — from a study, cell, or measurement page, ask “summarise this study” or “what’s odd about this measurement?” without spelling out the ids.

For scripted or repeatable work — CI, batch parameterization, anything you need to re-run unattended — use the Python API client instead.

Two ways to open it

Floating chat widget

A chat bubble in the bottom-right corner of every dashboard page. Clicking it opens a panel over the current view — the agent knows which page you are on and can resolve references like “this study” or “this cell” without you naming ids.

Full Agent page

Open Ionworks Agent in the Studio sidebar for the full experience: a session list on the left, the active conversation on the right, and room for larger plots and code output.

Both views talk to the same sessions — a conversation you started from the floating widget is available in the full Agent page, and vice versa.

What the agent can do

The agent has access to your project data through the same authenticated API your account uses, so every action respects your organization’s row-level permissions.

• Run PyBaMM simulations on your parameterized models and plot the results inline.
• Fit equivalent-circuit and physics-based models to measurements you have already uploaded.
• Query your data — list projects, cells, measurements, studies, models, and pipelines; open any of them by asking.
• Execute Python in a sandboxed environment. Code runs as read-only notebook cells in the chat, complete with captured stdout, results, and images. Each cell is a fresh interpreter — nothing carries over between them, so the agent re-imports and rebuilds client on every call.
• Attach files — drag any file up to 50 MB into the chat and ask the agent to inspect or process it. Attachments stay with the conversation, so later turns can reuse them without re-attaching. MATLAB .mat exports work except -v7.3 (HDF5) saves, which the sandbox cannot read.
• Link back into the app — when the agent points at a resource it renders a “Go to this page” button that navigates you there without tearing down the chat.
• Show you where things are — ask how or where to do something and the agent takes you to the right page, then picks the explanation back up once you arrive.

Page context

When you open the floating widget from a page like /projects/<id>/studies/<id> or a cell-instance measurements page, the agent receives a small structured note describing where you are — the page name and the ids of the project, study, cell spec, cell instance, measurement, model, or pipeline in view.

This lets you say “this study” or “the measurement I’m looking at” and have the agent resolve it correctly, without pasting ids into the prompt.

Only ids and page labels are sent — never URLs, query strings, or free-form page content. The backend re-sanitises the note before it reaches the model.

Sessions

Each conversation is its own session, persisted to your account so you can pick it up later or from another device. Sessions are scoped to a project — both views list only the sessions belonging to the project you are currently in.

• The floating widget resumes where you left off: on reopening it restores the session you last used in that project, falling back to the most recently updated one. Start a fresh chat, or switch to an earlier session, from the widget’s session menu.
• The full Agent page shows that project’s sessions in the left-hand list. Click one to resume, or start a new chat from the header.

You can stop an in-flight turn at any time — the agent finishes the current tool step, then hands control back to you.

Export a conversation as a notebook

Every conversation in the full Agent page has an Export notebook (.ipynb) action. Downloading it gives you a Jupyter notebook where:

• Every run_python step becomes a code cell, complete with captured outputs (stdout/stderr, result values, images, error tracebacks).
• Your prompts and the agent’s prose become markdown cells.
• Inline plots become embedded images.

The result is a complete record of the analysis the agent produced — open it in Jupyter to read, tweak, or hand it to a colleague.

The export carries the conversation and its captured outputs, not the environment they ran in. To re-execute the cells you need your own Python environment with whatever the code imports installed — typically ionworks (see Python API client) plus the usual scientific stack (pybamm, numpy, pandas, matplotlib).

Example prompts

Paste any of these into the chat to get a feel for what the agent will do.

Explore data

What cell specifications and measurements do I have in this project?
Which of my cells have GITT measurements?

Run a simulation

Run a 1C discharge on one of my parameterized models and plot voltage vs time.
Sweep C-rate from 0.5C to 3C on my NMC/Graphite parameterized model and overlay
the discharge curves.

Fit a model

Fit an ECM to one of my cells and show the voltage overlay against the
measured data.
Fit a single-particle model to my rate-capability data on cell "NMC-A" and
report the SoC-dependent parameters.

Contextual (with page context)

Summarise this study.
What's the SoC window covered by this measurement?
Open the fitted parameterized model.

Requirements and limits

• Available to any signed-in Ionworks Studio user. No extra install.
• Simulations, fits, and data queries run against your project data under your account permissions — you will only see cells, measurements, and models you already have access to.
• Python execution is stateless — every cell is a fresh interpreter, so variables do not carry from one to the next. Attached files and anything written to the working directory do persist for the life of the conversation, but not beyond it.
• Very long conversations are truncated on the model side. Export to a notebook before starting a new session if you want to preserve the full record.

Bring your own agent

The Ionworks Agentic Toolkit teaches your own coding agent to drive Ionworks, so you can stay in it instead of switching to the in-app chat. It covers the full R&D loop: data processing, validation, upload, cell and equipment management, model fitting, simulations, pipelines, and reporting.

It is a folder of SKILL.md files calling the Python API client, so there is no server to run and nothing to keep in sync. Works with Claude Code, Cursor, Codex, Gemini CLI, and GitHub Copilot.

Let your agent install it

One paste, no decisions: your agent works out where its own skills live and does the rest. Create a key on your Studio Account page, then paste this to your agent:

Ask your agent

Install the Ionworks Agentic Toolkit for yourself, then use it.

1. Check that IONWORKS_API_KEY is set in my shell. If it is missing, stop and
   tell me to create one at https://app.ionworks.com/dashboard/account — do not
   try to mint one yourself.

2. Install the SDK, which ships the installer for the toolkit:

   ```bash
   uv add ionworks-api   # or: pip install ionworks-api
   ```

3. Install the skills for yourself. This defaults to the current project; add
   -g to install for all projects, and -a to name agents explicitly if it does
   not detect you:

   ```bash
   ionworks skills install
   ```

4. Run `ionworks skills list` to confirm what landed, then invoke the `install`
   skill for the SDK's self-check.

5. Report what you did and anything left for me to do by hand.

If the `ionworks` command is unavailable, fall back to fetching the archive
directly and copying skills/* into your own skills directory:

   ```bash
   curl -fsSL -H "X-API-Key: $IONWORKS_API_KEY" \
     https://api.ionworks.com/agent/skills.zip -o /tmp/ionworks-skills.zip
   rm -rf ~/ionworks-skills && unzip -q /tmp/ionworks-skills.zip -d ~
   ```

The endpoint requires authentication: an X-API-Key header (above) or a logged-in Studio session (the download button). An unauthenticated request gets a 401, so the command will not work without the key.

Updating later

ionworks skills update is all it takes, but the SDK should be upgraded alongside it since the skills track the current API. To hand that off:

Ask your agent

Update the Ionworks Agentic Toolkit you already have installed.

1. Record the version you have now: `ionworks skills list`.

2. Upgrade the SDK, since the skills track the current API:

   ```bash
   uv add --upgrade ionworks-api   # or: pip install --upgrade ionworks-api
   ```

3. Update the skills. Use the same scope you installed with — add -g if they
   live in the user-level directory rather than this project:

   ```bash
   ionworks skills update
   ```

   This removes the skills from the previous install before copying the new
   set, so anything retired upstream does not linger. Do not hand-copy over the
   old files instead; that merges and leaves orphans behind.

4. Run `ionworks skills list` again and report the version you had, the version
   you now have, and anything that changed which affects how I should use these
   skills.

The Bring your own agent tab shows the current toolkit version, so you can check what you are updating to.

Or run the CLI yourself

For CI, containers, or anyone who would rather type it than delegate: the Python SDK ships an ionworks command that fetches the toolkit and installs it into whichever agents it finds. Create a key on your Studio Account page first.

uv add ionworks-api        # or: pip install ionworks-api
export IONWORKS_API_KEY="iw_..."

ionworks skills install    # this project
ionworks skills install -g # all projects

Scope and agent selection follow the same conventions as npx skills: project by default, -g for the user-level directory, -a claude-code cursor to name agents explicitly instead of auto-detecting. ionworks skills list shows what is installed and at which version.

Re-run it to update — ionworks skills update is the same operation. Whichever you use, the skills from the previous install are removed before the new set lands, so a skill retired upstream cannot linger and keep being loaded. Skills you wrote yourself are left alone.

Or install it by hand

1. Download the toolkit

   Open Ionworks Agent in the Studio sidebar, switch to the Bring your own agent tab, and click Download ionworks-skills.zip. Unzip it somewhere stable:

   unzip ~/Downloads/ionworks-skills.zip -d ~
   

   The archive carries its own ionworks-skills/ folder, so this creates ~/ionworks-skills. See Updating by hand below for refreshing it later.

2. Point your agent at it

   Copy the skills into your agent’s skills directory — ~/.claude/skills/ for Claude Code, ~/.cursor/skills/ for Cursor, .github/skills/ for Copilot:

   cp -r ~/ionworks-skills/skills/* ~/.claude/skills/
   

   Gemini CLI installs the unzipped folder as an extension (gemini extensions install ~/ionworks-skills); Codex installs it as a local plugin. The toolkit’s own README.md has the exact commands for each.

3. Install the SDK and set your key

   The skills call the Python client, so it needs to be installed in the environment your agent runs code in:

   uv add ionworks-api   # or: pip install ionworks-api
   

   Create an API key from your Studio Account page and export it:

   export IONWORKS_API_KEY="iw_..."
   
4. Check it works

   Ask your agent to use the install skill — it runs the SDK’s self-check and reports anything still missing.

Updating by hand

Two copies need replacing: the checkout, and the skills you copied out of it into your agent. Delete rather than overwrite — unzipping or copying over the old files merges, so a skill retired upstream would linger and your agent would keep loading it.

Clear the installed skills before refreshing the checkout: the list of what to remove comes from the old checkout, and a retired skill is no longer named in the new one.

# 1. remove what you installed last time, named from the OLD checkout
for s in $(ls ~/ionworks-skills/skills); do rm -rf ~/.claude/skills/"$s"; done

# 2. refresh the checkout and copy the new set in
rm -rf ~/ionworks-skills
unzip ~/Downloads/ionworks-skills.zip -d ~
cp -r ~/ionworks-skills/skills/* ~/.claude/skills/

# 3. the skills track the current API, so upgrade it too
uv add --upgrade ionworks-api

Adjust the skills path for your agent. If you installed as a Gemini extension or Codex plugin, uninstall and reinstall it instead of copying files.

Already unzipped it yourself? You can still hand off the rest — point your agent at ~/ionworks-skills/README.md and ask it to follow the local-checkout install path for whichever agent it is running in.

The download is tied to your Studio login, and the skills themselves carry no credentials — each one reads IONWORKS_API_KEY from the environment at run time, so everything your agent does still runs under your own account permissions.

Related

• Python API client — the same SDK the agent uses; call it directly from your own scripts.
• Quickstart — create a project, cell, and parameterized model so the agent has something to work with.