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. Managed deployment requests include an authored Agent's permission policy in the harness configuration sent to the control plane. 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. When agents serve or agents deploy cannot register the agent, the SDK emits agents.agent_registration.done with status error, the failure category and HTTP status, never the server's message. 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 and clients) and any Speakeasy-generated clients for the vibe_agents HTTP API as sibling submodules.

What's in this package

Two 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.

• 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 sessions_client submodule. Importing only session workflow 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.sessions_client import SessionsClient

Workflow child-session binding

For the Harness backend, Agent.to_workflow() takes no operator arguments. Its Workflow calls the Agents API Session procedures through WorkflowSessionControlPlaneBinding.from_worker_credential() (from mistralai.vibe_agents.sdk.app.worker.control_plane). Deployed workers (agents serve, agents run-worker and managed deployments) build this binding themselves.

• Credential and URL. The binding calls as the worker, with the service-account token at MISTRAL_SA_TOKEN_PATH, else MISTRAL_API_KEY, read again on every Activity attempt. The procedure root is /session-control-plane below AGENTS_SDK_DEPLOY_CONTROL_PLANE_URL when set, else below ${SERVER_URL}/v2/agents. The Agents API acts as the principal stored on the calling Session, and only for deployed agents in the worker's workspace. Signing keys and HTTP clients never enter Workflow payloads.
• Subagent policy. Each Session runs under the policy in its start input. The Agents API takes it from the agent's stored default when the root Session starts and copies it to every child. A Session with no policy cannot create subagents. A worker whose agent declares subagents=[...] registers a default policy of 10 child Turns; any other worker registers none, which clears an earlier one. Internal worker composition can give the private Workflow builder a binding and a static SubagentPolicy (from mistralai.vibe.harness.runtime.agents.policy), used when the start input has none. A worker whose agent declares subagents on a Sandbox its children cannot share fails at startup.
• Tools. The binding installs agents.list_configs, agents.spawn, agents.list, agents.send_message and agents.interrupt. Children run as independent top-level Workflows and borrow the root's Koyeb sandbox, or have none. The Session API checks the child Turn limit; its refusal reaches the model as a retryable error, as on a local Runtime. agents.spawn returns once the Session API has admitted the child, so the child is discoverable from then on.
• Results and interrupts. After each child Turn, its result goes to the parent through ordinary Session admission: a waiting parent wakes, an idle parent stays idle. Delivery never delays the Turn or changes its outcome. A parent's interrupt targets one exact child Turn and waits for it to end; it does not close the child Session. Only the parent-caused cancellation notice is hidden.

Independent Session discovery and observation

The Harness SessionClient exposes list_subagents(page=ListPageRequest(...)) for admitted direct-child links, newest first. Each link includes an ordinary summary, permanent alias, optional configuration name, and agent path. list_catalog() defaults to roots; DirectChildrenScope and TreeScope select ordinary summaries in newest-created order. Both use opaque next_cursor values bound to the caller and listing context. Import these request types from mistralai.vibe.harness.app_server.session.

rename_session(title) and archive_session(archived=True) update metadata only. The alias and execution remain unchanged; archived children remain in graph discovery, while catalog lists require include_archived=True to include them. These procedures use retained control-plane state, not child Workflow commands.

Attach each chosen child independently with its snapshot/cursor, then consume its own events after that cursor. A saved snapshot can be reattached through adopt_session_snapshot to replay a disconnected interval. Canonical metadata events can accompany legacy history during this migration; the SDK preserves the child's existing Turn/history state and exact Session/root lineage. Parent subscriptions do not include descendant transcripts.

Exact child callbacks and public interruption

An existing ClientToolDefinition without a handler compiles to a client-backed callback on both Local and Workflow Hosts. It can be inherited by a child even when that child authors its own Hooks. An authored permission_mode="ask" emits an approval callback on the exact child, before its client-tool callback. Other callback-backed hooks are available through the Harness Runtime registration API, not a new Agents SDK authoring wrapper.

Use async with root.provide_callbacks(kinds={"approval", "client_tool"}, handler=handler): one registration serves the callbacks of the Session and all its descendants, and answers each at the Session that opened it. The asynchronous handler receives the exact typed callback, with that Session in session_id, parent_session_id and agent_path, and returns a CallbackResult with its ID, or None to leave it pending. Closing the registration or client stops dispatch; it does not close the child's callback. A provider on a child serves that child and its own descendants; the first answer wins. These local kind claims do not replace Session authorization or guarantee exclusive processing across application clients. Use the callback ID for application-side effect idempotency. Authorized manual answer_callback(result, session_id=...) remains available. Handler failures interrupt the provider context with a task-group exception; the callback remains pending for another provider or an authorized manual reply.

The remote adapter retains callback variants through the existing callback history and result endpoints, including structured errors and annotations. It rejects stale or mismatched callback identities. Public child.interrupt_turn(expected_turn_id, reason="...") uses ordinary command admission, preserves completion races, and leaves later Turns untouched. The child and parent notification retain the public reason. Callback cleanup events may follow the terminal Turn event on interruption.

Workflow callback correlation and accepted replies remain available while their Turn or committed work still needs them. After that work commits, the Runtime retires the Host's request/result bookkeeping without deleting published history.

Public child control is limited to exact callback answers, exact interruption, rename, and archive. Reads stay available; start, steer, queue changes, configuration writes, compaction, reset, plugin reload, fork, delete, branching, and filesystem rewind do not become public child orchestration permissions.

Resource lifetime

Tool and Hook callable objects are shared by default within a local runtime or Workflow worker. Make them safe for concurrent calls. Each Session retains its own invocation context, Hook ordering, cancellation, and result correlation. Mutable callable memory is not durable Session state. Completion and connector HTTP clients are created per local Session or Workflow Activity; built-in HTTP MCP calls open separate protocol sessions, even when declarations are inherited.

Supported Sandbox-backed Sessions install process.* with Session-owned records, controls, and supervision. Each Session's process.* tools address only its own records. Children and grandchildren still share the root workspace and operating system; this is not OS-process security isolation. Ending a Turn or exporting execution for continuation does not dispose that workspace. Logical root closure deletes the Sandbox without closing descendant Sessions or removing their history; their Sandbox work can then fail. Child closure never deletes the root Sandbox. Saved definitions and continuation use binding and Sandbox references, not live clients or credentials.

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