From 14276f015b42e39b2896aebd40a5ca2d009a2c8a Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 09:33:46 -0800 Subject: [PATCH 1/7] Add documentation for running agents locally - Update agents overview documentation - Add new guide for running agents locally - Update docs.json configuration Generated with [Continue](https://continue.dev) Co-Authored-By: Continue --- docs/agents/overview.mdx | 43 ++- docs/docs.json | 6 +- docs/guides/run-agents-locally.mdx | 487 +++++++++++++++++++++++++++++ draft_pr.md | 22 ++ 4 files changed, 545 insertions(+), 13 deletions(-) create mode 100644 docs/guides/run-agents-locally.mdx create mode 100644 draft_pr.md diff --git a/docs/agents/overview.mdx b/docs/agents/overview.mdx index 037b91b14f4..ad359159874 100644 --- a/docs/agents/overview.mdx +++ b/docs/agents/overview.mdx @@ -34,44 +34,59 @@ You can run Agents in three main ways: **Interactive web interface** - + Trigger from the Continue Mission Control and review results in real-time. - + ```bash # Navigate to hub.continue.dev/agents # Click "Run Agent" on any agent # Monitor progress and review outputs ``` - + Perfect for: Interactive debugging, reviewing agent outputs, team collaboration **Interactive terminal mode** - + Launch from terminal for live interaction and testing. - + ```bash cn --agent my-org/github-pr-agent # Interactive chat interface opens # Type your specific request # Review and approve actions ``` - + Perfect for: Local development, testing prompts, quick one-off tasks **Automated execution** - + Run one-off or scheduled tasks automatically without interaction. - + ```bash cn -p --agent my-org/snyk-agent "Run weekly security scan" --auto ``` - + Perfect for: CI/CD pipelines, scheduled tasks, webhook integrations + + + **Version-controlled agents in your repository** + + Define agents in `.continue/agents/` and run them with the CLI or GitHub Actions. + + ```bash + # Run a local agent file + cn --agent .continue/agents/my-agent.md + ``` + + Perfect for: Team-shared workflows, CI/CD automation, version-controlled agent definitions + + [Learn more about local agents β†’](/guides/run-agents-locally) + ## Pre-configured Agents @@ -213,15 +228,19 @@ The practice of using cloud agents, which we call Continuous AI, requires foreth Build your first custom agent with prompts, rules, and tools - + + + Set up version-controlled agents in your repository + + Browse pre-built agents for security, analytics, and more - + Learn to run agents from the command line - + Access the web interface to manage agents diff --git a/docs/docs.json b/docs/docs.json index afd202c9568..0f34f38537f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -267,7 +267,11 @@ }, { "group": "CLI Guides", - "pages": ["guides/cli", "guides/doc-writing-agent-cli"] + "pages": [ + "guides/cli", + "guides/run-agents-locally", + "guides/doc-writing-agent-cli" + ] }, { "group": "Continuous AI Guides", diff --git a/docs/guides/run-agents-locally.mdx b/docs/guides/run-agents-locally.mdx new file mode 100644 index 00000000000..1279c789151 --- /dev/null +++ b/docs/guides/run-agents-locally.mdx @@ -0,0 +1,487 @@ +--- +title: "Run Agents Locally with .continue/agents" +sidebarTitle: "Run Agents Locally" +description: "Set up version-controlled agents in your repository and run them with Continue CLI or GitHub Actions" +--- + + + A local agent system that: + - Keeps agent definitions version-controlled alongside your code + - Runs agents with Continue CLI for local development + - Automates agent execution on pull requests via GitHub Actions + - Applies consistent workflows across your team + + +## Why Local Agents? + + + + Agent definitions evolve with your codebase. Track changes, review in PRs, and roll back when needed. + + + + Everyone runs the same agents with the same rules. No configuration drift across machines. + + + + Trigger agents automatically on pull requests, commits, or any GitHub event. + + + +## Prerequisites + +Before starting, ensure you have: + +- [Continue CLI installed](/cli/install) (`npm i -g @continuedev/cli`) +- An LLM API key (e.g., `ANTHROPIC_API_KEY`) +- [GitHub CLI](https://cli.github.com/) if your agents interact with GitHub + +## Quick Setup + + + + ```bash + mkdir -p .continue/agents + ``` + + + + Create a markdown file with YAML frontmatter defining the agent's behavior: + + ```bash + touch .continue/agents/my-agent.md + ``` + + Add content like: + + ```markdown + --- + name: My First Agent + description: Describes what this agent does + tools: built_in + --- + + You are an agent that helps with [specific task]. + + ## Your Task + + 1. First, do this + 2. Then, do that + 3. Finally, complete this + + ## Rules + + - Follow this guideline + - Avoid this pattern + ``` + + + + ```bash + cn --agent .continue/agents/my-agent.md + ``` + + For headless execution (useful for automation): + + ```bash + cn -p --agent .continue/agents/my-agent.md + ``` + + + +## Agent File Format + +Agent files are markdown documents with YAML frontmatter. The frontmatter configures the agent, and the markdown body contains the prompt instructions. + +### Frontmatter Options + +| Field | Required | Description | +|-------|----------|-------------| +| `name` | Yes | Display name for the agent | +| `description` | Yes | Brief description of what the agent does | +| `tools` | No | Tool configuration (`built_in` for standard tools) | + + + The markdown body is the agent's system prompt. Write clear, specific instructions with examples for best results. + + +## Example: Conventional PR Title Agent + +This agent updates pull request titles to follow conventional commit format: + +```markdown +--- +name: Conventional Title +description: Updates PR title to follow conventional commit format +tools: built_in +--- + +You are reviewing a pull request to format its title according to conventional commit standards. + +## Your Task + +1. **Get the current PR title and number:** + ```bash + gh pr view --json number,title -q '{number: .number, title: .title}' + ``` + +2. **Get the PR diff to understand changes:** + ```bash + git diff origin/main...HEAD --name-only + ``` + +3. **Analyze the changes to determine type:** + - `feat`: New feature + - `fix`: Bug fix + - `docs`: Documentation only + - `refactor`: Code refactoring + - `chore`: Build, tooling, configs + +4. **Update the PR title:** + ```bash + gh pr edit --title "type: description" + ``` + +## Rules + +- If title already follows format, do NOT modify +- Keep description under 72 characters +- Use lowercase, no period at end +``` + +## Security Considerations + + + Agents can execute commands and modify files. Review these security practices before deploying to CI/CD. + + +### Limit Agent Permissions + +When running agents in CI/CD, follow the principle of least privilege: + + + + Only grant the permissions your agent needs: + + ```yaml + permissions: + contents: read # Read repository files + pull-requests: write # Comment on PRs + # Avoid: contents: write unless agent needs to push commits + ``` + + + Avoid granting `contents: write` unless your agent specifically needs to push commits. This prevents accidental or malicious code modifications. + + + + + Use `cn` permission flags to restrict what agents can do: + + ```bash + # Only allow specific tools + cn --allow "Read()" --allow "Grep()" --exclude "Bash()" \ + --agent .continue/agents/analysis-only.md + + # Always ask before running commands + cn --ask "Bash(*)" --agent .continue/agents/my-agent.md + ``` + + Learn more in the [CLI documentation](/cli/overview#how-to-set-tool-permissions). + + + + Never commit secrets. Use GitHub Actions secrets or environment variables: + + ```yaml + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + GH_TOKEN: ${{ github.token }} # Scoped to the repo + ``` + + + Never hardcode API keys in agent files or workflows. Always use secrets management. + + + + +### Review Agent Outputs + +Before enabling fully automated agents: + +1. **Test locally first** - Run agents with `cn` to verify behavior +2. **Use `--ask` mode** - Require approval for sensitive operations during testing +3. **Review CI logs** - Check what commands agents execute in your workflows +4. **Start with read-only agents** - Begin with agents that analyze rather than modify + + + For high-risk operations (like pushing commits or modifying infrastructure), consider requiring manual approval steps in your workflow. + + +## GitHub Actions Integration + +Automate agent execution on pull requests with this workflow. + +### Basic Workflow + +Create `.github/workflows/continue-agents.yml`: + +```yaml +name: Continue Agents + +on: + pull_request: + types: [opened, reopened, synchronize] + branches: + - main + +permissions: + contents: write + checks: write + pull-requests: write + +jobs: + discover: + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.discover.outputs.matrix }} + has-agents: ${{ steps.discover.outputs.has_agents }} + steps: + - uses: actions/checkout@v4 + + - name: Discover agents + id: discover + run: | + AGENTS_DIR=".continue/agents" + if [ -d "$AGENTS_DIR" ]; then + FILES=$(find "$AGENTS_DIR" -name "*.md" -type f 2>/dev/null | jq -R . | jq -sc .) + COUNT=$(echo "$FILES" | jq 'length') + HAS_AGENTS=$([[ $COUNT -gt 0 ]] && echo "true" || echo "false") + else + FILES="[]" + HAS_AGENTS="false" + fi + + echo "matrix=$FILES" >> $GITHUB_OUTPUT + echo "has_agents=$HAS_AGENTS" >> $GITHUB_OUTPUT + + run-agent: + needs: discover + if: needs.discover.outputs.has-agents == 'true' + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + agent: ${{ fromJson(needs.discover.outputs.matrix) }} + steps: + - uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + + - name: Install Continue CLI + run: npm i -g @continuedev/cli + + - name: Extract agent name + id: agent-name + run: | + AGENT_FILE="${{ matrix.agent }}" + AGENT_NAME=$(basename "$AGENT_FILE" .md) + echo "name=$AGENT_NAME" >> $GITHUB_OUTPUT + + - name: Create Check Run + id: check + uses: actions/github-script@v7 + env: + AGENT_NAME: ${{ steps.agent-name.outputs.name }} + with: + script: | + const { data: check } = await github.rest.checks.create({ + owner: context.repo.owner, + repo: context.repo.repo, + name: `Continue: ${process.env.AGENT_NAME}`, + head_sha: context.sha, + status: 'in_progress', + started_at: new Date().toISOString(), + }); + core.setOutput('id', check.id); + + - name: Run agent + id: run + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + GH_TOKEN: ${{ github.token }} + run: | + AGENT_FILE="${{ matrix.agent }}" + + if OUTPUT=$(cn -p --agent "$AGENT_FILE" 2>&1); then + echo "success=true" >> $GITHUB_OUTPUT + echo "output<> $GITHUB_OUTPUT + echo "$OUTPUT" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + else + echo "success=false" >> $GITHUB_OUTPUT + echo "error<> $GITHUB_OUTPUT + echo "$OUTPUT" >> $GITHUB_OUTPUT + echo "EOF" >> $GITHUB_OUTPUT + fi + + - name: Update Check Run + if: always() + uses: actions/github-script@v7 + env: + AGENT_OUTPUT: ${{ steps.run.outputs.output }} + AGENT_ERROR: ${{ steps.run.outputs.error }} + AGENT_SUCCESS: ${{ steps.run.outputs.success }} + CHECK_RUN_ID: ${{ steps.check.outputs.id }} + with: + script: | + const success = process.env.AGENT_SUCCESS === 'true'; + const output = process.env.AGENT_OUTPUT || ''; + const error = process.env.AGENT_ERROR || ''; + + await github.rest.checks.update({ + owner: context.repo.owner, + repo: context.repo.repo, + check_run_id: parseInt(process.env.CHECK_RUN_ID, 10), + status: 'completed', + conclusion: success ? 'success' : 'failure', + completed_at: new Date().toISOString(), + output: { + title: success ? 'Agent completed' : 'Agent failed', + summary: success + ? `Agent completed.\n\n\`\`\`\n${output.slice(0, 60000)}\n\`\`\`` + : `Agent failed.\n\n\`\`\`\n${error.slice(0, 60000)}\n\`\`\``, + }, + }); + + - name: Fail if agent failed + if: steps.run.outputs.success != 'true' + run: exit 1 +``` + +### Required Secrets + +Add these secrets to your repository under **Settings > Secrets and variables > Actions**: + +| Secret | Description | +|--------|-------------| +| `ANTHROPIC_API_KEY` | Your Anthropic API key for Claude | + + + The `GH_TOKEN` is automatically provided by GitHub Actions via `${{ github.token }}`. This token is scoped to the repository and expires after the workflow completes. + + +## Environment Variables + +When running agents locally that interact with GitHub, set the `GH_TOKEN`: + +```bash +# Use your GitHub CLI token +export GH_TOKEN=$(gh auth token) +cn --agent .continue/agents/my-agent.md +``` + +## Directory Structure + +A typical setup looks like: + +``` +your-repo/ +β”œβ”€β”€ .continue/ +β”‚ └── agents/ +β”‚ β”œβ”€β”€ conventional-title.md +β”‚ β”œβ”€β”€ deploy-checklist.md +β”‚ └── security-scan.md +β”œβ”€β”€ .github/ +β”‚ └── workflows/ +β”‚ └── continue-agents.yml +└── ... +``` + +## Troubleshooting + + + + Ensure the path is correct and the file exists: + + ```bash + ls -la .continue/agents/ + ``` + + The path must be relative to your repository root. + + + + If agents using `gh` fail, verify authentication: + + ```bash + # Check auth status + gh auth status + + # Set token for local testing + export GH_TOKEN=$(gh auth token) + ``` + + In GitHub Actions, ensure `GH_TOKEN: ${{ github.token }}` is set in the environment. + + + + - Simplify the prompt and add more specific instructions + - Check if the agent has access to required tools + - Enable verbose logging: `cn --verbose --agent .continue/agents/my-agent.md` + - Review logs at `~/.continue/logs/cn.log` + + + + Verify your agents are in the correct directory: + + ```bash + find .continue/agents -name "*.md" -type f + ``` + + The workflow looks for `.md` files in `.continue/agents/`. + + + +## Best Practices + + + + Begin with read-only agents that analyze code before adding agents that make changes. + + + + Always run `cn --agent` locally before enabling CI automation. + + + + Name agent files clearly: `conventional-title.md`, `security-scan.md`, `deploy-checklist.md`. + + + + Each agent should do one thing well. Combine multiple agents for complex workflows. + + + +## Next Steps + + + + Learn about agent components and capabilities + + + + Full Continue CLI documentation + + + + Add external tools to your agents + + + + Configure agent behavior with rules + + diff --git a/draft_pr.md b/draft_pr.md new file mode 100644 index 00000000000..64fda5d7f09 --- /dev/null +++ b/draft_pr.md @@ -0,0 +1,22 @@ +## Description + +[TODO: Add a brief description of what changed in this PR] + +## AI Code Review + +- **Team members only**: AI review runs automatically when PR is opened or marked ready for review +- Team members can also trigger a review by commenting `@continue-review` + +## Checklist + +- [ ] I've read the [contributing guide](https://github.com/continuedev/continue/blob/main/CONTRIBUTING.md) +- [ ] The relevant docs, if any, have been updated or created +- [ ] The relevant tests, if any, have been updated or created + +## Screen recording or screenshot + +[TODO: Add screen recording or screenshot if applicable - see [this PR](https://github.com/continuedev/continue/pull/6455) as a good example] + +## Tests + +[TODO: Describe what tests were added or updated to ensure the changes work as expected] From d329fd43d0a3a56d5f978e19ed1fdae555ffb148 Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 11:39:27 -0800 Subject: [PATCH 2/7] Fix: Simplify title for run-agents-locally guide Removed redundant text from title to potentially fix Mintlify build issue Generated with [Continue](https://continue.dev) Co-Authored-By: Continue --- docs/guides/run-agents-locally.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/run-agents-locally.mdx b/docs/guides/run-agents-locally.mdx index 1279c789151..d68cf0503c1 100644 --- a/docs/guides/run-agents-locally.mdx +++ b/docs/guides/run-agents-locally.mdx @@ -1,5 +1,5 @@ --- -title: "Run Agents Locally with .continue/agents" +title: "Run Agents Locally" sidebarTitle: "Run Agents Locally" description: "Set up version-controlled agents in your repository and run them with Continue CLI or GitHub Actions" --- From 6e69981141326e80899e4d03da1949a0e91cfb69 Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 11:45:39 -0800 Subject: [PATCH 3/7] Fix broken internal anchor link in agents intro Fixed incorrect path from /hub/agents/overview to /agents/overview for the pre-configured-agents anchor link Generated with [Continue](https://continue.dev) Co-Authored-By: Continue --- docs/agents/intro.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/agents/intro.mdx b/docs/agents/intro.mdx index 10dcb9f5586..033c8cb363a 100644 --- a/docs/agents/intro.mdx +++ b/docs/agents/intro.mdx @@ -54,7 +54,7 @@ Use Mission Control to kick off agents for: - **New to agents?** Check out our [pre-configured agents](/hub/agents/overview#pre-configured-agents) to test out a workflow immediately. + **New to agents?** Check out our [pre-configured agents](/agents/overview#pre-configured-agents) to test out a workflow immediately. ## Try an Agent First: Your 60-Second Challenge From 138745e6807842cc29c07ca0e7c3da9e6edf559e Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 14:27:05 -0800 Subject: [PATCH 4/7] Clean up temporary files - Remove draft_pr.md (no longer needed) - Add discussion_response.md Generated with [Continue](https://continue.dev) Co-Authored-By: Continue --- draft_pr.md | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 draft_pr.md diff --git a/draft_pr.md b/draft_pr.md deleted file mode 100644 index 64fda5d7f09..00000000000 --- a/draft_pr.md +++ /dev/null @@ -1,22 +0,0 @@ -## Description - -[TODO: Add a brief description of what changed in this PR] - -## AI Code Review - -- **Team members only**: AI review runs automatically when PR is opened or marked ready for review -- Team members can also trigger a review by commenting `@continue-review` - -## Checklist - -- [ ] I've read the [contributing guide](https://github.com/continuedev/continue/blob/main/CONTRIBUTING.md) -- [ ] The relevant docs, if any, have been updated or created -- [ ] The relevant tests, if any, have been updated or created - -## Screen recording or screenshot - -[TODO: Add screen recording or screenshot if applicable - see [this PR](https://github.com/continuedev/continue/pull/6455) as a good example] - -## Tests - -[TODO: Describe what tests were added or updated to ensure the changes work as expected] From 7074a50e4a39f5b29927c8c90a4fb52769b64dff Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 16:35:45 -0800 Subject: [PATCH 5/7] fix: resolve MDX parsing error in run-agents-locally guide Use 4 backticks for outer code fence to prevent nested code blocks from breaking MDX parser. Co-Authored-By: Claude Opus 4.5 --- docs/guides/run-agents-locally.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/run-agents-locally.mdx b/docs/guides/run-agents-locally.mdx index d68cf0503c1..965c3191b57 100644 --- a/docs/guides/run-agents-locally.mdx +++ b/docs/guides/run-agents-locally.mdx @@ -109,7 +109,7 @@ Agent files are markdown documents with YAML frontmatter. The frontmatter config This agent updates pull request titles to follow conventional commit format: -```markdown +````markdown --- name: Conventional Title description: Updates PR title to follow conventional commit format @@ -139,7 +139,7 @@ You are reviewing a pull request to format its title according to conventional c 4. **Update the PR title:** ```bash - gh pr edit --title "type: description" + gh pr edit PR_NUMBER --title "type: description" ``` ## Rules @@ -147,7 +147,7 @@ You are reviewing a pull request to format its title according to conventional c - If title already follows format, do NOT modify - Keep description under 72 characters - Use lowercase, no period at end -``` +```` ## Security Considerations From 1ec2d35f08e062792e3c6a96623139435a9fe91e Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Tue, 13 Jan 2026 16:54:14 -0800 Subject: [PATCH 6/7] docs: recommend reusable workflow for GitHub Actions Replace inline workflow with Continue's reusable workflow which handles agent discovery, parallel execution, and check reporting. GH_TOKEN is now automatically provided for agents using the gh CLI. Co-Authored-By: Claude Opus 4.5 --- docs/guides/run-agents-locally.mdx | 157 +++++------------------------ 1 file changed, 28 insertions(+), 129 deletions(-) diff --git a/docs/guides/run-agents-locally.mdx b/docs/guides/run-agents-locally.mdx index 965c3191b57..472eebb471c 100644 --- a/docs/guides/run-agents-locally.mdx +++ b/docs/guides/run-agents-locally.mdx @@ -220,14 +220,14 @@ Before enabling fully automated agents: ## GitHub Actions Integration -Automate agent execution on pull requests with this workflow. +Continue provides a [reusable workflow](https://github.com/continuedev/continue/blob/main/.github/workflows/continue-agents.yml) that handles agent discovery, parallel execution, and GitHub Check reporting. -### Basic Workflow +### Using the Reusable Workflow (Recommended) -Create `.github/workflows/continue-agents.yml`: +Create `.github/workflows/run-agents.yml`: ```yaml -name: Continue Agents +name: Run Agents on: pull_request: @@ -235,143 +235,42 @@ on: branches: - main -permissions: - contents: write - checks: write - pull-requests: write +jobs: + agents: + uses: continuedev/continue/.github/workflows/continue-agents.yml@main + secrets: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +The reusable workflow automatically: +- Discovers all `.md` files in `.continue/agents/` +- Runs each agent in parallel +- Creates GitHub Check runs for each agent +- Provides `GH_TOKEN` for agents using the `gh` CLI +- Writes job summaries with agent output +### Configuration Options + +```yaml jobs: - discover: - runs-on: ubuntu-latest - outputs: - matrix: ${{ steps.discover.outputs.matrix }} - has-agents: ${{ steps.discover.outputs.has_agents }} - steps: - - uses: actions/checkout@v4 - - - name: Discover agents - id: discover - run: | - AGENTS_DIR=".continue/agents" - if [ -d "$AGENTS_DIR" ]; then - FILES=$(find "$AGENTS_DIR" -name "*.md" -type f 2>/dev/null | jq -R . | jq -sc .) - COUNT=$(echo "$FILES" | jq 'length') - HAS_AGENTS=$([[ $COUNT -gt 0 ]] && echo "true" || echo "false") - else - FILES="[]" - HAS_AGENTS="false" - fi - - echo "matrix=$FILES" >> $GITHUB_OUTPUT - echo "has_agents=$HAS_AGENTS" >> $GITHUB_OUTPUT - - run-agent: - needs: discover - if: needs.discover.outputs.has-agents == 'true' - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - agent: ${{ fromJson(needs.discover.outputs.matrix) }} - steps: - - uses: actions/checkout@v4 - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - - - name: Install Continue CLI - run: npm i -g @continuedev/cli - - - name: Extract agent name - id: agent-name - run: | - AGENT_FILE="${{ matrix.agent }}" - AGENT_NAME=$(basename "$AGENT_FILE" .md) - echo "name=$AGENT_NAME" >> $GITHUB_OUTPUT - - - name: Create Check Run - id: check - uses: actions/github-script@v7 - env: - AGENT_NAME: ${{ steps.agent-name.outputs.name }} - with: - script: | - const { data: check } = await github.rest.checks.create({ - owner: context.repo.owner, - repo: context.repo.repo, - name: `Continue: ${process.env.AGENT_NAME}`, - head_sha: context.sha, - status: 'in_progress', - started_at: new Date().toISOString(), - }); - core.setOutput('id', check.id); - - - name: Run agent - id: run - env: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} - GH_TOKEN: ${{ github.token }} - run: | - AGENT_FILE="${{ matrix.agent }}" - - if OUTPUT=$(cn -p --agent "$AGENT_FILE" 2>&1); then - echo "success=true" >> $GITHUB_OUTPUT - echo "output<> $GITHUB_OUTPUT - echo "$OUTPUT" >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT - else - echo "success=false" >> $GITHUB_OUTPUT - echo "error<> $GITHUB_OUTPUT - echo "$OUTPUT" >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT - fi - - - name: Update Check Run - if: always() - uses: actions/github-script@v7 - env: - AGENT_OUTPUT: ${{ steps.run.outputs.output }} - AGENT_ERROR: ${{ steps.run.outputs.error }} - AGENT_SUCCESS: ${{ steps.run.outputs.success }} - CHECK_RUN_ID: ${{ steps.check.outputs.id }} - with: - script: | - const success = process.env.AGENT_SUCCESS === 'true'; - const output = process.env.AGENT_OUTPUT || ''; - const error = process.env.AGENT_ERROR || ''; - - await github.rest.checks.update({ - owner: context.repo.owner, - repo: context.repo.repo, - check_run_id: parseInt(process.env.CHECK_RUN_ID, 10), - status: 'completed', - conclusion: success ? 'success' : 'failure', - completed_at: new Date().toISOString(), - output: { - title: success ? 'Agent completed' : 'Agent failed', - summary: success - ? `Agent completed.\n\n\`\`\`\n${output.slice(0, 60000)}\n\`\`\`` - : `Agent failed.\n\n\`\`\`\n${error.slice(0, 60000)}\n\`\`\``, - }, - }); - - - name: Fail if agent failed - if: steps.run.outputs.success != 'true' - run: exit 1 + agents: + uses: continuedev/continue/.github/workflows/continue-agents.yml@main + with: + agents-path: '.continue/agents' # Custom agents directory (optional) + secrets: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} ``` ### Required Secrets -Add these secrets to your repository under **Settings > Secrets and variables > Actions**: +Add this secret to your repository under **Settings > Secrets and variables > Actions**: | Secret | Description | |--------|-------------| | `ANTHROPIC_API_KEY` | Your Anthropic API key for Claude | - The `GH_TOKEN` is automatically provided by GitHub Actions via `${{ github.token }}`. This token is scoped to the repository and expires after the workflow completes. + The reusable workflow automatically provides `GH_TOKEN` via `${{ github.token }}`, so agents using the `gh` CLI work out of the box. ## Environment Variables From 9a701e28f1bc2831fe4d187d2bc89634851c4481 Mon Sep 17 00:00:00 2001 From: Brian 'bdougie' Douglas Date: Thu, 15 Jan 2026 09:45:05 -0800 Subject: [PATCH 7/7] docs: address review feedback on run-agents-locally guide - Add clarifying note distinguishing local vs cloud agents - Remove redundant CardGroup section - Fix API key naming to ANTHROPIC_API_KEY - Clarify GitHub CLI pre-installed on runners - Remove unnecessary tools: built_in from examples - Rename "Rules" to "Guidelines" to avoid frontmatter confusion - Flip headless/TUI order (headless is typical) - Simplify frontmatter table, link to reference - Move GitHub Actions section before Security - Remove --ask from CI guidance (requires user intervention) - Fix mac-only log path - Add ANTHROPIC_API_KEY to local env vars section - Clarify name field vs filename in best practices Co-Authored-By: Claude Opus 4.5 --- docs/guides/run-agents-locally.mdx | 171 +++++++++++++---------------- 1 file changed, 79 insertions(+), 92 deletions(-) diff --git a/docs/guides/run-agents-locally.mdx b/docs/guides/run-agents-locally.mdx index 472eebb471c..444ba7ff740 100644 --- a/docs/guides/run-agents-locally.mdx +++ b/docs/guides/run-agents-locally.mdx @@ -4,6 +4,10 @@ sidebarTitle: "Run Agents Locally" description: "Set up version-controlled agents in your repository and run them with Continue CLI or GitHub Actions" --- + + Looking for the easiest way to create and manage agents? [Cloud Agents in Mission Control](/agents/overview#pre-configured-agents) are recommended for most teams. This guide covers **local agents**β€”agent files stored in your repositoryβ€”for open source users or teams needing version-controlled definitions. + + A local agent system that: - Keeps agent definitions version-controlled alongside your code @@ -12,29 +16,13 @@ description: "Set up version-controlled agents in your repository and run them w - Applies consistent workflows across your team -## Why Local Agents? - - - - Agent definitions evolve with your codebase. Track changes, review in PRs, and roll back when needed. - - - - Everyone runs the same agents with the same rules. No configuration drift across machines. - - - - Trigger agents automatically on pull requests, commits, or any GitHub event. - - - ## Prerequisites Before starting, ensure you have: - [Continue CLI installed](/cli/install) (`npm i -g @continuedev/cli`) -- An LLM API key (e.g., `ANTHROPIC_API_KEY`) -- [GitHub CLI](https://cli.github.com/) if your agents interact with GitHub +- `ANTHROPIC_API_KEY` environment variable set +- [GitHub CLI](https://cli.github.com/) installed locally if your agents interact with GitHub (pre-installed on GitHub-hosted runners) ## Quick Setup @@ -58,7 +46,6 @@ Before starting, ensure you have: --- name: My First Agent description: Describes what this agent does - tools: built_in --- You are an agent that helps with [specific task]. @@ -69,22 +56,22 @@ Before starting, ensure you have: 2. Then, do that 3. Finally, complete this - ## Rules + ## Guidelines - - Follow this guideline - - Avoid this pattern + - Follow this pattern + - Avoid this anti-pattern ``` ```bash - cn --agent .continue/agents/my-agent.md + cn -p --agent .continue/agents/my-agent.md ``` - For headless execution (useful for automation): + For interactive development (TUI mode): ```bash - cn -p --agent .continue/agents/my-agent.md + cn --agent .continue/agents/my-agent.md ``` @@ -99,12 +86,13 @@ Agent files are markdown documents with YAML frontmatter. The frontmatter config |-------|----------|-------------| | `name` | Yes | Display name for the agent | | `description` | Yes | Brief description of what the agent does | -| `tools` | No | Tool configuration (`built_in` for standard tools) | The markdown body is the agent's system prompt. Write clear, specific instructions with examples for best results. +For additional options like `rules`, `model`, and MCP tool configuration, see the [Agent Configuration Reference](/agents/agent-file-reference). + ## Example: Conventional PR Title Agent This agent updates pull request titles to follow conventional commit format: @@ -113,7 +101,6 @@ This agent updates pull request titles to follow conventional commit format: --- name: Conventional Title description: Updates PR title to follow conventional commit format -tools: built_in --- You are reviewing a pull request to format its title according to conventional commit standards. @@ -149,6 +136,61 @@ You are reviewing a pull request to format its title according to conventional c - Use lowercase, no period at end ```` +## GitHub Actions Integration + +Continue provides a [reusable workflow](https://github.com/continuedev/continue/blob/main/.github/workflows/continue-agents.yml) that handles agent discovery, parallel execution, and GitHub Check reporting. + +### Using the Reusable Workflow + +Create `.github/workflows/run-agents.yml`: + +```yaml +name: Run Agents + +on: + pull_request: + types: [opened, reopened, synchronize] + branches: + - main + +jobs: + agents: + uses: continuedev/continue/.github/workflows/continue-agents.yml@main + secrets: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +The reusable workflow automatically: +- Discovers all `.md` files in `.continue/agents/` +- Runs each agent in parallel +- Creates GitHub Check runs for each agent +- Provides `GH_TOKEN` for agents using the `gh` CLI +- Writes job summaries with agent output + +### Configuration Options + +```yaml +jobs: + agents: + uses: continuedev/continue/.github/workflows/continue-agents.yml@main + with: + agents-path: '.continue/agents' # Custom agents directory (optional) + secrets: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +### Required Secrets + +Add this secret to your repository under **Settings > Secrets and variables > Actions**: + +| Secret | Description | +|--------|-------------| +| `ANTHROPIC_API_KEY` | Your Anthropic API key for Claude | + + + The reusable workflow automatically provides `GH_TOKEN` via `${{ github.token }}`, so agents using the `gh` CLI work out of the box. + + ## Security Considerations @@ -182,9 +224,6 @@ When running agents in CI/CD, follow the principle of least privilege: # Only allow specific tools cn --allow "Read()" --allow "Grep()" --exclude "Bash()" \ --agent .continue/agents/analysis-only.md - - # Always ask before running commands - cn --ask "Bash(*)" --agent .continue/agents/my-agent.md ``` Learn more in the [CLI documentation](/cli/overview#how-to-set-tool-permissions). @@ -210,76 +249,24 @@ When running agents in CI/CD, follow the principle of least privilege: Before enabling fully automated agents: 1. **Test locally first** - Run agents with `cn` to verify behavior -2. **Use `--ask` mode** - Require approval for sensitive operations during testing -3. **Review CI logs** - Check what commands agents execute in your workflows -4. **Start with read-only agents** - Begin with agents that analyze rather than modify +2. **Review CI logs** - Check what commands agents execute in your workflows +3. **Start with read-only agents** - Begin with agents that analyze rather than modify For high-risk operations (like pushing commits or modifying infrastructure), consider requiring manual approval steps in your workflow. -## GitHub Actions Integration - -Continue provides a [reusable workflow](https://github.com/continuedev/continue/blob/main/.github/workflows/continue-agents.yml) that handles agent discovery, parallel execution, and GitHub Check reporting. - -### Using the Reusable Workflow (Recommended) - -Create `.github/workflows/run-agents.yml`: - -```yaml -name: Run Agents - -on: - pull_request: - types: [opened, reopened, synchronize] - branches: - - main - -jobs: - agents: - uses: continuedev/continue/.github/workflows/continue-agents.yml@main - secrets: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} -``` - -The reusable workflow automatically: -- Discovers all `.md` files in `.continue/agents/` -- Runs each agent in parallel -- Creates GitHub Check runs for each agent -- Provides `GH_TOKEN` for agents using the `gh` CLI -- Writes job summaries with agent output - -### Configuration Options - -```yaml -jobs: - agents: - uses: continuedev/continue/.github/workflows/continue-agents.yml@main - with: - agents-path: '.continue/agents' # Custom agents directory (optional) - secrets: - ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} -``` - -### Required Secrets - -Add this secret to your repository under **Settings > Secrets and variables > Actions**: - -| Secret | Description | -|--------|-------------| -| `ANTHROPIC_API_KEY` | Your Anthropic API key for Claude | - - - The reusable workflow automatically provides `GH_TOKEN` via `${{ github.token }}`, so agents using the `gh` CLI work out of the box. - - ## Environment Variables -When running agents locally that interact with GitHub, set the `GH_TOKEN`: +When running agents locally, set these environment variables: ```bash -# Use your GitHub CLI token +# Required: Your Anthropic API key +export ANTHROPIC_API_KEY=your-api-key + +# Optional: GitHub token if your agents use the gh CLI export GH_TOKEN=$(gh auth token) + cn --agent .continue/agents/my-agent.md ``` @@ -331,7 +318,7 @@ your-repo/ - Simplify the prompt and add more specific instructions - Check if the agent has access to required tools - Enable verbose logging: `cn --verbose --agent .continue/agents/my-agent.md` - - Review logs at `~/.continue/logs/cn.log` + - Review logs with `cn --verbose` or check the Continue logs directory @@ -357,7 +344,7 @@ your-repo/ - Name agent files clearly: `conventional-title.md`, `security-scan.md`, `deploy-checklist.md`. + The `name` field in frontmatter is displayed to users. Use descriptive filenames for organization: `conventional-title.md`, `security-scan.md`.