Create Agent

Create and update Harness AI agent instances for automated code, build agentic workflows, and infrastructure tasks.

Instructions

Follow this workflow to create or update an agent. This is INTERACTIVE — show YAML for review and wait for confirmation before creating/updating the agent.

Phase 1: Check Existing Solutions First

IMPORTANT: Before creating a new agent, check if an existing one can solve the use case.

1. List existing agents — Call harness_list with resource_type="agent" (include org_id and project_id if scoped to a project)
   • Check if any system or custom agents already exist that can handle this task
   • Ask user if they want to use/modify an existing agent instead of creating new
2. For updating existing agents — Use harness_get with resource_type="agent" and agent_id to retrieve the current agent configuration
   • Review the current spec, name, description, and other fields
   • Identify what needs to be changed (spec, name, description, wiki, logo)
   • Use harness_update (not harness_create) to update the agent with only the fields that need modification
3. Refer to agent schema when needed — If you're not sure about the YAML structure, use harness_schema with resource_type="agent-pipeline" to explore available fields and sections
   • Use the path parameter to avoid context pollution: The full schema is 4k+ lines. Load only what you need:
     • harness_schema(resource_type="agent-pipeline") → Top-level summary (shows available sections)
     • harness_schema(resource_type="agent-pipeline", path="Agent") → Agent structure only
     • harness_schema(resource_type="agent-pipeline", path="stages") → Stage definitions only
   • For operations/API metadata: Use harness_describe(resource_type="agent") to see supported operations, filters, and execute actions
   • CRITICAL: The agent spec uses first-class agent format (version: 1, agent:, stages:, etc.), NOT pipeline format

Phase 2: Requirements Gathering

If creating a new agent or updating an existing one, collect the following before generating YAML:

1. Agent Metadata

• Name: Display name for the agent (e.g. "Code Coverage Agent", "PR Reviewer")
• Description: Brief description of the agent's purpose (optional)
• UID: Unique identifier (auto-generated from name if not provided — e.g. "Code Coverage Agent" → "code_coverage_agent")

2. Task Details

This is an INTERACTIVE requirements gathering process. Ask clarifying questions and verify understanding with the user before proceeding.

Step 1: Understand the Agent's Purpose

Ask and clarify the following with the user:

1. Agent's exact goal: What specific outcome should the agent achieve?
   • Examples: "Increase code coverage to 80%", "Review PRs for security vulnerabilities", "Generate unit tests for uncovered functions"
   • Be specific — avoid vague goals like "improve code quality"
2. Inputs the agent needs: What data or context does the agent require to start?
   • Repository information? (repo name, branch, PR number)
   • Execution context? (pipeline execution ID, previous step outputs)
   • Configuration? (coverage threshold, target files, exclusion patterns)
   • Secrets? (API keys, tokens for external services)
3. Outputs the agent produces: What artifacts, reports, or actions should result?
   • Files? (COVERAGE.md, test files, reports)
   • External actions? (create PR, post comments, send notifications)
   • Data? (metrics, logs, analysis results)
4. What the agent works on: What files, services, or systems does it interact with?
   • Specific file paths or patterns? (e.g., pkg/**/*.go, src/services/)
   • External services? (GitHub API, Slack, monitoring systems)
   • Databases or APIs? (read-only access, write operations)
5. Task workflow: Understand the user's workflow for the task — what should happen step-by-step (do 1, then 2, then 3, etc.)
6. Constraints and preferences: Any user preferences for completing the task — limitations, rules, or coding standards the agent should follow
   • Examples: "Use idiomatic Go code", "Do not modify existing tests", "Keep reports under 10000 characters"
7. Definition of done: How do you know the agent succeeded?
   • Specific criteria? ("Coverage increased by X%", "All files have tests")
   • Artifacts created? ("PR created with tests", "COVERAGE.md updated")
   • Exit conditions? ("No security vulnerabilities found", "All checks passed")

Step 2: Recommend Configuration

Based on the requirements gathered in Step 1, recommend specific configurations and verify with the user:

1. Task instructions (task field):
   • Break down the goal into detailed step-by-step instructions
   • Include specific commands, file paths, and expected outcomes
   • Reference inputs using <+inputs.fieldName> syntax
   • Example: "1. Run go test -cover ./... to measure coverage\n2. Identify functions below 80% coverage\n3. Generate tests for uncovered functions\n4. Create PR with new tests"
