mistralai-workflows-cli 1.2.2__tar.gz → 1.3.0__tar.gz

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/.gitignore

@@ -79,6 +79,9 @@ target/
 # Ruff
 .ruff_cache/
 
+# import-linter
+.import_linter_cache/
+
 # Jupyter Notebook
 .ipynb_checkpoints
 
@@ -128,6 +131,7 @@ celerybeat.pid
 .env.local
 .envrc
 .venv
+.run-vcw/
 env/
 venv/
 ENV/
@@ -222,6 +226,21 @@ jobs/run/checkpoints/test/consolidated/params.json
 
 # Agent plans (scratch planning docs)
 .agents/plans/
+
+# Playwright MCP accessibility snapshots (local browser-debug artifacts)
+.playwright-mcp/
+.playwright-cli/
+
 tsconfig.tsbuildinfo
 
 .vscode-test/
+infra/local/docker-compose.override.yaml
+
+# Atlas overlap-scan generated fixtures
+ts/packages/workflow-graph/tests/fixtures/overlap-views.json
+
+# Go build output (go/Makefile "build" target); already in go/.dockerignore
+go/bin/
+
+# GHA→Buildkite migration tracker (local working ledger, not version-controlled)
+tools/buildkite-pipeline/MIGRATION_STATUS.md

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/Makefile

@@ -42,6 +42,7 @@ integration-test:
 	$(MAKE) _test-start-examples
 	$(MAKE) _test-execute-help
 	$(MAKE) _test-execute-bad-json
+	$(MAKE) _test-make-check
 	$(MAKE) _test-wheel-contents
 	@echo ""
 	@echo "All integration tests passed."
@@ -124,3 +125,8 @@ _test-wheel-contents:
 		| grep -q "entrypoints/worker.py" \
 		&& echo "OK: wheel contains entrypoints package" \
 		|| (echo "FAIL: wheel is missing the entrypoints package" && exit 1)
+
+_test-make-check:
+	@echo "--- test: 'make check' (ruff, mypy, workflow lint) passes on the generated project"
+	cd $(GENERATED_PROJECT) && $(MAKE) check
+	@echo "OK: make check passes on the generated project"

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: mistralai-workflows-cli
-Version: 1.2.2
+Version: 1.3.0
 Summary: CLI to bootstrap Mistral Workflows projects
 Requires-Python: >=3.10
 Requires-Dist: click>=8.0

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/pyproject.toml

@@ -15,6 +15,7 @@ mistralai-workflows-cli = "mistral_workflows_cli.main:cli"
 
 [tool.uv]
 exclude-newer = "2 days"
+index-strategy = "first-index"
 
 [build-system]
 requires = ["hatchling", "uv-dynamic-versioning"]

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflows
-description: Framework for building durable workflows with orchestrated activities, used for background jobs, multi-step pipelines, scheduled tasks, LLM agents, or any process requiring fault tolerance, retries, and long-running execution. This skill provides comprehensive documentation and guidance for working with the Mistral Workflows framework.
+description: Use when writing, editing, or debugging Mistral Workflows code (`mistralai.workflows`): workflows and activities, background jobs, multi-step pipelines, scheduled tasks, durable LLM agents, and any process needing fault tolerance, retries, or long-running execution. Covers the determinism and import rules, the Mistral AI plugin API, activity timeouts and retries, signals and HITL, and a pre-flight check to run before finishing.
 license: Complete terms in LICENSE.txt
 ---
 
