Manage agent projects
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:
- Your admin has granted you the application-level permissions for Agent Projects, set in Admin Essentials (on-prem) or Cloud Hub (cloud). Without them, Agent Projects doesn’t appear in Platform, even if it’s enabled for your organization. These permissions are separate from the project-level roles set in project settings, and you need both. For the role each action requires, see Required permissions for project actions.
- A profile in Model Registry that specifies the provider, model, and permissions. A LLM admin configures this. For information, see Model registry.
- Users or groups configured in Admin Essentials, if you plan to add members to your project. For information, see Users and Groups.
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:
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.
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. For the full list of application permissions, see Authorization.
Assign project-level permissions
To add a user or group to a project, you must have the Owner role on that project.
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 for more information.
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.
/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 in Agent Builder.
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.
For the full list of permissions, see FlowAI roles.
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.
Import a project
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.
If a project with the same identifier already exists, you’re prompted to choose:
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:
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: