Working with workspaces

Edit online

Workspaces in IBM watsonx Orchestrate provide builders with secure, collaborative development spaces for creating and managing AI agents, tools, and related artifacts. This guide walks you through creating a workspace, navigating to it, and managing access for collaborators.

Important: Workspaces are currently supported only on IBM Cloud.

You are automatically switched to your new workspace and assigned as the owner.

Before you begin

Before you start working with workspaces, make sure you understand how access and permissions are managed.

Review the Managing access with trusted profiles page to familiarize yourself with trusted profiles and how they control user access.

Creating a workspace

To create your first workspace, follow these steps:

  1. From the main menu, go to Build.

  2. In the upper‑right corner, click Create workspace. A dialog Create new workspace appears.

  3. Enter a name for your workspace.

  4. Click Create.

A confirmation message appears indicating that the workspace was created successfully. The workspace name now appears in the workspace dropdown at the top left of the Build agents and tools page.

You are automatically switched to your new workspace and assigned as the owner.

Manage workspace access

When you create a workspace, you automatically become the workspace owner.

As a workspace owner, you can:
  • Add collaborators
  • Assign roles
  • Remove collaborators
  • Delete the workspace

The Manage access option is available only when you are inside a private workspace. When you are in the Global workspace, you can create new workspaces, but you cannot manage access for any workspace.

Adding members to a workspace

Before you begin, ensure that you have selected a workspace from the workspace dropdown. The Manage access option does not appear in the Global workspace.

Note: Members you add must already have the WO User role in watsonx Orchestrate before you can add them to a workspace.

  1. With your workspace selected, click Manage access in the upper-right corner.

  2. In the Manage access dialog, enter the email address of the user you want to add in the Email address field.

  3. Click Add.

The added user appears in the Collaborators list and can immediately access the workspace. All added users are assigned the Editor role by default.You can add up to 50 users in a single operation for efficient team onboarding.

Assigning roles

You can assign or update roles for workspace members:

  • Owner: Has full control of the workspace, including managing members, or deleting the workspace, and managing all artifacts.

    A private workspace can have multiple owners, enabling shared ownership. If a workspace has only one owner and that owner leaves the company before assigning another owner, remaining members cannot update roles. In this case, a service instance admin must promote an existing member to owner or add a new member and assign them the owner role. To prevent ownership gaps, it’s recommended to maintain at least one additional owner per private workspace.

  • Editor: Can create and modify artifacts (agents, tools, knowledge, and connections) but cannot manage workspace access or settings.

Changing user roles

You can update the roles of users who are already members of a private workspace.

  • Only workspace owners can update another member's role.
  • Role changes take effect immediately.

Owners can update a member’s role between owner and editor, for example to promote an editor to share workspace management or to reduce permissions while keeping the user as a collaborator.

Removing members

To remove a member from your workspace:

  1. In the Manage access dialog, locate the member in the Collaborators list.

  2. Click the remove icon next to their name.

  3. Confirm the removal.

The member immediately loses access to the workspace, although their previous contributions remain.

Viewing agents and tools in a workspace

Your workspace displays all artifacts associated with it:

  • Agents: AI agents that you create in the workspace

  • Tools: Custom tools and integrations

  • Knowledge assets: Knowledge bases and reference content that support your agents

Example:

  • In the Global workspace, you might see shared agents like AskOrchestrate under All agents.

  • In a new workspace (for example, AcmeProject), you do not see any agents until you create them.

Creating workspace artifacts

To begin adding content to a workspace, ensure that you have selected the correct workspace from the workspace dropdown. The artifacts that you create appear only in that workspace:

The workspace supports multiple artifact types. You can:

  1. Create new agents

  2. Configure tools and integrations

  3. Add knowledge assets for use in agent logic

All artifacts created within a workspace are visible only to workspace members, ensuring privacy and security for team-specific work.

Choosing between global and private workspaces

When to use the global workspace

Use the global workspace when your work is intended to be shared broadly across teams.

Choose a global workspace when you want to:

  • Make artifacts available to everyone across the tenant.

  • Share agents, tools, or knowledge that multiple teams rely on.

  • Provide standard templates or recommended practices for consistent onboarding.

  • Centralize integrations that will be reused across projects.

  • Reduce duplication by storing stable, reusable artifacts in a single shared location.

When to use a private workspace

Use a private workspace when you need controlled access or want to isolate your work.

Choose a private workspace when you want to:

  • Work privately before sharing early drafts or prototypes.

  • Collaborate with a limited group on project‑specific or departmental tasks.

  • Protect sensitive logic, data sources, or integrations from broad visibility.

  • Keep artifacts organized by project or team and separate from unrelated work.

  • Experiment or iterate in an environment that supports restricted access.