@@ -44,6 +44,8 @@ Focused snippets may use `from mistralai.workflows import workflow, activity, ..
 
 Call activities directly (`await my_activity(args)`); timeouts and retries live on the `@activity(...)` decorator, not at the call site.
 
+**Calling Mistral plugins:** prefer the plugin activities (`mistralai_chat_complete`, `mistralai_ocr`, `mistralai_embeddings`, `chat_parse_to_model`, …; see [Workflows Plugins](references/guides/workflows-plugins.mdx)) — they are sandbox-safe. Use the raw `mistralai.client.Mistral` only when no plugin fits, and import it inside the activity that uses it: a module-level import pulls in `httpx`, which the sandbox rejects at worker startup (see [Limitations](references/guides/limitations.mdx)). Hoist it to module scope only under `workflow.unsafe.imports_passed_through()`.
+
 ## Documentation Structure
 
 The documentation is organized into several categories:
@@ -76,22 +78,43 @@ The documentation is organized into several categories:
 - **[Connectors](references/guides/connectors.mdx)**: Call third-party tools (GitHub, Notion, Slack, ...) from a workflow or give them to an agent, without holding the service's credentials
 - **[Conversational Workflows](references/guides/assist-workflows.mdx)**: InteractiveWorkflow, HITL, ChatInput/FormInput, Canvas editing, Rich UI components, Tool UI states
 - **[Local Execution](references/guides/local-execution.mdx)**: No-infra dev mode with Pydantic model params
-- **[Limitations](references/guides/limitations.mdx)**: System constraints and limits
-- **[Workflows Plugins](references/guides/workflows-plugins.mdx)**: Mistral AI plugin, Webhook plugin, Nuage plugin, custom plugins
+- **[Limitations](references/guides/limitations.mdx)**: System constraints, determinism rules, sandbox import restrictions (module-level non-deterministic imports + `imports_passed_through`), I/O and heavy work belongs in activities, execution-history limits
+- **[Workflows Plugins](references/guides/workflows-plugins.mdx)**: Mistral AI plugin (calling chat / structured-output / embeddings / OCR models), Webhook plugin, Nuage plugin, custom plugins
 - **[Deployment Patterns](references/guides/_deployment-patterns.mdx)**: Best practices for deploying workflows
 - **[Migration v2 to v3](references/guides/migration-v2-to-v3.mdx)**: Breaking changes and upgrade steps from SDK v2 through v3.4.0
 
-### Testing
+### Testing & Diagnostics
 
 - **[Testing Workflows](references/guides/testing.md)**: Integration testing with `create_test_worker`, hang prevention, sandbox pitfalls
 - **[Diagnostics](references/guides/diagnostics.md)**: Run `wf-diagnose` locally or on Kubernetes to collect a diagnostic report for support triage
 
-**Quick-test script** — run any workflow in a local test environment with zero setup:
+### Internal References
+
+These are additional patterns and utilities not covered in the official docs:
+
+- **[Execution IDs](references/execution_ids.md)**: Generate deterministic execution IDs for child workflows
+- **[Pipeline Pattern](references/pipeline_pattern.md)**: Build multi-step workflows with declarative StepSpec definitions
+- **[Workflow Testing](references/workflow_testing.md)**: Ensure workflow classes are properly registered in workers
+
+## Testing
+
+Run the project's static checks before reporting a workflow as done. Three static checks are available:
+
+- `make lint` — Ruff: style, imports, and common errors (`make format` auto-fixes most)
+- `make typecheck` — mypy static type checking
+- `make lint-workflows` — Semgrep workflow rules: determinism violations, I/O outside activities, missing return-type annotations, unsafe imports (advisory — reports but does not block)
+
+And `make check` runs all three.
+
+To start the workflow and do a test run with sample inputs, use the `test_workflow.py` script:
+
 ```bash
