SDKs & Instrumentation

Interface preview

The SDK packages below are in active development. The interfaces shown are the committed design direction and may change before first release. What is shipped today: the resolver ladder (zero-code) and the header wire protocol (works from any language now).

Most attribution needs no code at all — SSO tokens, proxy headers, workload identity, and key mapping resolve ownership from infrastructure you already run. SDKs exist for the layer infrastructure can't see: which business workflow a call belongs to, and how an agent run is structured (branches, sub-agents, what contributed to the final output).

One principle across all languages: you declare business context once — the SDK carries it, propagates it, and speaks the wire protocol for you.

IdentityInfrastructure firstSSO, proxy, workload identity, or key mapping resolves ownership.

SDKWorkflow scopeThe app declares business context once around the work.

RuntimeClient wrapperCalls keep using the model client and provider shape they already use.

EvidenceLineage in the reportBranches, retries, fallbacks, and contribution markers become inspectable.

SDK workflow scopes turn agent execution structure into report evidence instead of leaving it as invisible application behavior.

Python — blackridge

Wrap the client you already use; nothing else changes:

from blackridge import Attribution, wrap
from openai import OpenAI

client = wrap(
    OpenAI(base_url=BRG_GATEWAY_URL),
    attribution=Attribution(app="support-portal", team="payments"),
)

Declare workflow context with a scope; every call inside it is attributed and lineage-linked automatically (context propagates via contextvars, including through asyncio):

import blackridge as brg

with brg.workflow("refund-agent", display_name="Refund processing"):
    triage = client.chat.completions.create(...)      # attributed + linked

    with brg.branch("policy-check"):                  # agent branch
        result = client.chat.completions.create(...)

    brg.contributed(triage)   # marks calls that fed the final output

Framework middleware receives inbound identity and starts the workflow scope: blackridge.fastapi / blackridge.django middleware, plus a LangChain callback handler and CrewAI/AutoGen hooks that map agent steps to branches without hand-instrumentation.

TypeScript / Node — @northwatch/blackridge

import { wrap, workflow } from "@northwatch/blackridge";
import OpenAI from "openai";

const client = wrap(new OpenAI({ baseURL: BRG_GATEWAY_URL }), {
  app: "support-portal",
  team: "payments",
});

await workflow("refund-agent", async () => {
  const res = await client.chat.completions.create(...); // attributed + linked
});

Context propagates via AsyncLocalStorage. Express/Fastify/Next middleware lifts identity from the inbound request (session, IdP token) into the workflow scope. A plain fetch wrapper covers non-OpenAI clients.

Go — github.com/northwatch-systems/blackridge-go

transport := blackridge.NewTransport(http.DefaultTransport,
    blackridge.Attribution{App: "support-portal", Team: "payments"})

ctx = blackridge.WithWorkflow(ctx, "refund-agent")
resp, err := client.Do(req.WithContext(ctx)) // RoundTripper stamps the wire protocol

http.RoundTripper wrapper plus context.Context carriers — idiomatic Go, no globals.

What every SDK guarantees

• Attribution via constructor, workflow via scope — no per-call header bookkeeping.
• Lineage without effort — parent/root/branch linkage derived from the active scope, so abandoned-branch waste and retry grouping get explicit (not heuristic) evidence.
• Declared context is graded OBSERVED — SDK context is caller_provided, the highest-provenance source.
• Body-free — SDKs send identity and structure only; never prompt or completion content.
• Escape hatch preserved — everything an SDK does is expressible as headers; the SDK is convenience and correctness, not lock-in.

No SDK for your language?

The wire protocol is plain HTTP headers and works from anything today — see agent integration for the minimal set, and the instrumentation guide for full lineage semantics.