Skip to content
Docs

Documentation navigation

Upgrading to the mAIvn SDK 2.0

Update from SDK 0.x: what moved, what was removed, and what to check before you deploy.

#Upgrading to the mAIvn SDK 2.0

SDK 2.0 replaces SDK 0.x. It keeps the same package name (maivn), the same credential, and almost the same public surface: of the names SDK 0.x exported, the large majority import unchanged in SDK 2.0. This page covers the rest — what moved, what was removed, and what to check before you deploy.

#Who needs to do anything

Most applications only need to upgrade the package and re-run their tests. If your code does not import from maivn.events and does not call compose_artifact_policy, get_interrupt_service, or set_interrupt_service, skip straight to Configuration changes to confirm your environment variables, then redeploy.

#1. Upgrade

Shell 
python -m pip install -U maivn

In a uv project:

Shell 
uv add maivn -U

The Python floor is unchanged: SDK 2.0 still requires Python 3.10 or newer, the same requirement as SDK 0.x.

#2. Your API keys keep working

Existing project API keys continue to authenticate after you upgrade. There is nothing to rotate and nothing to re-issue — the same MAIVN_API_KEY value (or the same key passed explicitly to Client(api_key=...) / Agent(api_key=...)) keeps working against SDK 2.0.

#3. Configuration changes

SDK 2.0 reads one renamed environment variable for the service address:

SDK 0.xSDK 2.0
MAIVN_SERVER_BASE_URLMAIVN_BASE_URL

There is exactly one address to set: mAIvn has a single public API entry point, and every SDK request goes there. If you never set MAIVN_SERVER_BASE_URL, there is nothing to change: the default address is https://api.maivn.io in both SDK 0.x and SDK 2.0.

MAIVN_API_KEY is unchanged.

#4. Import changes

Twenty-seven event and streaming helpers moved out of the top-level maivn module into maivn.events. Everything else you imported from maivn still imports from maivn.

Before (SDK 0.x):

Python 
from maivn import (
    AppEvent,
    EventBridge,
    RawSSEEvent,
    build_tool_start_payload,
    normalize_stream,
)

After (SDK 2.0):

Python 
from maivn.events import (
    AppEvent,
    EventBridge,
    RawSSEEvent,
    build_tool_start_payload,
    normalize_stream,
)

This covers AppEvent, UIEvent, RawSSEEvent, EventBridge, EventBridgeSecurityPolicy, BridgeAudience, BridgeRegistry, NormalizedStreamState, NormalizedEventForwardingState, APP_EVENT_CONTRACT_VERSION, every build_*_payload helper, forward_normalized_event, forward_normalized_stream, normalize_stream, and normalize_stream_event. If your import fails after upgrading with a message naming one of these, add maivn.events to that import line.

Everything else — Agent, Swarm, Client, ModelConfig, the tool_output / toolify / toolset decorators, the depends_on_* decorators, memory and resource configuration, and the schedule types (CronSchedule, IntervalSchedule, AtSchedule) — imports from maivn exactly as before.

#5. Removed APIs and what to use instead

Three names were removed. Both have a direct replacement.

compose_artifact_policy — this decorator restricted a specific tool argument's use of compose_artifact, including an approval requirement. There is no decorator equivalent in SDK 2.0. The closest replacement is an allow-list on your Agent or Swarm, through system_tools_config:

Python 
from maivn import Agent, SystemToolsConfig

agent = Agent(
    name="assistant",
    system_tools_config=SystemToolsConfig(
        approved_compose_argument_targets=["report_tool.summary"],
    ),
)

This allow-lists which "tool.argument" targets may receive a composed artifact at all. If you relied on compose_artifact_policy's per-argument approval requirement for a compliance control rather than a simple allow/deny, review that control specifically — the allow-list above does not carry an approval step of its own.

get_interrupt_service / set_interrupt_service — these managed a process-global interrupt service. There is no global registry in SDK 2.0. Pass your input handler directly where you declare the dependency instead:

Python 
from maivn import depends_on_interrupt

@depends_on_interrupt("approval", input_handler=my_input_handler, prompt="Approve this action?")
def send_email(approval, **kwargs):
    ...

If you previously swapped the global service in tests, construct and pass a handler per test instead of installing one globally.

#6. Signature and behavior changes

None found in the names carried over unchanged. Client, Agent, Swarm, ModelConfig, the schedule types, and every toolify / toolset / tool_output / depends_on_* decorator kept the same parameters and defaults. Invocation results kept the same fields you may already read — .response, .tool_names, .artifacts, .result, and .assistant_id are all still present with the same meaning.

#7. "This version of the mAIvn SDK is no longer supported"

If a call returns HTTP 426 with this body:

JSON 
{
  "detail": "This version of the mAIvn SDK is no longer supported. Upgrade with: pip install -U maivn. See the upgrade guide at https://developer.maivn.io/docs."
}

the platform has stopped accepting requests from an SDK release older than its current minimum supported version. This is unrelated to your API key, which is still valid — the fix is to upgrade the package (see step 1) and redeploy. There is no way to keep running the old release against the current platform.

#8. Calling the HTTP API directly

If your application talks to the HTTP API directly instead of through the maivn package, the REST API changed between SDK 0.x and SDK 2.0 alongside everything above. Do not guess at the new request or response shapes from this guide — work from the API Reference, which documents the current request and response shapes for every endpoint.

#Next steps

  • Versioning & Stability — what counts as a stable import going forward, and how future changes will be communicated.
  • Troubleshooting — concrete error messages and how to resolve each one.
  • Events — the full maivn.events surface.
  • API Reference — the per-endpoint HTTP reference.