-python .agents/skills/workflows/scripts/test_workflow.py <workflow_file> --input '{"key": "value"}' [--timeout 30]
+uv run python .agents/skills/workflows/scripts/test_workflow.py <workflow_file> --input '{"key": "value"}' [--timeout 30]
 ```
 
-**Timeout policy for testing:** Use aggressive (short) timeouts to keep the feedback loop tight. A hanging test wastes more time than a false timeout. Defaults:
+`ruff`, `mypy`, and `semgrep` are the project's dev dependencies; `make check` invokes them through `uv run`.
+
+Use timeouts to keep the feedback loop tight. A hanging test wastes more time than a false timeout. Defaults:
 
 | Context | Recommended timeout | When to increase |
 |---|---|---|
@@ -99,15 +122,9 @@ python .agents/skills/workflows/scripts/test_workflow.py <workflow_file> --input
 | `execution_timeout` (pytest) | `timedelta(seconds=10)` | Known long-running workflow |
 | `asyncio.wait_for` (pytest) | `15` seconds | Should always be slightly above `execution_timeout` |
 
-If a workflow is known to be long-running (e.g. multi-step agent, large data processing), increase timeouts proportionally — but start short and only raise them when you see legitimate timeout failures, not preemptively.
+If a workflow is known to be long-running (e.g. multi-step agent, large data processing), increase timeouts proportionally. Start short and only raise them when you see legitimate timeout failures, not preemptively.
 
-### Internal References
-
-These are additional patterns and utilities not covered in the official docs:
-
-- **[Execution IDs](references/execution_ids.md)**: Generate deterministic execution IDs for child workflows
-- **[Pipeline Pattern](references/pipeline_pattern.md)**: Build multi-step workflows with declarative StepSpec definitions
-- **[Workflow Testing](references/workflow_testing.md)**: Ensure workflow classes are properly registered in workers
+> **You must run the static checks and a test run before reporting a workflow as done.** This ensures that the workflow is deterministic, free of I/O outside activities, and passes basic integration tests. Failure to do so will result in failing workflows and wasted time for the developer. Never forget this.
 
 ## When to Use This Skill
 
@@ -139,4 +156,3 @@ Use this skill when you need to:
 - **Durable agents**: AI agents with MCP support, multi-agent handoffs, and persistent state
 - **Connectors**: Call external services with platform-managed credentials avoiding secrets in the workflow code
 - **Scalability**: Designed to handle complex, distributed applications
-

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/getting-started/value-proposition.mdx

@@ -59,7 +59,7 @@ result = await my_activity(name)  # Just call it
 
 ### 2. Configuration on Decorators
 
-- Activities: `@activity(start_to_close_timeout=..., retry_policy_max_attempts=..., rate_limit=..., name=...)`
+- Activities: `@activity(start_to_close_timeout=timedelta(seconds=30), retry_policy_max_attempts=3, name="fetch_data")`, where `start_to_close_timeout` takes a `datetime.timedelta`
 - Workflows: `@workflow.define(name=..., workflow_display_name=..., workflow_description=...)`
 - Configure once on the decorator instead of at every call site
 

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/activities.mdx

@@ -72,13 +72,15 @@ Customize activity identification with:
 Configure execution time limits to prevent runaway activities:
 
 ```python
