Syntic Code is live — install on macOS, Linux, and Windows →
Agent SDKAPI ReferenceMigration Guide

Migration Guide

This guide covers two kinds of upgrades: moving off legacy package names onto the current Syntic Agent SDK distributions, and upgrading across SDK releases. Read it before bumping a major version, and always pin an exact version in production so upgrades are deliberate rather than incidental.

Adopting the current package names

Early previews of the SDK shipped under provisional names. The supported packages are now @syntic/agent-sdk for TypeScript and syntic-agent-sdk for Python, both targeting Amara on the Syntic model via api.syntic.ai. If you are on an older package, switch the dependency and update your imports.

# TypeScript
npm uninstall <old-package>
npm install @syntic/agent-sdk
 
# Python
pip uninstall <old-package>
pip install syntic-agent-sdk
// Before
import { query } from "<old-package>";
// After
import { query } from "@syntic/agent-sdk";

The exported symbols — query, tool, createSdkMcpServer, and the message and option types — are unchanged, so most codebases only need the import path updated. Authentication continues to read SYNTIC_API_KEY from the environment.

Breaking changes across releases

Major releases may rename options, tighten types, or change defaults. When upgrading across a major boundary, review these areas first:

  • Options shape. Some fields have been consolidated. If your code sets a permission flag or system prompt via a removed key, migrate to permissionMode / permission_mode and the structured systemPrompt / system_prompt form.
  • Message union. The streamed message type values are stable, but additional fields may appear. Always branch on type rather than assuming positional shape, and treat unknown fields as forward-compatible.
  • Permission callbacks. The approval callback signature returns a structured PermissionResult. Older boolean-returning callbacks should be updated to return an explicit allow/deny/modify decision.

Recommended upgrade steps

  1. Read the release notes for every version between your current and target release — do not skip minors.
  2. Bump one major version at a time and run your test suite between each step.
  3. Exercise your permission and hook paths explicitly, since these guard production behavior.
  4. Verify cost and usage reporting still parses, as result message fields occasionally gain properties.
  5. Re-pin the exact version and commit the lockfile.

If a session was persisted under an older SDK, resuming it under a newer one is supported within the same major line; cross-major session resume is best-effort and should be validated before relying on it.

Python SDKOverview