diff --git a/docs/agents/overview.mdx b/docs/agents/overview.mdx index 8a6d1afcf0a..4774c7c0b26 100644 --- a/docs/agents/overview.mdx +++ b/docs/agents/overview.mdx @@ -28,44 +28,59 @@ These execution modes allow Continue agents to function as cloud agents, running **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" ``` - + 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) + ## Local vs. Cloud Agents @@ -234,16 +249,20 @@ 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 \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index cb02ca3737e..3adba60d6b6 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -273,7 +273,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..444ba7ff740 --- /dev/null +++ b/docs/guides/run-agents-locally.mdx @@ -0,0 +1,373 @@ +--- +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" +--- + + + 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 + - Runs agents with Continue CLI for local development + - Automates agent execution on pull requests via GitHub Actions + - Applies consistent workflows across your team + + +## Prerequisites + +Before starting, ensure you have: + +- [Continue CLI installed](/cli/install) (`npm i -g @continuedev/cli`) +- `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 + + + + ```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 + --- + + You are an agent that helps with [specific task]. + + ## Your Task + + 1. First, do this + 2. Then, do that + 3. Finally, complete this + + ## Guidelines + + - Follow this pattern + - Avoid this anti-pattern + ``` + + + + ```bash + cn -p --agent .continue/agents/my-agent.md + ``` + + For interactive development (TUI mode): + + ```bash + cn --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 | + + + 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: + +````markdown +--- +name: Conventional Title +description: Updates PR title to follow conventional commit format +--- + +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 PR_NUMBER --title "type: description" + ``` + +## Rules + +- If title already follows format, do NOT modify +- Keep description under 72 characters +- 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 + + + 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 + ``` + + 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. **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. + + +## Environment Variables + +When running agents locally, set these environment variables: + +```bash +# 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 +``` + +## 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 with `cn --verbose` or check the Continue logs directory + + + + 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. + + + + The `name` field in frontmatter is displayed to users. Use descriptive filenames for organization: `conventional-title.md`, `security-scan.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 + +