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

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.

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.

Quick Start

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)

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.",
            )
        ],
    )
)