You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: public/studio-api/workflows/building-workflows/durable_agents.md
+47-22Lines changed: 47 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,19 @@
1
1
---
2
2
id: durable-agents
3
-
title: Durable Agents
3
+
title: Durable agents
4
4
sidebar_position: 6
5
5
---
6
6
7
-
# Durable Agents
7
+
# Durable agents
8
8
9
-
A Durable Agent is an LLM agent whose loop (model calls, tool use, handoffs) runs **inside a workflow**, so its state survives crashes and restarts. The Mistral plugin (`mistralai-workflows[mistralai]`) provides the primitives — `Agent`, `Runner`, `RemoteSession`, and `LocalSession` (experimental) — for building them.
9
+
A durable agent is an LLM agent whose loop (model calls, tool use, and handoffs) runs **inside a workflow**, so its state survives crashes and restarts. The Mistral plugin (`mistralai-workflows[mistralai]`) provides the primitives for building them: `Agent`, `Runner`, `RemoteSession`, and `LocalSession` (experimental).
10
10
11
11
What you get on top of a regular agent loop:
12
12
13
13
-**Durability**: agent state is preserved across worker crashes and restarts
14
14
-**Tool integration**: workflow activities can be passed directly as agent tools
15
15
-**Multi-agent handoffs**: agents can delegate tasks to specialized agents
16
-
-**MCP support**: connect to external tools via the Model Context Protocol (stdio / SSE)
16
+
-**MCP support**: connect to external tools with the Model Context Protocol (stdio or SSE)
Agents can delegate tasks to specialized agents using handoffs. The coordinator agent's `instructions` and the specialized agents' `description` fields guide handoff decisions; the model decides when to hand off based on the user query and the available specialists' descriptions. The system automatically manages the handoff conversation.
Some stdio MCP servers need credentials, such as a bot token, to authenticate. Use `env_mapping` to pass them from the worker's environment into the subprocess. Each mapping entry pairs the subprocess variable name with the worker variable name:
215
+
216
+
<Tabs>
217
+
<TabItemvalue="python"label="Python">
218
+
219
+
```python
220
+
from mistralai.workflows.plugins.mistralai import MCPStdioConfig
Use a mapping instead of raw values because activity inputs are persisted to the workflow's [event history](/studio-api/workflows/getting-started/core_concepts/events). Loading secrets from the worker's environment and passing them directly would expose them there.
234
+
235
+
With `env_mapping`, only the variable names are serialized. The activity reads the secret values from the worker's environment, and the values never leave the worker. A mapping also lets you run several instances of the same server with different credentials on one worker. If a declared worker variable is missing from the environment, the activity fails fast.
Use Mistral's built-in tools alongside activities:
243
268
@@ -276,9 +301,9 @@ These tools are executed server-side by the Mistral platform; they do not run in
276
301
**Built-in tools require RemoteSession**: `LocalSession` silently drops built-in tools (logs a warning and proceeds without them). Use `RemoteSession` for any agent that relies on `WebSearchTool`, `CodeInterpreterTool`, `ImageGenerationTool`, or `DocumentLibraryTool`.
When a `RemoteSession` initializes a conversation, it iterates over every agent in the handoff graph and either creates or updates it via the Agents API:
314
339
315
-
-**`Agent(id=None)`** — a new remote agent is created via`beta.agents.create()`. The returned ID is stored back on the `Agent` object, so subsequent runs with the **same instance** will reuse it.
316
-
-**`Agent(id="existing-id")`** — the existing remote agent is updated via`beta.agents.update()`. No new agent is created.
340
+
-**`Agent(id=None)`**: a new remote agent is created with`beta.agents.create()`. The returned ID is stored back on the `Agent` object, so subsequent runs with the **same instance** reuse it.
341
+
-**`Agent(id="existing-id")`**: the existing remote agent is updated with`beta.agents.update()`. No new agent is created.
317
342
318
343
To reuse a pre-existing agent across workflow executions, set `agent.id` before calling `Runner.run()`:
Agents created by `RemoteSession` are **not cleaned up automatically** after a run completes. If you create agents dynamically (without setting `id`), a new remote agent will be created on every workflow execution.
1.**Use `RemoteSession` for production** so the agent runs against the Agents API rather than the raw completion endpoint.
456
-
2.**Set `agent.id`** on agents you want to reuse across runs, otherwise`RemoteSession` creates a new remote agent on every execution and never cleans them up.
481
+
2.**Set `agent.id`** on agents you want to reuse across runs. Otherwise,`RemoteSession` creates a new remote agent on every execution and never cleans them up.
457
482
3.**Wrap tool side-effects in activities** so they get retry isolation and appear in the execution history.
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments