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.

Agent SDK Compatibility Matrix

@keeptrusts/agent 0.1.0 is a preview server-side TypeScript package. Its gateway transport and tracing implementations are useful building blocks, but the release is not currently a general-purpose Node.js integration and several exported control-plane helpers do not match the live API contract.

:::danger Do not adopt version 0.1.0

This unlisted page is retained as a version-specific compatibility record. It is not a current SDK onboarding guide. Use the supported TypeScript gateway workflow for new integrations.

:::

Start with the Agent SDK overview for the package boundary and credential model. Use this page as the detailed compatibility checklist for the current release.

Do not start a production integration from this package version. Use the supported TypeScript gateway workflow while the SDK contract is corrected.

Current runtime boundary​

The package entrypoint imports the server-only marker package. In an ordinary Node.js process, that dependency throws while the SDK is being imported. The package's unit tests replace the marker with an empty test module, so a passing unit suite does not prove that a plain Node.js application can import the built package.

The entrypoint can load in a runtime that resolves the React react-server condition, but the 0.1.0 release does not declare or validate a complete framework-specific integration. Treat that as an implementation detail, not a supported workaround.

Verified implementation surface​

These parts are implemented and covered by package tests, subject to the entrypoint limitation above:

  • createOpenAIAgentTransport and createKeeptrustsFetch construct gateway-bound transports.
  • withTracing, createTracingHeaders, and generateTraceparent create and propagate request identity.
  • registerAgent, getAgent, and the supported fields of updateAgent map to existing control-plane routes.
  • buildClaudeConfig and buildCodexConfig build configuration objects; they do not launch either tool or ship the adapter scripts named by their defaults.

Exported helpers that are not runnable end to end​

AreaCurrent 0.1.0 issue
Agent listslistAgents expects a data or items wrapper; the API returns { "agents": [...] }.
Agent deletiondeleteAgent tries to parse JSON after the API returns 204 No Content.
Stats and eventsThe helper response types and wrappers differ from the live /v1/agents/{id}/stats and /v1/events responses; event queries also require since.
EvidenceThe helpers expect per-event digest fields and verification inputs that the trail API does not provide.
Actions and permissionsThe SDK calls agent action-registry and permission routes that are not registered by the API.
Deployment snapshotsdeploySnapshot posts to /v1/agents/{id}/snapshots, which is not an API route.
MCPgetMcpTools sends GET /tools; the published MCP endpoint requires a streamable-HTTP JSON-RPC exchange.

Credential boundary​

The control-plane bearer token and gateway access token are separate credentials, even though the SDK defaults both to KEEPTRUSTS_API_TOKEN when explicit options are absent. Production code must pass bearerToken and gatewayApiKey explicitly and must never put either secret in browser code.

Next steps​