Skip to main content

SDK & integration

Keep your harness. Add exact State and readback.

Keep Strands or your chosen harness, AG-UI, and Amazon Bedrock AgentCore. Call the private Kam State SDK from your backend to record supported results and read exact retained revisions. Harness checkpoints and external-effect recovery remain separate responsibilities.

Private SDK 0.59.4 · evaluation access required. No public npm release or hosted service.

Keep your existing stack

Keep Strands or your chosen harness, AG-UI, and AgentCore. Add explicit State calls at application-owned boundaries.

Application-owned adapter · no automatic wiring

Protect accepted State

Record a result, retry the same request, and read an exact retained revision.

Server-side example · authorized endpoint required

Request evaluation access

Agree the workflow, then obtain the reviewed private SDK artifact and the requirements for access to an authorized endpoint.

Evaluation only · no public npm release

Keep the agent loop. Connect the State boundary.

AG-UI
Carries messages, tool events, and UI state snapshots or deltas; a completed stream is not State acceptance.
Amazon Bedrock AgentCore + your harness
Run the model/tool loop with AgentCore Harness or your chosen framework. Your application connects Kam through explicit SDK calls.
Kam State SDK
Explicit backend calls record supported results and read exact retained revisions. The read-only console inspects available evidence.

These are responsibilities, not a drop-in adapter. Your application authorizes scope, maps records, and reconciles external effects. A harness checkpoint, finished AG-UI run, and accepted Kam write establish different facts.

Follow the AG-UI + AgentCore integration guide →
Context and runtime limits

This is an integration model, not a drop-in managed bridge. Exact Context uses item/byte bounds, not provider-token budgets. Automatic runtime interception and managed AgentCore wiring remain planned.

State, Memory, and Context across sessions →

Before you run the SDK

Approved SDK artifact
Obtain the supplied @kam-ai/agentcore-history-sdk package. The examples below target 0.59.4 and Node.js 22+. No public install command is offered.
Authorized server connection
Configure the approved endpoint, principal, and tenant binding in your backend. A browser-supplied tenant is not permission.
One declared result
Choose a stable identity, a supported success or failure outcome, and the exact input references your application can attest. Resolve unknown tool effects separately.

@kam-ai/agentcore-history-sdk 0.59.4 · OpenAPI 1.41.0. Offline artifact verification with synthetic transport. The broader backend contract review remains pinned to SDK 0.40.0; this artifact does not advance live qualification.

Reviewed source and package identities

SDK calls require authorized evaluation access.

Record, retry, correct, and read both revisions

Call the SDK from your application after it has a declared result. An identical retry preserves the accepted revision while its evidence is retained.

Implemented in source
Assert an exact retry, then read both revisions
// Private SDK 0.59.4. Not published to npm. Methods checked against the bundled typings.
// Run in Node 22+ with the supplied evaluation package and an authorized endpoint, tenant and token.
import assert from 'node:assert/strict';
import { createKamClient } from '@kam-ai/agentcore-history-sdk';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const checks = kam.state({ subjectId: 'checkout', type: 'deployment' });

// 1. Record revision 1, then resend the identical payload while its evidence is retained.
const original = { id: 'deploy-0412', occurredAt: '2026-10-06T17:00:00.000Z', status: 'success' };
const first = await checks.record(original);
const retry = await checks.record(original);
assert.equal(retry.status, 'duplicate');
assert.equal(retry.acceptedSequence, first.acceptedSequence);
assert.equal(retry.revision, first.revision); // No new accepted revision.

// 2. Correct it: the next revision, same id and occurredAt. Revision 1 is kept while retained.
const second = await checks.record({ id: 'deploy-0412', revision: 2, occurredAt: '2026-10-06T17:00:00.000Z', status: 'failure' });
console.log(first.acceptedSequence, second.acceptedSequence); // per-scope order

// 3. Read both exact revisions. Direct mode makes no day-membership claim.
const exact = await checks.byIds({ refs: [{ id: 'deploy-0412', revision: 1 }, { id: 'deploy-0412', revision: 2 }] });
for (const record of exact.records) console.log(record.ref.revision, record.status);

These are example identities and timestamps. Use a distinct stable ID for your own result, preserve its original timestamp on retry, and stay within the History window. Recording a result does not rerun the tool or prove an external action completed.

Handle a result-write timeout →

Read a pinned collection

