nightly-sdk

The Python SDK for Nightly, the on-call engineer for your AI agents.

AI agents rarely fail loudly. A prompt change, a model swap or a tool update ships, and the agent starts answering wrong, looping, refunding money it shouldn't, or failing its tools, while every request still returns HTTP 200. Nightly watches your agent's traces and outcomes, investigates when something breaks (traces, deploy log, diff, the coding-agent prompt behind the change), prices the damage, and applies the reversible fix your policy allows: roll back the release, fail over the model, switch off a capability, or cap the steps. It proves the fix by replaying the failed runs through your agent, then pages you once in Slack. Anything irreversible waits for your approval.

This SDK is how your agent takes part. With it, your agent can:

• Read its control plane (release, model, feature flags, step cap) so Nightly can steer it during an incident without a redeploy.
• Report deploys and outcomes so Nightly knows what changed and what a bad run costs.
• Run verification replays so a fix is proven on real failed inputs before Nightly calls it done.

It has no dependencies and fails open. If Nightly is unreachable, every call returns the default you passed, so the SDK can never take your agent down.

Install

pip install nightly-sdk

Python 3.9+. Pair it with neatlogs tracing (pip install neatlogs), which is where Nightly reads your agent's traces from.

Get a token

Sign in to Nightly with GitHub and open Connect an agent. Creating the agent shows its token (nsa_...) once. You can rotate it from the agent's page at any time.

export NIGHTLY_API_URL=https://<your Nightly API>
export NIGHTLY_AGENT_TOKEN=nsa_...

Quickstart

import neatlogs
from nightly_sdk import Nightly

neatlogs.init(api_key=NEATLOGS_KEY, workflow_name="support-agent")
ns = Nightly()  # reads NIGHTLY_API_URL and NIGHTLY_AGENT_TOKEN


def handle(ticket: str, dry_run: bool = False) -> dict:
    prompt = load_prompt(ns.release("v12"))        # the release Nightly says is live
    model = ns.model("claude-haiku")                # a failover model during a provider outage
    max_steps = ns.max_steps(8)                     # Nightly can lower it to stop a loop
    tools = TOOLS if ns.flag("auto_refunds", True) else TOOLS_WITHOUT_REFUNDS  # kill switch

    result = run_agent(ticket, prompt, model, tools, max_steps, dry_run=dry_run)

    if not dry_run:
        ns.record("ok" if result.ok else "failed", value_usd=result.money_lost)
    return {"ok": result.ok, "output": result.text}


# Let Nightly verify a fix by replaying failed inputs through the agent, with no side effects.
ns.serve_replays(lambda text: handle(text, dry_run=True))

In CI, when you ship:

Nightly().report_deploy("v13", commit=GIT_SHA)

API

report_deploy and record return True when Nightly accepted the call. They never raise.

Privacy

The SDK sends only what you pass to it: deploys, outcomes, the run details you choose, and replay results. Prompts and outputs stay in your own neatlogs project unless you pass them to record.

Links

• Website: https://web-emrq.vercel.app
• Docs: https://web-emrq.vercel.app/docs
• Source: https://github.com/e-man07/neat-hacks/tree/main/sdk/python