> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Manage agent projects

> Create and manage agent projects, the organizational containers that group related agents, enforce access control, and serve as the unit of portability for agent configurations.

Platform 6.5+

An agent project is the organizational container that groups agents and their tools. Every agent belongs to exactly one project; agents can't exist outside a project.

Projects provide:

* **Security boundary** - Agents can only invoke tools you explicitly authorize. Every tool association is intentional and auditable.
* **Access control** - Project roles control who can view, edit, and manage agents.
* **Portability** - Export a project to move agent configurations between environments, such as from development to production.

## Before you begin

Before you begin, make sure you have the following:

* A profile in Model Registry that specifies the provider, model, and permissions. A LLM admin configures this. For information, see [Model registry](/itential-platform/flowai/model-registry).
* Users or groups configured in Admin Essentials, if you plan to add members to your project. For information, see [Users](/itential-platform/admin-essentials/authorization#users) and [Groups](/itential-platform/admin-essentials/authorization#groups).
* Agent Projects roles assigned to your users or groups in

  [Admin Essentials](/itential-platform/admin-essentials/authorization#flowai-roles)

  . Ask your admin to assign these roles if you don't have them. Without them, Agent Projects doesn't appear in Platform, even if it's enabled for your organization. These roles are separate from the project-level roles you set in project settings, and you need both. Admins typically assign them once, up front. For the role each action requires, see [Access control](#access-control) below.

## Access control

Agent projects use roles to control who can view, edit, and manage agents. Assign roles to users and groups in the project settings.

| Role       | Capabilities                                                                                                                             |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**  | Configure project-level roles for users and groups; delete the project; all Editor and Viewer capabilities.                              |
| **Editor** | Edit the project name and description; export the project; create, edit, delete, and run agents in the project; all Viewer capabilities. |
| **Viewer** | View all project-level and agent-level contents, including agent configurations. Can't modify anything.                                  |

Application-level permissions and project-level roles work together, and neither is sufficient on its own. You need application-level permissions to open the **Agent Projects** application; without them, Agent Projects doesn't appear in the navigation. To see a specific project, you also need a project-level role on it.

Admins assign application-level permissions in Admin Essentials. For the permissions each action requires, see [Required permissions for project actions](#required-permissions-for-project-actions). For the full list of application permissions, see [Authorization](/itential-platform/admin-essentials/authorization).

### Assign project-level permissions

To add a user or group to a project, you must have the Owner role on that project.

In **Agent Projects**, either click **Project Settings** or the **⋮** next to the project > **Project Settings**.

Click **+ Add Members**.

Select a **User** or **Group**.

Enter the user's name, or enter a group name. Users and groups must already exist in Admin Essentials.

Select a role. See [project roles](#access-control) for more information.

Click **Save Changes**.

### Project Admin role

The Project Admin role is an application-level role, separate from the per-project Owner role. The `agent-project-service:admin` permission grants it on-prem, and `agents:admin` grants it on cloud. It provides access to all agent projects regardless of project membership, so Platform admins can manage permissions for or delete orphaned or inaccessible projects. Itential records all actions taken with this role in the audit log.

The Project Admin role operates only on `/admin/`-prefixed endpoints and is available only through the API.

### Required permissions for project actions

Each project action requires both an application-level permission and a project role; neither is sufficient on its own. An admin assigns these permissions in **Admin Essentials → Authorization** on-prem, or through Cloud Hub role management on cloud.

This table covers project-level actions. For agent-level actions, including adding tools and decorators, see [Access control](/itential-platform/flowai/agent-projects/agent-builder#access-control) in Agent Builder.

Every action also requires `agent-projects:read` to open the application. The permissions below are the `agent-project-service` permissions each action needs.

| Action                                     | Application permission(s)                                    | Minimum project role                 | Notes                                          |
| ------------------------------------------ | ------------------------------------------------------------ | ------------------------------------ | ---------------------------------------------- |
| Create a project                           | `agent-project-service:read`, `agent-project-service:create` | None. The creator becomes the Owner. |                                                |
| View projects in the UI                    | `agent-project-service:read`                                 | Viewer                               |                                                |
| View all projects as an admin              | `agent-project-service:admin`                                | None                                 | API only.                                      |
| Edit project permissions in the UI         | `agent-project-service:read`, `agent-project-service:update` | Owner                                | Only Owners can configure project-level roles. |
| Edit any project's permissions as an admin | `agent-project-service:admin`                                | None                                 | API only. Bypasses project-level roles.        |
| Copy a project                             | `agent-project-service:read`, `agent-project-service:create` | Editor                               | You become the Owner of the new project.       |
| Export a project                           | `agent-project-service:read`                                 | Editor                               |                                                |
| Import a project as a new copy             | `agent-project-service:read`, `agent-project-service:create` | None. The creator becomes the Owner. |                                                |
| Import a project over an existing one      | `agent-project-service:read`, `agent-project-service:create` | Owner on the existing project        |                                                |
| Delete a project in the UI                 | `agent-project-service:read`, `agent-project-service:delete` | Owner                                |                                                |
| Delete any project as an admin             | `agent-project-service:admin`                                | None                                 | API only. Bypasses project-level roles.        |

A custom role that grants the equivalent API endpoints provides the same access without these named permissions being assigned. For more information, see [Custom roles](/itential-platform/admin-essentials/authorization#custom-roles).

For the full list of permissions, see [FlowAI roles](/itential-platform/admin-essentials/authorization#flowai-roles). For the permissions to grant, see Agent Projects in [Grant FlowAI access](/itential-platform/admin-essentials/authorization#grant-flowai-access).

## Access Agent Projects

To access **Agent Projects**, go to the **Design** section in the navigation sidebar and click **Agent Projects**.

## Create a project

To create a new agent project:

In the sidebar, click **Create Agent Project**.

Click **Create Project**.

Enter a **Name**. Optionally, enter a **Description**.

Click **Create**. Itential saves the project and automatically assigns you the Owner role.

## View projects

The project list shows all projects you have permission to see, including each project's name, description, agent count, and who created it. Click a project to open it and view its agents.

## Import and export projects

Export a project to promote agent configurations across environments, such as from development to staging or production.

### Export a project

The export includes:

* All agents in the project and their configurations
* Tool associations per agent
* LLM profile per agent: profile name, provider name, and model name

The export doesn't include:

* Project role assignments. Access control is environment-specific and isn't promoted.
* Assets from referenced external projects or global tools.
* Decorator definitions. Migrate decorators separately using the decorator bulk export API. For more information, see [Promote decorators](http://localhost:3000/itential-platform/flowai/agent-projects/export-decorators).

Click the project that you'd like to export.

Click **Export Project**. The project file downloads to your device.

### Import a project

In **Agent Projects**, click **Import Project**.

Drag and drop your project file onto the upload area, or click to browse for it.

Click **Import**.

The import always succeeds whether or not the referenced tools, decorators, and profiles exist in the target environment. After import, the agent flags any unresolved references: a tool can be unauthorized, missing, or unreachable, and a decorator can be missing.

Each imported agent must pass its ready gate before it can run, so an agent with unauthorized tools starts as **Unable to launch**. For more information, see [Agent readiness](#agent-readiness).

If a project with the same identifier already exists, you're prompted to choose:

| Option        | Behavior                                                                                                                                                                                                                                                |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Keep Both** | Creates the imported project as a new, independent project alongside the existing one.                                                                                                                                                                  |
| **Replace**   | Overwrites the existing project. Requires Owner role on the existing project. Equivalent to deleting the project and reimporting. Preserves existing access settings. If you don't have Owner role on the existing project, **Replace** is unavailable. |

### Agent readiness

Before you import a project, its agent must pass two checks before it runs: a one-time **ready gate** when it's created, and a **session start gate** each time a session starts. Each agent shows a status that reflects the ready gate:

| Status               | Meaning                                          |
| -------------------- | ------------------------------------------------ |
| **Ready to launch**  | The agent has no unauthorized tools and can run. |
| **Unable to launch** | The agent has one or more unauthorized tools.    |

#### Ready gate

An agent becomes **Unable to launch** only when you clone or import it without access to one or more of its tools, which Itential flags as unauthorized. Agents you build directly are always ready, because you can only add tools you have access to.

To make the agent ready, resolve every unauthorized tool: validate it if you have access, or remove it from the agent. An agent that isn't ready can't be selected when you create an Operations Manager automation, and existing automations that reference it show why it can't run.

#### Session start gate

Passing the ready gate makes an agent runnable, but starting a session also depends on the agent's references still being available at runtime. To start a session, all of the following must be true:

* The agent has passed its ready gate.
* All referenced tools exist in the environment.
* All referenced decorators exist in the environment.
* The provider and model exist and are reachable.

If the ready gate is passed but one of the other conditions isn't met, for example, an admin deleted a tool, decorator, or provider profile after the agent passed its ready gate, you can still click **Save**. The session can't run, and the session details explain why.

## Delete a project

Only a project Owner or an Admin can delete an agent project.

Before deletion, Itential displays a warning that lists any agents in other projects that reference tools from this project. Deleting a project permanently removes it and all contained agents. Cross-project tool references in those other agents break; they can't start until you resolve them.

Agents in this project can also be used by workflows through a **Run Agent** task. Deleting the project breaks those workflows, so before you delete, review your workflows for any that call this project's agents.

Project deletion can't be undone. Agents in other projects that reference this project's tools, and workflows that call a deleted agent through a **Run Agent** task, can't run until you update them. Confirm nothing depends on this project's agents before you delete it.

To delete a project:

Open the project from the **Agent Projects** list.

Open the **Actions** menu and select **Delete Project**.

Review the warning that lists cross-project tool dependencies.

Confirm deletion.

## Next steps

#### [Agents](/itential-platform/flowai/agent-projects/agent-builder)

Create and configure agents inside your project.

#### [Agent Sessions](/itential-platform/flowai/agent-sessions)

Monitor running and completed agent sessions.