Metadata-Version: 2.5
Name: mistralai-agents
Version: 1.1.0rc1
Summary: Mistral Agents SDK - build and serve agents in Python
Author-email: Mistral AI <support@mistral.ai>
License: Apache-2.0
Keywords: agents,ai,llm,mistral,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: mistralai-vibe-harness[workflows]==0.1.3
Requires-Dist: mistralai-vibe-sdk<0.15,>=0.14.0
Requires-Dist: mistralai-workflows-plugins-mistralai<4.0.0,>=3.0.0a1
Requires-Dist: mistralai[workflow-payload-compression]<3,>=2.8.0
Requires-Dist: packaging>=24.1
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pyyaml>=6.0
Requires-Dist: structlog<26,>=25.5.0
Requires-Dist: typer>=0.15
Requires-Dist: typing-extensions>=4.16.0
Provides-Extra: alpha
Requires-Dist: mistralai-workflows-plugins-nuage-v2; extra == 'alpha'
Provides-Extra: bashkit
Requires-Dist: bashkit<0.15,>=0.14; extra == 'bashkit'
Provides-Extra: cli
Requires-Dist: typer>=0.15; extra == 'cli'
Provides-Extra: integration-events
Requires-Dist: mistralai-webhook-provider-contracts; extra == 'integration-events'
Provides-Extra: integration-manager
Requires-Dist: cachetools<8,>=7.1.6; extra == 'integration-manager'
Requires-Dist: httpx>=0.28.1; extra == 'integration-manager'
Provides-Extra: sessions-client
Requires-Dist: httpx>=0.28.1; extra == 'sessions-client'
Requires-Dist: mistralai-vibe-harness==0.1.3; extra == 'sessions-client'
Description-Content-Type: text/markdown

# vibe_agents_sdk

SDK for integrating with the `vibe_agents` platform.

> [!NOTE]
> Looking for the **alpha agents runtime** (`mistralai.agents.alpha`)? That is a
> separate self-contained bundle with its own docs. Full documentation - install,
> quickstart, capabilities - is on the official site:
> **https://docs-internal-frameworks.mistral.ai/agents-sdk/**
>
> Fastest way to install and play:
> `npx openskills install mistralai/dashboard/vibe_agents/nuage_v2/docs/skills/agents-sdk-alpha-helper`
>
> `mistralai.agents.alpha` keeps the Nuage-compatible authoring API. The
> Unified Harness API is `mistralai.vibe_agents.sdk.agents`.

The first Unified Harness backend release and its exact local/remote support
matrix are documented in
[`docs/unified-harness-backend.md`](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`](docs/agents-sdk-harness-target.md).
The shared pytest and manual QA entrypoint is documented in
[`docs/unified-harness-qa.md`](docs/unified-harness-qa.md).

- 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:

```python
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](./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.
