> 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-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/configuration.md).
# Worker Agent configuration
Configure Worker Agent model providers, instructions, MCP connectors, inputs, environment variables, outputs, triggers, and notifications.
Worker Agent definitions use `agent.uses: harnessAI@1.0.0`, with the prompt and connectors under `agent.with` and reusable parameters under `agent.inputs`. Configure pipeline triggers, per-run settings, and notification channels on the pipeline that references the agent.
***
### What you will learn in this topic
By the end of this topic, you will be able to:
* [Use GitHub Copilot as the model provider](#use-github-copilot-as-the-model-provider).
* [Configure instructions with Harness expressions for dynamic context](#configure-instructions-and-harness-expressions).
* [Set up MCP connectors to access Harness platform data and external services](#configure-mcp-connectors).
* [Define typed inputs to parameterize agent behavior](#configure-inputs).
* [Set environment variables for runtime configuration](#configure-environment-variables).
* [Configure allowed domains for network access](#configure-allowed-domains).
* [Configure pipeline triggers to automate agent execution](#configure-pipeline-triggers).
* [Publish agent outputs and consume them in later steps](#configure-agent-outputs).
* [Send Worker Agent results to Slack via multiple methods](#configure-slack-notifications).
***
### Before you begin
Before you configure a Worker Agent, ensure you have the following:
* **Worker Agent created**: A Worker Agent must exist in your Harness account. Go to [Worker Agents](/harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/example-agents.md) to create one if needed.
* **Model Connector configured**: Anthropic, OpenAI, or GitHub Copilot connector for the LLM provider. Go to [Choose a Model Connector](/harness-ai/use-harness-ai/connect-with-ai.md#choose-a-connector) for setup instructions.
* **Harness API key**: Required for MCP connector authentication. Go to [Manage API keys](/harness-ai/use-harness-platform/automation/api/add-and-manage-api-keys.md) to create one.
* **Access to Agent Definition**: Permission to view and edit Worker Agent definitions in AI > Worker Agents.
***
### Configure Model Connectors
The Model Connector defines the LLM provider and default model for your Worker Agent. When you create or select a connector, you choose a default model that the agent uses at runtime unless overridden by the optional **Model Name** field.
If you leave the model unset on both the LLM connector and the Worker Agent, Harness uses a default model for that provider. These defaults can change. The current defaults are Claude Sonnet 5.5 for Anthropic and GPT-5.4 for OpenAI.
Harness supports the following Model Connectors:
* **GitHub Copilot Connector**: Authenticate with your GitHub Copilot PAT and use models available to your Copilot account. Go to [Use GitHub Copilot as the model provider](#use-github-copilot-as-the-model-provider) to configure the connector and select a model.
* **Anthropic Model Connector**: Run agents on Claude models through direct Anthropic or AWS Bedrock endpoints. Go to [Anthropic Model Connector](/harness-ai/use-harness-ai/connect-with-ai/anthropic-model-connector.md) to review supported models and setup options.
* **OpenAI Model Connector**: Run agents on GPT-5.5 with configurable reasoning effort. Go to [OpenAI Model Connector](/harness-ai/use-harness-ai/connect-with-ai/openai-model-connector.md) to review supported models, effort levels, and setup options.
If you do not have access to a model provider, use a Harness-managed LLM connector instead of configuring your own credentials. Harness auto-provisions view-only managed connectors at the account level, `harnessAnthropic` for Claude models and `harnessOpenAI` for GPT models, that route requests through the Harness **LLM Gateway**. Inspect them under **Account Settings** > **Account Resources** > **Connectors**; you cannot edit or delete them.
Managed LLM connectors are controlled by the **Enable Harness Managed LLM Connectors** default setting under **Account Settings** > **General** > **Default Settings** > **Harness AI**. Worker Agents authenticate to the LLM Gateway through the `ML_HARNESS_MANAGED_LLM_CONNECTORS` permission, which is included in the agent scoped token by default. If you define an explicit [agent permission block](/harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/permissions.md), add `ai_llm_gateway: access` to retain LLM Gateway access.
***
## Use GitHub Copilot as the model provider
Connect a Worker Agent to GitHub Copilot with your personal access token (PAT) to use models available through your GitHub Copilot account for operations in Harness. Store the PAT as a Harness secret and reference it from a GitHub Copilot connector.
Before you begin, have a GitHub Copilot account with access to the model you want to use, a PAT for that account, and permission to create or select Harness connectors and secrets.
{% stepper %}
{% step %}
### Create the GitHub Copilot connector
In the Worker Agent form, use **Model provider** to create a connector and select **GitHub Copilot**.
In **Create GitHub Copilot connector**:
1. Enter a **Name** for the connector.
2. Set **Authentication Type** to **Personal Token**.
3. Under **API Key**, select **Create or Select** and reference the Harness secret containing your GitHub Copilot PAT.
4. Optionally select a default **Model Name** from the available models.
5. Select **Create**.
{% endstep %}
{% step %}
### Select the connector and model
Set the Worker Agent's **Model provider** to the GitHub Copilot connector you created.
Select **Model name** to choose a model for this agent. You can leave this field empty if a model is already set in the connector. Select a model available to your GitHub Copilot account; do not assume that leaving both model fields empty selects a supported default.
{% endstep %}
{% step %}
### Configure operations and save the agent
Configure the agent's **Instructions**, inputs, and **MCP connectors** for the task you want it to perform. Select **Save agent** when the configuration is complete.
The GitHub Copilot connector supplies model access. MCP connectors and the agent's Harness permissions determine which resources it can access and which operations it can perform. Keep the Harness MCP connection configured for tasks that use Harness tools.
Validate the setup with a read-only task in a known account, organization, and project, such as listing pipelines and summarizing their status. Check the execution result before using the agent for changes.
{% endstep %}
{% endstepper %}
{% hint style="info" %}
The GitHub Copilot model connector is separate from the GitHub MCP connector. Configuring Copilot as the model provider does not grant additional Harness or GitHub resource permissions.
{% endhint %}
If authentication fails, check the PAT referenced by **API Key** and the agent's access to that secret. If a model is unavailable, confirm that it is available to the GitHub Copilot account associated with the PAT, then select an available model.
***
### Configure instructions and Harness expressions
The **Instructions** field is the agent's system prompt. It defines what the agent does, how it reasons, and what it outputs.
Configure instructions in the **Worker Agent definition** (AI > Worker Agents > select the agent > **Instructions** field or **YAML** tab). In YAML, put the instructions in `agent.with.prompt`. The pipeline's Agent step references the agent by name and version.
If you need the agent to behave differently in a specific pipeline, use agent **Inputs** to parameterize the instructions, or supply pipeline-specific context via **Agent Settings** (which inject environment variables at runtime). The recommended approach is to edit the instructions directly in the agent definition. This keeps the prompt centralized, versioned, and reusable across pipelines.
{% hint style="info" %}
Use agent **Inputs** (such as `<+inputs.repoName>` or `<+inputs.planFile>`) to make instructions dynamic without duplicating the agent. Each pipeline can supply different input values at runtime while sharing the same prompt logic.
{% endhint %}
The table below lists expressions commonly used in Worker Agent instructions. For the full list of available variables and expressions, go to:
* [Add a variable](/harness-ai/use-harness-platform/variables-and-expressions/add-a-variable.md): Create custom pipeline, stage, and service variables.
* [Built-in and custom Harness variables reference](/harness-ai/use-harness-platform/variables-and-expressions/harness-variables.md): Complete reference for all built-in variables including pipeline, stage, step, trigger, and deployment variables.
* [Harness expressions reference](/harness-ai/use-harness-platform/variables-and-expressions/harness-expressions-reference.md): Syntax, usage patterns, and methods for working with expressions.
#### Supported expressions
| Expression | Resolves to |
| ---------------------------------- | ----------------------------------------------------------------- |
| `<+trigger.repoName>` | Name of the repository that triggered the pipeline |
| `<+trigger.branch>` | Branch name from the trigger event |
| `<+trigger.prNumber>` | Pull request number from the trigger event |
| `<+trigger.sourceBranch>` | Source branch of the pull request |
| `<+trigger.targetBranch>` | Target branch of the pull request |
| `<+trigger.commitSha>` | Head commit SHA of the PR |
| `<+trigger.baseCommitSha>` | Base commit SHA for the diff range |
| `<+inputs.accountID>` | Harness Account ID passed as a pipeline input |
| `<+inputs.orgId>` | Harness Organization ID passed as a pipeline input |
| `<+secret.getValue("secretName")>` | Value of a Harness secret (recommended for environment variables) |
#### Example instructions with dynamic context
The following system prompt uses trigger expressions to inject repository and branch context at runtime:
```
You are a Principal-level Staff Engineer and Security Architect acting as an
automated Pull Request reviewer.
Repository Name: <+trigger.repoName>
Branch: <+trigger.branch>
Review the diff across four domains: Security, Compliance, Schema/Architecture,
and Engineering Judgment. Output a structured findings table and architectural
assessment with a clear Approve / Request Changes / Block recommendation.
```
{% hint style="warning" %}
Harness expressions in the Instructions field are resolved at **pipeline execution time**, not when you save the agent.
{% endhint %}
***
### Configure MCP connectors
MCP (Model Context Protocol) connectors give the Worker Agent real-time access to Harness platform data and external services. Every MCP connector declares a `transport`:
* **Remote (`http`)**: Connects to an existing MCP server over HTTP, such as the Harness Hosted MCP endpoint or a third-party server.
* **Local (`stdio`)**: Runs the MCP server as a process inside the Worker Agent's own container, spun up at pipeline runtime.
{% hint style="warning" %}
**LOCAL MCP CONNECTORS RUN ON WORKER AGENT INFRASTRUCTURE ONLY**
A local (`stdio`) MCP connector only runs inside a Worker Agent's container at execution time. You cannot attach a local MCP connector anywhere else, including Harness AI Chat MCP connectors.
{% endhint %}
**Harness Hosted MCP** is the recommended remote connector for accessing Harness-native data, including pipelines, executions, services, and environments. GitHub is also supported as a remote MCP source.
{% hint style="warning" %}
**GITHUB MCP CONNECTOR**
The **GitHub MCP Connector** in the Harness Connector Catalog is designed for use with **AI Chat only**. It is not compatible with Worker Agents at this time. To give a Worker Agent access to GitHub data, use the Harness Hosted MCP connector or configure a custom MCP server endpoint.
{% endhint %}
#### Harness Hosted MCP endpoints
| Cluster | MCP URL |
| -------------- | ------------------------------------------------------------ |
| prod0 | `https://unifiedpipeline.harness.io/mcp-server-external/mcp` |
| prod0 (devday) | `https://devday.harness.io/mcp-server-external/mcp` |
| prod1 | `https://app.harness.io/prod1/mcp-server-external/mcp` |
| prod2 | `https://app.harness.io/gratis/mcp-server-external/mcp` |
| prod3 | `https://app3.harness.io/mcp-server-external/mcp` |
| harness0 | `https://harness0.harness.io/mcp-server-external/mcp` |
| eu1 | `https://accounts.eu.harness.io/mcp-server-external/mcp` |
| qa | `https://qa.harness.io/mcp-server-external/mcp` |
#### Set up an MCP Server Connector
*MCP Server Connector setup with server URL and custom header authentication*
To create an MCP Server Connector in Harness, do the following:
1. Navigate to **Connectors** in your project, organization, or account settings.
2. Search for **MCP** in the connector catalog and select **MCP Server**.
The remaining steps differ by transport.
{% tabs %}
{% tab title="Remote" %}
3\. In the **Details** step, enter the **Server URL** from the table above, or your third-party server's endpoint.
4\. Under **Authentication**, select **Custom Header**, **API Key**, or **None** for a public server that does not require credentials.
5\. For **Custom Header**, set the **Header Name** to `X-Api-Key` and the **Header Value** to your API key, stored as a Harness secret.
6\. Click **Continue**, select a connectivity mode, and run the connection test.
{% hint style="warning" %}
A remote MCP connector requires **both** a valid server URL and a credential, unless **Authentication** is set to **None**. A connector name alone is not sufficient.
{% endhint %}
{% endtab %}
{% tab title="Local" %}
3\. In the **Details** step, select **Local** as the transport.
4\. Enter the **Command** the agent runs to start the MCP server, and any **Arguments** it needs.
5\. Optionally add **Post-install commands**, shell commands that run once before the server starts, such as initializing a repository.
6\. Optionally add **Environment variables**. Reference a Harness secret for any sensitive value instead of entering it directly.
7\. Click **Continue**, select a connectivity mode, and run the connection test.
{% hint style="warning" %}
A local MCP connector is only usable by Worker Agents. It cannot be attached in Harness AI Chat or any other MCP consumer.
{% endhint %}
{% endtab %}
{% endtabs %}
#### MCP Connector YAML examples
The following examples show the connector YAML for a remote Harness MCP connector, a remote GitHub MCP connector, and a local MCP connector. You can create these connectors via the API or by importing the YAML in the Harness Connector settings.
**Remote MCP Connector (Harness MCP)**:
```yaml
connector:
name: Harness MCP
identifier: connector_Mcp_66c8
accountIdentifier:
orgIdentifier: default
projectIdentifier:
type: Mcp
spec:
transport: http
serverUrl: https://unifiedpipeline.harness.io/mcp-server-external/mcp
auth:
type: CustomHeader
spec:
headerName: X-Api-Key
headerValueRef:
executeOnDelegate: false
```
**Remote MCP Connector (GitHub MCP)**:
```yaml
connector:
name: Github_MCP
identifier: Github_MCP
accountIdentifier:
orgIdentifier: default
projectIdentifier:
type: Mcp
spec:
transport: http
serverUrl: https://api.githubcopilot.com/mcp
auth:
type: ApiKey
spec:
apiKeyRef:
executeOnDelegate: false
```
**Local MCP Connector**:
```yaml
connector:
name: git
identifier: git
accountIdentifier:
orgIdentifier: default
projectIdentifier:
type: Mcp
spec:
transport: stdio
executeOnDelegate: false
stdio:
command: uvx
args:
- "--with"
- mcp<2
- mcp-server-git
- "--repository"
- /harness/mcp-repo
env:
- name: GIT_TOKEN
type: Secret
secretRef:
postInstall:
- git init /harness/mcp-repo
```
Replace the placeholder values (``, ``, ``, ``, ``) with your actual account identifier, project identifier, and secret references. `stdio.command` and `stdio.args` define the process the Worker Agent launches to run the server, `stdio.postInstall` runs once before the server starts, and `stdio.env` supplies environment variables, with secret values referenced through `secretRef`.
***
### Configure inputs
Inputs are typed parameters defined on the agent. They surface in the pipeline step UI and can be passed from upstream steps, trigger payloads, or set manually.
Declare inputs under `agent.inputs`, and reference them with `<+inputs.inputName>`. Input names are case-sensitive. For example, an input named `projectName` must be referenced as `<+inputs.projectName>`.
Supported input types: `string`, `connector`, `array`
#### YAML reference
```yaml
agent:
uses: harnessAI@1.0.0
with:
prompt: |
List pipelines in project <+inputs.projectName> in organization <+inputs.orgId>.
Use Harness MCP and summarize the results.
connector: <+inputs.llmConnector>
mcp: <+inputs.mcpConnectors>
inputs:
projectName:
type: string
required: true
orgId:
type: string
default: default
llmConnector:
type: connector
default: account.harnessAnthropic
mcpConnectors:
type: array
default:
- harness_hosted_mcp
```
***
### Configure environment variables
The `harnessAI@1.0.0` template configures the agent runtime environment. Add custom environment variables under `agent.with.env` as a map of names to string values. Quote boolean-like strings such as `"true"` so YAML preserves them as strings.
Environment variable values can be:
* **Fixed value**: A static string (such as a model ARN or feature flag).
* **Secret expression**: `<+secret.getValue("secretName")>` to pull from Harness Secrets Manager at runtime.
```yaml
agent:
uses: harnessAI@1.0.0
with:
prompt: Summarize the codebase and recommend improvements.
connector: account.harnessAnthropic
allowed_domains: harness.io
env:
demo: "true"
swarm: "true"
```
For environment variables specific to a pipeline run, go to [Agent settings](#agent-settings).
#### Common variables
| Variable | Purpose |
| ----------------- | -------------------------------------------------------------------------------------------------- |
| `REPO_NAME` | Repository context for prompts that read an environment variable. |
| `TARGET_ENV` | Target environment for prompts that read an environment variable. |
| `ANTHROPIC_MODEL` | Model override for Claude-compatible runtimes, including the model ARN used in the agent examples. |
For reusable prompt parameters, prefer typed `agent.inputs` and reference them directly in `with.prompt`.
***
### Configure allowed domains
Set `agent.with.allowed_domains` to a comma-separated string of hostnames or regex patterns for the domains the agent can reach over the network. Harness domains are allowed by default.
For example, `allowed_domains: "harness.io,api.example.com"` adds access to `api.example.com`. Configure the patterns required by your agent's workflow.
***
### Configure pipeline triggers
Worker Agents support all standard Harness pipeline trigger types, including webhook, artifact, manifest, and scheduled triggers.
Add a trigger to your pipeline, then reference its expressions (`<+trigger.prNumber>`, `<+trigger.repoName>`, and others) in your agent's Instructions to scope behavior to the triggering event.
*All Harness pipeline trigger types are supported for Worker Agent pipelines*
Go to [Triggers overview](/harness-ai/use-harness-platform/triggers/triggers-overview.md) for more information on available trigger types.
***
### Configure Slack notifications
Worker Agent results can be forwarded to Slack using pipeline notifications, user group notifications, the Slack Notify step, or custom scripts.
#### Pipeline notifications (native)
Pipeline notifications send alerts based on pipeline events.
1. Click the **Notify** icon in the Harness pipeline studio.
2. Add a name and select the **Pipeline Events** to trigger the notification.
3. In **Notification Method**, select `Slack`.
4. Paste your Slack Incoming Webhook URL, or reference it as a secret: `<+secrets.getValue("slackwebhookURL")>`.
Go to [Configure pipeline notifications](/harness-ai/use-harness-platform/notifications-alerts-and-banners/notifications/configure-notifications.md#configure-pipeline-notifications) for complete setup instructions.
#### User group notifications
User group notifications alert specific teams based on pipeline events.
1. Navigate to **Access Control**, then select **User Groups**.
2. Select a User Group and navigate to **Notification Preferences**.
3. Select **Slack Webhook URL** and paste your webhook.
Go to [Send notifications using Slack](/harness-ai/use-harness-platform/notifications-alerts-and-banners/notifications/send-notifications-using-slack.md) for complete setup instructions.
#### Slack Notify step (CD pipelines)
A dedicated **Slack Notify Step** is available in CD and custom stages. It must be inside a step group with container-based execution. It supports channel ID or email targeting, plain text or Slack Block Kit, and threading via `thread_ts`.
```yaml
- step:
type: SlackNotify
name: SlackNotify_1
identifier: SlackNotify_1
spec:
channel: CHANNEL_ID
messageContent: <+input>
token: SLACK_TOKEN
threadTs: THREAD_ID
```
#### Custom Slack messages via script
To include additional pipeline data in Slack notifications, use a Shell Script or Run step with `curl`:
```bash
curl -X POST -H 'Content-type: application/json' --data '{
"text": "Slack notifications - Harness",
"attachments": [{
"fields": [
{"title": "Pipeline Name", "value": "<+pipeline.name>", "short": true},
{"title": "Triggered by", "value": "<+pipeline.triggeredBy.email>", "short": true}
]
}]
}' https://hooks.slack.com/services/
```
{% hint style="info" %}
Always store your Slack webhook URL as an encrypted text secret in Harness and reference it via `<+secrets.getValue("your-secret-id")>`. Go to [Add and use text secrets](/harness-ai/use-harness-platform/secrets/add-use-text-secrets.md) for more information on setting up encrypted secrets.
{% endhint %}
***
### Agent settings
**Agent Settings** is a key-value configuration field on the Agent step that maps directly to environment variables at runtime. Any key-value pair you define is injected into the agent's execution context as an environment variable, scoped to the step level rather than the agent definition.
This is useful when you have a Worker Agent template with multiple input fields and you want to supply values at the pipeline step level without modifying the agent definition itself. For example, if your agent template defines five input fields (`targetEnv`, `slackChannel`, `approvalPolicy`, `maxRetries`, `notifyOnFailure`), you provide those values in Agent Settings when adding the step to your pipeline. Each one is converted into a corresponding environment variable available to the agent at runtime.
***
### Configure agent outputs
To publish pipeline variables, tell the agent in **Instructions** which variables to output and which values to use. You do not set `agent.with.output`. You do not write to `$HARNESS_OUTPUT` or `$DRONE_OUTPUT`.
For example, add this to the agent instructions:
```
When you finish, output a variable TASK_SUCCESS with value true if the work succeeded, or false if it failed.
```
After the run, `TASK_SUCCESS` appears on the Agent step **Output** tab. Later steps can gate, notify, or branch on that value.
You can output more than one variable. Name each variable and state the allowed values:
```
When you finish, output these variables:
- TASK_SUCCESS: true if the work succeeded, false if it failed
- RECOMMENDATION: APPROVE, REVIEW, or REJECT
```
{% hint style="info" %}
**No output key and no output files**
Named pipeline variables come from the instruction. Do not add an `output` field to the agent YAML, and do not ask the agent to append `KEY=value` lines to `$HARNESS_OUTPUT` or `$DRONE_OUTPUT`.
{% endhint %}
### How named output variables work
Harness collects the variables the agent outputs at the end of the step. Each name becomes an output variable on the Agent step.
If a variable is missing after a successful run, the instructions did not ask for it, or the agent did not output it. Open the execution, expand the Agent step group, and check the **Output** tab.
### Publish outputs from agent instructions
Put the output request in the agent **Instructions** (`agent.with.prompt`). The pipeline Agent step only references the agent. It does not declare output variables.
Keep names stable across agent versions. Expression names are case-sensitive.
### Reference outputs in downstream steps
At execution time, Harness expands the Agent step into a **step group**. The expression must include the outer Agent step identifier and the inner step name:
```
<+steps..steps..output.outputVariables.>
```
For example, if the Agent step identifier is `run_task` and the inner step is `my_agent_1`:
```
<+steps.run_task.steps.my_agent_1.output.outputVariables.TASK_SUCCESS>
```
To fail a later step when the agent reports failure, use a condition such as:
```
<+steps.run_task.steps.my_agent_1.output.outputVariables.TASK_SUCCESS> == "true"
```
Run the pipeline once, expand the Agent step group in the execution view, and copy the inner step name from there. On the **Output** tab, use the copy icon next to a variable to copy the exact expression. A shorter path such as `<+steps..output.outputVariables.KEY>` does not resolve, because the Agent step is a group.
Go to [Use Worker Agents in pipelines](/harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/worker-agent-in-pipeline.md#agent-step-expands-to-a-step-group-at-runtime) for the full expression path and a gating pipeline example.
### Best practices for agent outputs
Use the following rules when you publish and consume agent outputs:
* **Ask in the instruction:** Name the variable and the allowed values in **Instructions**. That is the only setup required.
* **Keep key names stable:** Use the same names across agent versions. Expression names are case-sensitive.
* **Read outputs after the Agent step finishes:** Later steps can read a variable only after the Agent step has completed. Do not reference the variable from a parallel step.
***
### Next steps
* [Worker Agents](/harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/example-agents.md): Create and manage Worker Agents, including output examples.
* [Use Worker Agents in pipelines](/harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/worker-agent-in-pipeline.md): Add an Agent step and reference output variables.
* [Choose a Model Connector](/harness-ai/use-harness-ai/connect-with-ai.md): Configure Anthropic or OpenAI connectors for your agents, or go to [Use GitHub Copilot as the model provider](#use-github-copilot-as-the-model-provider) for Copilot setup.
* [Harness expressions reference](/harness-ai/use-harness-platform/variables-and-expressions/harness-expressions-reference.md): Expression syntax for dynamic agent configuration.
{% @harness-feedback/feedback module="harness-ai" pagePath="harness-ai/use-harness-ai/core-capabilities/in-your-pipelines/worker-agent/configuration" %}