Ctrlk
Sign UpGet a DemoContact Us
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Worker Agent configuration

Configure Worker Agent 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:

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 to create one if needed.

  • Model Connector configured: Anthropic or OpenAI connector for the LLM provider. Go to Choose a Model Connector for setup instructions.

  • Harness API key: Required for MCP connector authentication. Go to Manage API keys 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:

  • Anthropic Model Connector: Run agents on Claude models through direct Anthropic or AWS Bedrock endpoints. Go to Anthropic Model Connector 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 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, add ai_llm_gateway: access to retain LLM Gateway access.

MANAGED CONNECTOR BILLING

Until August 2026, usage of the Harness-managed LLM connector is included in your Harness subscription at no additional cost. After August 2026, Harness bills managed LLM connector usage separately, in addition to your Harness subscription.

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.

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.

The table below lists expressions commonly used in Worker Agent instructions. For the full list of available variables and expressions, go to:

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:

Harness expressions in the Instructions field are resolved at pipeline execution time, not when you save the agent.

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.

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.

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.

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.

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.

  1. In the Details step, enter the Server URL from the table above, or your third-party server's endpoint.

  2. Under Authentication, select Custom Header, API Key, or None for a public server that does not require credentials.

  3. For Custom Header, set the Header Name to X-Api-Key and the Header Value to your API key, stored as a Harness secret.

  4. Click Continue, select a connectivity mode, and run the connection test.

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.

  1. In the Details step, select Local as the transport.

  2. Enter the Command the agent runs to start the MCP server, and any Arguments it needs.

  3. Optionally add Post-install commands, shell commands that run once before the server starts, such as initializing a repository.

  4. Optionally add Environment variables. Reference a Harness secret for any sensitive value instead of entering it directly.

  5. Click Continue, select a connectivity mode, and run the connection test.

A local MCP connector is only usable by Worker Agents. It cannot be attached in Harness AI Chat or any other MCP consumer.

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):

Remote MCP Connector (GitHub MCP):

Local MCP Connector:

Replace the placeholder values (<your_account_id>, <your_project>, <your_harness_api_key_secret>, <your_github_oauth_token_secret>, <your_secret_ref>) 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

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.

For environment variables specific to a pipeline run, go to 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 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 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 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.

Custom Slack messages via script

To include additional pipeline data in Slack notifications, use a Shell Script or Run step with curl:

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 for more information on setting up encrypted secrets.

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:

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:

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.

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:

For example, if the Agent step identifier is run_task and the inner step is my_agent_1:

To fail a later step when the agent reports failure, use a condition such as:

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.<step_identifier>.output.outputVariables.KEY> does not resolve, because the Agent step is a group.

Go to Use Worker Agents in pipelines 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

PreviousAgent permissions
NextAgent examples

Last updated

Was this helpful?