-from datetime import datetime
+from datetime import timedelta
 
 @workflows.activity(
-    start_to_close_timeout=datetime.timedelta(minutes=10)
+    start_to_close_timeout=timedelta(minutes=10),
 )
 ```
 
+`start_to_close_timeout` and the other `*_timeout` params must be a `datetime.timedelta`. Passing an int or a string raises at activity-definition time.
+
 [Learn more about timeouts](#)
 
 ### 3. Retry Policies

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/concurrency.mdx

@@ -26,6 +26,26 @@ All patterns are built on the platform's workflow continuation primitives, provi
 - **Fault Tolerance**: Built-in error handling and retry mechanisms
 - **Progress Tracking**: Monitor execution progress through built-in observability features
 
+## Small Batches: `asyncio.gather`
+
+The patterns described in the other sections add continue-as-new, per-item progress, retry, and scale past a few thousand items. For fewer items, `asyncio.gather` is enough. Activities are awaitables, so gathering them runs concurrently with no bookkeeping, and you stay under the 51,200-event history limit that continue-as-new exists to manage.
+
+```python
+import asyncio
+
+# Named, heterogeneous calls:
+a, b, c = await asyncio.gather(
+    fetch(user_a),
+    fetch(user_b),
+    fetch(user_c),
+)
+
+# A collection you hold in full:
+results = await asyncio.gather(*[process_item(item) for item in params.items])
+```
+
+Use `execute_activities_in_parallel` past a few thousand items, or when you need continue-as-new, progress tracking, or per-item retry.
+
 ## List Executor Pattern
 
 ### Use Case

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/connectors.mdx

@@ -121,7 +121,6 @@ class GitHubIssueCreatorWorkflow:
 Fall back to worker credentials (omit `on_behalf_of`) when there's no triggering user or you deliberately want one shared identity. Caveats (platform-enforced):
 
 - **Needs a triggering user.** Starting an `on_behalf_of=True` workflow without a user session is rejected (`403 "On-behalf-of workflows require user identity"`). For the same reason it **can't be combined with `schedules`** — the SDK raises at definition time, since a scheduled run has no triggering user.
-- **Restricted to Mistral-internal orgs.** Registering an `on_behalf_of=True` workflow returns `403 "on_behalf workflows are currently restricted to Mistral-internal organizations"` unless the org is internal or the `ON_BEHALF_WORKFLOWS_ENABLED` feature flag is enabled.
 
 ## Connectors in durable agents
 

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/diagnostics.md

@@ -11,13 +11,13 @@ sidebar_position: 21
 ## Running Locally
 
 ```bash
-wf-diagnose
+uv run wf-diagnose
 ```
 
 Or via module:
 
 ```bash
-python -m mistralai.workflows.scripts.diagnose
+uv run python -m mistralai.workflows.scripts.diagnose
 ```
 
 ## Running on a Kubernetes Cluster

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/durable-agents.mdx

@@ -225,6 +225,31 @@ agent = Agent(
 )
 ```
 
+#### Forwarding credentials to a stdio server
+
+Some stdio MCP servers need credentials (e.g. a bot token) to authenticate. Use
+`env_mapping` to inject them from the worker's environment into the subprocess.
+The mapping goes from **subprocess variable name** to **worker variable name**:
+
+```python
+mcp_config = MCPStdioConfig(
+    command="npx",
+    args=["-y", "@notionhq/notion-mcp-server"],
+    name="notion_bot_a",
+    env_mapping={"NOTION_TOKEN": "NOTION_TOKEN_BOT_A"},
+)
+```
+
+Why pass a mapping instead of the raw values? Activity inputs are persisted to
+the Temporal event history, so loading secrets from the worker's environment and
+passing them directly would expose them there. With `env_mapping`, only the
+mapping names are serialized into activity params and event history; the secret
+values are read from the worker's environment inside the activity and never leave
+it. This also lets you run several instances of the same server with different
+credentials (e.g. `NOTION_TOKEN_BOT_A` and `NOTION_TOKEN_BOT_B`) on one worker.
+If a declared worker variable is missing from the environment, the activity
+fails fast.
+
 ### SSE MCP Server
 
 For remote MCP servers over Server-Sent Events:
