Vibe SDK

High-level Python interface for running Vibe agents.

The SDK gives you:

• Agent and stateful async/sync sessions
• Pydantic-based tool authoring
• Built-in filesystem tools
• Client-handled tools for UI- or host-dependent actions, such as asking the user a question
• Skills: reusable instruction sets advertised in the prompt and loaded on demand
• MCP server integration — discover a server's tools and expose them to the agent

For architecture and design references, see ARCHITECTURE.md and documentation/INDEX.md.

Advanced raw task-protocol examples live in examples/advanced_task_protocol_examples. They are not the primary public SDK API, but they are useful end-to-end probes for local, HTTP, and workflow execution.

Quick Start

Use run_to_completion() when you just want the final task state for one turn:

from mistralai.vibe.sdk import Agent, AgentConfig
from mistralai.vibe.sdk.providers.completion import MistralCompletionConfig

agent = Agent(
    config=AgentConfig(
        completion=MistralCompletionConfig(model="mistral-large-latest"),
        system_prompt="You are a concise assistant.",
    )
)

async with agent.session() as session:
    state = await session.run_to_completion("Hello")
    print(state.output)

Use run() when the host needs streaming updates, callback requests, or direct access to task protocol events:

from mistralai.vibe.sdk import Agent, AgentConfig
from mistralai.vibe.sdk.execution_record.patching.json_patch import apply_patches
from mistralai.vibe.sdk.execution_record.state import TaskState
from mistralai.vibe.sdk.providers.completion import MistralCompletionConfig
from mistralai.vibe.sdk.transports.events import TaskResultEvent, TaskStateUpdateEvent

agent = Agent(
    config=AgentConfig(
        completion=MistralCompletionConfig(model="mistral-large-latest"),
        system_prompt="You are a concise assistant.",
    )
)

async with agent.session() as session:
    state = TaskState(input="Hello")
    async for event in session.run("Hello"):
        if isinstance(event, TaskStateUpdateEvent):
            state = apply_patches(state, event.payload.patches)
        elif isinstance(event, TaskResultEvent):
            state = event.payload.result

    print(state.output)

Tool annotations

Use ToolResult to return metadata to non-model consumers while keeping the model-visible result compact:

from pydantic import BaseModel

from mistralai.vibe.sdk.capabilities import ToolResult, tool


class EditFileArgs(BaseModel):
    path: str
    previous_content: str


class EditFileResult(BaseModel):
    lines_changed: int


@tool(name="edit_file", description="Edit a file", input_schema=EditFileArgs)
def edit_file(args: EditFileArgs) -> ToolResult[EditFileResult]:
    return ToolResult(
        value=EditFileResult(lines_changed=2),
        annotations={"example.file_before": args.previous_content},
    )

Annotations are stored on the corresponding task-result history entry and are not included in the tool result sent to the model.

Skills

Skills let an agent discover short task-specific summaries up front and load the full instructions only when needed through the builtin skill tool.

from mistralai.vibe.sdk import Agent, AgentConfig, SkillDefinition
from mistralai.vibe.sdk.providers.completion import MistralCompletionConfig

agent = Agent(
    config=AgentConfig(
        completion=MistralCompletionConfig(model="mistral-large-latest"),
        skills=[
            SkillDefinition(
                name="interview",
                description="Use when running a structured user interview.",
                content="Ask one question at a time and summarize decisions at the end.",
            )
        ],
    )
)

MCP Servers

Add MCP servers in the mcps field of AgentConfig as a dict mapping a short local name to each server's config.

See the agent README for details on MCP support implementation.

Local (stdio) servers

Use StdioMcpConfig to launch a local subprocess and talk to it over stdio:

from mistralai.vibe.sdk import Agent, AgentConfig
from mistralai.vibe.sdk.capabilities.mcp import StdioMcpConfig

agent = Agent(
    config=AgentConfig(
        model="mistral-large-latest",
        mcps={
            "demo": StdioMcpConfig(command="python", args=["demo_mcp_server.py"]),
        },
    )
)

Secrets are never stored in the config. To pass host environment variables into the subprocess, list their names with env_key_names; the values are read from the host at launch:

StdioMcpConfig(
    command="my-mcp-server",
    args=[],
    env_key_names=["MY_SERVER_TOKEN"],
    timeout_ms=30_000,
)

Connector-backed servers

Use ConnectorMcpConfig to reach a Mistral connector instead of a local subprocess. By default it uses the SDK transport, reading the API key from MISTRAL_API_KEY. ConnectorMcpConfig accepts:

• connector_id_or_name — the connector to reach, by id or name (required).
• credentials_name — selects which named credential set the connector uses to resolve, list, and call tools. Leave unset to use the connector's default credential resolution.
• transport — how to reach the connector. Two modes are available:

1. ConnectorMcpSdkTransport reaches the connector through the public Mistral SDK. Accepts:

   • api_key_env_var — name of the host environment variable holding the Mistral API key. The value is read at runtime, so the secret is never stored in the serialized config. Defaults to MISTRAL_API_KEY.
   • server_url — override the Mistral API base URL. Optional; unset uses the SDK default.
   • timeout_ms — request timeout in milliseconds passed to the Mistral client. Optional; unset uses the SDK default.

2. ConnectorMcpDirectTransport reaches the connector directly over JSON-RPC HTTP, bypassing the public SDK. Accepts:

   • base_url — base URL of the connectors service to call (required).
   • origin_service — name of the calling service, used to identify the caller (required).
   • scoped_headers — extra HTTP headers sent with each request. Defaults to an empty mapping.
   • timeout_ms — request timeout in milliseconds. Must be greater than 0. Defaults to 30000.
   • mcp_path_template — endpoint path, relative to base_url, of the direct MCP endpoint. May include a {{connector_id}} placeholder that is substituted at runtime. Optional; rarely overridden. Defaults to /connectors-gateway/{{connector_id}}/mcp.

Example of a connector config for direct transport:

from mistralai.vibe.sdk.capabilities.mcp import (
    ConnectorMcpConfig,
    ConnectorMcpDirectTransport,
)

ConnectorMcpConfig(
    connector_id_or_name="<your-connector-id-or-name>",
    transport=ConnectorMcpDirectTransport(
        base_url="<base-url>",
        origin_service="<my-service>",
        scoped_headers={"x-tenant-id": "acme"},
        timeout_ms=30_000,
    ),
)

Remote HTTP servers

Use HttpMcpConfig to connect to a standard MCP server over Streamable HTTP:

from mistralai.vibe.sdk import Agent, AgentConfig
from mistralai.vibe.sdk.capabilities.mcp import HttpMcpConfig

agent = Agent(
    config=AgentConfig(
        model="mistral-large-latest",
        mcps={
            "remote": HttpMcpConfig(url="https://mcp.example.com/mcp"),
        },
    )
)

HttpMcpConfig accepts:

• url — the MCP server endpoint (required).
• scoped_headers — extra HTTP headers sent on every request. Values may be literals or {{ENV_VAR}} templates resolved from the host environment at request time, so secrets are never stored in the serialized config.
• timeout_ms — timeout in milliseconds for the MCP handshake and list_tools requests. Defaults to 30000.
• sse_read_timeout_ms — read timeout in milliseconds for streaming tool responses (SSE). Defaults to 300000 (5 min). Use this to tune long-running streaming tool calls.

See agent/ for how MCP tools are wired into the runtime, and examples/basic_repl for a runnable stdio demo.