Stability levels

Every AgentsKit package declares an alpha / beta / stable level. This page defines each level plus the promotion / demotion criteria.

Every @agentskit/* package's package.json carries an agentskit.stability field with one of three values: alpha, beta, stable. This page is the contract.

#Levels

Level	Public API	Breaking changes	Versioning	Coverage threshold
`alpha`	Subject to change	Allowed in any minor	0.x	≥ 60% lines (target)
`beta`	Stable in shape	Allowed in next major (semver-respecting)	0.x → 1.x	≥ 70% lines
`stable`	Frozen contract per ADR	Major-version only with migration guide	≥ 1.0	≥ 80% lines

The levels are about contract, not about maturity in the colloquial sense. A package can be stable and still gain features — what's frozen is the existing surface.

#Current status

Package	Level	Note
`@agentskit/core`	stable	Sacred package; contract-stable per ADRs 0001–0006.
`@agentskit/adapters`	beta	Provider contract and resilience hardening continue toward 1.0.
`@agentskit/runtime`	beta	ReAct, topology, and durable APIs are still settling.
`@agentskit/tools`	beta	Core tools are usable; integrations and MCP ergonomics evolve.
`@agentskit/memory`	beta	Main backends work; vector-store surface is sharpening.
`@agentskit/skills`	beta	Catalog and contract hardening continue toward promotion.
`@agentskit/observability`	beta	Lifecycle, cost-guard, and provider coverage continue to grow.
`@agentskit/react`	beta	Production-ready; shared `ChatReturn` remains pre-1.0.
`@agentskit/ink`	beta	Terminal parity and keyboard UX continue to mature.
`@agentskit/cli`	beta	Core commands are useful; programmatic surface is settling.
`@agentskit/rag`	beta	Retriever, loader, and resilience contracts are hardening.
`@agentskit/eval`	beta	Suite, replay, snapshot, and CI surfaces are still pre-1.0.
`@agentskit/sandbox`	beta	Lifecycle, config, and backend surfaces are still pre-1.0.
`@agentskit/templates`	beta	Scaffold and validation surfaces are still pre-1.0.
`@agentskit/validation`	beta	Private implementation behind the public tools validation surface.
`@agentskit/statechart`	beta	Serializable interaction-state contract is hardened but pre-1.0.
`@agentskit/eval-braintrust`	beta	Private implementation exposed through the public eval surface.
`@agentskit/observability-langfuse`	beta	Private workspace implementation exposed through observability.
`@agentskit/integrations`	beta	Fetch-only catalog and execution boundaries are still pre-1.0.
`@agentskit/mcp`	beta	Tool bridge and bounded registry surfaces are still pre-1.0.
`@agentskit/vue`	beta	Framework binding at headless parity, still pre-1.0.
`@agentskit/svelte`	beta	Framework binding at headless parity, still pre-1.0.
`@agentskit/solid`	beta	Framework binding at headless parity, still pre-1.0.
`@agentskit/react-native`	beta	Framework binding at headless parity, still pre-1.0.
`@agentskit/angular`	beta	Framework binding at headless parity, still pre-1.0.

#Promotion criteria

#`alpha → beta`

Promote when all of:

API stable for ≥ 2 sprints. No breaking changes in the public surface across the last 4 weeks of release notes.
Coverage ≥ 70% lines. Per-package vitest threshold raised to 70 in CI.
At least one external integration story. Either an example app in apps/example-*, a recipe in /docs/reference/recipes/, or a public consumer.
Stability note in package.json updated to summarise what is and isn't covered.

#`beta → stable`

Promote when all of:

An ADR locks the contract. New ADR or amendment in docs/architecture/adrs/ with Status: Accepted.
Coverage ≥ 80% lines. Per-package vitest threshold raised to 80 in CI.
No breaking changes for ≥ 1 quarter. Empirical, measured by changeset majors in the package.
Migration guide for the upcoming major if any breaking change is queued.
Version bumped to 1.0.0 in the same release.

#Demotion criteria

Stable is not a one-way door. A package returns to beta when:

A breaking change is required that can't ship behind a flag (rare; almost always avoided).
A security or correctness incident invalidates the contract (e.g. an injection class missed by @agentskit/core/security).

Demotions are loud — they go in the changelog under their own heading, link to the incident, and ship with a migration guide for any consumer that depended on the now-revised behaviour.

#Until-promoted

If you depend on an alpha or beta package today, do the following:

Pin to a specific minor. @agentskit/vue@^0.2.1, not *.
Read the stability note in package.json — it lists the parts of the surface most likely to move.
Open an issue when you hit a constraint. Stable promotions are triggered by real-world feedback.

#Roadmap

The framework bindings are the most concrete near-term promotion target. Once their coverage thresholds and release evidence are complete, promotion follows. The beta packages graduate when their respective ADRs are written + locked.

Explore nearby

✎ Edit this page on GitHub·Found a problem? Open an issue →·How to contribute →