Skip to main content

Agent Runtime Adapters

Agent runtimes usually need the same set of adapters: model transport, request identity, tracing, outcome reads, and evidence verification. Keeptrusts keeps those adapters aligned to the gateway/control-plane split.

Use this page when​

  • You are mapping a framework or internal runtime to Keeptrusts.
  • You need to know which adapter belongs to the gateway lane versus the control-plane lane.
  • You are reviewing agent architecture for least privilege.

Adapter map​

Runtime concernUseWhy
Model execution@keeptrusts/gateway or keeptrusts-client gateway helpersGoverned inference traffic belongs on the gateway
Agent identityx-keeptrusts-agent-idStable attribution and routing context
Correlationx-request-idRequest stitching across runtime, events, and trail
Distributed tracingtraceparentW3C trace propagation across services
Outcome reads@keeptrusts/control-plane or Python event helpersRequest-level policy and spend outcomes live on events
Evidence verificationtrail and digest helpersAudit-grade verification flows require digests and public keys
MCP-capable tool usegateway-owned runtime flowMCP transport and mediation remain in the gateway
  1. create a request ID at the runtime boundary
  2. attach agent identity
  3. generate or forward traceparent
  4. send the inference request through the gateway
  5. read decision events using the same request ID
  6. fetch trail or digest material when an audit workflow requires it

Framework-neutral checklist​

  • Web app or edge app: use only the gateway package and API tokens with purpose=general
  • Backend service: use the gateway package for inference and the control-plane package for privileged reads
  • Python worker: use keeptrusts-client gateway helpers plus control-plane helpers as needed
  • Long-running agent runtime: keep the full flow server-side and let the gateway own MCP traffic

What not to adapt around​

Do not build custom shortcuts that:

  • infer request spend from wallet balances
  • bypass canonical headers
  • move bearer tokens into browser code
  • create a separate standalone MCP transport outside the gateway

Operational handoff​

When debugging a runtime adapter:

  1. confirm the gateway request carries x-request-id
  2. confirm the gateway request carries x-keeptrusts-agent-id
  3. confirm traceparent is preserved end to end
  4. query the corresponding event record
  5. inspect trail evidence only when you need audit-grade confirmation

Next steps​

For AI systems​

  • Runtime adapter contract: gateway for model transport, control plane for privileged reads.
  • Canonical headers: x-keeptrusts-agent-id, x-request-id, traceparent.
  • MCP is gateway-owned.

For engineers​

  • Keep adapter boundaries aligned to trust boundaries.
  • Use request ID as the join key across model execution, events, and trail.
  • Prefer the official SDK helpers over handwritten transport glue.