PR-Agent

https://docs.pr-agent.ai
Admin
PR-Agent is an open-source, AI-powered code review agent that automates pull request analysis with...
Tokens:113,395
Snippets:867
Trust Score:2.4
Update:6 days ago
Show doc for...
Tokens:
Raw
### Example configuration for add_docs

Source: https://docs.pr-agent.ai/tools/add_docs

Configuration example for customizing the documentation style. Add this to your configuration file under [pr_add_docs].

```ini
[pr_add_docs]  

docs_style = "Google Style with Args, Returns, Attributes...etc"  

extra_instructions = "Focus on documenting public methods and include usage examples"  

```

--------------------------------

### Example extra instructions for the review tool

Source: https://docs.pr-agent.ai/tools/review

Example of configuring extra instructions for the review tool to guide the model's feedback. Use triple quotes for multi-line instructions and bullet points for readability.

```text
[pr_reviewer]  
extra_instructions="""\  
In the code feedback section, emphasize the following:  
- Does the code logic cover relevant edge cases?  
- Is the code logic clear and easy to understand?  
- Is the code logic efficient?  
...  
"""  
```

--------------------------------

### Basic Setup (OpenAI Default) GitHub Actions workflow

Source: https://docs.pr-agent.ai/installation/github

Minimal workflow to get started with PR Agent using the default OpenAI models. Requires an OPENAI_KEY secret and a GITHUB_TOKEN secret. Triggers on pull_request events (opened, reopened, ready_for_review) and issue_comment events.

```yaml
name: PR Agent  

on:  

  pull_request:  

    types: [opened, reopened, ready_for_review]  

  issue_comment:  

jobs:  

  pr_agent_job:  

    if: ${{ github.event.sender.type != 'Bot' }}  

    runs-on: ubuntu-latest  

    permissions:  

      contents: read  

      issues: write  

      pull-requests: write  

    steps:  

      - name: PR Agent action step  

        uses: the-pr-agent/pr-agent@main  

        env:  

          OPENAI_KEY: ${{ secrets.OPENAI_KEY }}  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  


```

--------------------------------

### Install similar-issue extra dependencies

Source: https://docs.pr-agent.ai/tools/similar_issues

Run this command to install the vector databases and datasets required by the similar issue tool. A bare `uv sync` does not include these extras.

```bash
uv sync --group similar-issue
```

--------------------------------

### Best practices file example: before adding null check

Source: https://docs.pr-agent.ai/tools/improve

Example code before adding defensive null/empty checks before accessing object properties.

```python
def get_pr_code(pr_data):  

    if "changed_code" in pr_data:  

        return pr_data.get("changed_code", "")  

    return ""  

```

--------------------------------

### Best practices file example: after adding null check

Source: https://docs.pr-agent.ai/tools/improve

Example code after adding defensive null/empty checks before accessing object properties.

```python
def get_pr_code(pr_data):  

    if pr_data is None:  

        return ""  

    if "changed_code" in pr_data:  

        return pr_data.get("changed_code", "")  

    return ""  

```

--------------------------------

### Custom labels configuration file example

Source: https://docs.pr-agent.ai/tools/describe

Example configuration file for enabling custom labels and defining label descriptions. The [config] section sets enable_custom_labels=true, and each [custom_labels."name"] section provides a conditional description for when the label should be suggested.

```ini
[config]  

enable_custom_labels=true  

  

  

[custom_labels."sql_changes"]  

description = "Use when a PR contains changes to SQL queries"  

[custom_labels."test"]  

description = "use when a PR primarily contains new tests"  

...  



```

--------------------------------

### Install dependencies with uv sync

Source: https://docs.pr-agent.ai/installation/locally

Installs project dependencies using uv, creating a .venv from uv.lock. Requires Rust to be installed and in PATH if a Rust-related error occurs.

```bash
uv sync
```

--------------------------------

### Configure ask tool in configuration file

Source: https://docs.pr-agent.ai/tools/ask

Example configuration for the `ask` tool. Sets a custom heading and extra instructions. The heading renders as `### **Architecture Question** ❓`.

