> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> karta-runtime - embed Karta in-process or serve it over HTTP.

`karta-runtime` is the Python SDK. It embeds an agent
in your own Python process or serves it over HTTP. It is also the engine behind
the [`karta` CLI](/cli/overview)'s `karta dev`, which bootstraps it for you.

## Install

```bash theme={null}
pip install karta-runtime

# optional session backends:
pip install karta-runtime[postgres]   # PostgreSQL
pip install karta-runtime[s3]         # S3
```

You also need a [supported harness](/build/supported-harnesses) installed for
the agent project you want to run.

## The two entry points

<CardGroup cols={2}>
  <Card title="Karta" icon="cube" href="/sdks/python/karta">
    The orchestrator. Detects your harness, discovers agents, and sends/streams
    turns.
  </Card>

  <Card title="Session" icon="comments" href="/sdks/python/sessions">
    A multi-turn handle with participants and agent handoff.
  </Card>
</CardGroup>

## Three lines to a response

```python theme={null}
from karta import Karta

app = Karta()                              # auto-detects the harness here
print(app.send_sync("Hello!").text)
```

Karta detects the harness from the current directory: `.claude/` or
`CLAUDE.md` means Claude Code, `.opencode/` means OpenCode, `.deepagents/`
means DeepAgents, `.goose/` means Goose, and `.codex/config.toml` means Codex CLI.

## Sync and async, send and stream

Every send has four shapes - sync/async x accumulated/streamed:

```python theme={null}
# accumulated (a final Response)
resp = app.send_sync("...")              # sync
resp = await app.send("...")             # async

# streamed (typed events)
for event in app.stream_sync("..."):     # sync
    ...
async for event in app.stream("..."):    # async
    if event.type == "text":
        print(event.data["part"]["text"], end="")
```

See [Streaming events](/concepts/streaming-events) for the event model.

## Serve over HTTP

Run your agent behind the [HTTP API](/api-reference/introduction) locally with
the CLI - the same session API production serves:

```bash theme={null}
karta dev
```

To run it in production, [deploy it](/deploy/deploy-loop).

## Where to go

<CardGroup cols={2}>
  <Card title="Karta reference" icon="cube" href="/sdks/python/karta">
    Constructor, properties, and every method.
  </Card>

  <Card title="Hooks & policies" icon="webhook" href="/sdks/python/hooks-and-policies">
    React to lifecycle events; gate messages with policies.
  </Card>
</CardGroup>