> ## 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

> Perform task efficiently by using and creating specialized agents

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

## 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](/en/administration/iam/group-management/understanding-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](/api-reference-v3/agents/create-a-new-agent) endpoint. The `ownership` field determines who can access the 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,       # 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](/api-reference-v3/tools/list-native-tools) and the MCP servers available within you company using [GET /api/v3/mcp](/api-reference-v3/mcp/list-mcp-servers) endpoint.

Now your agent is created and you can use it with the [Threads API](/en/developer-resources/agents-and-threads/threads).

## 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](/en/developer-resources/agents-and-threads/threads), 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.

| `ownership`  | Who can access it             | `group_id` required? |
| ------------ | ----------------------------- | -------------------- |
| `"personal"` | The creator only              | No                   |
| `"company"`  | All users in the organization | No                   |
| `"team"`     | Members of the specified team | Yes                  |

Only **Company Admin** and **System Admin** can create agents with `ownership` set to `"company"` or `"team"`. Regular users can only create `"personal"` agents.

<Info>
  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](#workspace-scoping) below.
</Info>

## 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      |
| -------------------- | ----------------------------- | ------------------------------- |
| **Workspaces**       | All group workspaces          | Only the listed workspaces      |
| **Files**            | All files in group workspaces | Only files in listed workspaces |
| **Tags**             | All tags in group workspaces  | Only tags in listed workspaces  |
| **Varies per user?** | No                            | No                              |

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](/api-reference-v3/agents/retrieve-a-single-agent) and inspecting the `workspaces` field.

When [scoping a thread turn on specific files, workspaces or tags](/en/developer-resources/agents-and-threads/threads#scoping-by-file-workspaces-or-tags), you are only permitted to reference resources that fall within the agent's effective workspace scope:

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

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