Agents
Coming soonAn agent uses a model, instructions, and tools to decide what to do next. Use the Agents SDK to define an agent in Python, give it access to your systems, and run it locally or from a worker.
For a single model request without an agent loop, use Chat completions. For a process with explicit steps, retries, and branching, see Workflows.
Get started with the Agents SDK
- Install the SDK and configure your API key.
- Follow the quickstart to define and run an agent with a Python tool.
- Choose a run mode when you are ready to use a worker.
The SDK has three main concepts: an Agent defines the model and instructions, a Harness defines capabilities, and a Session manages turns and events.
Add capabilities
The SDK exposes capabilities through the harness rather than the built-in tool configuration used by the Agents API:
| Task | SDK guide |
|---|---|
| Call your own Python functions | Tools |
| Connect to external systems over HTTP or MCP | Connectors & MCP |
| Run commands and work with files | Sandbox |
| Reuse instructions and resources | Skills |
| Require approval before tool calls | Permission |
| Check structured-output support and limitations | Structured output |
| Customize the agent loop | Custom hooks |
These are SDK capabilities, not a promise of one-to-one compatibility with the older API's tools or handoffs. Use each SDK guide to check its configuration and limitations.
Run in production
Start in-process while developing. For durable execution, the SDK supports self-hosted workers and Mistral-managed workers. The run modes guide explains registration, deployment, sessions, tracing, and replay-safe code.
- Managed agents: Mistral hosts the worker.
- Self-hosted agents: you run the worker; Mistral provides orchestration.
Existing Agents API users
The SDK and Agents API are different interfaces. The runtime SDK uses Python; the Agents API guides include Python, TypeScript, and cURL examples. Existing API documentation remains available in the Deprecated navigation group:
The SDK migration guide covers upgrading the SDK from 1.0.7 to 1.1.0. It is not a migration guide from the Agents API. Do not assume that API agents, tools, handoffs, or conversation state transfer automatically to SDK agents.