Skip to main content

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​

  1. 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 with pip show katonic-sdk; it should report 7.0.18.

  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:

    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.

  3. Make a call from a cell

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

    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.

  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 seeWhat to do
No matching distribution found for katonic-sdk>=7The workspace runs Python 3.10 or older. Create a workspace on JupyterLab · Python 3.11 or a newer image.
ValueError: No Katonic API keyThe key variable is not set in this kernel. Set it again after a kernel restart.
RuntimeError about a running event loopThe cell calls asyncio.run(main()). End it with await main().
Every call fails with an HTTP error, and the base URL ends in /public/v1Set it to the bare Studio host; the client adds the path.
HTTP 401The key is wrong, expired or revoked.
HTTP 403The 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 elseThe legacy katonic package is installed in the same environment. Use a fresh workspace or environment for the SDK.

Describes the platform as of .

Was this page helpful?