Metadata-Version: 2.5
Name: mistralai-agents
Version: 1.1.0rc5
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.4
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: 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: koyeb
Requires-Dist: koyeb-sdk<2,>=1.5; extra == 'koyeb'
Provides-Extra: sessions-client
Requires-Dist: httpx>=0.28.1; extra == 'sessions-client'
Requires-Dist: mistralai-vibe-harness==0.1.4; extra == 'sessions-client'
Description-Content-Type: text/markdown

# vibe_agents_sdk

SDK for integrating with the `vibe_agents` platform.

> [!NOTE]
> The authoring API is `mistralai.vibe_agents.sdk.agents`. Full documentation -
> install, quickstart, capabilities - is on the official site:
> **https://docs-internal-frameworks.mistral.ai/agents-sdk/**

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

## 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
```

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