2. Runtime inputs (inputs section in spec):
   • Only add if user confirms runtime parameters are needed
   • Map each input to what the agent needs (repo, branch, executionId, thresholds, etc.)
   • Example: repo (string), coverageThreshold (string), llmKey (secret)
3. User preferences (rules field):
   • Convert constraints and coding standards into bullet points
   • Be specific and actionable
   • Example: "Use idiomatic Go code", "Do not modify existing tests", "Keep COVERAGE.md under 10000 characters"
4. MCP servers (mcp_servers in spec):
   • Identify which external services the agent needs to interact with
   • GitHub? → Recommend GitHub Copilot MCP: https://api.githubcopilot.com/mcp/
   • Harness platform? → Recommend Harness MCP URL
   • Slack/notifications? → Recommend notification MCP
   • Recommend MCPs based on the user's task or workflows
5. Secrets (via <+secrets.getValue("key")):
   • List all secrets needed for authentication (GitHub PAT, API keys, tokens)
   • Remind user to create these in Harness UI before running the agent
   • Example: bedrock_api_key, github_pat, slack_token
6. Connectors:
   • GitHub/GitLab/Bitbucket connector for repository access
   • Container registry connector for custom images (if needed)
   • Cloud connectors (if agent interacts with AWS/GCP/Azure)
7. Tools (with.allowed_tools):
   • Recommend tools based on what the agent needs to do
   • File operations: Read, Write, Grep, Glob
   • MCP tools: mcp__github__*, mcp__harness__* (use * for all tools from that MCP)
   • Shell: Bash

Present this recommended configuration to the user and iterate until confirmed.

3. Default Configuration

Use these defaults unless user specifies otherwise:

Repository clone:

• Only add this section if the task depends on a repository

clone:
  depth: 1000
  ref:
    type: branch
    name: main
  repo: <repo>
  connector: <connector>

Platform:

platform:
  os: linux
  arch: arm64

Container image:

• The Claude Code plugin is packaged via this image

container:
  connector: account.harnessImage
  image: pkg.harness.io/vrvdt5ius7uwygso8s0bia/harness-agents/claude-code-plugin:main

Environment variables (Bedrock configuration):

env:
  ANTHROPIC_MODEL: arn:aws:bedrock:us-east-1:587817102444:application-inference-profile/7p8sn93lhspw
  AWS_BEARER_TOKEN_BEDROCK: <+secrets.getValue("bedrock_yaml_key")>
  AWS_REGION: us-east-1
  CLAUDE_CODE_USE_BEDROCK: "1"

Max turns:

• Depending on task complexity, adjust this in the range from 100 to 200

max_turns: 150

4. MCP Servers

Based on the MCPs needed (clarified with the user), configure MCP server connections:

How to Connect MCP Servers?

Remote MCP Server:

• If your MCP server is publicly accessible, connect it directly using a Personal Access Token (PAT)
• Create a secret in Harness for the PAT and reference it in the agent YAML

Example — Remote MCP Server:

mcp_servers:
  harness:
    url: https://<your-ngrok-url>/mcp
  github:
    url: https://api.githubcopilot.com/mcp/
    headers:
      Authorization: Bearer <+secrets.getValue("github_pat")>

Local MCP Server:

• Use ngrok to expose your local MCP server so the Harness runner can reach it

Example — Single MCP Server:

mcp_servers:
  harness:
    url: https://<your-ngrok-url>/mcp

Allowing MCP Tools:

• To allow the coding agent to use MCP tools, add mcp__name__* in allowed_tools
• Optionally specify a log_file for debugging MCP interactions

mcp_servers:
  harness:
    url: https://<your-ngrok-url>/mcp
with:
  allowed_tools: Read,Edit,Bash,Glob,Grep,Write,mcp__harness__*
  log_file: .agent/output/mcp-test-log.jsonl

Common MCP servers:

• GitHub/Code/PRs: https://api.githubcopilot.com/mcp/ with Bearer <+secrets.getValue("github_pat")>
• Harness platform: https://<your-harness-mcp-url>/mcp with Bearer token
• Slack/Notifications: https://<your-slack-mcp-url>/mcp with Bearer token
• Grafana: https://<your-grafana-mcp-url>/mcp (dashboards, alerts, annotations) with Bearer token
• Datadog: https://<your-datadog-mcp-url>/mcp with Bearer token
• Jira: https://<your-jira-mcp-url>/mcp with Bearer token
• PagerDuty: https://<your-pagerduty-mcp-url>/mcp with Bearer token

