SDK Documentation

import blackbox_sdk as bb

bb.configure(api_url="https://blackbox-gold.vercel.app
")

with bb.run("my_first_run", model="claude-sonnet-4-6", system_prompt="You are a helpful assistant.") as r:
    r.reasoning("Analysing the user request...")
    r.tool_call("web_search", result={"query": "...", "hits": []})
    r.output("Here is the answer.", cost_usd=0.0031, latency_ms=820)
    r.seal()

# Run is now sealed, chain is valid, replay at:
# https://blackbox-gold.vercel.app
/v1/runs/my_first_run

pip install blackbox-sdk

git clone https://github.com/Leclezio69/blackbox.git
cd blackbox/sdk && pip install -e .

with bb.run("run_id", model="gpt-4o", system_prompt=SYSTEM) as r:
    for step in agent_loop():
        if step.type == "reasoning":
            r.reasoning(step.title, payload=step.data)
        elif step.type == "tool":
            # timed_tool_call(tool, inputs, fn, *args) executes fn and records latency
            result = r.timed_tool_call(step.tool_name, step.args, execute_tool, step.tool_name, step.args)
        elif step.type == "output":
            r.output(step.text, cost_usd=step.cost, latency_ms=step.ms)
    r.seal()
# If an exception escapes, it's recorded as a fault event automatically.

import blackbox_sdk as bb

async with bb.async_run("my_async_run", model="claude-sonnet-4-6", system_prompt=SYSTEM) as r:
    await r.reasoning("Planning the response...")
    result = await my_async_tool()
    await r.tool_call("my_tool", result=result)
    await r.output("Done.", tokens_in=200, tokens_out=40, cost_usd=0.0018)
    await r.seal()

import blackbox_sdk as bb

# Call once at startup — before any LLM calls
bb.configure(api_url="https://blackbox-gold.vercel.app
")
bb.instrument()  # patches openai + anthropic clients

# Every client.messages.create() / client.chat.completions.create()
# is now automatically recorded as a BLACKBOX run.
# Pass record_openai=False or record_anthropic=False to selectively disable.
bb.instrument(record_openai=False)  # Anthropic only

import httpx

run = httpx.get("https://blackbox-gold.vercel.app
/v1/runs/my_run_001").json()
print(run["chain_valid"])       # True
print(run["event_count"])       # e.g. 4
print(run["first_broken_seq"])  # None if valid

# Public audit certificate — no API key needed, share with any auditor:
cert = httpx.get("https://blackbox-gold.vercel.app
/v1/audit/my_run_001").json()
print(cert["chain_valid"])      # True
print(cert["chain_head_hash"])  # sha256 of final event

npm install @blackbox-ai/sdk
# or
pnpm add @blackbox-ai/sdk

import { BlackboxClient } from "@blackbox-ai/sdk";

const bb = new BlackboxClient({
  apiUrl: process.env.BLACKBOX_API_URL,
  apiKey: process.env.BLACKBOX_AGENT_KEY,
});

const run = bb.run("invoice-review-4821");

await run.genesis({
  system_prompt: "You are a financial analyst.",
  model_snapshot: "gpt-4o",
  tools: ["ocr_extract", "calculator"],
});

await run.reasoning("Analysing the invoice...");
await run.toolCall("ocr_extract", { path: "/tmp/invoice.pdf" });
await run.reasoning("No anomalies detected.");
await run.seal();

// Verify the chain:
const cert = await bb.getAuditCertificate("invoice-review-4821");
console.log(cert.chain_valid); // true

import { instrument } from "@blackbox-ai/sdk";

// Call once at startup — before any LLM calls
instrument({ apiUrl: process.env.BLACKBOX_API_URL });

// Every OpenAI/Anthropic call is now auto-recorded.
// Pass recordOpenAI: false or recordAnthropic: false to be selective:
instrument({ apiUrl: "...", recordOpenAI: false }); // Anthropic only

# Append an event
curl -X POST https://blackbox-gold.vercel.app
/v1/events \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "my_run_001",
    "type": "genesis",
    "title": "Run started",
    "genesis": {
      "system_prompt": "You are a helpful assistant.",
      "tools": ["web_search"],
      "model_snapshot": "claude-sonnet-4-6",
      "sampling": {"temperature": 0.3}
    }
  }'

# Replay the run
curl https://blackbox-gold.vercel.app
/v1/runs/my_run_001

# Zero-config: set env vars, done
export OTEL_EXPORTER_OTLP_ENDPOINT="https://blackbox-gold.vercel.app
"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://blackbox-gold.vercel.app
/v1/otel/traces"
export OTEL_SERVICE_NAME=my-agent

# Python: BLACKBOX accepts OTLP/HTTP JSON — use the built-in BlackboxExporter
# pip install opentelemetry-instrumentation-anthropic opentelemetry-sdk anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, SpanExporter, SpanExportResult
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
import json, urllib.request

class BlackboxExporter(SpanExporter):
    def export(self, spans):
        payload = {"resourceSpans": [{"resource": {"attributes": [
            {"key": "service.name", "value": {"stringValue": "my-agent"}}]},
            "scopeSpans": [{"spans": [{"traceId": format(s.context.trace_id,"032x"),
                "spanId": format(s.context.span_id,"016x"), "name": s.name,
                "startTimeUnixNano": str(s.start_time), "endTimeUnixNano": str(s.end_time),
                "attributes": [{"key":k,"value":{"stringValue":str(v)}}
                               for k,v in (s.attributes or {}).items()],
            } for s in spans]}]}]}
        req = urllib.request.Request("https://blackbox-gold.vercel.app
/v1/otel/traces",
            data=json.dumps(payload).encode(),
            headers={"Content-Type": "application/json"}, method="POST")
        urllib.request.urlopen(req, timeout=10)
        return SpanExportResult.SUCCESS
    def shutdown(self): pass

provider = TracerProvider()
provider.add_span_processor(SimpleSpanProcessor(BlackboxExporter()))
trace.set_tracer_provider(provider)
AnthropicInstrumentor().instrument()
# Every Anthropic call is now sealed to BLACKBOX

# Get a public certificate — no API key needed
curl https://blackbox-gold.vercel.app
/v1/audit/{run_id}