Skip to main content

Agent SDK Overview

The Keeptrusts agent SDK lane is for server-side agent runtimes that need both governed inference and privileged governance APIs.

Use this page when​

  • You are building a backend agent runtime or worker.
  • You need one mental model for the gateway SDK, control-plane SDK, and agent-specific helpers.
  • You need the trust-boundary rules before adding tools, MCP, or audit verification.

The role of the agent SDK​

The agent SDK composes two lower-level lanes:

  1. @keeptrusts/gateway for governed model traffic
  2. @keeptrusts/control-plane for privileged operations such as provisioning, events, trail, and deployment metadata

That means the agent SDK is always server-only.

What belongs in the agent lane​

Use the agent lane for:

  • runtime helpers that consistently attach agent identity and request correlation
  • backend orchestration that reads event outcomes after model calls
  • privileged automation around agent registration, deployment metadata, and governance state
  • evidentiary audit workflows that connect request IDs, decision events, and trail verification

What does not belong in the agent lane​

Do not use the agent lane for:

  • browser bundles
  • frontend-only chat widgets
  • direct wallet polling as a substitute for request-level spend attribution
  • starting or owning a standalone MCP server

Agent request model​

A Keeptrusts-managed agent flow should preserve this sequence:

  1. create or forward x-request-id
  2. attach x-keeptrusts-agent-id
  3. propagate traceparent
  4. send inference through the gateway
  5. read decision events for cost and policy outcomes
  6. verify trail evidence when you need audit-grade confirmation

Spend attribution rule​

Agent runtimes must report request spend from event data:

  • use event_cost_attribution
  • preserve source_spend_log_id when present
  • treat wallet APIs as balance and ledger views, not per-request attribution

Gateway-owned MCP rule​

MCP remains gateway-owned even in agent runtimes.

The agent SDK may help describe MCP-capable requests or apply agent metadata, but:

  • the gateway owns MCP transport
  • the gateway owns policy enforcement on tool traffic
  • the gateway owns outbound mediation to tools and connectors

Release-shape note​

The public agent lane is being finalized on top of the gateway and control-plane packages. Until the package lands completely, you can apply the same boundary rules by composing those packages directly in your server runtime.

For AI systems​

  • @keeptrusts/agent is server-only.
  • It builds on @keeptrusts/gateway plus @keeptrusts/control-plane.
  • MCP is gateway-owned.
  • Request-level spend attribution must come from event reads.

For engineers​

  • Keep the agent runtime on the server side.
  • Use gateway calls for inference, then control-plane calls for outcome, evidence, and provisioning workflows.
  • Preserve x-keeptrusts-agent-id, x-request-id, and traceparent across the full flow.