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

Créez un agent via l’endpoint POST /api/v3/agents. Le champ ownership détermine qui peut accéder à l’agent : 
import os
import requests

api_key = os.getenv("PARADIGM_API_KEY")
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 HR Agent",
      "company_id": 123,
      "ownership": "team",   # "personal" | "company" | "team"
      "group_id": 456,       # requis uniquement quand ownership est "team"
      "description": "An agent that processes 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"],
      "scoped_workspace_ids": [789, 790]  # optionnel : restreindre à des workspaces spécifiques
    }
).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.

​
Appartenance des agents

Le champ ownership contrôle qui peut accéder à un agent. Il est défini à la création et ne peut pas être modifié par la suite.
ownershipQui peut y accédergroup_id requis ?
"personal"Le créateur uniquementNon
"company"Tous les utilisateurs de l’organisationNon
"team"Les membres de l’équipe spécifiéeOui
Seuls les Company Admin et System Admin peuvent créer des agents avec ownership défini à "company" ou "team". Les utilisateurs standard ne peuvent créer que des agents "personal".
Le champ ownership et scoped_workspace_ids sont disponibles à partir de Xenial Xerus (mars 2026). Sur les versions antérieures, utilisez group_id avec scope_workspaces_by_group — reportez-vous au comportement legacy de restriction des workspaces ci-dessous.

​
Contrôle d’accès

Les agents ne peuvent être consultés et utilisés que par les utilisateurs qui y ont accès via l’appartenance de l’agent :
  • "personal" : uniquement le créateur.
  • "company" : tous les utilisateurs de l’organisation.
  • "team" : les membres de l’équipe spécifiée par group_id.

​
Restriction des workspaces

Par défaut, un agent accède à tous les workspaces appartenant à son équipe. Vous pouvez restreindre cela à un sous-ensemble spécifique via le champ scoped_workspace_ids (une liste d’identifiants de workspaces) lors de la création ou de la mise à jour d’un agent.
Sans restriction (par défaut)scoped_workspace_ids défini
WorkspacesTous les workspaces du groupeUniquement les workspaces listés
FichiersTous les fichiers des workspaces du groupeUniquement les fichiers des workspaces listés
TagsTous les tags des workspaces du groupeUniquement les tags des workspaces listés
Varie par utilisateur ?NonNon
Lorsque scoped_workspace_ids est défini, la restriction s’applique quel que soit l’utilisateur qui appelle l’agent. Vous pouvez récupérer la liste effective des workspaces d’un agent via GET /api/v3/agents/:id en inspectant le champ workspaces. Lors de la restriction d’un tour de thread à des fichiers, workspaces ou tags spécifiques, vous ne pouvez référencer que les ressources appartenant au périmètre effectif de l’agent :
Avant Xenial Xerus (mars 2026) : Les champs ownership et scoped_workspace_ids n’existent pas. Utilisez group_id pour associer un agent à une équipe et scope_workspaces_by_group (booléen, true par défaut) pour contrôler l’accès aux workspaces. Lorsque true, l’agent accède uniquement aux workspaces de l’équipe ; lorsque false, il accède à tous les workspaces accessibles à l’utilisateur appelant. scope_workspaces_by_group est toujours accepté dans Xenial Xerus et les versions ultérieures pour compatibilité ascendante, mais est déprécié.