Agent SDK Overview

Build governed AI agents that automatically enforce policies, attribute costs, and produce audit-grade evidence. The Keeptrusts Agent SDK gives you the same governance controls that power enterprise deployments — programmable in TypeScript and Python.

import { createAgentRuntime } from "@keeptrusts/agent";

const agent = createAgentRuntime({
  agentId: "agent-ops-reviewer",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  apiUrl: "https://api.keeptrusts.example",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN,
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
});

const result = await agent.chat({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "Review today's policy escalations." }],
});

// Every request is automatically governed, attributed, and traceable
console.log(result.requestId);      // correlation key
console.log(result.agentId);        // identity attestation
console.log(result.costAttribution); // per-request spend from events

The Agent SDK includes built-in governance enforcement, request correlation, spend attribution, and evidence collection — so your agent ships with enterprise-grade controls from day one.

Get started

1. Install the SDK

npm install @keeptrusts/agent

The agent package composes @keeptrusts/gateway (browser-safe governed inference) and @keeptrusts/control-plane (server-only privileged operations) into a single server-side runtime surface.

2. Set your credentials

export KEEPTRUSTS_API_TOKEN=kt-your-api-token
export KEEPTRUSTS_GATEWAY_URL=https://gateway.keeptrusts.example/v1
export KEEPTRUSTS_API_URL=https://api.keeptrusts.example

The SDK supports two credential tiers:

Credential	Purpose	Required
API token (KEEPTRUSTS_API_TOKEN)	Gateway inference traffic (data-plane) and control-plane operations	Yes

3. Register your agent

import { registerAgent } from "@keeptrusts/agent";

const agent = await registerAgent({
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
  apiUrl: process.env.KEEPTRUSTS_API_URL,
  name: "ops-reviewer",
  description: "Reviews daily escalations and produces evidence bundles",
});

console.log(agent.id); // use this as your agentId going forward

Or register through the console at Agents → Create Agent.

4. Run your first governed request

import { createAgentRuntime } from "@keeptrusts/agent";

const agent = createAgentRuntime({
  agentId: "agent-ops-reviewer",
  gatewayUrl: process.env.KEEPTRUSTS_GATEWAY_URL,
  apiUrl: process.env.KEEPTRUSTS_API_URL,
  accessKey: process.env.KEEPTRUSTS_API_TOKEN,
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
});

const result = await agent.chat({
  model: "gpt-5.4-mini",
  messages: [{ role: "user", content: "What files need review?" }],
});

console.log(result.choices[0]?.message?.content);

Every request automatically:

• attaches x-keeptrusts-agent-id for attribution
• generates and forwards x-request-id for correlation
• propagates traceparent for distributed tracing
• enforces all gateway policies (redaction, firewall, escalation)
• records a decision event with cost attribution

Capabilities

Governed inference

Your agent's requests pass through the full Keeptrusts policy chain:

Capability	What it does
Policy enforcement	Input and output policies applied automatically
Request correlation	Every request gets a unique x-request-id
Agent attribution	x-keeptrusts-agent-id links requests to the registered agent
Cost attribution	event_cost_attribution on every decision event
Streaming support	Full SSE streaming preserved end-to-end
Provider routing	Gateway routes to configured upstream providers

Observability

Read back what happened after any request:

const events = await agent.listEvents({ requestId: result.requestId });
const event = events[0];

console.log(event.event_cost_attribution);
console.log(event.policy_outcome);
console.log(event.source_spend_log_id);

Evidence collection

Produce audit-grade proof for any request window:

const bundle = await agent.createEvidenceBundle({
  requestId: result.requestId,
});

// bundle contains: event, trail records, digest, public key, verification
console.log(bundle.verification.chain_integrity); // true

Agent-scoped views

The SDK defaults to agent-scoped reads before org-wide views:

const actions = await agent.listActions();     // this agent's actions
const stats = await agent.getStats();          // this agent's stats
const snapshots = await agent.listSnapshots(); // deployment history

Deployment and gateway management

await agent.setDeployment({ status: "active", version: "1.2.0" });
await agent.addGateway("gateway-prod-us-east");
await agent.removeGateway("gateway-staging");

Compare the Agent SDK to other Keeptrusts SDKs

	Agent SDK	Gateway SDK	Control-Plane SDK
Runtime	Server-only	Browser-safe	Server-only
Governed inference	✓	✓	✗
Agent identity	Automatic	Manual header	N/A
Event reads	✓	✗	✓
Trail and evidence	✓	✗	✓
Agent provisioning	✓	✗	✓
Wallet reads	✓ (billing helpers)	✗	✓
MCP consumption	✓ (gateway-owned)	✓ (gateway-owned)	✗

Use the Agent SDK when you need both governed inference and privileged control-plane access in the same runtime.

Use the Gateway SDK when you only need to route model traffic through the gateway from browser or server code.

Use the Control-Plane SDK when you need privileged reads (events, trail, wallets) without sending inference traffic.

Architecture

┌─────────────────────────────────────────────┐
│              Agent Runtime                    │
│                                              │
│  ┌──────────────┐    ┌───────────────────┐  │
│  │ @keeptrusts/ │    │  @keeptrusts/     │  │
│  │   gateway    │    │  control-plane    │  │
│  └──────┬───────┘    └────────┬──────────┘  │
│         │                     │              │
└─────────┼─────────────────────┼──────────────┘
          │                     │
          ▼                     ▼
┌──────────────────┐   ┌────────────────────┐
│  Keeptrusts      │   │  Keeptrusts        │
│  Gateway         │   │  Control-Plane API │
│                  │   │                    │
│ • Policy chain   │   │ • Events           │
│ • Provider route │   │ • Trail & digests  │
│ • MCP bridge     │   │ • Agents           │
│ • Cost tracking  │   │ • Wallets          │
└──────────────────┘   └────────────────────┘

Next steps

• Quickstart — build your first governed agent in 5 minutes
• Capabilities — full feature reference
• Configuration — environment, adapters, and runtime options
• Observability — events, spend, and request correlation
• Evidence & Audit — trail verification and evidence bundles
• MCP Integration — consume gateway-owned tools
• Enterprise Operations — bulk registration, rotation, and rollout