Use allIds() to get a bounded page and its generation. Pass those exact references to byIds(); preserve generation and cursor when paging.

Implemented in source
Scoped, generation-bound History read
// Private SDK 0.59.4. Obtain the approved artifact through an evaluation.
// Run on your backend with Node 22+; this website does not execute these calls.
import { createKamClient } from '@kam-ai/agentcore-history-sdk';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const deployments = kam.state({ subjectId: 'checkout', type: 'deployment' });
const page = await deployments.allIds({ day: '2026-10-06', limit: 16 });
if (page.status === 'ready' && page.items.length > 0) {
  const exact = await deployments.byIds({
    day: page.day,
    generation: page.generation,
    refs: page.items,
  });
  console.log(exact.records); // Keep every position and result status.
}
// A short page is not the end when nextCursor is present.
// Continue with the SAME generation and returned cursor.

Your adapter can project authorized records into AG-UI state. Keep missing, expired, and unresolved records explicit; an exact read never substitutes latest.

Optional depth

Add the contracts your workflow needs.

Query current State and inspect the work limits

Query current State

A query selects evidence references from one Active State. Inspect the plan, then use the result only when its status is current.

Implemented in source
Bounded State query
// Private SDK 0.59.4 · current artifact typings · authorized endpoint required
const deployment = kam.state({ subjectId: 'checkout', type: 'deployment' });
const history = deployment.component('trajectory-current');

const required = history.query()
  .where('required', 'eq', true)
  .orderBy('key', 'asc')
  .pick(['key', 'revision', 'source.id'])
  .take(5);

// Inspect the plan before it runs.
const plan = await required.explain();

// Execute over the admitted Active State's evidence references.
const result = await required.value();
if (result.status === 'current') console.log(result.items);
// absent, blocked and stale results carry no usable items.

explain() plan fields · SDK typings
explain() → kam.state-query-plan.v1     (fields from SDK 0.59.4 typings)
  storageAccess        tenant_bound_verified_active_state_read
  maxStorageReads      36
  tableScan            false
  crossTenant          false
  limits               16 stages · 32 pick paths · take ≤ 32
  executionAvailable   true

  • SelectwherepickorderBytakeFilter, project, and bound one Active State's evidence. Exposed by bundled private SDK 0.59.4.
  • Plan & runexplainvalueSee the bounded plan, then execute it. Exposed by bundled private SDK 0.59.4.
  • CombinegroupuniondiffexpandhydrateRelate collections and resolve references to exact revisions. Planned.
  • AggregatecountsummeanreduceDerive metrics that update incrementally as inputs change. Planned.
  • OperatematerializewatchKeep a result current and react when it changes. Planned.

Merged in PR #220, not published to npm. Introduced in SDK 0.37.0; included in the reviewed private SDK 0.40.0. These operators run only over one verified Active State's selected evidence-reference collection. They do not query arbitrary customer payloads, establish external completeness, provide a managed metrics service, or add automatic AgentCore lifecycle integration. configure() is a bounded, non-atomic sequence; configuration alone does not establish current State.

Review State queries and operators →
Planned State API designsPlanned · not available
Design preview — materialize and watch are not available
// DESIGN PREVIEW · collection sources, materialize and watch are not available in any SDK
const atRiskCustomers = kam
  .state('customers')
  .where(lt('health', 0.6))
  .pick(['id', 'mrr', 'health', 'renewalDate'])
  .orderBy('mrr', 'desc')
  .take(100)
  .materialize('atRiskCustomers');

// Run your agent only when this view changes.
atRiskCustomers.watch(change => startCustomerSuccessAgent(change));

// Ask how Kam will execute it before it runs.
atRiskCustomers.explain();

The backend contract review is pinned to SDK 0.40.0 and OpenAPI 1.31.0. Bundled SDK 0.59.4 retains scoped State, Components, bounded evidence-reference queries, composition, and exact Context interfaces, with separate offline artifact evidence. Neither checkpoint establishes customer-production qualification or a public npm release. Queries operate on admitted evidence references; general source-payload queries, managed metrics, materialize(), watch(), and managed lifecycle integration remain planned capabilities.

Inspect the recorded changed-input contract example

Check evidence for a changed refund request

Your AgentCore agent calls an eligibility tool. Kam checks whether its recorded input matches the current request. Your application chooses what to refresh and controls any refund.

current → blocked → current. Synthetic observations supplied directly to Rust. This does not prove SDK acceptance, persistence, agent execution, or a deployed service.

