Skip to main content

Integrate one structured workload

Record one AgentCore workload result, then read both sides of a correction.

Reviewed 2026-10-14 · prelaunchRead this guide as Markdown
Guide context

Add recorded State to an AgentCore application while your runtime keeps model calls, tools and business decisions. Use the existing SDK candidate against an authorized endpoint.

Keep your AgentCore runtime and record one declared result in Kam: what happened, to which record, and when. Retry the same identity, record a correction, then read both retained versions. Your application supplies the business meaning and controls external actions.

On this page · 5 sections

Record one workload result

  1. Authorize the State connection

    Use an approved evaluation endpoint and an authorized application identity.

  2. Record the declared result

    Your AgentCore application supplies stable identity and result meaning.

  3. Read the correction exactly

    Request both retained revisions; do not rerun the original tool to inspect them.

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.

Read the scoped SDK example See the retry assertion and correction

Choose the operation that matches your task#

  1. outcome()

    Record a result, retry the exact same payload, or supply the next correction revision.

  2. allIds() → byIds()

    Browse a pinned UTC-day collection, then retrieve its exact revision references. Keep generation and cursor together.

  3. trajectory()

    Read precomputed last-ten and 30/90-day comparisons, with freshness and pending-work information.

  4. history() / why()

    Inspect accepted-revision history or a deterministic explanation of calculated values. why() is not causal investigation.

  5. 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.40.0 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.

Read one bounded page using the existing SDK candidate
// Save as a .mjs file in an authorized backend source checkout. SDK candidate 0.40.0.
// This is a read-only example, not code executed by the website.
import { createKamClient } from './server/trajectory/sdk/index.mjs';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const deployments = kam.scope({ 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.

Agent-readable documentation manifest