Utiliser une clé API partagée pour un connecteur (recherche sur le Web avec Tavily)

La plupart des connecteurs appellent un service tiers au nom de l'utilisateur qui a démarré la session : Gmail ou Linear, où chaque utilisateur se connecte avec son propre compte. La recherche sur le Web n'utilise pas de compte individuel. L'espace de travail stocke une clé Tavily que toutes les sessions utilisent. Le connecteur de cet agent s'exécute sous l'identité du déploiement.

Ce que montre cet exemple : les connecteurs et leur identité, la mise à disposition et le déploiement d'un agent.

Exécutez (après la configuration ci-dessous), depuis le dossier de l'exemple : MISTRAL_API_KEY=... uv run agents serve

from mistralai import agents

# Tavily authenticates with one bearer key held for the workspace, so there is no per-user grant to
# act on behalf of.
tavily = agents.connector("tavily", run_as="deployment", credentials_name="tavily-shared")

agent = agents.Agent(
    model="mistral-large-4",
    name="deployment-identity-agent",
    description="Answers questions from the web using the workspace's shared Tavily key.",
    instructions=(
        "Answer questions by searching the web. Cite the URLs you used. Keep answers to a few sentences. "
        "If a search returns nothing useful, say so instead of guessing."
    ),
    connectors=[tavily],
)

from mistralai import agents

# Tavily authenticates with one bearer key held for the workspace, so there is no per-user grant to
# act on behalf of.
tavily = agents.connector("tavily", run_as="deployment", credentials_name="tavily-shared")

agent = agents.Agent(
    model="mistral-large-4",
    name="deployment-identity-agent",
    description="Answers questions from the web using the workspace's shared Tavily key.",
    instructions=(
        "Answer questions by searching the web. Cite the URLs you used. Keep answers to a few sentences. "
        "If a search returns nothing useful, say so instead of guessing."
    ),
    connectors=[tavily],
)

Les connecteurs utilisent par défaut run_as="auto", qui appelle le service tiers au nom de l'utilisateur de la session. run_as="deployment" utilise à la place des identifiants détenus par l'espace de travail.

Une session qui s'exécute sous l'identité du déploiement n'a aucun utilisateur à solliciter. Elle ne peut donc pas lancer de connexion OAuth2. Un connecteur OAuth2 utilisant run_as="deployment" échoue, sauf si l'espace de travail détient déjà des identifiants pour ce connecteur. Pour vérifier comment un connecteur s'authentifie :

curl -H "Authorization: Bearer $MISTRAL_API_KEY" \
  https://api.mistral.ai/v1/connectors/tavily/authentication_methods

curl -H "Authorization: Bearer $MISTRAL_API_KEY" \
  https://api.mistral.ai/v1/connectors/tavily/authentication_methods

Tavily renvoie "method_type": "bearer".

L'agent n'inclut aucune clé Tavily. Enregistrez la vôtre une seule fois dans une connexion Tavily partagée avec l'espace de travail et nommée tavily-shared, dans Mistral Studio ou via l'API.

Dans Mistral Studio, ouvrez le connecteur Tavily, ajoutez une connexion nommée tavily-shared, collez votre clé et cochez Partager ces identifiants avec tout l'espace de travail.

Avec l'API :

curl -X POST -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.mistral.ai/v1/connectors/tavily/workspace/credentials \
  -d '{"name": "tavily-shared", "credentials": {"bearer_token": "<your-tavily-api-key>"}}'

curl -X POST -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -H "Content-Type: application/json" \
  https://api.mistral.ai/v1/connectors/tavily/workspace/credentials \
  -d '{"name": "tavily-shared", "credentials": {"bearer_token": "<your-tavily-api-key>"}}'

credentials_name="tavily-shared" sélectionne cette connexion par son nom. L'agent utilise donc votre clé même si une autre connexion Tavily est définie par défaut dans l'espace de travail.

Depuis le dossier de l'exemple, vérifiez ce que la CLI charge :

MISTRAL_API_KEY=... uv run agents info

MISTRAL_API_KEY=... uv run agents info

Elle affiche l'agent et son unique connecteur :

Posez-lui une question dans votre terminal. agents chat exécute l'agent dans votre processus :

MISTRAL_API_KEY=... uv run agents chat -m "Who won the 2026 Tour de France? Cite your source."

MISTRAL_API_KEY=... uv run agents chat -m "Who won the 2026 Tour de France? Cite your source."

L'agent recherche sur le Web avec la clé Tavily de l'espace de travail, puis répond en citant ses sources :

Puis rendez-le accessible :

MISTRAL_API_KEY=... uv run agents serve

MISTRAL_API_KEY=... uv run agents serve

ou poussez le dossier vers un dépôt GitHub accessible au connecteur GitHub, puis déployez-le sur Mistral (Déployer) :

MISTRAL_API_KEY=... uv run agents deploy

MISTRAL_API_KEY=... uv run agents deploy

Un déploiement durci accepte uniquement les processus qui le rendent accessible, via agents serve ou agents deploy, et qui sont enregistrés avec votre clé.

Un agent dont les connecteurs s'exécutent sous l'identité de l'utilisateur de la session agit pour le compte de cet utilisateur. Son déploiement doit donc être durci : personne d'autre ne peut alors agir pour le compte de vos utilisateurs. agents deploy durcit automatiquement ce type de déploiement. N'utilisez pas --no-hardened dans ce cas : le worker ne peut pas s'enregistrer et le déploiement ne démarre pas.

Cet agent n'agit pour le compte d'aucun utilisateur. agents deploy laisse donc son déploiement non durci, sans option supplémentaire.

• Connecteurs : connecteurs, serveurs MCP et identifiants.
• Déployer : agents deploy et ses options.