vibe_agents_sdk

SDK for integrating with the vibe_agents platform.

The first Unified Harness backend release and its exact local/remote support matrix are documented in docs/unified-harness-backend.md. Agent folders authored with mistralai.agents use the Unified Harness remote runtime by default. The Nuage folder loader rejects them; use mistralai.agents.alpha for legacy Nuage agents. The long-term system boundaries, dependency direction, and delivery plan are documented in docs/agents-sdk-harness-target.md. The shared pytest and manual QA entrypoint is documented in docs/unified-harness-qa.md. Successful local session creation emits agents.session_started telemetry with stable identifiers and bounded dimensions. Failed startup emits no success event.

• PyPI / distribution name: mistralai-agents
• Import path: mistralai.vibe_agents (PEP 420 namespace package)

Layout follows the mistralai-workflows pattern: a single package that, over time, will host both the handwritten SDK (contract types, IntegrationManager client) and any Speakeasy-generated clients for the vibe_agents HTTP API as sibling submodules.

What's in this package

Three stable submodules today, plus the private-preview alpha agents bundle:

• mistralai.vibe_agents.session_workflow — pure type contract for session workflows: SessionStartIntent, SessionWorkflowStartInput / SessionWorkflowOutput including public_final_message for concise end-user termination text and failure_code for stable failed-session categories, SessionWorkflowCommand discriminated union and subtypes, Principal, SessionWorkflowSubscription, Toolset (per-session connector toolset binding, identified by id or name), WorkflowSessionEvent, WorkflowSessionEventType, SESSION_EVENT_TASK_TYPE, and the shared Task Protocol HistoryEntry / StateEntry / TaskState payload models. Principal requires distinct customer_id, organization_id, and workspace_id UUIDs; user_id is optional. workflow_name and deployment_name are control-plane dispatch metadata, not durable workflow input fields. Imported by any runtime that implements the vibe_agents SessionWorkflow contract. Hard dependencies are kept minimal: pydantic, structlog, typing-extensions. Emission is a one-liner workflows.task(SESSION_EVENT_TASK_TYPE, state=WorkflowSessionHistoryEntryEvent(...).model_dump()) at the caller using the concrete event variant for the row being emitted. Slack-specific integration-event helpers under session_workflow.integration_events.slack depend on the integration-events extra. They include typed channel-scoped agent_session_stopped control events.

• mistralai.vibe_agents.integration_manager — shared IntegrationManager capability contracts and identity models, including typed Slack session status and rename operations plus code-channel creation, property updates, archival, and block-only message updates that reject empty content. Concrete HTTP clients live in mistralai.vibe_agents.integration_manager.client and the live runtime builder lives in mistralai.vibe_agents.integration_manager.runtime; those pieces depend on httpx behind the integration-manager extra.

• mistralai.vibe_agents.sessions — typed HTTP client and response models for the vibe_agents sessions API, including the nullable generated session title read field. The concrete client depends on httpx behind the sessions-client extra.

• mistralai-agents-sdk-alpha — private-preview Cloudsmith bundle that installs the alpha Nuage agents runtime. It exposes from mistralai.agents.alpha import agents.

Future

A Speakeasy-generated client for the vibe_agents HTTP API will be added as a sibling submodule, under mistralai.vibe_agents.<name>.*. Same package, same distribution. This mirrors the mistralai-workflows setup where mistralai.workflows.worker_client (autogen) lives inside the same package as the handwritten workflow SDK.

Import discipline

The root __init__.py does NOT eagerly import the integration_manager submodule. Importing only session workflow or IntegrationManager contract types must not pull in HTTP client dependencies. Import concrete submodules explicitly:

from mistralai.vibe_agents.session_workflow import SessionWorkflowStartInput
from mistralai.vibe_agents.integration_manager.client import IntegrationManagerClient

The alpha agents runtime (mistralai.agents.alpha) is documented separately - install, quickstart, capabilities, and customization are on the official site: https://docs-internal-frameworks.mistral.ai/agents-sdk/ (or the local quickstart in ALPHA.md). Fastest way to install and play: npx openskills install mistralai/dashboard/vibe_agents/nuage_v2/docs/skills/agents-sdk-alpha-helper.

What this package does NOT contain

• vibe_agents service code. The service lives in its own package.
• Any dependency on vibe_agents. Runtimes using this SDK MUST NOT transitively pull in the vibe_agents service.

Contributing

• make lint — ruff format check + ruff check
• make typecheck — mypy
• make test — pytest (includes fuzz + integration tiers; excludes perf)
• make test-unit — unit tier only (excludes fuzz, integration, perf); CI runs this as its own job
• make coverage — pytest with branch coverage + missing-line report
• make fuzz — Hypothesis property tests over the parse/fold surfaces
• make test-integration — real client vs in-process fake ASGI server
• make perf — informational pytest-benchmark microbenchmarks (never gated)
• make format — ruff format + fix
• make installdeps — uv sync

Bundle wheel tree-shake (keep scripts/build_bundle_wheel.sh in sync)

scripts/build_bundle_wheel.sh packs the alpha SDK into one wheel and tree-shakes subtrees the import closure never loads via a hand-maintained PRUNE list. That list is an invariant tied to what the SDK imports, so it can drift when imports change. When you add, move, or remove an import in the SDK closure (or a dynamically/registry-loaded module such as a nuage integration, a polymorphic_type, a vibe.core tool, or a kazekit subpkg), re-check the PRUNE list: build the wheel, import it in a clean env, and confirm nothing it pruned is now needed. Do not prune anything loaded dynamically rather than via a static import.