# State queries, Components, and what comes next

Select bounded State evidence for an AgentCore application with the private SDK. Components and queries are implemented; general metrics, materialize and watch remain planned.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Private SDK 0.40.0 implements scoped State, Components, bounded evidence-reference queries, composition, and exact Context APIs (OpenAPI 1.31.0). Its clean offline artifact round trip passed on reviewed main. The SDK is not published to npm or qualified for customer production. Queries operate on admitted evidence references; general source-payload queries, managed metrics, materialize(), watch(), and managed lifecycle integration remain planned capabilities.

Reviewed: 2026-10-14.
Backend source: e16b81b4a637acec91f3aed8a71cf5b0f42f0c19.
Native toolkit: merged in PR #176, reviewed at e16b81b4a637acec91f3aed8a71cf5b0f42f0c19.
HTML: /docs/state-api

## In short

Give an AgentCore task a bounded selection of current State evidence. Bind one scope, name a View as a Component, and inspect the query plan before running it. The result supplies evidence; your application still decides whether to invoke a model or tool.

**Available today:** Queries, Components and bounded selection operators are in private SDK 0.40.0. General materialize, watch and metrics remain planned; managed runtime wiring is separate.

> Give an AgentCore task bounded evidence; keep the decision in your application.

## Read evidence before starting work

- **Choose one task question** — Bind the State scope your AgentCore application may read.
- **Inspect the admitted plan** — Check limits before value(); only a current result carries items.
- **Keep execution outside the query** — Your application decides when to invoke the agent or tool.

## Implemented in private SDK 0.40.0

state({ subjectId, type }) binds one scope; component() names a maintained View. Declarations perform no I/O. A query selects from the admitted evidence references of that View’s current Active State, not from arbitrary source payloads.

Rust admits the plan before anything runs: tenant-bound, at most 16 stages, 32 pick paths, take ≤ 32 as the terminal stage, at most 36 storage reads, and never a table scan. value() re-reads and re-checks current State, and only a current result carries items.

### Bounded State query — SDK 0.40.0 typings

```javascript
// Private SDK 0.40.0 · implemented in source · not on npm or production-qualified
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.
```

## Bounded operators introduced in SDK 0.37.0

SDK 0.40.0 retains the thirteen stages introduced in 0.37.0: chunk, flattenDepth, differenceBy, intersectionBy, indexUnique, distinctExact, diffRevisions, partition, groupBy, countBy, sumIntBy, allMatch, anyMatch. They operate on declared bounded evidence-reference collections, not arbitrary customer payloads. diffRevisions compares two explicit collections; its completeness describes those inputs, not outside source coverage.

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.

## What explain() returns

These are the fixed fields of the plan type in the SDK typings, not a captured response or a latency measurement. explain() reports the bound; it does not perform the reads.

### StateQueryPlan fields (SDK 0.40.0 typings)

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

## Design preview: collections, materialized views, and watch

The direction beyond today’s SDK: chain operators over named source collections, keep the result materialized, and recompute it only when an input it reads changes.

Naming in the preview follows one concept: source collections are plural nouns (customers, subscriptions); derived views and metrics are camelCase descriptions of what they hold (atRiskCustomers, businessHealth).

### Design preview — collection sources, materialize and watch are not available

```javascript
// 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();
```

## A small set of composable operators

1. **Select: where, pick, orderBy, take** — Filter, project, and bound one Active State's evidence. In private SDK 0.40.0.

2. **Plan & run: explain, value** — See the bounded plan, then execute it. In private SDK 0.40.0.

3. **Combine: group, union, diff, expand, hydrate** — Relate collections and resolve references to exact revisions. Planned.

4. **Aggregate: count, sum, mean, reduce** — Derive metrics that update incrementally as inputs change. Planned.

5. **Operate: materialize, watch** — Keep a result current and react when it changes. Planned.

## Planned metrics would recompute when their inputs change

This synthetic example illustrates the planned metrics model. One subscription is upgraded. The dependency graph identifies mrr, arr, businessHealth for recomputation. churnRate, dailyActiveUsers, p99Latency, supportSla read other inputs, so the design would reuse their existing values.

In this planned design, a businessHealth change would notify its subscriber. Your application would decide whether to run the executive agent; the other 4 metrics would not notify their subscribers while their inputs remain unchanged.

Synthetic example of the planned metrics model. Counts are derived nodes in this diagram (3 of 7 recomputed, found by graph reachability from the changed input), not a measured benchmark.

## Planned subscriptions would notify your application when a View changes

watch() is the planned way to start work: subscribe to a materialized view and receive the change, including the exact revisions that caused it. Your code decides what to do, such as invoking an AgentCore agent. For supported changes, this could reduce repeated polling and unnecessary agent starts. Your application would still need appropriate recovery and monitoring; the savings would depend on the workload.

Customer realtime subscriptions are not implemented. The current internal event path is bounded and maintenance-redrivable, and it is not a public subscription API.

## Authorization, work limits, and deadlines are separate controls

Today’s State queries already carry fixed work bounds. The planned general work envelope (maxReads, maxItems, maxBytes, maxDepth, maxFanout, maxRetries, deadline) extends those consumption limits to joins, aggregates and metrics.

Authorization independently restricts which data and operations the principal may access. A small unauthorized read is still unauthorized. Deadlines and retry policy determine how long the caller waits and what happens when bounded work does not finish.

The planner bounds the operation’s work. It does not establish a latency guarantee; measured latency and convergence require a declared workload.

1. **Cross-tenant access · Implemented in source** — The server resolves the authorized tenant; a caller-supplied tenant ID is not authorization.

2. **Silent mutation · Implemented in source** — Revisions are immutable. Corrections add a revision and keep the earlier one inspectable.

3. **Model output becoming truth · Implemented in source** — Only your application declares results. No model, reducer, or AgentCore call fills a missing record.

4. **Oversized reads · Implemented in source** — History pages and View membership sets have explicit limits and cursors.

5. **Unbounded traversal · Implemented in source** — View dependency membership is bounded and cycles are rejected at registration.

6. **Stale or duplicate work · Implemented in source** — Commit-time fences reject work whose lifecycle, membership, or source version has moved.

7. **Unbounded State queries · Implemented in source** — Rust admits a query plan before execution: tenant-bound, at most 16 stages, 32 pick paths, take ≤ 32 and 36 storage reads, and never a table scan.

8. **General query work limits · Planned · not available** — A general declared envelope (maxReads, maxItems, maxBytes, maxDepth, maxFanout, deadline) for joins, aggregates and metrics, checked before execution.

9. **Acting on stale State · Planned · not available** — Revalidate the exact State a decision read before a consequential external action.

## A specialized database, not a replacement

Kam is a specialized, DynamoDB-backed State database for applications built on Amazon Bedrock AgentCore. Your databases stay authoritative for their business records. Kam is authoritative for the State it accepts: its revision identities, membership, and publication history.

Store the State worth reusing, not every byte worth keeping.

Not offered, by design: general SQL, arbitrary joins, or transactions across your other data sources.

## Where to start

Evaluate the History contract and one bounded View with the SDK candidate against an authorized endpoint. Metrics, materialize and watch are shaped by those evaluations.

[Integrate one structured workload](/docs/integrate)

[Read the State contract](/docs/state)