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: List and view organizations.
agentengine project: List and view projects.
agentengine workspace: Create and manage workspaces for a deployed agent.
agentengine service-account: Create and manage service accounts for your project or organization.
agentengine version: 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 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:
Flag | Description |
|---|---|
| Project ID |
| Organization ID for multi-org routing |
| Platform API base URL |
| Output raw JSON instead of a human-readable table |
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:
Flag | Description |
|---|---|
| Project ID |
| Organization ID for multi-org routing |
| Platform API base URL |
| Output raw JSON instead of human-readable key-value pairs |
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:
Flag | Description |
|---|---|
| Workspace description. Overrides the value from |
| Agent framework (for example, |
| Project ID |
| Organization ID for multi-org routing |
| Platform API base URL |
| Output JSON with |
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:
Flag | Description |
|---|---|
| Workspace display name |
| Workspace description |
| Agent framework |
| LLM model name |
| Enabled tools (comma-separated) |
| Enable or disable guardrails ( |
| Enable or disable memory ( |
| Agent card summary text |
| Agent card capabilities (comma-separated) |
| GitOps provider |
| GitOps repository URL |
| GitOps branch |
| GitOps manifest path |
| GitOps connection reference |
| Project ID |
| Organization ID for multi-org routing |
| Platform API base URL |
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:
Endpoint | Description |
|---|---|
| Lists the workspaces in the project. |
| Creates a workspace in the project. |
| Returns the details for a single workspace. |
| Updates the fields that you include in the request body. |
| Deletes the workspace. |
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.
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, usePROJECT_OWNERorPROJECT_READ_ONLY. For an organization account, useORG_GROUP_CREATORorORG_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:
Flag | Description |
|---|---|
| Required. Role granted to the service account. |
| Organization ID for an organization-scoped account. |
| Project ID for a project-scoped account. |
| Human-readable description. |
| Secret lifetime in hours, such as |
| IP addresses or CIDR blocks allowed to use the credential. |
| Outputs the created service account, the one-time client secret, and resolved context as JSON. Warnings do not appear in stdout. |
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:
Flag | Description |
|---|---|
| Download and install the latest release even if the current CLI is already up to date. |
| Enable automatic self-updates before most commands run. Pass the |
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:
Resource | Limit |
|---|---|
Workspaces | 25 |
API keys | 100 |
Credential providers | 100 |
Project service accounts | 100 |
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.
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.