The Agent

Coming soon

The Agent is the brains - the model plus its system prompt - and the entrypoint to everything. What the agent can do lives on the Harness; the Agent owns the model, the prompt, and how the loop runs (which built-in tools, how many steps, when to compact).

from mistralai.agents import agents

agent = agents.Agent(model="mistral-medium-3-5", instructions="Be concise.")

from mistralai.agents import agents

agent = agents.Agent(model="mistral-medium-3-5", instructions="Be concise.")

Constructor

agents.Agent(...) takes the model and prompting policy. The most common fields:

Field	Type	Description
`model`	`str`	The Mistral model to run, e.g. `"mistral-medium-3-5"`.
`instructions`	`str`	The system prompt - the agent's instructions. When set, it replaces the runtime's default identity prompt; when unset, that default applies.
`harness`	`Harness`	The body the agent uses (tools, sandbox, hooks). Omit for a default `Harness()`.
`provider`	`"mistral" \| "openai" \| "anthropic"`	Built-in completion provider. Defaults to `"mistral"`.
`completion`	`CompletionConfig`	A built-in completion configuration or a registered custom completion provider. Replaces `provider`; do not pass both.
`max_iterations`	`int`	Cap on agent-loop steps per run.
`reasoning_effort`	`"none" \| "minimal" \| "low" \| "medium" \| "high" \| "xhigh"`	Select the model reasoning level.
`temperature`	`float`	Sampling temperature between `0` and `2`. Lower it (e.g. `0.1`) for more consistent, deterministic answers. Supported by the `"mistral"` and `"openai"` providers; not `"anthropic"`.
`auto_compact_threshold`	`int`	Token budget before the loop summarizes older turns. Off by default (`0`); set a positive budget to enable.
`first_output_timeout_seconds`	`float`	Seconds one model call waits for its first output before it fails and is retried. Later output has no deadline. Off by default (`None`).

Provider retries

Built-in providers retry the initial stream request when the provider reports a transient failure. The retry policy is part of the serialized completion configuration.

from mistralai.agents import agents
from mistralai.vibe.harness.runtime.completion import RetryConfig
from mistralai.vibe.harness.runtime.completion.providers.mistral import MistralCompletionConfig

agent = agents.Agent(
    model="mistral-medium-3-5",
    completion=MistralCompletionConfig(
        model="mistral-medium-3-5",
        retry=RetryConfig(max_attempts=5, retry_after_max_wait_seconds=30),
    ),
)

from mistralai.agents import agents
from mistralai.vibe.harness.runtime.completion import RetryConfig
from mistralai.vibe.harness.runtime.completion.providers.mistral import MistralCompletionConfig

agent = agents.Agent(
    model="mistral-medium-3-5",
    completion=MistralCompletionConfig(
        model="mistral-medium-3-5",
        retry=RetryConfig(max_attempts=5, retry_after_max_wait_seconds=30),
    ),
)

max_attempts defaults to 3. retry_after_max_wait_seconds defaults to 60 seconds.

The policy is the same in local, served, and managed execution. Exhausted attempts fail the current Turn. The Session remains usable for another Turn.

:::note Tools live on the Harness Your own functions and connectors go on the Harness (tools=[...]), not the Agent. Passing tools= to Agent(...) raises, to catch that mix-up early. :::

run() vs a session

`run()` vs a session

The Agent exposes exactly two ways to run. Both use the harness and prompting policy fixed on the Agent at construction.

agent.run(content, *, response_format=None) answers a single prompt and returns a RunResult. Under the hood it opens a one-turn session and closes it.

result = await agent.run("Say hello in three words.")
print(result.text)

result = await agent.run("Say hello in three words.")
print(result.text)

agent.create_session(...) is the other one: a conversation the agent remembers across turns, which you can also steer or interrupt while a turn runs. It is a different shape, streaming events rather than returning a RunResult, and it has its own page. See Sessions.

await agent.run_worker() runs the agent as a durable worker, without registering it. It's mostly an internal API that you don't use directly. See Run modes.

RunResult

agent.run(...) returns a RunResult:

Attribute	Type	Description
`text`	`str`	The agent's final text reply.
`output`	`T \| None`	The reply parsed into your Pydantic model - populated only when you passed `response_format=`. `None` otherwise.
`turn_number`	`int`	Number of user turns in the conversation so far.
`stop_reason`	`str`	`"completed"` or `"error"`.

result = await agent.run("Say hello.")
print(result.text)

result = await agent.run("Say hello.")
print(result.text)

Structured output

Pass a Pydantic model as response_format= and RunResult.output comes back parsed instead of None. It is run-scoped, and currently broken. See Structured output.

Auto-compaction

Set auto_compact_threshold to a positive token budget and the loop summarizes older turns once the live context passes it, so a long conversation keeps going. Off by default. See Auto-compaction.