Manage Organizations, Projects, and Workspaces

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

Manage Organizations, Projects, and Workspaces

MongoDB Atlas Agent Engine is in Public Preview and intended for evaluation and prototyping purposes only. We do not recommend production deployments during preview and expect to communicate breaking changes with you periodically. To learn more about preview feature considerations, see Preview Features.

Overview

In this guide, you can learn how to manage your MongoDB Atlas Agent Engine organizations, projects, and workspaces. This guide describes the following management commands:

• [agentengine organization](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-org: List and view organizations.

• [agentengine project](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-projects: List and view projects.

• [agentengine workspace](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-workspaces: Create and manage workspaces for a deployed agent.

• [agentengine service-account](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-service-accounts: Create and manage service accounts for your project or organization.

• [agentengine version](https://www.mongodb.com/docs/agentengine/manage/project-org-workspace/manage-project.md#std-label-agent-engine-manage-cli: Manage the CLI version.

Prerequisites

Before you begin, ensure that you install and authenticate the agentengine CLI. To learn more, see the [Install and Authenticate](https://www.mongodb.com/docs/agentengine/build/install-authenticate.md#std-label-agent-engine-set-up-install-authenticate guide.

View Organizations

Organizations are the top-level grouping for your teams and resources on the MongoDB Atlas Agent Engine. The agentengine CLI can list and view organizations, but it can't change them. To change an Atlas-backed organization, use MongoDB Atlas:

• To create, update, or delete an organization, see the Manage Organizations guide.

• To add, update, or remove organization users, see the Manage Organization Users guide.

If your organization isn't MongoDB Atlas-backed, use the Atlas Agent Engine UI to change your organization.

List All Organizations

To list all organizations your account belongs to, run the following command:

agentengine organization list

Get Organization Details

To retrieve details for a specific organization, run the following command. Replace <org-id> with your organization ID:

agentengine organization get <org-id>

View Projects

Projects exist within an organization and group the resources for a specific agent or team. The agentengine CLI can list and view projects, but it can't change them. To change an Atlas-backed project, use MongoDB Atlas:

• To create, update, or delete a project, see the Manage Projects guide.

• To add, update, or remove project users, see the Manage Access to a Project guide.

If your project isn't MongoDB Atlas-backed, use the Atlas Agent Engine UI to change your project.

List All Projects

To list all projects in your organization, run the following command:

agentengine project list [--org-id <org-id>]

You can use the --org-id flag to specify the organization ID. By default, the CLI reads this value from your locally stored authentication state.

Get Project Details

To retrieve details for a specific project, run the following command. Replace <project-id> with your project ID:

agentengine project get <project-id>

Manage Workspaces

A workspace is the runtime environment for a deployed agent within a project. Use the following commands to create and manage workspaces. The examples in this section use the <workspace-id> placeholder. Replace this placeholder with your workspace ID.

List All Workspaces

To list all workspaces in your project, run the following command:

agentengine workspace list [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]

The following table describes the available flags:

Get Workspace Details

To retrieve details for a specific workspace, run the agentengine workspace get command:

agentengine workspace get <workspace-id> [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]

The following table describes the available flags:

Create a Workspace

The agentengine workspace create command creates a new workspace on the platform. Run this command from an agent directory that contains an agent.yaml file that includes the name and entrypoint fields.

The command automatically reads description, framework, features, and agent_card from agent.yaml and auto-detects GitOps fields from the local git repository, if present. Use the --description and --framework flags to override values from agent.yaml.

If a workspace already exists for the project, the command prints the existing workspace ID and exits successfully.

agentengine workspace create [--description <desc>] [--framework <fw>] [--project-id <id>] [--org-id <id>] [--base-url <url>] [--json]

The following table describes the available flags:

Update a Workspace

The agentengine workspace update command partially updates an existing workspace. Only flags that are explicitly provided are included in the update request.

agentengine workspace update <workspace-id> [flags]

The following table describes the available flags:

Manage Workspaces by Using the API

The workspace commands call the Atlas Agent Engine API. To manage workspaces programmatically, call these endpoints directly.

Each workspace endpoint is scoped to a single project. If you're calling endpoints in more than one project, include the project ID in the request.

The following table describes the available endpoints. Replace {project-id} with your project ID and {workspace-id} with your workspace ID:

Manage Service Accounts

A service account is a programmatic identity that belongs to a project or an organization instead of a person. Use the following commands to create, list, rotate, and delete service accounts.

To retrieve your service account access token, pass your client ID and secret in a POST request to the /api/v1/oauth/token endpoint. To learn more, see [Invoke an Agent.](https://www.mongodb.com/docs/agentengine/deploy/invoke-agent.md#std-label-agent-engine-invoke-agent

The examples in this section use the following placeholders:

• <name>: The service account name.

• <role>: The role to grant the service account. For a project account, use PROJECT_OWNER or PROJECT_READ_ONLY. For an organization account, use ORG_OWNER, ORG_GROUP_CREATOR, or ORG_READ_ONLY.

• <client-id>: The service account's client ID.

Create a Service Account

To create a new service account, run the following command:

agentengine service-account create <name> --role <role> [--org-id <id> | --project-id <id>] [--description <text>] [--secret-expires-in <duration>] [--ip-access-list <ip-or-cidr>,...] [--json]

The command outputs the plaintext client secret and the service account's details, as shown in the following example:

Client Secret: agp_sa_sk_...
Client ID:     agp_sa_id_...
Name:          ci-pipeline
...

Important:

Save the client secret when it is displayed. It is only shown once.

The following table describes the available flags:

List Service Accounts

To list all service accounts for the current project or organization, run the following command:

agentengine service-account list [--org-id <id>] [--project-id <id>] [--limit <n>]

The command displays a table with the client ID, name, roles, active status, secret expiry, secret last-used date, and description for each service account.

By default, the command lists service accounts for the project in your locally stored authentication state. Use the --org-id or --project-id flag to list service accounts for a different organization or project.

Rotate a Service Account Secret

To issue a new client secret for a service account, run the following command:

agentengine service-account rotate <client-id> [--org-id <id>] [--project-id <id>] [--secret-expires-in <duration>]

The command outputs the new plaintext client secret. The previous secret remains valid for up to seven days or until its own expiration, whichever comes first.

Tip:

To immediately revoke the previous secret, rotate the secret a second time or delete the service account.

Delete a Service Account

To permanently delete a service account, run the following command:

agentengine service-account delete <client-id> [--org-id <id>] [--project-id <id>]

After you delete a service account, it can no longer request access tokens, and any token it already holds fails on its next use.

Manage CLI Versions

This section describes the commands you can use to retrieve and update your CLI version.

Check the CLI Version

The agentengine version command prints the CLI release version, the git commit the binary was built from, and the default container image tags used by the local development stack.

To retrieve the CLI version, run the following command:

agentengine version [--json]

Tip:

By default, this command prints a human-readable plain-text string. Pass the --json flag to print a stable, machine-readable JSON object that includes the schema_version, status, version, git_commit, build, and embedded images fields.

The output resembles the following:

0.1.94-alpha (commit: <hash>)
image registry: ECR
runner-base: <registry>/runner-base:0.1.94-alpha
runner-base-typescript-langgraph: <registry>/runner-base-typescript-langgraph:0.1.94-alpha
playground-ui: <registry>/playground-ui:0.1.94-alpha
orchestrator: <registry>/orchestration-engine:<version>
memory-server: <registry>/memory-server:<version>

Update the CLI

The agentengine self-update command downloads the latest matching release asset for your current OS and architecture, verifies the SHA-256 checksum of that asset, and replaces the existing binary at its current installation path.

When you are logged in to the Atlas Agent Engine, the CLI retrieves the list of available releases from the platform API Gateway.

Note:

The agentengine self-update command downloads the new binary into the directory that holds your current binary, so you must have write access to that directory. If you don't have write access, prefix the command with sudo or reinstall the CLI to a different directory.

To update the CLI, run the following command:

agentengine self-update [--force] [--auto[=true|false]]

The following table describes the available flags:

When you run most agentengine commands, the CLI prints a one-line notice to stderr if a newer release is available. The CLI runs the update check once every 24 hours. To disable the check entirely, set the AGENTENGINE_NO_UPDATE_CHECK=1 environment variable in your shell.

Note:

On Windows, the agentengine self-update command downloads the updated binary for manual replacement because a running agentengine.exe cannot be replaced in place.

Resource Limits

Each organization can have up to 100 organization service accounts. If you exceed this limit, the request returns a 400 Bad Request error with a RESOURCE_LIMIT_EXCEEDED message.

The following table lists the resource limits for each project:

If you exceed a resource limit, the request returns a 400 Bad Request error with a RESOURCE_LIMIT_EXCEEDED message.

To review all limitations that apply during Public Preview, see [MongoDB Atlas Agent Engine Limitations.](https://www.mongodb.com/docs/agentengine/reference/limitations.md#std-label-agent-engine-limitations

Next Steps

After you set up your organizations, projects, and workspaces, you can build and run your agent locally. To learn how, see [Build Your Local Environment.](https://www.mongodb.com/docs/agentengine/build/run-local.md#std-label-agent-engine-build-local