5. MCP Tool Access

• All tools: mcp__harness__*,mcp__github__*,Read,Edit,Bash,Glob,Grep,Write
• Specific tools: mcp__github__create_pr,mcp__github__list_files,Read,Write

6. Runtime Inputs (optional)

Only add inputs section in the agent spec if user confirms it's needed.

Inputs

agent:
  inputs:
    branch:
      type: string
      default: main
    version:
      type: string
      required: true
    deploy_env:
      type: string
      enum: [dev, staging, prod]
    api_key:
      type: secret
      default: account.my_secret

Input types: string, secret, boolean

Reference inputs with: ${{ inputs.branch }}

Common input examples:

• repo (string): Repository identifier
• llmKey (secret): LLM API key
• executionId (string): Pipeline execution ID
• branch (string): Branch to analyze

Expression syntax:

# Input references
<+inputs.variableName>

# Connector token
<+inputs.connectorName.token>

# Step outputs
<+pipeline.stages.STAGE.steps.STEP.output.outputVariables.VAR>

# Environment variables
<+env.HARNESS_ACCOUNT_ID>
<+env.HARNESS_ORG_ID>
<+env.HARNESS_PROJECT_ID>

# Alternative syntax for inputs in env blocks
${{inputs.repo}}

Phase 3: Generate Agent Spec

Using the requirements from Phase 2 and defaults from section 3-6, assemble the complete agent YAML specification (spec field):

1. Start with version: 1 and agent: structure
2. Add clone: section if task depends on repository
3. Create stages: with platform (linux/arm64) and steps
4. For each step, include:
   • Container image and connector
   • Environment variables (Bedrock configuration)
   • task: field with step-by-step instructions
   • rules: field with user preferences
   • mcp_servers: based on external services needed
   • with.allowed_tools: and with.log_file:
   • max_turns: adjusted for task complexity (100-200)
5. Add inputs: section only if confirmed with user (reference with ${{ inputs.fieldName }})

Generate complete, valid YAML ready to be used as the spec value.

Phase 4: Present for Review

Present the complete agent configuration to the user:

• Agent metadata (name, description, uid)
• Full spec YAML
• Required secrets and connectors

Wait for explicit confirmation before creating/updating the agent.

Phase 5: Create or Update Agent

Only after confirmation, use harness_create to create a new agent or harness_update to update an existing one:

Creating a New Agent

Call MCP tool: harness_create
Parameters:
  resource_type: "agent"
  org_id: "<organization>"
  project_id: "<project>"
  body: {
    uid: "<agent_identifier>",
    name: "<Agent Display Name>",
    description: "<Brief description of agent purpose>",
    spec: "<agent YAML spec as a string>",
    wiki: "<optional: markdown documentation>"
  }

Key fields for creation:

• uid (required): Unique identifier. Auto-generated from name if not provided (e.g. "Code Coverage Agent" → "code_coverage_agent")
• name (required): Display name for the agent
• description (optional): Brief description
• spec (required): The full agent YAML specification as a string (includes version: 1, agent:, stages:, etc.)
• wiki (optional): Markdown documentation for the agent

Updating an Existing Agent

Call MCP tool: harness_update
Parameters:
  resource_type: "agent"
  agent_id: "<agent_identifier>"
  org_id: "<organization>"
  project_id: "<project>"
  body: {
    name: "<Updated Display Name>",           # optional
    description: "<Updated description>",     # optional
    spec: "<updated agent YAML spec>",        # optional
    wiki: "<updated markdown docs>"           # optional
  }

Key notes for updates:

• All fields in the body are optional — only provide fields you want to update
• Only custom agents (role='custom') can be updated; system agents cannot be modified
• The spec field replaces the entire agent specification when provided
• Use harness_get first to retrieve the current agent configuration before updating

Agent YAML Extends Pipeline Constructs

CRITICAL UNDERSTANDING: Agent YAML extends the traditional Harness pipeline schema. You can use BOTH agent-specific features AND traditional pipeline steps.

What This Means

1. Agent-specific features (new):
   • agent step type with task, rules, mcp_servers, max_turns
   • Claude Code plugin integration
   • MCP server connections
   • AI-powered autonomous execution
