SDK API reference

The wrapper SDK has a small public surface: init(), shutdown(), a config object, and the automatic model-capture helpers (wrap= on init() in Python; wrapAnthropic() / wrapOpenAI() in TypeScript — see the Quickstart). Everything else — AGT identity, hash chain, framework adapters — lives in Microsoft's Agent Governance Toolkit. We don't re-document AGT here. See the AGT repo for the AuditLog / AuditLogger API.

Install

Both SDKs pull Microsoft AGT in automatically. No extras to remember.

Python

1pip install wytness-ai

agent-governance-toolkit[full]==4.1.0 is a hard dependency — installed automatically. We wrap AGT's audit log cleanly so framework adapters work unchanged. Requires Python 3.11+.

TypeScript

1npm install @wytness/ai

@microsoft/agent-governance-sdk@5.0.0 is a hard dependency since version 0.2.0-dev.0. Targets Node 18+ — uses the global fetch. Ships ESM + CJS dual output.

init()

Resolves config, builds the shared transport, constructs audit + event sinks, and (when auto_wire / autoWire is True, the default) wires AGT's audit log so every entry it chains is forwarded into the Wytness envelope path. Idempotent — a second call returns the existing config without rebuilding.

Python

1import wytness_ai
2 
3config = wytness_ai.init(
4    # Reads from WYTNESS_* env vars by default — all of these are optional
5    # kwargs that override the env var lookup.
6    api_key="wyt_api_live_...",
7    endpoint="https://api.wytness.ai",
8    signing_key="<base64 Ed25519 private>",
9    # PII keys are optional but paired — supply both to enable
10    # pseudonymisation, or neither for no-PII mode. Mismatched pair
11    # raises ConfigError at init time.
12    pii_pubkey="<base64 X25519 public>",
13    pii_secret="<base64 HMAC secret>",
14 
15    # Behaviour flags
16    auto_wire=True,            # Auto-wire AGT's audit log. Default True.
17    batch_size=100,            # Events per batch flush. Default 100.
18    flush_interval_ms=5000,    # Max ms between flushes. Default 5000, min 100.
19 
20    # PII fields — dotted-path list of values to pseudonymise.
21    pii_fields=["customer.email", "customer.name"],
22)

TypeScript

1import { init } from "@wytness/ai";
2 
3const config = await init({
4  // Reads from WYTNESS_* env vars by default — all of these are optional
5  // kwargs that override the env var lookup.
6  apiKey: "wyt_api_live_...",
7  endpoint: "https://api.wytness.ai",
8  signingKey: "<base64 Ed25519 private>",
9  // PII keys are optional but paired — supply both to enable
10  // pseudonymisation, or neither for no-PII mode. Mismatched pair
11  // raises ConfigError at init time.
12  piiPubkey: "<base64 X25519 public>",
13  piiSecret: "<base64 HMAC secret>",
14 
15  // Behaviour flags
16  autoWire: true,            // Auto-wire AGT's audit logger. Default true.
17  batchSize: 100,            // Events per batch flush. Default 100.
18  flushIntervalMs: 5000,     // Max ms between flushes. Default 5000, min 100.
19 
20  // PII fields — dotted-path list of values to pseudonymise.
21  piiFields: ["customer.email", "customer.name"],
22});

Config parameters

Environment variables

The SDK reads these as process environment variables by default — set them in your secrets manager (Azure Key Vault, AWS Secrets Manager, Vercel env, k8s secrets, etc.) or, for local dev, a .env file loaded by python-dotenv / Node’s --env-file. Either way, init() reads from os.environ / process.env — call it with no args.

shutdown()

Flushes the in-flight batch, unwires the audit hook, and tears down the transport. Idempotent — safe to call before init() or twice. Returns True if everything flushed within the timeout.

Python

1# Default timeout 5000 ms
2ok = wytness_ai.shutdown()
3 
4# Or with a custom timeout
5ok = wytness_ai.shutdown(timeout_ms=2000)

TypeScript

1// Default timeout 5000 ms
2const ok = await shutdown();
3 
4// Or with a custom timeout
5const ok2 = await shutdown(2000);

Manual wiring (auto_wire=False)

Auto-wire hooks AGT's audit log so every entry it chains flows into Wytness without you touching your existing AGT code. If you'd rather wire it explicitly, set auto_wire=False / autoWire: false and write to the audit sink directly.

Python

