Build a Telegram weather bot with the Mistral Agents SDK

Coming soon

Build a Telegram bot that answers weather questions in French, preserves the current conversation, and resets it when the user sends /new. You will test the agent and bot locally, then deploy the agent to Mistral without changing the bot code.

How it works

Telegram sends each text message to bot.py. The bot opens one Agents SDK session for the chat, forwards the message, and sends the agent's reply back to Telegram. The session retains the conversation until the user sends /new.

Telegram chat → bot.py → Agents SDK session → weather agent → get_weather()

Telegram chat → bot.py → Agents SDK session → weather agent → get_weather()

The get_weather() tool always returns sunny in <city>. Keeping the tool predictable makes it easy to test the agent and Telegram connection before replacing it with a weather API.

During local development, agents serve runs the agent on your computer. After deployment, Mistral runs the agent instead. The bot code does not change; you only update the agent name in .env.

The example in the SDK

The complete, runnable code lives in the Agents SDK repository — clone it and follow along:

git clone https://github.com/mistralai/dashboard.git
cd dashboard/agents/agents_sdk/examples/telegram_weather_bot

git clone https://github.com/mistralai/dashboard.git
cd dashboard/agents/agents_sdk/examples/telegram_weather_bot

File	What it shows
`agent/main.py`	The whole agent: a typed `@agents.tool`, and the `agent` object the CLI loads
`agent/run_agent.py`	A one-shot in-process run that imports that same `agent` object
`agent_client.py`	Opening a session, streaming a turn, and extracting the assistant reply
`bot.py`	Telegram handlers: one session per chat, `/new` reset, allowed-user check
`agent/Dockerfile`	The image a managed deployment builds

The example's README.md has the full setup and chat script.

Prerequisites

You need:

Python 3.12 and uv.
A Mistral API key with Workflows access. agents serve and agents deploy both require it.
A Telegram account.
To deploy the agent: a GitHub repository that you grant access to through the GitHub Connector in AI Studio. You can complete the local steps without it.

1. Try the agent

From the agent/ project, install and inspect what the CLI discovers:

cd agent
uv sync
uv run --frozen --env-file .env agents info

cd agent
uv sync
uv run --frozen --env-file .env agents info

agents info lists the agent and its get_weather tool. Then run it once from Python before adding Telegram:

uv run --frozen --env-file .env python run_agent.py

uv run --frozen --env-file .env python run_agent.py

run_agent.py imports the same agent object out of main.py that the CLI loads, so the script and the served agent cannot drift. You should receive a short French answer saying Paris is sunny.

2. Serve the agent

bot.py runs separately from the agent, so it cannot use the in-process Agent object from step

Start the agent with agents serve so the bot can open sessions against it:

uv run --frozen --env-file .env agents serve

uv run --frozen --env-file .env agents serve

The command registers the agent with Mistral Workflows, runs it on your computer, and prints links to chat with it or inspect its runs. Keep the command running while you test the Telegram bot.

Mistral identifies served and deployed agents by name. The example uses alice as a placeholder: replace it with a unique lowercase identifier, such as your GitHub handle, everywhere it appears.

3. Run the bot

Create a bot with Telegram's verified @BotFather account (/newbot, pick a name and a username ending in bot, copy the token). Keep the token secret: anyone who has it can control your bot.

Back in the telegram_weather_bot/ directory, copy .env.example to .env and fill in the bot token, your Mistral API key, and the agent name. TELEGRAM_ALLOWED_USER_ID stays at 0 until the first run — the bot's /id command tells you your Telegram user ID, and the check stops other users from spending your Mistral quota.

uv sync
uv run --frozen --env-file .env python bot.py

uv sync
uv run --frozen --env-file .env python bot.py

In your direct chat with the bot, send /id, put the number into TELEGRAM_ALLOWED_USER_ID, restart the bot, then:

/start
Quel temps fait-il à Paris ?
Souviens-toi que ma ville préférée est Lyon.
Quelle est ma ville préférée ?
/new
Quelle est ma ville préférée ?

/start
Quel temps fait-il à Paris ?
Souviens-toi que ma ville préférée est Lyon.
Quelle est ma ville préférée ?
/new
Quelle est ma ville préférée ?

The weather answer should be in French. The agent should remember Lyon within that session. After /new, it should no longer know which city you chose.

4. Deploy the agent to Mistral

The bot currently depends on agents serve running on your computer. A managed deployment builds the agent from Git — push agent/ to a repository the GitHub Connector can read (never commit .env), then deploy without the -local suffix:

cd agent
uv run --frozen --env-file .env \
  agents deploy . --name french-weather-agent-alice

cd agent
uv run --frozen --env-file .env \
  agents deploy . --name french-weather-agent-alice

The locally served agent and managed deployment share a Mistral workspace, where names are unique. Using french-weather-agent-alice-local locally and french-weather-agent-alice for the deployment keeps the two registrations from colliding.

Stop agents serve, change AGENT_NAME in the bot's .env to the deployed name, and restart bot.py. If the bot still answers, it is using the agent hosted by Mistral. Only the agent is deployed; bot.py still runs on your computer.

To update the deployment, push the change and deploy again with the same name — reusing a name updates that deployment, a different one creates a separate deployment.

Inspect sessions in Mistral Studio

Sessions handled by agents started with either agents serve or agents deploy appear in Agent sessions in Mistral Studio. Open a session to review its messages, tool calls, and status.

Troubleshooting

`agents serve` cannot register the agent

Check that MISTRAL_API_KEY is valid and has Workflows access. A key that can call a model may still lack permission to register a worker.

`uv run --frozen` cannot find `uv.lock`

Run uv sync once in that project, then retry the command.

Package installation returns `403` or filters the release

Follow the mirror and exclude-newer fixes on the Installation page.

The Telegram bot does not answer

Keep bot.py running. While testing locally, keep agents serve running too. Send messages in a direct chat, confirm TELEGRAM_ALLOWED_USER_ID matches /id, and check AGENT_NAME. Restart the bot after changing .env, then inspect its terminal for the reported error.

Telegram reports a polling conflict

Only one bot.py process can poll with a bot token. Stop the other process and restart this one.

The managed deployment cannot read the source

Confirm that the commit is pushed to a repository in the Mistral GitHub organization and that the GitHub Connector is enabled in AI Studio and has access to that repository.

Resources and next steps

Sessions explains conversation history and the event stream used by bot.py.
Tools shows how to replace the mocked weather function with a real integration.
Run modes compares direct calls, self-hosted workers, and managed deployments, and documents what the CLI loads from a project.