Recorded on Linux x86-64 with Rust 1.90.0. Replay requires Python 3 and the approved private worker matching the recorded checksum. Network access was disabled.

Replay the same three synthetic cases
python3 readiness-contract.py \
  --worker "$KAM_TRAJECTORY_WORKER_BIN" \
  --expected-worker-sha256 404cc06e577fdb183b66faee81b3657571e42433f38747f68aaded3cc247dbf9 \
  --output ./readiness-result

Configure the readiness rule · private SDK 0.40
// Private SDK 0.40.0; supplied artifact, owner-authorized evaluation endpoint,
// and an application-owned producer of retained request/eligibility Observations required.
// This file configures a View. It does not publish source Observations or execute an agent or refund.
// Configuration is not convergence: these are separate non-atomic writes, and
// their receipts do not establish that readiness is current.
// History sourceRefs are opaque application strings, not trusted exact witnesses.
// AgentCore hosts the agent runtime; the application controls tool calls and refund actions.
// The trusted adapter derives an eligibility->request witness from the retained eligibility
// Observation's selected input, including the request revision and content hash.

/**
 * @param {import('@kam-ai/agentcore-history-sdk').Client} client
 * @param {{subjectId: string, type: string}} identity
 */
export async function configureReadiness(client, identity) {
  const state = client.state(identity);
  const view = await state.configureStateView({
    expectedVersion: 0,
    mutationId: 'readiness-view-create-0001',
    view: {
      id: 'readiness',
      revision: 1,
      maxItems: 2,
      maxReferenceBytes: 4096,
      dependencies: [
        {
          key: 'request',
          source: { subjectId: identity.subjectId, type: identity.type, id: 'request' },
          required: true,
          priority: 0,
          maxAgeMs: 300000,
        },
        {
          key: 'eligibility',
          source: { subjectId: identity.subjectId, type: identity.type, id: 'eligibility' },
          required: true,
          priority: 1,
          maxAgeMs: 300000,
        },
      ],
      compatibility: {
        schema: 'kam.state-compatibility.v1',
        rules: [
          { id: 'eligibility-matches-request', kind: 'references_exact', source: 'eligibility', target: 'request' },
        ],
      },
    },
  });
  const requestMembership = await state.configureStateDependency({
    sourceViewId: 'request',
    dependentViewId: 'readiness',
    expectedVersion: 0,
    mutationId: 'readiness-request-link-0001',
  });
  const eligibilityMembership = await state.configureStateDependency({
    sourceViewId: 'eligibility',
    dependentViewId: 'readiness',
    expectedVersion: 0,
    mutationId: 'readiness-eligibility-link-0001',
  });
  // Keep the original mutation IDs and request bytes for supported exact retries.
  // A failed later step leaves earlier accepted configuration writes in place.
  return { view, requestMembership, eligibilityMembership, atomic: false, currentState: 'not_checked' };
}

/**
 * Read after the private source adapter publishes and processing is reconciled.
 * Only status=current carries a usable State payload. Configuration may be absent.
 * A retained Observation is historical evidence, never current action permission.
 * @param {import('@kam-ai/agentcore-history-sdk').Client} client
 * @param {{subjectId: string, type: string}} identity
 */
export async function inspectReadiness(client, identity) {
  const state = client.state(identity);
  const current = await state.activeState({ viewId: 'readiness' });
  const assessment = current.activeStateVersion === undefined ? null
    : await state.observation({ viewId: 'readiness', activeStateVersion: current.activeStateVersion });
  return { current, assessment };
}

/**
 * Exact Component Observation addresses; no latest substitution and no History
 * byIds call that confuses a Component version with an accepted outcome revision.
 * Reads may return unavailable if the private producer has not supplied/retained them.
 * @param {import('@kam-ai/agentcore-history-sdk').Client} client
 * @param {{subjectId: string, type: string}} identity
 */
export async function inspectOriginalInputs(client, identity) {
  const state = client.state(identity);
  const request = await state.observation({ viewId: 'request', activeStateVersion: 1 });
  const eligibility = await state.observation({ viewId: 'eligibility', activeStateVersion: 1 });
  return { request, eligibility };
}

Requires an authorized endpoint and a producer adapter for retained request/eligibility Observations. Configuration is not convergence. History sourceRefs do not supply trusted dependency witnesses.

Download the SDK configuration →

