Agent SDK Configuration

Configure the agent runtime for different deployment environments, provider preferences, and external agent framework adapters.

Environment variables

The SDK reads these variables when explicit options are not provided:

Variable	Purpose	Default
KEEPTRUSTS_API_TOKEN	API token for gateway inference and control-plane operations	—
KEEPTRUSTS_GATEWAY_URL	Gateway base URL	http://localhost:41002/v1
KEEPTRUSTS_API_URL	Control-plane API base URL	https://api.keeptrusts.com
KEEPTRUSTS_AGENT_ID	Default agent identity	—
KEEPTRUSTS_TRACE_ENABLED	Enable traceparent propagation	true
KEEPTRUSTS_RETRY_MAX	Max retry attempts	3
KEEPTRUSTS_TIMEOUT_MS	Request timeout in milliseconds	120000

Runtime options

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

const agent = createAgentRuntime({
  // Required
  agentId: "agent-compliance-bot",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  apiUrl: "https://api.keeptrusts.example",
  accessKey: "kt-access-key",
  bearerToken: "bearer-token",

  // Optional
  trace: true,                    // enable traceparent propagation
  retryMax: 3,                    // max retry attempts
  timeoutMs: 120_000,             // request timeout
  defaultModel: "gpt-5.4-mini",        // default model for chat calls
  defaultHeaders: {},             // additional headers on every request
  onEvent: (event) => {},         // callback when a decision event is received
  onError: (error) => {},         // callback on errors (before throw)
});

Multi-environment setup

Development

const agent = createAgentRuntime({
  agentId: "agent-dev-test",
  gatewayUrl: "http://localhost:41002/v1",
  apiUrl: "https://api.keeptrusts.com",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
});

Staging

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

Production

const agent = createAgentRuntime({
  agentId: "agent-compliance-bot",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  apiUrl: "https://api.keeptrusts.example",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
  bearerToken: process.env.KEEPTRUSTS_API_TOKEN!,
  retryMax: 5,
  timeoutMs: 180_000,
});

Runtime adapters

The Agent SDK ships config builders for common agent frameworks. Each adapter configures the external framework to route through the Keeptrusts gateway — the adapter does not own or replace the framework's runtime.

OpenAI Agents SDK

Route OpenAI Agents traffic through Keeptrusts governance:

import { openaiAgentsAdapter } from "@keeptrusts/agent/adapters";

const config = openaiAgentsAdapter({
  agentId: "agent-openai-researcher",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
});

// Use with the OpenAI Agents SDK
import { Agent, Runner } from "openai-agents";

const agent = new Agent({
  name: "researcher",
  model: config.model,
  // The adapter configures the client to route through Keeptrusts
});

const runner = new Runner({ client: config.client });

Claude Agent SDK (Claude Code)

Configure Claude Code to route through Keeptrusts:

import { claudeAgentAdapter } from "@keeptrusts/agent/adapters";

const config = claudeAgentAdapter({
  agentId: "agent-claude-reviewer",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
  pathToClaudeCodeExecutable: "/usr/local/bin/claude",
  adapterCommand: "code-review",
});

// config.executablePath — path to the Claude Code binary
// config.env           — environment variables for governance routing
// config.args          — command-line arguments

The adapter produces a configuration object. It does not start or own the Claude Code process — your orchestrator or process manager handles execution.

Codex SDK

Configure OpenAI Codex to route through Keeptrusts:

import { codexAdapter } from "@keeptrusts/agent/adapters";

const config = codexAdapter({
  agentId: "agent-codex-assistant",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
  codexPathOverride: "/usr/local/bin/codex",
});

// config.executablePath — path to the Codex binary
// config.env           — environment variables for governance routing

Generic fetch adapter

For any HTTP-based agent framework:

import { genericFetchAdapter } from "@keeptrusts/agent/adapters";

const fetchConfig = genericFetchAdapter({
  agentId: "agent-custom-framework",
  gatewayUrl: "https://gateway.keeptrusts.example/v1",
  accessKey: process.env.KEEPTRUSTS_API_TOKEN!,
});

// fetchConfig.baseUrl — the gateway URL to use
// fetchConfig.headers — canonical headers to attach
// fetchConfig.fetch   — a wrapped fetch function with headers pre-applied

Use fetchConfig.fetch as a drop-in replacement for globalThis.fetch in frameworks that accept a custom fetch implementation.

Credential rotation

The SDK supports updating credentials without restarting the runtime:

agent.updateCredentials({
  accessKey: "kt-new-access-key",
  bearerToken: "new-bearer-token",
});

This is useful for environments with short-lived tokens or automated rotation.

Timeout and retry

Retry behavior

The SDK retries on:

• Network errors (connection reset, DNS failure)
• HTTP 429 (rate limited) — with exponential backoff
• HTTP 502, 503, 504 (gateway/upstream errors)

The SDK does not retry on:

• HTTP 400 (bad request)
• HTTP 401 (unauthorized)
• HTTP 403 (forbidden)
• HTTP 409 (policy block — this is a governance decision, not an error)

Custom retry strategy

const agent = createAgentRuntime({
  // ...
  retryMax: 5,
  retryBackoff: "exponential", // "exponential" | "linear" | "fixed"
  retryBaseMs: 1000,           // base delay between retries
});

Logging

The SDK uses structured logging compatible with standard Node.js patterns:

const agent = createAgentRuntime({
  // ...
  logLevel: "info", // "debug" | "info" | "warn" | "error" | "silent"
});

At debug level, the SDK logs:

• Request/response headers (with secrets redacted)
• Retry attempts and backoff delays
• Event query results
• Trail verification outcomes

TypeScript configuration

The SDK ships ESM and CJS entry points with full TypeScript declarations:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true
  }
}

Minimum TypeScript version: 5.4+