# Python Quickstart (/agent/adk-python)

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

<Callout type="warning">
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.
</Callout>

<Steps>

### Install the ADK and runtime [#install-the-adk-and-runtime]

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

<Tabs items={['macOS / Linux', 'Windows PowerShell']}>
  <Tabs.Tab>
```bash
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'])")"
```
  </Tabs.Tab>
  <Tabs.Tab>
```powershell
mkdir jan-python-demo; cd jan-python-demo
py -3 -m venv .venv
.venv\Scripts\Activate.ps1
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'])")
```
  </Tabs.Tab>
</Tabs>

The command looks up the current build and installs its versioned wheel, checked against the
SHA-256 the build published. The [download page](https://delta.jan.ai/adk-nightly/index.html) shows
the same command with the URL written out.

Install the `jan` runtime:

<Tabs items={['macOS / Linux', 'Windows PowerShell']}>
  <Tabs.Tab>
```bash
curl -fsSL https://delta.jan.ai/jan-cli/install-jan-agent.sh | bash
export PATH="$HOME/.local/bin:$PATH"
```
  </Tabs.Tab>
  <Tabs.Tab>
```powershell
irm https://delta.jan.ai/jan-cli/install-jan-agent.ps1 | iex
```
Follow the installer's PATH instructions before continuing.
  </Tabs.Tab>
</Tabs>

```bash
jan cli agent rpc --help
```

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

### Connect a model [#connect-a-model]

Sign in to Tokamak:

```bash
jan login
```

Or [configure your own provider](/agent/quickstart#connect-a-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-and-run-the-script]

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

```python filename="hello.py"
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}")
```

```bash
python hello.py
```

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

</Steps>

## What just happened? [#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 [#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](/agent/adk-nightly#source-install-fallback). |
| 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](/agent/adk-runtime) for error handling in an application.

## Next: give the agent a function [#next-give-the-agent-a-function]

The first script cannot act on your app. Add a [host tool](/agent/adk-tools) when you want it
to read application data or perform an action.