Python Quickstart

Run a script that asks Jan a question and prints its answer as it arrives.

You need Python 3.11+ and access to a model provider. No Git checkout, Node.js, Jan Desktop or Rust toolchain is needed. Python talks directly to the Jan runtime.

⚠️

The ADK is a preview and is not published to PyPI yet: pip install jan-adk does not work. Install the nightly wheel below instead. The runtime is a separate, prebuilt download.

Install the ADK and runtime

Create a demo directory and an isolated Python environment, then install the latest nightly wheel:


mkdir jan-python-demo && cd jan-python-demo
python3 -m venv .venv
source .venv/bin/activate
python -m pip install "$(python -c "import json, urllib.request as r; p = json.load(r.urlopen('https://delta.jan.ai/adk-nightly/manifest.json'))['packages']['python']; print(p['url'] + '#sha256=' + p['sha256'])")"

The command looks up the current build and installs its versioned wheel, checked against the SHA-256 the build published. The download page (opens in a new tab) shows the same command with the URL written out.

Install the jan runtime:


curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash
export PATH="$HOME/.local/bin:$PATH"


jan cli agent rpc --help

If you already have a current Jan runtime, skip its installation.

Connect a model


jan login

Or configure your own provider. Both the CLI and ADK use Jan's provider configuration. If you have already configured Jan, skip this step.

Save and run the script

Save this complete example as hello.py in jan-python-demo:


from jan_adk import JanRuntime
with JanRuntime.start() as runtime:
    session = runtime.create_session(ephemeral=True, builtins=False)
    turn = session.prompt("Explain what a mutex is in one sentence.")
    for event in turn:
        if event["type"] == "token":
            print(event["text"], end="", flush=True)
    result = turn.result()
    if result.stop_reason == "error":
        raise RuntimeError(result.error)
    print(f"\nFinished: {result.stop_reason}")


python hello.py

The answer depends on your model. A successful run prints answer text followed by Finished: completed.

What just happened?

start() launched the Jan runtime and checked its protocol version.
create_session() created a conversation. ephemeral=True avoids saving it; builtins=False disables built-in and external tool sources, so this first example only answers a question.
prompt() started a turn. Each token event contains another piece of the answer.
result() returned the final status. Leaving the with block closed the runtime, including when an exception occurred.

Send another prompt on the same session to continue the conversation. To select a specific configured model, add model="provider/model-id" to create_session().

The Python API is synchronous: iterating a turn waits for events. In an async application, run blocking ADK work in a worker thread rather than on your event loop.

If it fails

Problem	What to do
`ModuleNotFoundError: jan_adk`	Activate the demo's virtual environment and run the `pip install` command above with that Python.
The wheel download fails	No nightly is available right now. Use the source install.
Cannot start `jan`	Add it to PATH, or pass its absolute path as `JanRuntime.start(bin="/path/to/jan")`.
Unknown `rpc` command or protocol mismatch	Run `jan update`, then retry startup.
No model, authentication error, or provider error	Run `jan login` or fix the provider configuration. A model override must name a model that provider serves.

See Process & failures for error handling in an application.

Next: give the agent a function

The first script cannot act on your app. Add a host tool when you want it to read application data or perform an action.

JavaScript Quickstart Host Tools