2. Traditional pipeline features (still valid):
   • Shell script steps (run.shell, run.script)
   • Container plugin steps (run.container)
   • Step groups
   • Parallel execution
   • Environment variables
   • Conditional execution
   • All other standard pipeline constructs
   • Only use these when the requirement needs them or user explicitly requests them — don't add unnecessarily
   • For traditional pipeline constructs: Reference the /create-pipeline-v1 skill to look up native actions, templates, and step syntax if it's available

When to Use Traditional Steps

• Shell scripts: For running git commands, file operations, or custom scripts
• Container plugins: For integrating with existing Harness plugins (SonarQube, Snyk, etc.)
• Mixed workflows: Combine agent steps with traditional steps in the same pipeline

Example: Mixed Agent and Shell Steps

version: 1
agent:
  stages:
    - name: Build and Analyze
      id: build_analyze
      platform:
        os: linux
        arch: arm64
      steps:
        # Traditional shell step
        - name: Run Tests
          run:
            shell: bash
            script: |-
              go test -cover ./...
              echo "Tests completed"
        
        # Agent step (AI-powered)
        - id: analyze_coverage
          name: Analyze Coverage with AI
          agent:
            container:
              connector: account.harnessImage
              image: pkg.harness.io/vrvdt5ius7uwygso8s0bia/harness-agents/claude-code-plugin:main
            env:
              ANTHROPIC_MODEL: arn:aws:bedrock:us-east-1:587817102444:application-inference-profile/7p8sn93lhspw
              AWS_BEARER_TOKEN_BEDROCK: <+secrets.getValue("bedrock_yaml_key")>
              AWS_REGION: us-east-1
              CLAUDE_CODE_USE_BEDROCK: "1"
            task: |
              Analyze the test coverage output and generate improvement recommendations.
            max_turns: 100

Schema Validation

All agent specs are validated using harness_schema(resource_type="agent-pipeline") which supports BOTH:

• Agent-specific constructs (use path="Agent" to explore)
• Traditional pipeline constructs (use path="stages", path="steps" to explore)

If a user asks to add shell steps, container steps, or any traditional pipeline feature, it's perfectly valid to include them in the agent spec.

CRITICAL GUIDELINES

These are essential rules you MUST follow when creating/updating agents:

Examples

• "Create an agent that reviews PRs for security issues" - Gather requirements, generate agent spec with GitHub MCP, create via harness_create
• "Update my code coverage agent to use a different model" - Fetch agent with harness_get, modify spec, update via harness_update
• "Build an agent that runs tests and reports results to Slack" - Multi-MCP setup with GitHub and Slack servers
• "Create an autonomous agent to fix failing tests" - Agent with repo clone, shell steps, and Claude Code plugin

Performance Notes

• Use harness_schema(resource_type="agent-pipeline", path="...") with specific path values to avoid loading the full 4k+ line schema into context.
• Always check for existing agents with harness_list before creating new ones to avoid duplicates.
• Set max_turns proportional to task complexity: 100 for simple tasks, 150-200 for complex multi-step workflows.
• Use depth: 1 for branch clones and depth: 1000 for PR clones to balance clone speed and diff history.

Troubleshooting

SCM Provider Detection Failing

1. Verify DRONE_REPO_SCM environment variable is available
2. Check that connector tokens have correct permissions
3. Test with a known SCM provider before adding multi-provider logic

Output Variables Not Available

1. Write outputs using echo "KEY=value" >> $DRONE_OUTPUT
2. Write secret outputs using echo "KEY=value" >> $HARNESS_OUTPUT_SECRET_FILE
3. Reference with full path: <+pipeline.stages.STAGE.steps.STEP.output.outputVariables.KEY>

Best Practices

• Never hardcode secrets -- use type: secret inputs
• Use type: connector for authentication rather than raw tokens
• Include meaningful descriptions on all inputs
• Keep stages focused on single responsibilities
• Always include the SCM detection pattern for multi-provider support
• Store secret outputs with $HARNESS_OUTPUT_SECRET_FILE, not $DRONE_OUTPUT
• Set depth: 1000 for PR clones to ensure full diff history
• Set depth: 1 for branch clones to minimize clone time
• Provide detailed step-by-step instructions in task field
• Increase max_turns in the spec (default: 150) if task is complex.