```ini
[pr_questions]  
ask_heading = "Architecture Question"  
extra_instructions = "Do not answer questions that ask to rate PR quality on a scale of 1 to 10."  
```

--------------------------------

### Command line options for add_docs

Source: https://docs.pr-agent.ai/tools/add_docs

Pass configuration options directly in the command. Example shows setting docs_style to Numpy Style.

```markdown
/add_docs --pr_add_docs.docs_style="Numpy Style"  

```

--------------------------------

### Example run details section output

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Example of the collapsible run details section appended to PR comments on GFM-supporting providers. Shows model, tokens, time cost, AI calls, and estimated API cost breakdown.

```markdown
⚙️ Agent run details  

- Model: provider/fallback-model (fallback)  

- Tokens: 12,340 in / 1,205 out / 13,545 total  

- Time cost: 8.2s  

- AI calls: 1  

- Estimated API cost: $0.08 USD  

  - anthropic/claude-opus-5: $0.07 USD  

  - anthropic/claude-sonnet-5: $0.01 USD  
```

--------------------------------

### BitBucket App: Repository-level .pr_agent.toml example

Source: https://docs.pr-agent.ai/usage-guide/automations_and_usage

Upload a .pr_agent.toml file to the root of the repo's default branch to customize parameters that support repository-level overrides. This example sets extra_instructions for the pr_reviewer tool, which will be used each time /review is invoked. Upload the file before creating a PR for the configuration to take effect.

```toml
[pr_reviewer]  

extra_instructions = "Answer in japanese"  


```

--------------------------------

### Best practices file example: before adding error handling

Source: https://docs.pr-agent.ai/tools/improve

Example code before adding proper error handling with try-except blocks around external function calls.

```python
# Some code that might raise an exception  

return process_pr_data(data)  

```

--------------------------------

### Install pr-agent with GitHub extra

Source: https://docs.pr-agent.ai/installation/locally

Installs the pr-agent package with the GitHub provider SDK. Other provider extras include gitlab, bitbucket, azure, codecommit, and gitea; google adds Vertex AI, mosaico adds the Mosaico server, and pr-agent[all] installs every integration.

```bash
pip install "pr-agent[github]"
```

--------------------------------

### Best practices file example: after adding error handling

Source: https://docs.pr-agent.ai/tools/improve

Example code after adding proper error handling with try-except blocks around external function calls.

```python
try:  

    # Some code that might raise an exception  

    return process_pr_data(data)  

except Exception as e:  

    logger.exception("Failed to process request", extra={"error": e})  

```

--------------------------------

### .pr_agent.toml configuration file

Source: https://docs.pr-agent.ai/installation/github

Example .pr_agent.toml file that sets the model, fallback models, and tool-specific settings. Place it in the repository root.

```toml
[config]  
model = "gemini/gemini-3.8-flash"  
fallback_models = ["anthropic/claude-opus-5"]  

[pr_reviewer]  
extra_instructions = "Focus on security issues and code quality."  

[pr_code_suggestions]  
num_code_suggestions_per_chunk = 6  
suggestions_score_threshold = 7  

```

--------------------------------

### Example record JSON

Source: https://docs.pr-agent.ai/usage-guide/push_outputs

Shows the structure of a record emitted for each finished tool run. Fields include type, timestamp, payload, and markdown.

```json
{
  "type": "review",
  "timestamp": "2026-09-08T14:03:21+00:00",
  "payload": {},
  "markdown": "# PR Reviewer Guide ..."
}
```

--------------------------------

### Use extra_instructions with /update_changelog

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Shows how to pass free-text extra instructions to a PR-Agent tool using the extra_instructions parameter. The example uses /update_changelog to instruct the model to also update the version.

```bash
/update_changelog --pr_update_changelog.extra_instructions="Make sure to update also the version ..."  
```

--------------------------------

### SKILL.md example with YAML frontmatter

Source: https://docs.pr-agent.ai/core-abilities/agent_skills

A skill is a directory containing a SKILL.md file with YAML frontmatter (name + description) followed by a markdown body. The description is used as the signal for when the skill applies.