@@ -247,6 +272,87 @@ agent = workflows_mistralai.Agent(
 )
 ```
 
+### Streamable HTTP MCP Server
+
+For remote MCP servers that speak the Streamable HTTP transport (`--transport http`),
+such as a self-hosted server behind an HTTP endpoint:
+
+> **Requires `mistralai>=2.8.0`.** The Streamable HTTP client ships in the `mistralai`
+> client from 2.8.0 (client-python#592). This plugin keeps a permissive floor
+> (`mistralai>=2.0.0`), so if you use `MCPStreamableHTTPConfig`, pin
+> `mistralai>=2.8.0` in your own project's dependencies.
+
+```python
+from mistralai.workflows.plugins.mistralai import MCPStreamableHTTPConfig
+
+mcp_config = MCPStreamableHTTPConfig(
+    url="https://your-mcp-server.com/mcp",
+    name="remote-tools",
+)
+
+agent = Agent(
+    model="mistral-medium-latest",
+    name="streamable-http-mcp-agent",
+    description="Agent with access to a Streamable HTTP MCP server",
+    mcp_clients=[mcp_config],
+)
+```
+
+#### Forwarding credentials to a Streamable HTTP server
+
+A Streamable HTTP server usually needs credentials on every request: a bearer token
+gating the endpoint and/or a per-request integration token. Set them from the
+worker's environment so no secret is ever serialized into the Temporal event history
+(the same reasoning as `env_mapping` above).
+
+Use `auth_token_env` for the endpoint bearer. The SDK reads the raw token from that
+worker variable inside the activity and sends it as `Authorization: Bearer <value>`,
+so store the raw token in your secret manager and let the SDK add the scheme:
+
+```python
+mcp_config = MCPStreamableHTTPConfig(
+    url="https://your-mcp-server.com/mcp",
+    name="remote-tools",
+    auth_token_env="MCP_ENDPOINT_TOKEN",
+)
+```
+
+Use `header_mapping` for any other per-request secret header. Like `env_mapping`,
+each entry maps an **HTTP header name** to a **worker variable name**, and only the
+names are serialized; the values are read from the worker's environment inside the
+activity:
+
+```python
+mcp_config = MCPStreamableHTTPConfig(
+    url="https://your-mcp-server.com/mcp",
+    name="notion",
+    auth_token_env="MCP_ENDPOINT_TOKEN",                    # -> Authorization: Bearer <value>
+    header_mapping={"Notion-Token": "NOTION_TOKEN_BOT_A"},  # header <- whole env value
+)
+```
+
+Only put non-secret values in the static `headers` field, since those are serialized
+into activity params. As with `env_mapping`, a declared worker variable that is
+missing from the environment makes the activity fail fast. A fresh client is opened
+per call, so different callers or tokens never share a session.
+
+**Redirects**
+
+By default the client does **not** follow HTTP redirects (`follow_redirects=False`).
+On a redirect, `httpx` only strips the `Authorization` header on cross-origin hops,
+so the per-request secret headers above (e.g. `Notion-Token`) would be resent to the
+redirect target, letting a compromised or open-redirecting MCP exfiltrate them. If
+your MCP server relies on redirects (for example `/mcp` -> `/mcp/`) and you trust
+every host it can redirect to, opt in:
+
+```python
+mcp_config = MCPStreamableHTTPConfig(
+    url="https://your-mcp-server.com/mcp",
+    name="remote-tools",
+    follow_redirects=True,
+)
+```
+
 ## Built-in Tools
 
 Use Mistral's built-in tools alongside activities:

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/limitations.mdx

@@ -144,6 +144,17 @@ if os.getenv("ENV") == "prod":
 
 must be performed in activities. While activities themselves can produce different outputs for the same inputs (as they might contain non-deterministic operations), the workflow code must behave deterministically based on the activity results it receives.
 
+### Imports must be deterministic too
+
+The sandbox also validates **imports**. A module-level `import` of a non-deterministic library (`httpx`, `requests`, `aiohttp`, the raw `mistralai` client, etc.) in a workflow file won't work in the sandbox — the worker rejects it while validating the workflow at startup, so the workflow never becomes runnable. Keep such imports **inside the activity** that uses them, or — when a top-level import is unavoidable (e.g. shared type hints) — wrap it so the sandbox lets it through:
+
+```python
+with workflows.workflow.unsafe.imports_passed_through():
+    import httpx
+```
+
+Only pass through imports you know are side-effect-free (no import-time I/O or global-state mutation).
+
 ### Maximum Execution History
 
 The execution history for each workflow is capped at 51,200 events or 50MB per workflow execution. This is a hard limit of the durable execution engine. In order to avoid hitting this limit, we recommend using `workflows.execute_activities_in_parallel`, that allows you to execute large amounts of activities in parallel, while having the lowest footprint on the execution history. [Learn more about concurrency patterns](concurrency).

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/rate-limiting.mdx

@@ -28,32 +28,30 @@ When **a key is provided**, multiple different activities that use the same key
 
 ```python
 import mistralai.workflows as workflows
