> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/worker-agent-commands.md).

# Harness Worker Agents

Harness Worker Agents are Harness-managed automation workers. Each agent is defined by a wrapper YAML file whose `spec` key carries the agent pipeline definition, which means you can keep agent definitions in version control and apply them from the CLI. The commands live in the `platform` module.

This page covers all Harness Worker Agent resources and actions available in the CLI.

***

### What you will learn in this topic <a href="#what-you-will-learn-in-this-topic" id="what-you-will-learn-in-this-topic"></a>

By the end of this page, you will know how to:

* List the Harness Worker Agents in scope.
* Retrieve an agent definition in a form you can edit and reapply.
* Create an agent from a wrapper YAML file.
* Update an existing agent definition.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **Harness CLI installed and authenticated:** For setup steps, see [Install and upgrade](/harness-platform/use-harness-cli/harness-cli/install-and-upgrade.md) and [Authenticate](/harness-platform/use-harness-cli/harness-cli/authenticate.md).
* **Scope configured:** Worker Agents resolve against the scope in your profile. Pass `--account`, `--org`, or `--project` to override it for a single command.

***

### The wrapper YAML <a href="#the-wrapper-yaml" id="the-wrapper-yaml"></a>

An agent definition is a wrapper document with three parts:

* **`name`:** The display name of the agent.
* **`description`:** A short summary of what the agent does.
* **`spec`:** A string that carries the agent pipeline definition.

Because `spec` is a string, the agent pipeline is nested inside the wrapper rather than merged into it. Retrieve an existing agent with `-o yaml` to get a valid wrapper that you can edit and pass straight back to `create` or `update`.

***

### Worker Agents <a href="#worker-agents" id="worker-agents"></a>

#### List agents <a href="#list-agents" id="list-agents"></a>

```sh
harness list agent
harness list agent --all --format json
harness list agent --columns "name,id"
```

#### Get agent details <a href="#get-agent-details" id="get-agent-details"></a>

Use `-o yaml` to produce a valid wrapper document for editing.

```sh
harness get agent <agent_id>
harness get agent <agent_id> -o yaml
harness get agent <agent_id> --format json
```

#### Create an agent <a href="#create-an-agent" id="create-an-agent"></a>

Create an agent from a wrapper YAML file.

```sh
harness create agent <agent_id> -f <agent_file>.yaml
```

#### Update an agent <a href="#update-an-agent" id="update-an-agent"></a>

Update an agent from a wrapper YAML file. To round-trip a definition, retrieve it, edit it locally, and apply it back.

```sh
harness update agent <agent_id> -f <agent_file>.yaml
```

```sh
harness get agent <agent_id> -o yaml > <agent_file>.yaml
$EDITOR <agent_file>.yaml
harness update agent <agent_id> -f <agent_file>.yaml
```

***

### Related articles <a href="#related-articles" id="related-articles"></a>

* [Platform](/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/platform-commands.md): Manage the connectors, secrets, and delegates an agent depends on.
* [Continuous Delivery](/harness-platform/use-harness-cli/harness-cli/harness-cli-commands/cd-and-pipeline-commands.md): Manage pipelines and executions.