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 run on the Unified Harness remote runtime. 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. Set AGENTS_SDK_TELEMETRY_ENABLED=false in tests and CI: the SDK then emits no telemetry, and asks the control plane, through X-Mistral-Exclude-From-Analytics, to flag the events it emits for the run so they stay out of product analytics.

• 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 mistralai.agents authoring surface:

• 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, block-only message updates that reject empty content, and Slack thread history that preserves complete secondary-attachment JSON. 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_client — 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. Cloud smoke tests can use MessageCommand(source="cloud_test", ...) to identify test traffic while exercising the web cloud runtime without an unknown-source warning.

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

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