Skip to main content

Migration Guide

Version française : ../../fr/guides/migration.md

This guide explains how the API and the contracts stay compatible, and how to upgrade the SDK, the CLI and your manifests to a new release without breaking a deployed agent. Who: developers and release managers. Duration: about 15 minutes per project.

Compatibility​

The API is versioned under /v1; services/control-plane/src/eai/api_openapi.py refuses to regenerate docs/api/openapi-v1.json on a breaking change, so a minor SDK upgrade stays compatible. Contracts carry schema_version.

WhatRuleWhere it is checked
Routes and fields of the APIadded, never removed or retyped under /v1services/control-plane/src/eai/api_openapi.py (--check in CI)
Request surfaceevery route has its published request descriptiondocs/api/control-plane-v1.requests.json, services/control-plane/tests/test_api_surface.py
JSON Schema contractseach document carries schema_version; the SDK validates against the contracts it shipscontracts/v1, enterprise-ai test sdk-conformance
Error envelopecode, message, message_i18n, details, request_id keep their meaningSDK typed errors

Upgrade​

Upgrade the SDK, then validate the manifests again and run the conformance tests before deploying again.

pip install -U enterprise-ai
enterprise-ai doctor
enterprise-ai validate -f agent.yaml
enterprise-ai test sdk-conformance

Procedure​

  1. Read the release notes. They list what is new, changed and fixed, and the known issues of the release, so you know which manifests to review.

    Open the release notes of the target release.

    Expected result: you have the list of changed contracts and routes that your projects use.

    If it fails: when a change is not listed, compare the published schema docs/api/openapi-v1.json of the two releases.

  2. Upgrade the SDK and the CLI. The CLI ships with the Python SDK, so one upgrade covers both.

    pip install -U enterprise-ai

    Expected result: pip show enterprise-ai shows the new version.

    If it fails: check the package index or mirror your pip reads.

  3. Check the versions against the Control Plane. enterprise-ai doctor checks that the server reports the API version v1 (GET /v1/meta) and knows every contract the SDK ships (GET /v1/contracts).

    enterprise-ai doctor

    Expected result: the versions check is PASS.

    If it fails: FAIL means the server does not report the API version v1; WARN lists contracts the server does not know. Upgrade the side that is behind.

  4. Validate every manifest again. A newer contract may add a required field or a stricter rule.

    enterprise-ai validate -f agent.yaml

    Expected result: the manifest is valid.

    If it fails: fix each reported field; remotely the same check is POST /v1/contracts/{name}/validate, which answers "valid": false with the list of errors.

  5. Run the conformance and project tests. They prove the SDK and the server agree, and that the agent still behaves as before.

    enterprise-ai test sdk-conformance
    enterprise-ai test authz
    enterprise-ai test security --threshold 0

    Expected result: exit code 0 for each command.

    If it fails: exit code 1; see the Testing Guide.

  6. Deploy to dev, then promote. A deployment goes through the quality gate; a promotion to prod needs its approval.

    enterprise-ai deploy agent -f agent.yaml --env dev

    Expected result: the new version is listed in Agents > Registry (GET /v1/agents/{agent_id}/versions).

    If it fails: 409 gate_failed lists the failing checks in details.failures.

Per SDK notes​

The "Endpoints and fields aligned with the backend" tables of the TypeScript and Go guides list the fields and routes aligned with API v1 and contracts 1.1.

Troubleshooting​

SymptomCauseFix
enterprise-ai doctor: versions FAILthe server does not report the API version v1upgrade the SDK or the Control Plane so both match
enterprise-ai doctor: versions WARNthe server does not know a contract of the SDKupgrade the Control Plane, or keep the previous SDK
enterprise-ai test sdk-conformance exit code 1contract mismatchalign the SDK version with the server
422 invalid_manifest when a manifest is appliednew required field or stricter rulefix the manifest, validate again
409 gate_failed at deploymentthe new version fails an evaluation or red team targetfix, run the suites again

Next steps​