Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

@keeptrusts/agent 0.1.0 configuration contract

:::danger Reference only

This unlisted page documents the code contract of an SDK version that is not available as a supported Node.js integration. Do not treat the examples as an adoption quickstart.

:::

This page documents what the 0.1.0 constructors and builders read. It does not remove the package's ordinary Node.js import blocker or make an incompatible high-level helper safe to use.

Client options​

KeeptrustsAgentClient accepts:

OptionRequiredPurpose
regionYeseu-west, us-east, or global. There is no region environment fallback.
baseUrlUnless KEEPTRUSTS_API_URL is setControl-plane API base URL. The synchronous constructor does not perform region discovery.
bearerTokenUnless KEEPTRUSTS_API_TOKEN is setControl-plane bearer token.
gatewayBaseUrlNoGateway model API base URL.
gatewayApiKeyNoGateway access token used for bearer authorization.
gatewayHeadersNoStatic headers merged into gateway calls.
fetchNoCustom fetch implementation for both surfaces.

The exact resolution order is:

ValueResolution order
Control-plane URLbaseUrl -> KEEPTRUSTS_API_URL -> configuration error
Control-plane tokenbearerToken -> KEEPTRUSTS_API_TOKEN -> configuration error
Gateway URLgatewayBaseUrl -> KEEPTRUSTS_GATEWAY_URL -> http://localhost:41002/v1
Gateway tokengatewayApiKey -> KEEPTRUSTS_API_TOKEN -> kt-gateway

The local gateway defaults are development conveniences, not production credentials.

Pass separate credentials explicitly​

When the entrypoint is usable in your evaluated server runtime, construct the client with distinct secret variables:

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

const client = new KeeptrustsAgentClient({
  region: "us-east",
  baseUrl: process.env.KEEPTRUSTS_API_URL,
  bearerToken: process.env.KEEPTRUSTS_CONTROL_PLANE_TOKEN,
  gatewayBaseUrl: process.env.KEEPTRUSTS_GATEWAY_URL,
  gatewayApiKey: process.env.KEEPTRUSTS_GATEWAY_TOKEN,
  gatewayHeaders: {
    "x-keeptrusts-team": "risk-platform",
  },
});

This snippet describes the constructor contract; it is not a plain Node.js quickstart for 0.1.0. See the supported TypeScript workflow for a runnable direct gateway integration.

Synchronous and asynchronous construction​

new KeeptrustsAgentClient(options) requires a resolved control-plane URL from baseUrl or KEEPTRUSTS_API_URL.

await KeeptrustsAgentClient.create(options) can discover the region endpoint when baseUrl is absent. In that case, KEEPTRUSTS_API_URL is still required as the host for GET /v1/regions; the selected region entry must expose an api_endpoint.

Both paths require region explicitly. The SDK does not read KEEPTRUSTS_REGION.

Gateway header precedence​

The fetch adapter merges headers in this order, with later values winning:

  1. client gatewayHeaders;
  2. adapter defaultHeaders;
  3. headers already present on a Request input;
  4. per-call RequestInit.headers;
  5. tracing headers generated for the active agent context.

Bearer authorization is added only when an auth token is available, authScheme is not "none", and the merged headers do not already contain an Authorization value.

OpenAI-compatible transport​

createOpenAIAgentTransport selects:

  • baseUrl option, then client.gatewayBaseUrl;
  • apiKey option, then client.gatewayApiKey;
  • client gateway headers, then transport defaultHeaders;
  • an enforced x-keeptrusts-agent-id for the supplied agentId.

Its custom fetch reads the current withTracing context at request time, so a model call inside that callback carries the callback's request ID and traceparent.

Generic fetch transport​

Relative inputs are resolved against the configured gateway base URL. A path such as /chat/completions becomes http://localhost:41002/v1/chat/completions with the default base.

The adapter does not serialize request bodies and does not set JSON content type. Callers sending JSON must provide both:

headers: { "Content-Type": "application/json" },
body: JSON.stringify(payload),

Claude and Codex builders​

The builders return plain configuration objects. Their default child commands reference ./claude-agent-adapter.mjs and ./codex-agent-adapter.mjs, which the package does not ship.

The generated child environment contains:

  • KEEPTRUSTS_GATEWAY_URL;
  • KEEPTRUSTS_API_TOKEN, containing the gateway key;
  • KEEPTRUSTS_AGENT_ID;
  • KEEPTRUSTS_REQUEST_ID;
  • KEEPTRUSTS_TRACEPARENT;
  • KEEPTRUSTS_GATEWAY_HEADERS_JSON.

Only use a builder when your application supplies and owns a compatible adapter process. The SDK does not launch Claude Code or Codex.

Credential rotation​

Clients and transports capture credential strings when they are created. After rotating a secret, create a new client and any transports derived from it. Do not mutate the readonly fields or keep using an old transport.

Next steps​