Migrate from 1.0.7 to 1.1.0

This guide covers migration from Agents SDK 1.0.7 to the 1.1.0 API, including package and import changes, explicit Agent / Harness wiring, tools, permissions, custom completion providers, and sessions. The examples target mistralai-agents==1.1.0rc4, a release candidate for 1.1.0.

For folder-based agents (agent/agent.py, AGENTS.md, and discovered slots), steps 2 and 3 show how to replace discovery with a Python entrypoint. If you already construct your agent in Python, keep that layout and review the API and capability changes below. Your prompts and tool implementations can stay in separate files.

Review the capability differences below before upgrading an existing application; updating imports and wiring alone does not establish runtime parity.

:::warning Subagents are a migration blocker The subagents page is work in progress. Moving child definitions into Python does not restore delegation, background execution, wait_subagents, or parent harness/sandbox inheritance. Do not silently drop children or present a hand-written agent-as-tool wrapper as equivalent to the old beta. :::

Replace the old Agents SDK dependency (mistralai-agents-sdk-alpha, or the intermediate mistralai-agents-sdk distribution) with the renamed package. Preserve your application's other dependencies and any extras it actually needs:

[project]
name = "support-triage"
version = "0.1.0"
requires-python = ">=3.12,<3.15"
dependencies = ["mistralai-agents[cli]==1.1.0rc4"]

[tool.mistralai.agents]
entrypoint = "main:agent"

[tool.uv]
prerelease = "allow"

[project]
name = "support-triage"
version = "0.1.0"
requires-python = ">=3.12,<3.15"
dependencies = ["mistralai-agents[cli]==1.1.0rc4"]

[tool.mistralai.agents]
entrypoint = "main:agent"

[tool.uv]
prerelease = "allow"

The package is available on PyPI. Remove obsolete source/index mappings for the replaced SDK dependency, while keeping indexes needed by other packages. Follow Installation if your environment has a package cutoff or index policy. Regenerate and commit your lockfile after changing dependencies.

Delete [tool.mistralai.agents].runtime ("remote" or "nuage"): the new CLI rejects it. Update SDK imports from from mistralai.agents.alpha import agents to from mistralai.agents import agents. Check each imported beta/helper against the new API; a namespace replacement alone is not a migration.

Here is a minimal legacy project:

support-triage/
├── pyproject.toml
└── agent/
    ├── agent.py
    ├── AGENTS.md
    └── tools/
        └── lookup_order.py

support-triage/
├── pyproject.toml
└── agent/
    ├── agent.py
    ├── AGENTS.md
    └── tools/
        └── lookup_order.py

The old agent/agent.py left instructions unset so the loader read AGENTS.md:

from mistralai.agents.alpha import agents

agent = agents.Agent(
    name="support-triage",
    description="Look up an order's status.",
    model="mistral-medium-3-5",
)

from mistralai.agents.alpha import agents

agent = agents.Agent(
    name="support-triage",
    description="Look up an order's status.",
    model="mistral-medium-3-5",
)

Keep the prompt file. Turn the remaining files into ordinary importable Python modules:

support-triage/
├── pyproject.toml
├── main.py
└── support_agent/
    ├── __init__.py
    ├── AGENTS.md
    └── tools.py

support-triage/
├── pyproject.toml
├── main.py
└── support_agent/
    ├── __init__.py
    ├── AGENTS.md
    └── tools.py

For this example, support_agent/AGENTS.md contains:

You help users look up orders. Use lookup_order for order status.
If the tool returns unknown, say that the order was not found.

You help users look up orders. Use lookup_order for order status.
If the tool returns unknown, say that the order was not found.

Move the tool implementation into support_agent/tools.py, using the new import:

from pydantic import BaseModel

from mistralai.agents import agents


class LookupOrderInput(BaseModel):
    order_id: str


@agents.tool(
    name="lookup_order",
    description="Look up an order's status.",
    input_schema=LookupOrderInput,
)
async def lookup_order(args: LookupOrderInput) -> dict[str, str]:
    # Example data; retain your existing business implementation when migrating.
    return {"status": "shipped" if args.order_id == "A1" else "unknown"}

from pydantic import BaseModel

from mistralai.agents import agents


class LookupOrderInput(BaseModel):
    order_id: str


@agents.tool(
    name="lookup_order",
    description="Look up an order's status.",
    input_schema=LookupOrderInput,
)
async def lookup_order(args: LookupOrderInput) -> dict[str, str]:
    # Example data; retain your existing business implementation when migrating.
    return {"status": "shipped" if args.order_id == "A1" else "unknown"}

Then construct the agent in main.py:

import asyncio
from pathlib import Path

from mistralai.agents import agents

from support_agent.tools import lookup_order


PROJECT_ROOT = Path(__file__).resolve().parent