1import wytness_ai
2 
3wytness_ai.init(auto_wire=False)
4 
5# Access the sink that init() built. write() accepts either a fully-canonical
6# snake_case dict or the AGT AuditEntry shape — the canonical transform
7# runs at the sink boundary.
8transport = wytness_ai.get_transport()

TypeScript

1import { init, getAuditSink } from "@wytness/ai";
2 
3await init({ autoWire: false });
4 
5const sink = getAuditSink()!;
6sink.write({
7  agentId: "agent-1",
8  action: "tool_invocation:search_web",
9  decision: "allow",
10  hash: "<sha-256>",
11  previousHash: "0".repeat(64),
12  data: { query: "..." },
13});

setNextEntryExtras() (TypeScript only)

Microsoft's TypeScript AGT SDK accepts a small camelCase entry shape on AuditLogger.log() — agentId, action, decision, resource, previousHash, hash. Wytness extras (data, outcome, resource) aren't part of AGT-TS's surface, so stash them on the next entry with setNextEntryExtras(...).

1import { setNextEntryExtras, AuditLogger } from "@wytness/ai";
2 
3const audit = new AuditLogger();
4 
5setNextEntryExtras({
6  data: { customer: { email: "alice@example.com" }, query: "..." },
7  outcome: "success",
8  resource: "https://example.com",
9});
10 
11audit.log({
12  agentId: "audit-test-agent",
13  action: "tool_invocation:search_web",
14  decision: "allow",
15});

Python doesn't need this — AGT's Python AuditLog.log() takes data=, outcome=, and resource= as named parameters, so they can be passed inline. The full signature is log(event_type, agent_did, action, resource=None, data=None, outcome="success", policy_decision=None, trace_id=None) — it does not accept arbitrary keyword arguments. Custom fields belong inside data={...}.

Errors

Both SDKs raise a small typed hierarchy rooted at WytnessSDKError — catch that to handle the whole family.

Diagnostics

Three read-only helpers expose SDK state for your own /healthz integration. All are safe to call at any time, initialised or not.

CLI

Both packages ship a wytness-ai command (python -m wytness_ai / npx @wytness/ai). All commands read the same WYTNESS_* env vars and never generate keys — customer-held keys come from the dashboard Keys page.

Dead-letter file

If the transport can't reach /ingest after retries, the batch is written to a local dead-letter file at ~/.wytness/wytness-deadletter.jsonl — one CloudEvents envelope per line, plain JSONL. Replay is manual: the wrapper endpoint expects a JSON array, so wrap the lines with jq -s before POSTing.

1jq -s . ~/.wytness/wytness-deadletter.jsonl | curl -X POST https://api.wytness.ai/ingest \
2  -H "Content-Type: application/vnd.wytness.agt+json" \
3  -H "Authorization: Bearer $WYTNESS_API_KEY" \
4  --data-binary @-

REST API — bulk event export

GET /export streams your org's audit events as CSV or JSONL — the full column set including encrypted_token_map, the AGT chain values, and the envelope signature, so exports stay verifiable and your PII stays decryptable offline. It's the same API the dashboard's Export page drives. Authenticate with a dashboard-issued access token (Authorization: Bearer); rate limit 5/minute; JSONL requires the JSONL-export plan feature.

A single response returns at most 100,000 rows. When more rows match, the response carries X-Export-Truncated: true, X-Export-Row-Limit, and X-Export-Total-Rows (rows remaining from the cursor position). Walk the full history by re-requesting with after= set to the last row's event_id until the truncation header disappears. Ordering is deterministic — timestamp ascending with event_id as the tie-break — so pages never overlap or skip rows.

1# Page 1
2curl -sD headers.txt "https://api.wytness.ai/export?from_ts=2026-01-01T00:00:00&to_ts=2026-07-01T00:00:00&format=jsonl" \
3  -H "Authorization: Bearer $ACCESS_TOKEN" -o page1.jsonl
4 
5# While headers.txt contains X-Export-Truncated: true, continue from the last event_id
6last=$(tail -1 page1.jsonl | jq -r .event_id)
7curl -s "https://api.wytness.ai/export?from_ts=2026-01-01T00:00:00&to_ts=2026-07-01T00:00:00&format=jsonl&after=$last" \
8  -H "Authorization: Bearer $ACCESS_TOKEN" -o page2.jsonl

Related

• Quickstart (Python)
• Quickstart (TypeScript)
• PII Protection
• Event schema
• Built on AGT — the two ways in (wrapper + direct), feature matrix, and how to choose