Track changed inputs in your workflow →

Inspect locally with the toolkit

Run the local toolkit

Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Run the local toolkit
# Merged toolkit, no public binary. Use an approved Linux x64 artifact.
# No public installer is available. These commands run locally.
kam init --template deployment-agent
kam init --template deployment-agent --write
kam doctor --json
kam generate --check
kam dev --json
kam replay --scenario invalidated --json
kam atlas --scenario corrected --json
kam qualify --json

The toolkit uses Kam’s Rust code to prepare local Turn Frames without AWS or a model. Your AgentCore runtime owns model and tool calls; preparing a frame grants no permission.

Read the local toolkit guide →
How exact reads and fixed lists work

Two primitives

What exactly is this? What belongs together?

allIds fixes ordered membership; byIds reads exact revisions.

Exact record

byIds

What exactly is this?

Read the requested (id, revision) in its authorized scope. Verify its identity and integrity; never substitute the latest revision.

Ordered list

allIds

What belongs together?

Browse exact references in a fixed generation. Keep that generation while paging, with coverage and completeness stated explicitly.

One foundation. Three experiences.

Timeline
Browse references within one fixed generation.
History
Compare retained revisions with their corrections.
Replay and inspection
Local toolkit: synthetic replay. Kam State console: read-only.

What stays exact

Every returned record matches its requested exact identity in its authorized scope. In generation mode, the read also verifies membership in the supplied day and generation. Unavailable, unresolved, expired, denied, or incomplete results stay explicit and are never replaced with a newer revision or presented as complete success.

The guarantees behind each read
GuaranteebyIdsallIds
IdentityExact (id, revision) in one scopeExact generation of one collection
ConsistencyNo fallback to the latest revisionMembership stays pinned while paging
IntegrityContent hash recomputed on readOrdered membership checked against its generation
AuthorizationEvery read authorized for its scopeEnumeration authorized for its scope
HistoryRetained earlier revisionsRetained earlier generations
BoundsBatched point reads, up to 32 per callIndexed pages, up to 32 references
RecoveryUnavailable, expired, and unresolved stated explicitlyCursor continuation on the same generation
LifecycleRetention deadlines; export-bound deletionCorrections publish a successor generation
Implemented in source

Implemented in source for the History contract: outcome revisions and their UTC-day membership. Generalized objects and collections over the same guarantees are planned.

List fixed references, then read exact versions
// Private SDK 0.59.4. Obtain the approved artifact through an evaluation.
// Run on your backend with Node 22+; this website does not execute these calls.
import { createKamClient } from '@kam-ai/agentcore-history-sdk';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const deployments = kam.state({ subjectId: 'checkout', type: 'deployment' });
const page = await deployments.allIds({ day: '2026-10-06', limit: 16 });
if (page.status === 'ready' && page.items.length > 0) {
  const exact = await deployments.byIds({
    day: page.day,
    generation: page.generation,
    refs: page.items,
  });
  console.log(exact.records); // Keep every position and result status.
}
// A short page is not the end when nextCursor is present.
// Continue with the SAME generation and returned cursor.

Two primitives. Many compositions. One deterministic State engine.

Compare the available reads

Which read should I use?

The reviewed History and State contracts are available for private evaluation. watch() remains planned.

QuestionCallReturns
I know the record and revision. What exactly is it?byIds({ refs: [{ id, revision }] })The exact revision, or found / unresolved / unavailable / expired
Which records belong to this day, as published?allIds({ day }) → byIds({ day, generation, refs })One ordered, fixed list of exact versions, followed by records checked against that list
What was accepted, in order, after sequence N?history({ generation, afterSequence })Accepted revisions with the prior revision each one corrected
What is the current rolling comparison?trajectory()Last-10 and 30/90-day comparisons with accepted and applied sequence
What does the current View say, and is it usable?component('id').read()current, absent, blocked, or stale; only current carries a payload
Which current evidence matches a filter?query().where(…).take(n).value()A query with a fixed work limit over one Active State
What did Kam consider current at version N?observation({ activeStateVersion })The exact retained assessment, never the latest substitute
Tell me when this View changeswatch() Planned · not availableNothing yet. No customer subscription exists

Keep the contract close

Give your coding assistant the same guides.

One application. One operation.

Evaluate one operation in your application.

Bring a correction or an uncertain save. Agree the exact readback, failure checks, scope, duration, and price before starting.