runkite-runner

Python runner for Runkite, a self-hosted Agent Protocol control plane.

This package is the process that does the work: it connects to a Runkite control plane over gRPC, claims jobs, loads your agent from langgraph.json, executes LangGraph, and streams events, heartbeats, and terminal status back so clients see live SSE / WebSocket progress in the Admin UI.

  Client / SDK ──HTTP/SSE──► Runkite control plane (Go)
                                    │ gRPC Runner Protocol
                                    ▼
                           runkite-runner (this package)
                                    │
                              your LangGraph agent

Why a separate runner?

Runkite keeps the control plane framework-agnostic (auth, threads, runs, queues, Admin UI). Framework-specific execution lives in a runner so you can scale workers independently, mix Python and TypeScript agents on one plane, and upgrade LangGraph without redeploying the Go binary.

Install

pip install runkite-runner

Requires Python 3.11+. Pulls in LangGraph, gRPC, checkpoint Postgres support, httpx, and uvicorn (see pyproject.toml). Tracing is optional:

pip install 'runkite-runner[otel]'

Without the extra, the runner still starts; OTEL_* env vars log once and stay no-op until the packages are installed.

Quick start

1. Control plane (pick one):

# Docker
docker pull ghcr.io/getrunkite/runkite:latest
docker run --rm -p 2026:2026 -p 50051:50051 \
  -e RUNKITE_ALLOW_INSECURE_SERVE=1 \
  ghcr.io/getrunkite/runkite:latest \
  dev --config /app/examples/echo_agent/langgraph.json

# or binary from https://github.com/getrunkite/runkite/releases

2. Runner (this package):

runkite-runner \
  --config path/to/langgraph.json \
  --grpc-address 127.0.0.1:50051 \
  --http-address http://127.0.0.1:2026

3. Admin UI: http://127.0.0.1:2026/admin/

Minimal langgraph.json:

{
  "graphs": {
    "echo_agent": "./graph.py:graph"
  },
  "dependencies": ["."]
}

Examples live in the Runkite repo (echo_agent, react_agent, approval_agent, …).

Features

• LangGraph graphs with streaming chunks, cancel, and HITL interrupt/resume
• Durable checkpoints via AsyncPostgresSaver when POSTGRES_DSN points at the control plane's Postgres database; otherwise via the HTTP checkpoint proxy when an HTTP address is configured. MemorySaver is the ephemeral fallback when neither is available. An explicitly blank RUNKITE_HTTP_URL selects that local fallback.
• Store / vector dual-mode against the control plane's APIs
• Concurrency: --concurrency N / RUNKITE_CONCURRENCY for overlapping I/O-bound jobs
• OpenTelemetry: runkite.run span under the control plane traceparent, plus thin runkite.llm / runkite.tool children when OTLP env is set
• Production auth: runner kind tokens (RUNNER_TOKEN / RUNNER_TOKEN_*) matching control-plane config

Framework adapters from a checkout

The published Python package and its CLI run LangGraph. CrewAI, LlamaIndex, AutoGen and plain LangChain adapters live under python/adapters/ in the source tree and share runkite_runner.generic_worker. They are not included by pip install runkite-runner and are not separate PyPI packages. Install the chosen adapter from a clone with its isolated dependencies. See docs/runners.md.

The managed Vercel AI SDK runner in the working tree is a TypeScript backend, not a Python CLI mode, and requires an updated checkout build until released. Microsoft Agent Framework currently has checkout-only function governance middleware in python/runkite_governance, not a managed runner. That helper keeps the model loop and pending continuation in the app and creates no Runkite thread or run. See the SDK integration guide.

Configuration

Related artifacts

Links

• Homepage: https://getrunkite.com/
• Source: https://github.com/getrunkite/runkite/tree/main/python
• Issues: https://github.com/getrunkite/runkite/issues
• Changelog: https://github.com/getrunkite/runkite/blob/main/CHANGELOG.md
• Known limitations: https://github.com/getrunkite/runkite/blob/main/docs/limitations.md
• Security: https://github.com/getrunkite/runkite/blob/main/SECURITY.md