Passer au contenu principal
Les agents sont disponibles à partir de la version Wise Wolf (février 2026). Si vous êtes sur Unique Urchin (décembre 2025) ou Victorious Vicuna (janvier 2026), veuillez consulter la documentation héritée des threads agentiques.

​
Motivation

Les agents sont l’évolution du système legacy ChatSettings. Il peut y en avoir plusieurs au sein d’une même organisation et ils vous permettent de créer et d’utiliser un prompt spécialisé ainsi qu’un ensemble d’outils, de serveurs MCP et de workspaces restreints pour accomplir une tâche spécifique. Les agents sont liés à des Groupes qui contrôlent qui peut y accéder et quels workspaces peuvent être utilisés avec eux.

​
Démarrage rapide

Commencez par vérifier à quels groupes vous avez accès via le GET /api/v3/groups. Une fois le groupe identifié pour associer votre agent, créez-le via l’endpoint POST /api/v3/agents : 
import os
import requests

# Récupérer la clé API depuis l'environnement
api_key = os.getenv("PARADIGM_API_KEY")
# Récupérer l'URL de base depuis l'environnement (par défaut : instance publique)
base_url = os.getenv("PARADIGM_BASE_URL", "https://paradigm.lighton.ai/api/v3")

response = requests.post(
    f"{base_url}/agents",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
      "name": "My new agent",
      "company_id": 123,
      "group_id": 456,
      "description": "An agent that process HR documents",
      "instructions": "Transform the user input into a specific query, perform a document search and display relevant data to the user",
      "native_tool_ids": ["4b247d97-2d87-4181-9590-c6aaea2785aa"],
      "mcp_server_ids": ["5af81947-271b-4611-a8de-9b064ddc95bd"],
      "scope_workspaces_by_group": true
    }
).json()
Vous pouvez lister les outils natifs disponibles au sein de votre organisation via GET /api/v3/tools et les serveurs MCP disponibles via l’endpoint GET /api/v3/mcp. Votre agent est maintenant créé et vous pouvez l’utiliser avec l’API Threads.

​
Agent par défaut

Chaque organisation possède un agent par défaut lié au groupe global de l’organisation dont tous les utilisateurs de l’organisation sont membres. Lors de l’utilisation de l’API Threads, si vous ne spécifiez pas de champ agent_id, l’agent par défaut sera utilisé implicitement.

​
Agents personnels

Étant donné que chaque utilisateur possède son propre groupe personnel, chaque utilisateur peut créer un agent personnel lié à son groupe personnel. Ces agents ne seront pas accessibles aux autres utilisateurs. Seuls les Company Admin et System Admin sont autorisés à créer des agents pour des groupes autres que leurs propres groupes personnels.

​
Contrôle d’accès

Les agents ne peuvent être consultés et utilisés que par les utilisateurs membres du même groupe que celui lié à l’agent en question.

​
Restriction des workspaces

Bien que les agents ne soient accessibles qu’aux utilisateurs membres du groupe qui leur est associé, vous pouvez activer/désactiver la restriction de portée des workspaces en utilisant le champ booléen scope_worskpace_by_group (true par défaut) lors de la création d’un agent via l’endpoint POST /api/v3/agents ou lors de sa modification via l’endpoint PATCH /api/v3/agents/:id). Le comportement d’un agent en fonction de ce paramètre est le suivant :
scope_workspaces_by_group = true (par défaut)scope_workspaces_by_group = false
WorkspacesUniquement les workspaces du groupeTous les workspaces accessibles à l’utilisateur
FichiersUniquement les fichiers dans les workspaces du groupeTous les fichiers accessibles à l’utilisateur
TagsUniquement les tags sur les fichiers dans les workspaces du groupeTous les tags sur les fichiers accessibles à l’utilisateur
Varie par utilisateur ?NonOui
  • true (par défaut) : l’agent n’aura accès qu’aux fichiers contenus dans les workspaces du groupe qui lui est associé. Lors de l’utilisation d’un tel agent pour restreindre un tour de thread à des fichiers, workspaces ou tags spécifiques, vous ne pourrez passer que : -> workspaces : uniquement ceux appartenant au groupe lié à l’agent, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id en inspectant le composant workspaces du payload. -> fichiers : uniquement les fichiers contenus dans les workspaces appartenant au groupe lié à l’agent, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id/files. -> tags : uniquement les tags associés aux fichiers contenus dans les workspaces appartenant au groupe lié à l’agent, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id/tags.
  • false : l’agent aura le même accès que l’utilisateur qui l’utilise (y compris les workspaces du groupe lié à l’agent puisque l’utilisateur doit être membre du même groupe pour accéder à l’agent). Lors de l’utilisation d’un tel agent pour restreindre un tour de thread à des fichiers, workspaces ou tags spécifiques, vous ne pourrez passer que : -> workspaces : tous les workspaces accessibles à l’utilisateur courant à travers tous les groupes dont il est membre, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id en inspectant le composant workspaces du payload. Veuillez noter que le résultat de cet appel d’endpoint variera selon l’utilisateur qui l’appelle. -> fichiers : uniquement les fichiers contenus dans les workspaces accessibles par l’utilisateur, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id/files. Veuillez noter que le résultat de cet appel d’endpoint variera selon l’utilisateur qui l’appelle. -> tags : uniquement les tags associés aux fichiers contenus dans les workspaces accessibles à l’utilisateur, vous pouvez les lister via l’endpoint GET /api/v3/agents/:id/tags. Veuillez noter que le résultat de cet appel d’endpoint variera selon l’utilisateur qui l’appelle.