-from mistralai import Mistral, Messages
 from mistralai.workflows import Depends
 from pydantic import BaseModel
 
-def get_mistral_client() -> Mistral:
-    """Creates a shared chat completion client with rate limiting"""
-    client = Mistral(
-        api_key="your_api_key",
-    )
-    return client
+
+def get_mistral_client():
+    """Shared Mistral client wired with workflows tracking + OBO interceptors."""
+    from mistralai.workflows.plugins.mistralai import get_mistral_client as _get_client
+
+    return _get_client()
+
 
 class CompletionParams(BaseModel):
     model: str
-    messages: Messages
+    messages: list[dict]
+
 
 @workflows.activity(rate_limit=workflows.RateLimit(time_window_in_sec=1, max_calls=100))
-async def generate_chat_response(
-    params: CompletionParams,
-    client: Mistral = Depends(get_mistral_client)
-):
-    """Generates a chat response using a shared client"""
-    # This activity can be called from multiple workflows
-    # but will share the same rate limit across all of them
+async def generate_chat_response(params: CompletionParams, client=Depends(get_mistral_client)):
+    """Generate a chat response using the shared client."""
     return await client.chat.complete_async(model=params.model, messages=params.messages)
 ```
 
+The `mistralai.workflows.plugins.mistralai` import lives inside `get_mistral_client`, not at module scope. Imported at the top of a workflow file, it pulls in `httpx`, which the determinism sandbox rejects at startup.
+
 **Behavior**: All workflows calling `generate_chat_response` share the same 100 calls/sec limit. If Workflow A makes 60 calls and Workflow B makes 50 calls in the same second, they compete for the same pool.
 
 **With a key**: Add `key="mistral_api"` to share this limit across multiple activities (e.g., `generate_chat_response`, `generate_embeddings`, `moderate_content`).

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/testing.md

@@ -11,7 +11,7 @@ sidebar_position: 20
 The fastest way to verify a workflow works end-to-end. No test files, no conftest, no pytest:
 
 ```bash
-python .agents/skills/workflows/scripts/test_workflow.py src/workflows/my_workflow.py \
+uv run python .agents/skills/workflows/scripts/test_workflow.py src/workflows/my_workflow.py \
   --input '{"key": "value"}' \
   --timeout 30
 ```
@@ -19,7 +19,7 @@ python .agents/skills/workflows/scripts/test_workflow.py src/workflows/my_workfl
 For interactive workflows that use `wait_for_input()`, provide `--interactions`:
 
 ```bash
-python .agents/skills/workflows/scripts/test_workflow.py src/workflows/my_workflow.py \
+uv run python .agents/skills/workflows/scripts/test_workflow.py src/workflows/my_workflow.py \
   --input '{}' \
   --interactions '[{"choice": "WFL"}]' \
   --timeout 60
@@ -40,6 +40,7 @@ Options:
 - `--timeout` (default 30): max seconds before the workflow is killed
 - `--workflow-name`: select a specific workflow if the file contains multiple
 - `--interactions`: JSON array of responses for interactive workflows
+- `DEPLOYMENT_NAME` (env): deployment the worker registers under; defaults to `"default"`
 
 Because the script uses a real worker, you get full worker logs (activity errors, retries, HTTP failures) in real time on stderr. No time-skipping — activities execute with real network calls.
 
