Skip to main content
Agents are available for the Wise Wolf release (February 2026) and later, if you are on Unique Urchin (December 2025) or Victorious Vicuna (January 2026), please refer to the legacy agentic threads documentation.

​
Motivation

Agents are the evolution of the legacy ChatSettings system, there can be several within the same company and allows you to create and use a specialized prompt as wess as set of tools, MCP servers and scoped workspaces to achieve a specific task. test The agents are linked to Groups which controls who can access them and which workspaces can be accessed with them.

​
Quickstart

First let’s start by checking which groups you have access to, use the GET /api/v3/groups, once you identified the group you want to associate your agent with, let’s create your agent using the POST /api/v3/agents endpoint: 
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()
You can list native tools available within your company using GET /api/v3/tools and the MCP servers available within you company using GET /api/v3/mcp endpoint. Now your agent is created and you can use it with the Threads API.

​
Default agent

Every company has a default agent linked to the company’s default company-wide group of which every company’s users are member of. When using the Threads API, if you don’t specify an agent_id field, the default agent will be used implicitely.

​
Personal agents

Given that every user has its own personal group, every user can create a personal agent linked to his personal group, these agents will not be accessible to other users. Only Company Admin and System Admin are allowed to create agents for other groups than their own personnal groups.

​
Access control

Agents can only be viewed and used by users which are members of the same group as the one linked to the agent in question.

​
Workspace scoping

While agents are only accessible to users that are members of the group associated to them, you can enable/disable their workspace scoping restriction using the scope_worskpace_by_group boolean field (true by default) when creating an agent through the POST /api/v3/agents endpoint or when editing it through the PATCH /api/v3/agents/:id) endpoint. The behaviour of an agent depending of this parameter is as follows:
scope_workspaces_by_group = true (default)scope_workspaces_by_group = false
WorkspacesOnly the group’s workspacesAll workspaces accessible to the user
FilesOnly files within the group’s workspacesAll files accessible to the user
TagsOnly tags on files within the group’s workspacesAll tags on files accessible to the user
Varies per user?NoYes
  • true (default): the agent will only have access to files contained in the workspaces of the group associated with it, when using such an agent when scoping a thread turn on specific files, workspaces or tags, you will only be permited to pass: -> workspaces: only the one belonging to the group linked to the agent, you can list them using the GET /api/v3/agents/:id endpoint and inspecting the workspaces component of the payload. -> files: only the files contained within the workspaces belonging to the group linked to the agent, you can list them using the GET /api/v3/agents/:id/files endpoint. -> tags: only the tags associated to files contained within the workspaces belonging to the group linked to the agent, you can list them using the GET /api/v3/agents/:id/tags endpoint.
  • false: the agent will have the same access as the user using it (including the workspaces of the group linked to the agent of course since the user has to be member of the same group to access the agent anyway), when using such an agent when scoping a thread turn on specific files, workspaces or tags, you will only be permited to pass: -> workspaces: all the workspaces accessible to the present user across all groups the user is member of, you can list them using the GET /api/v3/agents/:id endpoint and inspecting the workspaces component of the payload, please note that the result of this endpoint call will differ depending on which user calls it. -> files: only the files contained within the workspaces which are accessible by the user, you can list them using the GET /api/v3/agents/:id/files endpoint, please note that the result of this endpoint call will differ depending on which user calls it. -> tags: only the tags associated to files contained within the workspaces accessible to the user, you can list them using the GET /api/v3/agents/:id/tags endpoint, please note that the result of this endpoint call will differ depending on which user calls it.