@keeptrusts/agent 0.1.0 compatibility

:::danger Do not read implemented exports as supported workflows

Version 0.1.0 cannot be adopted in an ordinary Node.js application. This unlisted matrix exists to document its exact compatibility gaps, not to advertise an available SDK.

:::

This matrix separates code that exists from workflows that are compatible with the current API. All entries still inherit the 0.1.0 ordinary Node.js import blocker described in the overview.

Gateway and tracing

Export	What the implementation does	Current status
createOpenAIAgentTransport	Creates an OpenAI 4.x client using the gateway base URL, gateway key, agent header, and a custom fetch.	Implemented and unit-tested.
createKeeptrustsFetch	Resolves relative URLs against the gateway, merges headers, adds bearer authorization, and reads tracing context.	Implemented and unit-tested.
withAgentContext	Adds agent tracing headers to an existing fetch function, reusing a matching active context when present.	Implemented and unit-tested.
withKeeptrustsContext	Adds tracing headers to a request object before a supplied model call, reusing a matching active context when present.	Implemented and unit-tested.
withTracing	Stores one agent ID, UUID request ID, and W3C traceparent in AsyncLocalStorage for a callback.	Implemented and unit-tested.
createTracingHeaders	Reuses the current tracing context for the same agent or creates new values.	Implemented and unit-tested.

createKeeptrustsFetch does not automatically add Content-Type to gateway JSON bodies. Supply Content-Type: application/json when the wrapped client does not do so.

Agent lifecycle

Export	Live route	Compatibility
registerAgent	POST /v1/agents	Compatible for name, description, configurationId, and gatewayIds. teamId and metadata are not request fields on the live API.
getAgent	GET /v1/agents/{id}	Compatible for the common agent fields. The live response has additional fields the SDK does not type.
updateAgent	PUT /v1/agents/{id}	Compatible for name, description, status, and gatewayIds. metadata is not a live request field.
listAgents	GET /v1/agents	Incompatible: the API returns { "agents": [...] }, which its normalizer rejects. The live route does not accept the helper's list filters.
deleteAgent	DELETE /v1/agents/{id}	Incompatible: the API returns 204 No Content, but the helper requires JSON.
linkGateway	PUT /v1/agents/{id}/gateways	The request reaches a live route, but it replaces the full gateway set with the single supplied ID; it is not an additive link operation.
deploySnapshot	POST /v1/agents/{id}/snapshots	Incompatible: this route does not exist.

For safe lifecycle management today, use kt agent or the documented control-plane API rather than the incompatible helpers.

Observability

Export	Current issue
getAgentEvents	Omits the required since value by default, does not canonicalize a UUID request ID for the API's exact event filter, expects a data wrapper instead of { "events": [...] }, and types several event fields incorrectly.
getAgentStats	Types agent_id, window, and totals; the API returns flat counts and accepts since but not until.
getSpendAttribution	Depends on the incompatible event helper and therefore cannot calculate a live response.
lookupRequestEvent	Expects normalized records with digest_id; the trail lookup returns { "events": [...] } trail records and requires a UUID request ID.

Use the observability page for the exact live event and statistics contracts.

Evidence

getPublicKey maps to the current /v1/trail/public-key response. The other evidence helpers are not compatible:

• trail event queries do not accept the helper's agent_id, request_id, since, or until parameter names;
• trail events do not carry a digest_id field;
• digest downloads return storage_key and dsse_envelope, not the helper's digest_id, encoding, and body fields;
• /v1/trail/verify verifies a time window with start_time, end_time, and optional deep_verify; it does not verify an individual event ID.

See Evidence & Audit for the supported API workflow.

Actions, permissions, deployment, and MCP

The following exports must not be presented as runnable in 0.1.0:

• declareActions and getActions call an unregistered /v1/agents/{id}/actions/registry route;
• requestPermission and checkPermission call unregistered agent permission routes;
• deploySnapshot calls an unregistered agent snapshot route;
• getMcpTools uses REST-style GET /tools instead of the MCP JSON-RPC protocol.

The API's existing GET /v1/agents/{id}/actions route is a historical action timeline, not the declaration registry modeled by the SDK.

Configuration builders

buildClaudeConfig, buildCodexConfig, and buildMcpGatewayConfig return objects with generated agent, request, and trace headers. They do not establish a vendor integration, run a child process, validate the named adapter script, or perform an MCP handshake.

Next steps

• Configuration
• Observability
• Evidence & Audit
• MCP Integration