```markdown
---  

name: terraform-standards  

description: Use when reviewing Terraform code — checks state safety and risky deletions.  

---  

  

# Terraform Review Guidance  

  

- Flag any resource deletion that is not explicitly called out in the PR description.  

- Require `prevent_destroy` on stateful resources.  

- ...  

```

--------------------------------

### Define Environment Variables in .env File

Source: https://docs.pr-agent.ai/installation/locally

Example .env file for configuring PR-Agent to connect to a self-hosted GitLab instance. Uses the convention <TABLE>__<KEY>=<VALUE>.

```bash
CONFIG__GIT_PROVIDER="gitlab"  

GITLAB__URL="<your url>"  

GITLAB__PERSONAL_ACCESS_TOKEN="<your token>"  

OPENAI__KEY="<your key>"  
```

--------------------------------

### BitBucket App: Enable push trigger with push_commands

Source: https://docs.pr-agent.ai/usage-guide/automations_and_usage

Set handle_push_trigger = true and define push_commands to run tools automatically on each push to the PR. This example runs /describe and /review on every push.

```ini
[bitbucket_app]  

handle_push_trigger = true  

push_commands = [  

    "/describe",  

    "/review",  

]  


```

--------------------------------

### Gemini Setup GitHub Actions workflow

Source: https://docs.pr-agent.ai/installation/github

Ready-to-use workflow for Gemini models. Requires a GEMINI_API_KEY secret and a GITHUB_TOKEN secret. Sets config.model to 'gemini/gemini-3.8-flash' and enables auto_review, auto_describe, and auto_improve.

```yaml
name: PR Agent (Gemini)  

on:  

  pull_request:  

    types: [opened, reopened, ready_for_review]  

  issue_comment:  

jobs:  

  pr_agent_job:  

    if: ${{ github.event.sender.type != 'Bot' }}  

    runs-on: ubuntu-latest  

    permissions:  

      contents: read  

      issues: write  

      pull-requests: write  

    steps:  

      - name: PR Agent action step  

        uses: the-pr-agent/pr-agent@main  

        env:  

          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  

          config.model: "gemini/gemini-3.8-flash"  

          config.fallback_models: '["gemini/gemini-3.8-flash"]'  

          GOOGLE_AI_STUDIO.GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}  

          github_action_config.auto_review: "true"  

          github_action_config.auto_describe: "true"  

          github_action_config.auto_improve: "true"  


```

--------------------------------

### Enable run details output for /review

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Use /review with config.output_run_details=true to see which model answered, token consumption, and AI processing time.

```markdown
/review --config.output_run_details=true  
```

--------------------------------

### Install optional gRPC exporter

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Install the optional exporter for OTLP over gRPC. The endpoint is then used as-is, typically on port 4317.

```bash
pip install pr-agent[otel-grpc]  

```

--------------------------------

### CLI command for Help tool

Source: https://docs.pr-agent.ai/tools

Run the help tool from the CLI by providing the PR URL.

```bash
python -m pr_agent.cli --pr_url=<PR_URL> help
```

--------------------------------

### Enable run details and API cost output for /review

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Enable both config.output_run_details and config.output_run_cost to collect API cost and add it inside the run-details section.

```markdown
/review --config.output_run_details=true --config.output_run_cost=true  
```

--------------------------------

### Print all available configurations as a PR comment

Source: https://docs.pr-agent.ai/usage-guide/additional_configurations

Use the /config command to print all available configurations as a comment on your PR.

```markdown
/config  
```

--------------------------------

### Authentication header examples for private endpoints

Source: https://docs.pr-agent.ai/usage-guide/configuration_options

Set the PR_AGENT_EXTRA_CONFIG_AUTH_HEADER environment variable to provide a single header for private endpoints. The examples show formats for a GitLab Personal Access Token, a GitLab CI job token, and a generic bearer token. The header must be formatted as '<HeaderName>: <value>'.

```bash
# GitLab Personal Access Token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="PRIVATE-TOKEN: <your-personal-access-token>"

# GitLab CI job token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="JOB-TOKEN: $CI_JOB_TOKEN"

# Generic bearer token
export PR_AGENT_EXTRA_CONFIG_AUTH_HEADER="Authorization: Bearer <your-token>"
```

