Metadata-Version: 2.5
Name: mistralai-agents
Version: 1.1.0rc11
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.10
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-workflows<4,>=3.16.0
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.20,>=0.18; extra == 'bashkit'
Provides-Extra: cli
Requires-Dist: typer>=0.15; extra == 'cli'
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.2; extra == 'koyeb'
Provides-Extra: observability
Requires-Dist: mistralai-otel-observability>=0.4.1; extra == 'observability'
Requires-Dist: mistralai-vibe-harness[observability,workflows]==0.1.10; extra == 'observability'
Provides-Extra: sessions-client
Requires-Dist: httpx>=0.28.1; extra == 'sessions-client'
Requires-Dist: mistralai-vibe-harness==0.1.10; 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.
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`](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. 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.

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

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

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

Attach the child, then use
`async with child.provide_callbacks(kinds={"approval", "client_tool"}, handler=handler)`.
The asynchronous handler receives the exact typed callback 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.
Register independently on each Session. 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(...)` 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