@@ -115,7 +116,7 @@ Always use both.
 ### `start_to_close_timeout` must be a `timedelta`
 
 ```python
-# WRONG — causes infinite retry loop
+# WRONG — raises AttributeError: 'int' object has no attribute 'total_seconds'
 @activity(start_to_close_timeout=60)
 
 # RIGHT
@@ -148,3 +149,12 @@ The test client returns raw dicts. Access fields directly: `result["message"]`,
 ### Don't add `_emit_*` activities manually
 
 `create_test_worker` already registers all workflow-lifecycle event activities. Adding them again causes duplicate-activity registration errors.
+
+### `AMBIGUOUS_WORKFLOW` error
+
+Happens when multiple deployments register the same workflow name and the API can't tell which worker should run it. Set `DEPLOYMENT_NAME` to match the deployment your worker should register under:
+
+```bash
+DEPLOYMENT_NAME=my-deployment python .agents/skills/workflows/scripts/test_workflow.py \
+  src/workflows/my_workflow.py --input '{}'
+```

{mistralai_workflows_cli-1.2.2 → mistralai_workflows_cli-1.3.0}/src/mistral_workflows_cli/_template/template/.agents/skills/workflows/references/guides/workflows-plugins.mdx

@@ -78,6 +78,77 @@ class SummarizeWorkflow:
         return result.choices[0].message.content
 ```
 
+**Example — structured output:** to get a validated Pydantic object back instead of a string, define a model and build the same `ChatCompletionRequest` as above, then swap the final call for `chat_parse_to_model`:
+
+```python
+from pydantic import BaseModel
+from mistralai.workflows.plugins.mistralai import chat_parse_to_model
+
+class Sentiment(BaseModel):
+    label: str
+    score: float
+
+# inside the entrypoint, with `request` built as in the chat example above:
+sentiment = await chat_parse_to_model(Sentiment, request)
+```
+
+For the raw response instead of a parsed model, call `mistralai_chat_parse(request, response_format)` directly.
+
+**Example — embeddings** (call from inside an entrypoint or activity):
+
+```python
+from mistralai.workflows.plugins.mistralai import (
+    MistralEmbeddingsParams,
+    mistralai_embeddings,
+)
+
+response = await mistralai_embeddings(
+    MistralEmbeddingsParams(model="mistral-embed", inputs=["first text", "second text"]),
+)
+vectors = [item.embedding for item in response.data]
+```
+
+**Example — OCR** extracts text from a document or image URL:
+
+```python
+from mistralai.workflows import activity
+from mistralai.workflows.plugins.mistralai import OCRRequest, mistralai_ocr
+
+
+@activity()
+async def extract_text(document_url: str) -> list[str]:
+    from mistralai.client.models import DocumentURLChunk
+
+    result = await mistralai_ocr(
+        OCRRequest(
+            model="mistral-ocr-latest",
+            document=DocumentURLChunk(document_url=document_url),
+        ),
+    )
+    return [page.markdown for page in result.pages]
+```
+
+**Raw client (when a plugin activity isn't enough):** call the Mistral API directly from inside an activity, and keep the `from mistralai.client import Mistral` import inside the activity function. A module-level import of the raw client pulls in `httpx`, which the determinism sandbox rejects while validating the workflow at startup (see [Limitations](./limitations)). `mistralai` is a namespace package, so the path is `mistralai.client`; `from mistralai import Mistral` does not work:
+
+```python
+import os
+from mistralai.workflows import activity
+
+@activity()
+async def summarize(text: str) -> str:
+    # Import inside the activity so the workflow sandbox doesn't reject it.
+    from mistralai.client import Mistral  # NOT `from mistralai import Mistral`
+
+    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
+    resp = await client.chat.complete_async(
+        model="mistral-small-latest",
+        messages=[{"role": "user", "content": text}],
+    )
+    return resp.choices[0].message.content
+```
+
+Model calls and other I/O must run inside an activity, never in the workflow body; see [Limitations](./limitations) for the determinism and import rules.
+
 For full documentation on `Agent`, `Runner`, sessions, MCP, and multi-agent handoffs, see the [Durable Agents guide](./durable-agents).
 
 ### Webhook Plugin