TnsAI is pre-1.0, so the public API can shift between minor versions. The framework deliberately does not ship long-lived @Deprecated shims — when a replacement lands, the old surface goes in the same release. That means every upgrade is potentially a small surgical step rather than a sprawling deprecation cleanup, but it also means you have to read the right release notes to know what to change.

Where the migration steps live

Each release's CHANGELOG entry includes a Migration subsection whenever consumers need to do something other than bump the version. So the canonical guide for moving from version X to Y is every CHANGELOG entry strictly between X (exclusive) and Y (inclusive).

→ Changelog has the full list, newest first.

This page is a roadmap: it points to the entries that contain non-trivial breaking changes so you don't have to read the entire changelog when planning an upgrade.

Releases that require active migration

Only release entries where ignoring the steps would actually break consumer code are listed here. Patch releases that touch internals only are omitted.

0.7.0 — Legacy `Tool` interface removed

Function-shape ToolMethod is now the only tool abstraction in the runtime. If your code still does class MyTool implements Tool, this is the breaking change to plan for.

Migration paths: convert to a POJO with @Tool-annotated methods (recommended), or build a DynamicToolMethod directly.
See Changelog → 0.7.0 → Migration for the exact replacement snippets.

0.6.0 — `Tool` interface metadata methods + `ChatRequest.tools` type changed

Removed the 12 metadata-discovery default methods (getCategory, getUsageExamples, etc.) and changed ChatRequest.getTools() from List<ToolDefinition> to List<Map<String, Object>> (JSON-Schema fragments).

Custom-tool-catalog callers that built ChatRequest directly must switch to the new map shape.
Direct Tool implementers can simply drop overrides of the removed metadata methods — they're no longer called.
See Changelog → 0.6.0 → Migration for before/after snippets.

0.5.7 — Legacy tool catalog removed from `tnsai-tools`

The 130+ extends AbstractTool classes were replaced by ~60 typed POJOs exposing ~190 @Tool-annotated methods. Most consumers already used AgentBuilder.toolPojos(...) and don't need to touch anything.

Consumers still using AgentBuilder.tool(Tool) keep working through the compatibility surface in this release.
See Changelog → 0.5.7 → Consumer migration.

0.5.0 — `AgentState.READY` renamed to `RUNNING`

Single-token rename. No deprecation shim: search-and-replace AgentState.READY → AgentState.RUNNING in your code.

Other 0.5.0 behaviour changes that can surface as silent breaks if your code depended on them:

Agent.chat() now throws IllegalStateException after the agent has been stopped (was silent / undefined before).
BridgeLLMClient.streamChat() now throws LLMCapabilityException (was returning a single-element synthetic stream).
BridgeLLMClient.chat() now throws typed LLMException (was raw RuntimeException).

See Changelog → 0.5.0 → Migration notes.

0.4.0 — Monorepo migration

Not a code break, but a coordinate break: the 11 separately-published modules consolidated under a single tnsai-bom. The recommended dependency shape is now to import the BOM once and depend on individual modules without <version>.

See Changelog → 0.4.0 → For Consumers for the new dependency snippet.

When in doubt

If you're skipping multiple versions, walk forward one minor at a time and read the migration subsection of each entry. The deletions are intentionally aggressive — sleeping on the changelog for six months and trying to jump from 0.5 to 0.10 in one go is harder than four 30-minute upgrade sessions spread across releases.

For changes that aren't covered above but caused you grief, open a discussion on the framework repo — the entry will land here in the next release.

Migration

On this page