agent = agents.Agent(
    name="support-triage",
    description="Look up an order's status.",
    model="mistral-medium-3-5",
    instructions=(PROJECT_ROOT / "support_agent" / "AGENTS.md").read_text(encoding="utf-8"),
    harness=agents.Harness(tools=[lookup_order]),
)


async def main() -> None:
    result = await agent.run("What is the status of order A1?")
    print(result.text)


if __name__ == "__main__":
    asyncio.run(main())

import asyncio
from pathlib import Path

from mistralai.agents import agents

from support_agent.tools import lookup_order


PROJECT_ROOT = Path(__file__).resolve().parent

agent = agents.Agent(
    name="support-triage",
    description="Look up an order's status.",
    model="mistral-medium-3-5",
    instructions=(PROJECT_ROOT / "support_agent" / "AGENTS.md").read_text(encoding="utf-8"),
    harness=agents.Harness(tools=[lookup_order]),
)


async def main() -> None:
    result = await agent.run("What is the status of order A1?")
    print(result.text)


if __name__ == "__main__":
    asyncio.run(main())

AGENTS.md no longer has automatic prompt semantics. Read it explicitly, relative to the module, and include it in the deployed artifact. If the old agent.py already specified instructions, preserve that value instead: it took precedence over the file.

The CLI imports main:agent, so keep network calls and agent execution out of module-level code. The __main__ guard above allows both CLI inspection and direct execution.

Use the old agents info output as an inventory, captured in the old environment before upgrading. Account for every discovered object in the new definition:

See Harness, Tools, Connectors & MCP, and Sandbox for the supported constructors. Local skills still support SKILL.md directories through LocalSkillBundle.from_directory(); they are separate from whole-agent folder discovery.

Review enabled_tools / disabled_tools instead of copying them unchanged. In 1.0.7 these selected built-in tools; in 1.1.0rc4 they also filter your authored tools by name (with glob patterns). An old enabled_tools=["web_search"] can therefore hide lookup_order. enabled_tools=[] disables all authored tools; neither setting installs the old hosted web-search tool. Wire the replacement tools explicitly and verify that they can be called at runtime. agents info lists authored tools before these filters, so it cannot prove that a tool reaches the model.

Two changes need particular care:

• Permissions: the default permission_mode="auto" permits tool calls. Do not remove old permission betas and accidentally allow previously restricted actions. Reimplement and test the intended policy using Permission and, if needed, a custom hook. "ask" requires a session that answers callbacks; agent.run() cannot do that.
• Hooks: preserve configuration when rebuilding hooks on a worker with to_unified_state() and from_unified_state(). A successful local run does not exercise worker reconstruction. Follow Custom hooks, including the limits on hook state and session-history visibility.

1.1.0rc4 supports Agent(completion=...) without widening a private SDK union or patching SDK internals. Follow Custom completion provider for a complete registered adapter example.

Port the old config and provider to the unified CompletionConfigBase / CompletionProvider protocol; an old CompletionConfig subclass is not automatically compatible. Give the config a unique type discriminator and register it with register_completion_provider before constructing the agent. Make the registration module importable and execute registration in every process that deserializes the config or builds the provider, including activity workers.

Set Agent.model to exactly completion.model, and omit provider=. Keep secret references in serialized config and resolve credentials in the provider's runtime environment. Custom completion does not support Agent(reasoning_effort=...), Agent(temperature=...), or run(..., response_format=...) in this release. Verify tool-call streaming and error handling against your gateway before removing the old adapter or patch.

Agent.load_from("path/to/project") is no longer the public folder loader. Import the Python agent object for local use. Agent.load_from(agent_name="...") attaches to an agent that runs on the control plane; it does not load a local directory.

From the example project root:

uv sync
uv run agents info .
uv run python main.py

uv sync
uv run agents info .
uv run python main.py

Inspection needs no model call. Running main.py needs credentials for the selected provider (MISTRAL_API_KEY for this example). Compare the listed tools, connectors, sandbox, and hooks with the old inventory. Review the complete prompt and tool schemas in source: agents info truncates the prompt and does not print schemas or the filtered runtime catalog. It confirms the entrypoint loads, not behavioral equivalence.

Before switching traffic:

• Run representative conversations against old and new versions: successful tool calls, missing data, denied actions, approvals, failures, and multi-turn context.
• Adapt streaming consumers to the session events and callbacks. Do not assume old local snapshots or in-flight workflow state can be loaded into the new runtime.
• Test the worker path separately with uv run agents serve . --name support-triage-migration in a test workspace. Use a separate agent name to keep existing traffic on the old worker.
• Build the actual deployment image and verify it installs the pinned SDK, your tools and provider package, and includes prompts and skills. A local dependency install does not prove that the Dockerfile installs the same dependencies. See Run modes.
• Keep the previous artifact and lockfile available for rollback. Move traffic only after required capabilities and regression checks pass; leave existing sessions on their compatible worker until your session transition has been validated.

Going further