--------------------------------

### Run standalone MOSAICO container with docker pull and run

Source: https://docs.pr-agent.ai/installation/mosaico_server

Boot the server from a bare docker pull, then run the container with required environment variables. Verify the agent card with curl and python3.

```bash
docker pull pragent/pr-agent:0.41.0-mosaico_agent
```

```bash
docker run -d --name pr-agent-mosaico -p 9000:9000 \
  -e API_BASE=https://your-openai-compatible-endpoint/v1 \
  -e API_KEY=sk-... \
  -e MODEL_NAME=openai/your-model-slug \
  pragent/pr-agent:0.41.0-mosaico_agent
```

```bash
curl -s http://localhost:9000/.well-known/agent-card.json | python3 -m json.tool
```

--------------------------------

### Azure AD authentication settings in .secrets.toml

Source: https://docs.pr-agent.ai/usage-guide/changing_a_model

For Azure AD (Entra ID) authentication, install the `azure` extra (`pip install "pr-agent[azure]"`) and set these values in `.secrets.toml` or GitHub Secrets. Requires your Azure AD client ID, client secret, tenant ID, and the Azure OpenAI service base URL.

```toml
[azure_ad]  

client_id = ""  # Your Azure AD application client ID  

client_secret = ""  # Your Azure AD application client secret  

tenant_id = ""  # Your Azure AD tenant ID  

api_base = ""  # Your Azure OpenAI service base URL (e.g., https://openai.xyz.com/)  

```

--------------------------------

### Select Qdrant in configuration.toml

Source: https://docs.pr-agent.ai/tools/similar_issues

After adding Qdrant credentials, select Qdrant in `configuration.toml` by setting `vectordb = "qdrant"` under `[pr_similar_issue]`.

```toml
[pr_similar_issue]  

vectordb = "qdrant"  

```

--------------------------------

### GET /.well-known/agent-card.json

Source: https://docs.pr-agent.ai/installation/mosaico_server

Retrieves the A2A agent card, which advertises the agent's skills, name, version, and required extension.

```APIDOC
## GET /.well-known/agent-card.json

### Description
Returns the A2A agent card for the MOSAICO solution agent. The card advertises the skills `review`, `improve`, `describe`, and `ask`, the name `"PR-Agent Solution Agent"`, a version derived from the running build, and the required `https://mosaico-project.eu/extensions/mosaico-observability` extension. Streaming is advertised as disabled.

### Method
GET

### Endpoint
/.well-known/agent-card.json

### Response
#### Success Response (200)
- **name** (string) - The agent name, `"PR-Agent Solution Agent"`.
- **skills** (array of strings) - The advertised skills: `review`, `improve`, `describe`, `ask`.
- **version** (string) - The version derived from the running build.
- **extensions** (array) - Contains the required extension `https://mosaico-project.eu/extensions/mosaico-observability`.
- **capabilities** (object) - Includes `streaming` set to `false`.

#### Response Example
{
  "name": "PR-Agent Solution Agent",
  "skills": ["review", "improve", "describe", "ask"],
  "version": "v0.36.0",
  "extensions": ["https://mosaico-project.eu/extensions/mosaico-observability"],
  "capabilities": {
    "streaming": false
  }
}
```

--------------------------------

### Clone PR Agent repository

Source: https://docs.pr-agent.ai/installation/gitlab

Clones the PR Agent repository from GitHub to get the source code for the webhook server.

```bash
git clone https://github.com/the-pr-agent/pr-agent.git
```

--------------------------------

### Configure pr_help_docs in configuration file

Source: https://docs.pr-agent.ai/tools/help_docs

Configuration options for the help_docs tool under the [pr_help_docs] section. Set repo_url, docs_path, and repo_default_branch to customize the documentation source.

```ini
[pr_help_docs]  
repo_url = ""                 # The repository to use as context  
docs_path = "docs"            # The documentation folder  
repo_default_branch = "main"  # The branch to use in case repo_url overwritten  
  
