Skip to content

API Stability and Deprecation Policy

kneo-agent follows Semantic Versioning on the public surface defined below. This page tells you what you can pin, what you can rely on across upgrades, and how deprecations are communicated.

What counts as public surface

A name is public if it satisfies all of these:

  1. It is listed in kneo_agent.__all__ (top-level package), or in the __all__ of one of the documented subpackages (kneo_agent.core, kneo_agent.patterns, kneo_agent.providers, kneo_agent.runtime, kneo_agent.workflows, kneo_agent.utils, kneo_agent.mcp, kneo_agent.observability, kneo_agent.middleware).
  2. It is documented in the rendered API reference (docs/pub/kneo_agent_api_reference.html / .pdf).
  3. It is not marked experimental (see below).

The set of public names is pinned by tests/unit/test_public_api_snapshot.py. A change to that snapshot must land in the same PR as the matching CHANGELOG.md entry and the API-reference update.

Anything else — modules, classes, functions whose name begins with _, attributes only reachable via implementation paths — is internal. It can change without notice between any two releases, including patch releases. Don't import it.

Stability tiers

Stable (default)

Public names ship under SemVer. You can pin to a minor version range (kneo-agent ~= 1.2) and trust that:

  • No public name in __all__ is removed within a minor line.
  • No public function or method drops a parameter, narrows a type, or changes a documented return shape within a minor line.
  • New public names, new optional parameters, and additive type-widening changes ship in minor releases (1.2.0 → 1.3.0).
  • Breaking changes — removing names, renaming parameters, narrowing return types — only ship in major releases (1.x → 2.0).

Experimental

Some new APIs ship marked experimental so we can iterate without charging the deprecation tax. Experimental names:

  • Are flagged in their docstring with .. note:: Experimental — interface may change in any release.
  • Are flagged with the same wording in their CHANGELOG entry.
  • Are flagged in the API reference manual.
  • Can change shape or be removed in any release (including patch) until they are graduated to stable. Graduation lands in a minor release with a CHANGELOG entry that says "Graduated from experimental to stable".

If you depend on an experimental API in production, pin to an exact version (kneo-agent == 1.2.3).

Deprecated

When we need to remove a stable name, it goes through a deprecation window:

  1. Mark deprecated — the name still works and behaves the same, but emits DeprecationWarning on use. The CHANGELOG entry announces the deprecation, the replacement (if any), and the target removal version. The API reference flags the name with a Deprecated since X.Y.0 note.
  2. Grace window — the name is preserved through the next minor release at minimum. So a deprecation announced in 1.2.0 is only eligible for removal in 1.4.0 or later (not 1.3.0).
  3. Remove in a major release — actual removal happens in the next major bump (2.0). For long-lived APIs we may extend the grace window further.

Tests in tests/unit/ cover deprecated names with two assertions: (a) calling the name emits DeprecationWarning, and (b) the documented behavior still works.

What's not covered

Behavior outside SemVer guarantees, even if you can observe it:

  • Internal module layouts (anything under kneo_agent.providers.<provider>.* not re-exported from kneo_agent.providers).
  • Tool dispatch ordering beyond the documented "static-then-per-run" middleware chain.
  • Log message formats and logger names.
  • Wire formats of provider SDKs we wrap (those are upstream).
  • Optional dependency floor versions — these can move within a minor line if upstream forces a security or compatibility fix.
  • Telemetry attribute values beyond the OpenTelemetry GenAI semantic-convention keys we explicitly map.

Reporting drift

If you spot a public name that changed without a CHANGELOG entry, or an experimental name without the experimental marker, please open an issue. Drift in either direction is a bug.