create-agent

Custom AI Agents

Create and update Harness AI agent instances - standalone templates used as building blocks in pipelines for automated code, 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

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/UUID: Always generate this from the name and pass it explicitly to create/update APIs. Do not rely on the create API fallback.
  • Generation rule : prefix with ca_, then lowercase the name, convert spaces and hyphens (-) to _, replace any remaining non-alphanumeric runs with _, collapse duplicate _, and trim leading/trailing _ from the slug portion (e.g. "Code Coverage Agent" → ca_code_coverage_agent, "PR Reviewer" → ca_pr_reviewer)
  • If the generated UID conflicts with an existing agent, ask the user whether to reuse/update that agent or append a short suffix