Record agent results with the Kam SDK
Kam State adds versioned application state to Amazon Bedrock AgentCore.
Use one scoped Kam State integration to record, retry, correct and read AgentCore workload results, with execution controlled by your application.
Guide context
Integrate Kam State with Amazon Bedrock AgentCore through one scoped SDK contract for recording, retrying and reading results. An authorized evaluation endpoint is required.
Record one declared AgentCore workload result in Kam State, retry its exact identity, correct it and read both retained versions. The shared SDK contract is intended to reduce custom revision tracking and retry checks around recorded State. Your application supplies business meaning, controls external actions and keeps its existing runtime; deduplicating a record does not deduplicate a model or tool action.
On this page · 7 sections
Record one workload result
Authorize the State connection
Use an approved evaluation endpoint and an authorized application identity.
Record the declared result
Your AgentCore application supplies stable identity and result meaning.
Read the correction exactly
Request both retained revisions; do not rerun the original tool to inspect them.
Arrange SDK access before running the example#
These examples use private SDK 0.59.4 from the approved evaluation artifact. Its offline verification is distinct from the broader backend review pinned to SDK 0.40.0. Configure the authorized endpoint, principal and server-owned tenant binding in a trusted Node.js 22+ backend.
Keep credentials out of AG-UI state and browser code. The application adapter calls Kam explicitly; no public npm installer, hosted endpoint or automatic AgentCore wiring is provided.
Send identity, time, and a declared result#
Supply ID, subject, type, occurrence time, status, category, and optional source references. Revision defaults to 1. The server resolves the authorized tenant; a supplied tenant ID is not authorization by itself.
Only success and failure are accepted. Do not convert pending, cancelled, or unknown results into failure just to fit the API. Occurrence time must be canonical UTC, not in the future, and within the working window.
Record, retry, correct, and inspect#
Replace the example identity and time with one declared result from your workflow. Preserve the original timestamp and payload for an identical retry. A correction advances the revision under that same identity.
// 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);Choose the operation that matches your task#
record()
Record a result, retry the exact same payload, or supply the next correction revision. outcome() remains a compatible alias.
allIds() → byIds()
Browse a pinned UTC-day collection, then retrieve its exact revision references. Keep generation and cursor together.
trajectory()
Read precomputed last-ten and 30/90-day comparisons, with freshness and pending-work information.
history() / why()
Inspect accepted-revision history or a deterministic explanation of calculated values. why() is not causal investigation.
deliveryStatus()
Read metadata-only delivery counts, coverage, and oldest unfinished work. It does not return memory content.
Bind a scope once; preserve the returned references#
SDK 0.59.4 provides state({ subjectId, type }) (scope() is the same adapter) as a thin layer over the same API. It cannot override its bound subject or type and does not create a second state engine. Use the exact approved package or authorized source checkout; there is no public npm release.
// 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.Keep AgentCore execution in your application#
createKamApp, conversation and invocation create immutable scoped handles without I/O. Use them for the State layer of an AgentCore application. Your runtime and application create, invoke and dispose models, tools and Memory connections; Kam does not take over that lifecycle.
Component configuration is a bounded sequence of individually idempotent steps, not one atomic transaction. An acknowledged configuration does not prove that derived State has converged.
Authorize the destination separately#
A subscription does not grant access to a customer AWS account. Server-owned bindings select the approved Region, memory, strategy, and namespace. Background jobs do not retain a browser JWT.