> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lighton.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Effectuez des tâches efficacement en utilisant et en créant des agents spécialisés

<Info>
  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](/fr/developer-resources/chat-and-ai-models/agent-api).
</Info>

## 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](/fr/administration/iam/group-management/understanding-groups) 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](/api-reference-v3/agents/create-a-new-agent). Le champ `ownership` détermine qui peut accéder à l'agent :

```python theme={null}
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](/api-reference-v3/tools/list-native-tools) et les serveurs MCP disponibles via l'endpoint [GET /api/v3/mcp](/api-reference-v3/mcp/list-mcp-servers).

Votre agent est maintenant créé et vous pouvez l'utiliser avec l'[API Threads](/fr/developer-resources/agents-and-threads/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](/fr/developer-resources/agents-and-threads/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.

| `ownership`  | Qui peut y accéder                      | `group_id` requis ? |
| ------------ | --------------------------------------- | ------------------- |
| `"personal"` | Le créateur uniquement                  | Non                 |
| `"company"`  | Tous les utilisateurs de l'organisation | Non                 |
| `"team"`     | Les membres de l'équipe spécifiée       | Oui                 |

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"`.

<Info>
  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](#restriction-des-workspaces) ci-dessous.
</Info>

## 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                 |
| --------------------------- | ------------------------------------------ | --------------------------------------------- |
| **Workspaces**              | Tous les workspaces du groupe              | Uniquement les workspaces listés              |
| **Fichiers**                | Tous les fichiers des workspaces du groupe | Uniquement les fichiers des workspaces listés |
| **Tags**                    | Tous les tags des workspaces du groupe     | Uniquement les tags des workspaces listés     |
| **Varie par utilisateur ?** | Non                                        | Non                                           |

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](/api-reference-v3/agents/retrieve-a-single-agent) en inspectant le champ `workspaces`.

Lors de la [restriction d'un tour de thread à des fichiers, workspaces ou tags spécifiques](/fr/developer-resources/agents-and-threads/threads#restreindre-par-fichier-espaces-de-travail-ou-tags), vous ne pouvez référencer que les ressources appartenant au périmètre effectif de l'agent :

* **workspaces** : listez-les via [GET /api/v3/agents/:id](/api-reference-v3/agents/retrieve-a-single-agent)
* **fichiers** : listez-les via [GET /api/v3/agents/:id/files](/api-reference-v3/agents/list-files-scoped-to-an-agent)
* **tags** : listez-les via [GET /api/v3/agents/:id/tags](/api-reference-v3/agents/list-tags-used-in-workspaces-for-an-agent)

<Warning>
  **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é.
</Warning>