```

--------------------------------

### Clone the PR Agent repository

Source: https://docs.pr-agent.ai/installation/github

Clone the PR Agent repository to your local machine to proceed with the GitHub App setup.

```bash
git clone https://github.com/the-pr-agent/pr-agent.git  

```

--------------------------------

### CLI command for Add Documentation tool

Source: https://docs.pr-agent.ai/tools

Run the add_docs tool from the CLI by providing the PR URL.

```bash
python -m pr_agent.cli --pr_url=<PR_URL> add_docs
```

--------------------------------

### Define custom labels in [custom_labels] section

Source: https://docs.pr-agent.ai/tools/generate_labels

Define custom labels in the [custom_labels] section. Each label has a description. See custom_labels.toml for examples.

```toml
[custom_labels."Bug fix"]  
description = "A fix for a bug in the codebase"  
  
[custom_labels."Feature"]  
description = "A new feature or enhancement"  
  
[custom_labels."Documentation"]  
description = "Documentation changes only"  
  
[custom_labels."Tests"]  
description = "Adding or modifying tests"  
  
[custom_labels."Refactoring"]  
description = "Code refactoring without functional changes"  
```

--------------------------------

### Manual trigger with configurations

Source: https://docs.pr-agent.ai/tools/review

Add configuration options to the /review command by appending --pr_reviewer.some_config1=... and --pr_reviewer.some_config2=... to the command.

```markdown
/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...  
```

--------------------------------

### AWS CodeCommit CLI Example

Source: https://docs.pr-agent.ai/installation/github

Runs PR-Agent CLI to review a specific CodeCommit pull request. Replace the PYTHONPATH and PR URL with your own.

```bash
PYTHONPATH="/PATH/TO/PROJECTS/pr-agent" python pr_agent/cli.py \

  --pr_url https://us-east-1.console.aws.amazon.com/codesuite/codecommit/repositories/MY_REPO_NAME/pull-requests/321 \

  review
```

--------------------------------

### Use /ask with extra_instructions in a PR comment

Source: https://docs.pr-agent.ai/tools/ask

Example of using the `--pr_questions.extra_instructions` option in a PR comment to override the extra instructions for a single question.

```markdown
/ask "What does this change do?" --pr_questions.extra_instructions="Answer in one short paragraph."  
```

--------------------------------

### GET /health

Source: https://docs.pr-agent.ai/installation/mosaico_server

Live LLM connectivity probe. Returns 200 when an LLM round-trip succeeds, 503 otherwise. Configurable timeout via mosaico.health_timeout_seconds.

```APIDOC
## GET /health

### Description
Performs a live LLM connectivity probe. Returns HTTP 200 when an LLM round-trip succeeds, and HTTP 503 otherwise. The probe uses a configurable timeout (`mosaico.health_timeout_seconds`, default 10 seconds). Invalid timeout values produce the generic unhealthy response (503).

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **body** (string) - Empty or a success message.

#### Failure Response (503)
- **body** (string) - `Unhealthy: LLM probe failed` for provider failures.

#### Response Example (Success)
HTTP/1.1 200 OK

#### Response Example (Failure)
HTTP/1.1 503 Service Unavailable
Unhealthy: LLM probe failed
```

--------------------------------

### OpenRouter Router Models Configuration

Source: https://docs.pr-agent.ai/usage-guide/changing_a_model

Selects OpenRouter's router models directly without setting custom_model_max_tokens. The example uses the 'auto' and 'free' routers.

```toml
[config]  

model = "openrouter/auto"  

fallback_models = ["openrouter/free"]  

```

--------------------------------

### Configure Qwen (DashScope) model and API key

Source: https://docs.pr-agent.ai/usage-guide/changing_a_model

Set the model to dashscope/qwen3.8-max in configuration.toml and provide the DashScope API key in .secrets.toml.

```toml
[config] # in configuration.toml  

model = "dashscope/qwen3.8-max"  

fallback_models=["dashscope/qwen3.8-max"]  


```

```toml
[dashscope] # in .secrets.toml  

key = ...  


```
Tokens:
Raw