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. The agents are linked to Groups which controls who can access them and which workspaces can be accessed with them.

​
Quickstart

Create an agent using the POST /api/v3/agents endpoint. The ownership field determines who can access the 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,       # required only when ownership is "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]  # optional: restrict to specific workspaces
    }
).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.

​
Agent ownership

The ownership field controls who can access an agent. It is set at creation and cannot be changed afterwards.
ownershipWho can access itgroup_id required?
"personal"The creator onlyNo
"company"All users in the organizationNo
"team"Members of the specified teamYes
Only Company Admin and System Admin can create agents with ownership set to "company" or "team". Regular users can only create "personal" agents.
The ownership field and scoped_workspace_ids are available from Xenial Xerus (March 2026). On earlier versions, use group_id with scope_workspaces_by_group — refer to the legacy workspace scoping behavior below.

​
Access control

Agents can only be viewed and used by users who have access through the agent’s ownership:
  • "personal": only the creator.
  • "company": all users in the company.
  • "team": members of the team specified by group_id.

​
Workspace scoping

By default, an agent accesses all workspaces belonging to its team. You can restrict this to a specific subset using the scoped_workspace_ids field (a list of workspace IDs) when creating or updating an agent.
No restriction (default)scoped_workspace_ids set
WorkspacesAll group workspacesOnly the listed workspaces
FilesAll files in group workspacesOnly files in listed workspaces
TagsAll tags in group workspacesOnly tags in listed workspaces
Varies per user?NoNo
When scoped_workspace_ids is set, the restriction applies regardless of which user calls the agent. You can retrieve the effective workspace list for an agent using GET /api/v3/agents/:id and inspecting the workspaces field. When scoping a thread turn on specific files, workspaces or tags, you are only permitted to reference resources that fall within the agent’s effective workspace scope:
Before Xenial Xerus (March 2026): The ownership field and scoped_workspace_ids do not exist. Use group_id to associate an agent with a team and scope_workspaces_by_group (boolean, default true) to control workspace access. When true, the agent accesses only the team’s workspaces; when false, it accesses all workspaces the requesting user has access to. scope_workspaces_by_group is still accepted in Xenial Xerus and later for backwards compatibility but is deprecated.