Use the SDK in a workspace
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
- Install the SDK into the workspace
Open a terminal in the workspace, or a notebook cell, and install it for your user:
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 withpip show katonic-sdk; it should report 7.0.18. - 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:
import os, getpassos.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. - Make a call from a cell
A notebook kernel already runs an event loop, so call your function with
await, notasyncio.run():from katonic import KatonicClientasync 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()withoutstream=True; in 7.0.18 the streaming form ofchat()fails with a JSON decode error. - 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. |
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
- SDK methods and the katonic command
- Create a workspace in the help centre
- The Developer Hub