create-agent

# 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 ```yaml clone: depth: 1000 ref: type: branch name: main repo: <repo> connector: <connector> ``` **Platform:** ```yaml platform: os: linux arch: arm64 ``` **Container image:** - The Claude Code plugin is packaged via this image ```yaml container: connector: account.harnessImage image: pkg.harness.io/vrvdt5ius7uwygso8s0bia/harness-agents/claude-code-plugin:main ``` **Environment variables (Bedrock configuration):** ```yaml 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 ```yaml 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: ```yaml 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: ```yaml 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 ```yaml 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 ```yaml 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:** ```yaml # 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 }