Skip to main content

TypeScript Agent Quickstart

This quickstart shows the server-side composition pattern the Keeptrusts agent SDK follows: gateway for inference, control plane for privileged observability and verification.

Use this page when​

  • You are wiring a server-side agent runtime in TypeScript.
  • You need a working pattern before or alongside the higher-level agent helpers.
  • You want the canonical request, spend, and evidence flow in one example.

Install​

npm install @keeptrusts/gateway @keeptrusts/control-plane openai

Compose the two SDK lanes​

import {
  buildKeeptrustsHeaders,
  createKeeptrustsGatewayClient,
  generateTraceparent,
} from "@keeptrusts/gateway";
import {
  KeeptrustsControlPlane,
  getEvent,
  listEvents,
} from "@keeptrusts/control-plane";

const requestId = crypto.randomUUID();
const agentId = "agent-ops-reviewer";
const traceparent = generateTraceparent();

const gateway = createKeeptrustsGatewayClient({
  baseUrl: "https://gateway.keeptrusts.example/v1",
  apiKey: "kt-access-key",
  agentId,
  defaultHeaders: buildKeeptrustsHeaders({ requestId, agentId, traceparent }),
});

const controlPlane = new KeeptrustsControlPlane({
  baseUrl: "https://api.keeptrusts.example",
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN,
});

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

const events = await listEvents(controlPlane, {
  since: new Date(Date.now() - 5 * 60_000).toISOString(),
  requestId,
  limit: 1,
});

const event = events.events[0] ? await getEvent(controlPlane, events.events[0].event_id) : null;

console.log(completion.choices[0]?.message?.content);
console.log(event?.event_cost_attribution.source_spend_log_id);

Why this matches the agent lane​

This pattern keeps the responsibilities clean:

  • gateway SDK for governed model execution
  • control-plane SDK for privileged event and audit reads
  • one request ID stitched across the full flow

Verification add-on​

When you need evidence-grade confirmation, extend the flow with trail helpers:

import {
  downloadDigest,
  getPublicKey,
  verifyTrail,
} from "@keeptrusts/control-plane";

const verification = await verifyTrail(controlPlane, {
  startTime: "2026-05-31T00:00:00Z",
  endTime: "2026-05-31T23:59:59Z",
  deepVerify: false,
});

const publicKey = await getPublicKey(controlPlane);
const digest = await downloadDigest(controlPlane, "digest-123");

console.log(verification.chain_integrity, publicKey.kid, digest.storage_key);

Guardrails to keep​

  • keep bearer tokens server-side only
  • forward x-keeptrusts-agent-id, x-request-id, and traceparent
  • query request spend from events, not wallets
  • let the gateway own MCP transport and tool mediation

Next steps​

For AI systems​

  • The TypeScript agent pattern composes @keeptrusts/gateway and @keeptrusts/control-plane.
  • Keep the runtime server-only.
  • Use requestId to join inference, events, and evidence.

For engineers​

  • Generate one requestId per agent task or turn.
  • Pass the same identity and trace headers to the gateway and use them again when reading events.
  • Use event reads for request-level spend and trail helpers for verification.