| title | Install |
|---|---|
| description | Install the NullRun Python SDK, create an API key, and see which HTTP clients and agent frameworks the SDK instruments automatically. |
| maturity | stable |
pip install nullrunThe package needs Python 3.10 or newer. It depends on httpx and nothing else.
python -c "from nullrun import protect; print('ok')"Sign in at nullrun.io. Open Access → API keys and click New key. The dialog asks for a name, a workflow, and when the key expires.
The key is enough. The SDK signs its requests with the key and fetches the matching signing secret from POST /api/v1/auth/verify on first use. Without a key the SDK raises NullRunAuthenticationError with the code NR-C001.
export NULLRUN_API_KEY=nr_live_...Set NULLRUN_SECRET_KEY yourself only if your secret manager already holds the signing secret.
Instrumentation attaches when the runtime starts — at init(), or at the first @protect call if you never call init(). The SDK patches the HTTP client and each agent framework it recognises. A framework that is not installed is skipped.
| Package | What the SDK attaches |
|---|---|
httpx |
Token counting for every provider built on it |
requests |
Token counting through Session.send |
langchain-core |
Callback manager and chat model hooks |
openai-agents |
Runner.run and Runner.run_sync |
langgraph |
Pregel.invoke, stream, ainvoke, astream |
llama-index |
LLM chat-end and function-call events |
crewai |
Crew.kickoff and kickoff_async |
autogen |
BaseChatAgent.on_messages and the OpenAI chat client |
Provider traffic is recognised by host, not by package:
| Host | Provider |
|---|---|
api.openai.com |
OpenAI |
openai.azure.com |
Azure OpenAI |
api.anthropic.com |
Anthropic |
generativelanguage.googleapis.com |
Gemini |
api.cohere.ai |
Cohere |
api.mistral.ai |
Mistral |
bedrock-runtime.amazonaws.com |
Bedrock |
NullRun never imports a vendor package. Install the vendor package you already use.
Install the framework next to the SDK. No extra is needed for any of them.
pip install nullrun langgraph langchain-openai
pip install nullrun crewai
pip install nullrun openai-agents| Extra | Installs | When you need it |
|---|---|---|
nullrun[websocket] |
websockets |
Real-time workflow state push. Without it the SDK polls the gateway for state changes, and a kill or pause takes longer to reach the agent. |
nullrun[opentelemetry] |
opentelemetry-api, opentelemetry-sdk |
Exporting spans to an OpenTelemetry collector. |
nullrun[dev] |
websockets, pytest, pytest-asyncio, pytest-rerunfailures, pytest-xdist, pytest-cov, respx, coverage, httpx, mypy, ruff, langchain-core, fastapi, tomli (Python 3.10 only) |
Running the SDK test suite locally. |
pip install "nullrun[websocket]"The SDK logs one warning when @protect has run 50 times and the SDK has seen no LLM call. The gate is enforced, but no cost is booked. The usual causes are a raw httpx client outside the instrumented surface, a custom transport, or a framework that is not on the list above.