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
SDK & integration
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 Strands or your chosen harness, AG-UI, and AgentCore. Add explicit State calls at application-owned boundaries.
Application-owned adapter · no automatic wiring
Record a result, retry the same request, and read an exact retained revision.
Server-side example · authorized endpoint required
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
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 →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 →@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.
SDK calls require authorized evaluation access.
Call the SDK from your application after it has a declared result. An identical retry preserves the accepted revision while its evidence is retained.
// 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 →Use allIds() to get a bounded page and its generation. Pass those exact references to byIds(); preserve generation and cursor when paging.
// 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
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// 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() → 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 truewherepickorderBytakeFilter, project, and bound one Active State's evidence. Exposed by bundled private SDK 0.59.4.explainvalueSee the bounded plan, then execute it. Exposed by bundled private SDK 0.59.4.groupuniondiffexpandhydrateRelate collections and resolve references to exact revisions. Planned.countsummeanreduceDerive metrics that update incrementally as inputs change. Planned.materializewatchKeep 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.
// 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.
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.
python3 readiness-contract.py \
--worker "$KAM_TRAJECTORY_WORKER_BIN" \
--expected-worker-sha256 404cc06e577fdb183b66faee81b3657571e42433f38747f68aaded3cc247dbf9 \
--output ./readiness-result// 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 →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.
# 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 --jsonThe 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 →Two primitives
allIds fixes ordered membership; byIds reads exact revisions.
Exact record
byIdsWhat exactly is this?
Read the requested (id, revision) in its authorized scope. Verify its identity and integrity; never substitute the latest revision.
Ordered list
allIdsWhat belongs together?
Browse exact references in a fixed generation. Keep that generation while paging, with coverage and completeness stated explicitly.
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.
| Guarantee | byIds | allIds |
|---|---|---|
| Identity | Exact (id, revision) in one scope | Exact generation of one collection |
| Consistency | No fallback to the latest revision | Membership stays pinned while paging |
| Integrity | Content hash recomputed on read | Ordered membership checked against its generation |
| Authorization | Every read authorized for its scope | Enumeration authorized for its scope |
| History | Retained earlier revisions | Retained earlier generations |
| Bounds | Batched point reads, up to 32 per call | Indexed pages, up to 32 references |
| Recovery | Unavailable, expired, and unresolved stated explicitly | Cursor continuation on the same generation |
| Lifecycle | Retention deadlines; export-bound deletion | Corrections publish a successor generation |
Implemented in source for the History contract: outcome revisions and their UTC-day membership. Generalized objects and collections over the same guarantees are planned.
// 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.
The reviewed History and State contracts are available for private evaluation. watch() remains planned.
| Question | Call | Returns |
|---|---|---|
| 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 changes | watch() Planned · not available | Nothing yet. No customer subscription exists |
Keep the contract close
One application. One operation.
Bring a correction or an uncertain save. Agree the exact readback, failure checks, scope, duration, and price before starting.