> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](#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](/api-client) instead.

## Two ways to open it

<CardGroup cols={2}>
  <Card title="Floating chat widget" icon="comment">
    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.
  </Card>

  <Card title="Full Agent page" icon="messages">
    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.
  </Card>
</CardGroup>

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.

<Note>
  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.
</Note>

## 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.

<Note>
  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](/api-client)) plus the usual scientific
  stack (`pybamm`, `numpy`, `pandas`, `matplotlib`).
</Note>

## Example prompts

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

```text Explore data theme={null}
What cell specifications and measurements do I have in this project?
Which of my cells have GITT measurements?
```

```text Run a simulation theme={null}
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.
```

```text Fit a model theme={null}
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.
```

```text Contextual (with page context) theme={null}
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](/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:

````text Ask your agent theme={null}
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 ~
   ```
````

<Note>
  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.
</Note>

#### 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:

````text Ask your agent theme={null}
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**](https://app.ionworks.com/dashboard/agent?tab=byo)
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.

```bash theme={null}
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

<Steps>
  <Step title="Download the toolkit">
    Open **Ionworks Agent** in the Studio sidebar, switch to the [**Bring your
    own agent**](https://app.ionworks.com/dashboard/agent?tab=byo) tab, and
    click **Download ionworks-skills.zip**. Unzip it somewhere stable:

    ```bash theme={null}
    unzip ~/Downloads/ionworks-skills.zip -d ~
    ```

    The archive carries its own `ionworks-skills/` folder, so this creates
    `~/ionworks-skills`. See [Updating by hand](#updating-by-hand) below for
    refreshing it later.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    uv add ionworks-api   # or: pip install ionworks-api
    ```

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

    ```bash theme={null}
    export IONWORKS_API_KEY="iw_..."
    ```
  </Step>

  <Step title="Check it works">
    Ask your agent to use the `install` skill — it runs the SDK's self-check
    and reports anything still missing.
  </Step>
</Steps>

#### 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.

```bash theme={null}
# 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.

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>

## Related

* [Python API client](/api-client) — the same SDK the agent uses; call it
  directly from your own scripts.
* [Quickstart](/quickstart) — create a project, cell, and parameterized model
  so the agent has something to work with.