# Use the SDK in a workspace

Install katonic-sdk into a JupyterLab workspace on Python 3.11, call the platform from a notebook with a scoped key, and revoke the key when you finish.

A workspace in My Workspaces is a good place to try the Python SDK: you get a notebook next to the platform, with no local setup. This page walks through installing `katonic-sdk` 7.0.18 into a workspace, calling the platform from a notebook cell, and cleaning up afterwards.

**Who can use it:** anyone who can create a workspace in a tenant licensed for workspaces and the public API, with a `kapi_` key from the Developer Hub.

## Prerequisites

- **A workspace on Python 3.11 or newer.** **JupyterLab · Python 3.11** works. The SDK needs 3.11, and on a Python 3.10 image, including the Spark workspace images, `pip install "katonic-sdk>=7"` fails with "No matching distribution found". A custom image works when its Python is 3.11 or newer.
- **An API key** with the scopes your calls need, created under **API keys** in the Developer Hub. Give it a short expiry when it is only for an experiment.
- **The Studio address you browse**, with no path after the host. The Developer Hub shows it as the **SDK base URL** chip.

## Install and call

  
**Step 1. Install the SDK into the workspace**

Open a terminal in the workspace, or a notebook cell, and install it for your user:

```bash
pip install --user "katonic-sdk>=7"
```

In a notebook cell, prefix the line with `%`, as `%pip install --user "katonic-sdk>=7"`, then restart the kernel so it picks up the new package. Check the version with `pip show katonic-sdk`; it should report 7.0.18.

  
**Step 2. Give the client the address and the key**

Set both in the notebook before you create the client. Read the key from a prompt rather than typing it into a cell, so it never lands in the saved notebook:

```python
import os, getpass
os.environ["KATONIC_BASE_URL"] = "https://<your-studio-host>"
os.environ["KATONIC_API_KEY"] = getpass.getpass("API key: ")
```

The base URL is the bare host. Do not add `/public/v1`: the client adds it, and in 7.0.18 an address that already ends with it does not work.

  
**Step 3. Make a call from a cell**

A notebook kernel already runs an event loop, so call your function with `await`, not `asyncio.run()`:

```python
from katonic import KatonicClient

async def main():
    async with KatonicClient() as k:
        agents = await k.list_agents()
        print([a.id for a in agents])
        resp = await k.chat("<agent-id>", "Summarise the leave policy.")
        print(resp.message.content)

await main()
```

Replace the placeholder with an id from the printed list. Use `chat()` without `stream=True`; in 7.0.18 the streaming form of `chat()` fails with a JSON decode error.

  
**Step 4. Revoke the key when you finish**

Open **API keys** in the Developer Hub and revoke the key you made for the workspace. Anyone who can read the workspace's files or environment could otherwise reuse it.

## Verify

`pip show katonic-sdk` reports version 7.0.18, `import katonic` succeeds, and `await k.list_agents()` returns the published agents your key can see. An empty list with no error means the key works but sees no published agents.

## Troubleshooting

| What you see | What to do |
| --- | --- |
| No matching distribution found for `katonic-sdk>=7` | The workspace runs Python 3.10 or older. Create a workspace on **JupyterLab · Python 3.11** or a newer image. |
| `ValueError: No Katonic API key` | The key variable is not set in this kernel. Set it again after a kernel restart. |
| `RuntimeError` about a running event loop | The cell calls `asyncio.run(main())`. End it with `await main()`. |
| Every call fails with an HTTP error, and the base URL ends in `/public/v1` | Set it to the bare Studio host; the client adds the path. |
| HTTP 401 | The key is wrong, expired or revoked. |
| HTTP 403 | The key lacks the scope this call needs, or the platform does not allow the call over the public API; see [SDK methods and the katonic command](/developers/libraries/python-sdk-methods). |
| `import katonic` loads something else | The legacy `katonic` package is installed in the same environment. Use a fresh workspace or environment for the SDK. |

## Related

- [The Python SDK](/developers/libraries/python-sdk)
- [SDK methods and the katonic command](/developers/libraries/python-sdk-methods)
- Create a workspace in the help centre
- The Developer Hub

Source: https://docs.katonic.ai/developers/libraries/python-sdk-workspace
