Clés de recherche

Les clés de recherche sont des paires clé/valeur attachées à une exécution pour la retrouver plus facilement. Elles sont extraites de l’entrée du workflow ou ajoutées en cours d’exécution, et stockées sous forme de métadonnées d’exécution. Filtrez les exécutions par leurs clés de recherche avec GET /v1/workflows/runs ou dans la vue Exécutions de Studio.

Transmettez une liste de chemins en notation pointée dans search_keys à @workflows.workflow.define pour extraire des valeurs de l’entrée du point d’entrée au début de chaque exécution. Les chemins sont validés au démarrage du worker.

import mistralai.workflows as workflows
from pydantic import BaseModel


class OrderInput(BaseModel):
    order_id: str
    customer_tier: str


@workflows.workflow.define(
    name="order_processor",
    search_keys=["order_id", "customer_tier"],
)
class OrderProcessor:
    @workflows.workflow.entrypoint
    async def run(self, params: OrderInput) -> str:
        return f"Processed {params.order_id}"

import mistralai.workflows as workflows
from pydantic import BaseModel


class OrderInput(BaseModel):
    order_id: str
    customer_tier: str


@workflows.workflow.define(
    name="order_processor",
    search_keys=["order_id", "customer_tier"],
)
class OrderProcessor:
    @workflows.workflow.entrypoint
    async def run(self, params: OrderInput) -> str:
        return f"Processed {params.order_id}"

L’endroit où un chemin commence dépend de la signature du point d’entrée :

Avec un paramètre BaseModel unique, le type du paramètre est le modèle d’entrée, donc les chemins ignorent le nom du paramètre et commencent par ses champs. Avec plusieurs paramètres, le SDK génère un modèle wrapper dont les champs sont les paramètres, donc chaque chemin commence par un nom de paramètre.

@workflows.workflow.define(
    name="order_processor_multi",
    search_keys=["payload.order_id", "context.tenant"],
)
class MultiParamProcessor:
    @workflows.workflow.entrypoint
    async def run(self, payload: OrderInput, context: TenantContext) -> str:
        return f"Processed {payload.order_id} for {context.tenant}"

@workflows.workflow.define(
    name="order_processor_multi",
    search_keys=["payload.order_id", "context.tenant"],
)
class MultiParamProcessor:
    @workflows.workflow.entrypoint
    async def run(self, payload: OrderInput, context: TenantContext) -> str:
        return f"Processed {payload.order_id} for {context.tenant}"

Les champs avec une valeur par défaut utilisent cette valeur par défaut lorsque l’appelant les omet.

Les valeurs qui n’existent qu’après l’exécution de certaines tâches (par exemple, un niveau récupéré depuis une activité, un ID de batch dérivé de l’état) peuvent être attachées avec workflows.workflow.add_search_keys, appelable depuis le corps d’un workflow ou depuis une activité.

import mistralai.workflows as workflows


@workflows.workflow.define(name="enriched_processor")
class EnrichedProcessor:
    @workflows.workflow.entrypoint
    async def run(self, params: OrderInput) -> str:
        customer = await fetch_customer(params.order_id)
        await workflows.workflow.add_search_keys({"customer.tier": customer.tier})
        return f"Processed {params.order_id}"

import mistralai.workflows as workflows


@workflows.workflow.define(name="enriched_processor")
class EnrichedProcessor:
    @workflows.workflow.entrypoint
    async def run(self, params: OrderInput) -> str:
        customer = await fetch_customer(params.order_id)
        await workflows.workflow.add_search_keys({"customer.tier": customer.tier})
        return f"Processed {params.order_id}"

Attendre add_search_keys confirme que les valeurs sont persistées.

Les clés peuvent également être supprimées avec workflows.workflow.delete_search_keys, ce qui libère leurs emplacements dans le budget de 20 clés. Cette opération est idempotente : les clés que l’exécution ne possède pas sont ignorées.

await workflows.workflow.delete_search_keys(["customer.tier"])

await workflows.workflow.delete_search_keys(["customer.tier"])

Les mêmes règles s’appliquent aux chemins déclarés et à add_search_keys :

• Les clés ne doivent pas être vides, ne doivent pas contenir de : , ne doivent pas se terminer par =, ne doivent pas avoir d’espaces de remplissage, ne doivent pas commencer par le préfixe réservé internal. et ne doivent pas dépasser 256 caractères.
• Les valeurs sont converties en chaînes de caractères : les énumérations utilisent leur valeur, les booléens sont en minuscules, les dates et heures utilisent le format ISO 8601, tout le reste utilise str().
• Les valeurs dépassant 8192 caractères sont tronquées.
• Une exécution peut contenir au maximum 20 clés au total, et add_search_keys accepte au maximum 20 clés par appel.

Les échecs de stockage ne font jamais échouer l’exécution : le SDK effectue 3 tentatives en cas d’erreurs temporaires (5xx, 429, 408, délais d’attente), puis enregistre un avertissement et continue. Les rejets permanents sont enregistrés au niveau erreur et ignorés : un déploiement serveur peut produire ces erreurs à l’échelle de la flotte en cours d’exécution. À la limite de 20 clés, les nouvelles clés sont ignorées ; la réponse du serveur signale les clés ignorées et tronquées.

Les clés invalides (vides, contenant : , se terminant par =, utilisant le préfixe internal. , dépassant 256 caractères ou plus de 20 clés dans un seul appel) génèrent une erreur non réessayable et font échouer l’exécution. Une erreur inattendue en cours de traitement pendant le stockage, comme une valeur que le SDK ne peut pas convertir, fait échouer l’exécution de la même manière. Ces deux cas sont des bogues de code qui échouent de manière identique à chaque exécution, donc privilégiez les clés littérales plutôt que les clés construites à partir de données non fiables.

Filtrez les exécutions avec le paramètre de requête search_key répété sur GET /v1/workflows/runs. Chaque entrée correspond à une clé exacte, les entrées sont combinées avec un ET, et au maximum 3 entrées sont autorisées par requête :

curl -H "Authorization: Bearer $MISTRAL_API_KEY" \
  "https://api.mistral.ai/v1/workflows/runs?search_key=order_id:12345&search_key=customer_tier==:premium"

curl -H "Authorization: Bearer $MISTRAL_API_KEY" \
  "https://api.mistral.ai/v1/workflows/runs?search_key=order_id:12345&search_key=customer_tier==:premium"

Pour la liste complète des paramètres, voir la référence List Runs.