> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp/getting-started/configuring-llm-providers.md).

# Configuring LLM Providers

This guide covers the setup and configuration of Large Language Model (LLM) providers for AI-powered features in sfp:

* [**AI Assisted Architecture Analysis**](/flxbl/sfp/analysing-a-project/ai-pr-linter.md) - Architectural review of pull request changes
* [**AI Assisted Insight Reports**](/flxbl/sfp/analysing-a-project/ai-powered-report.md) - On-demand project analysis reports
* [**AI-Assisted Error Analysis**](/flxbl/sfp/validating-a-change/ai-assisted-error-analysis.md) - Intelligent validation error analysis

All three features are exclusive to **sfp-pro** and share the single provider configuration described on this page — configure a provider once and every AI feature can use it.

## Prerequisites

* **sfp-pro** installed — AI features are not available in the community edition.
* Credentials for at least one supported provider: an API key (Anthropic, OpenAI), an AWS Bedrock bearer token, a GitHub Copilot token, or — for Claude on Google Vertex — a Google Cloud project with a service account.
* No separate runtime to install — sfp bundles the OpenCode agent that talks to the providers.

{% hint style="info" %}
When sfp runs against an **sfp server** (for example inside a CI/CD pipeline connected to your server), provider credentials can be managed centrally on the server rather than configured in every pipeline. See [Server-Managed Credentials](#server-managed-credentials).
{% endhint %}

## Supported LLM Providers

sfp currently supports the following LLM providers through the bundled OpenCode runtime:

| Provider                    | Status            | Recommended | Best For                                                                       |
| --------------------------- | ----------------- | ----------- | ------------------------------------------------------------------------------ |
| **Anthropic (Claude)**      | ✅ Fully Supported | ⭐ Yes       | Best overall performance, Flxbl framework understanding                        |
| **OpenAI**                  | ✅ Fully Supported | Yes         | Wide model selection, good performance                                         |
| **Amazon Bedrock**          | ✅ Fully Supported | Yes         | Enterprise environments with AWS infrastructure                                |
| **GitHub Copilot**          | ✅ Fully Supported | Yes         | Teams with existing Copilot subscriptions, no extra cost                       |
| **Claude on Google Vertex** | ✅ Fully Supported | Yes         | Claude licensed through Google Cloud (traffic and billing in your GCP project) |

## Provider Configuration

### Anthropic (Claude) - Recommended

Anthropic's Claude models provide the best understanding of Salesforce and Flxbl framework patterns. The default model used is `claude-sonnet-4-5-20250929` which offers optimal balance between performance and cost.

#### Setup

**Step 1: Environment Variable**

```bash
# Add to your shell profile (.bashrc, .zshrc, etc.)
export ANTHROPIC_API_KEY="sk-ant-xxxxxxxxxxxxx"

# Verify the configuration works
sfp ai test --provider anthropic
```

**Step 2: Configuration File** Create or edit `config/ai-assist.yaml`:

```yaml
enabled: true
provider: anthropic
# Model is optional - uses claude-sonnet-4-5-20250929 by default
```

{% hint style="info" %}
`config/ai-assist.yaml` is the current configuration file. The older `config/ai-architecture.yaml` is still read for backward compatibility, but new projects should use `ai-assist.yaml`.
{% endhint %}

#### Getting an Anthropic API Key

1. Visit [console.anthropic.com](https://console.anthropic.com)
2. Sign up or log in to your account
3. Navigate to API Keys section
4. Create a new API key for sfp usage
5. Copy the key (starts with `sk-ant-`)

{% hint style="info" %}
**Claude Models Available:**

* `claude-sonnet-4-5-20250929` - Recommended, best balance (default)
  {% endhint %}

### OpenAI

OpenAI provides access to GPT models with good code analysis capabilities.

#### Setup

**Step 1: Environment Variable**

```bash
export OPENAI_API_KEY="sk-xxxxxxxxxxxxx"

# Verify the configuration works
sfp ai test --provider openai
```

**Step 2: Configuration File**

```yaml
# In config/ai-assist.yaml
enabled: true
provider: openai
# Model is optional - uses gpt-4o by default
```

#### Getting an OpenAI API Key

1. Visit [platform.openai.com](https://platform.openai.com)
2. Sign up or log in
3. Go to API Keys section
4. Create a new secret key
5. Copy the key (starts with `sk-`)

### Amazon Bedrock

Amazon Bedrock is ideal for enterprise environments already using AWS infrastructure. It provides access to Claude models through AWS.

#### Setup

**Step 1: AWS Profile**

```bash
# Set both required environment variables
export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token"
export AWS_REGION="us-east-1"

# Both variables must be set for authentication to work
# Verify the configuration works
sfp ai test --provider amazon-bedrock
```

**STEP 3: Configuration File**

```yaml
# In config/ai-assist.yaml
enabled: true
provider: amazon-bedrock
model: anthropic.claude-sonnet-4-5-20250929-v1:0  # Default model
```

{% hint style="warning" %}
**Important**: AWS Bedrock requires both `AWS_BEARER_TOKEN_BEDROCK` and `AWS_REGION` environment variables to be set. Authentication will fail if either is missing.
{% endhint %}

{% hint style="warning" %}
**Bedrock Model Access**: Ensure your AWS account has access to the Claude models in Bedrock. You may need to request access through the AWS Console under Bedrock > Model access.
{% endhint %}

#### Regional Considerations

Bedrock automatically handles model prefixes based on your AWS region:

* **US Regions**: Models may require `us.` prefix
* **EU Regions**: Models may require `eu.` prefix
* **AP Regions**: Models may require `apac.` prefix

The OpenCode SDK handles this automatically based on your `AWS_REGION`.

### GitHub Copilot

GitHub Copilot can be used if you have an active subscription with model access enabled.

#### Setup

{% hint style="info" %}
**Prerequisites:**

* Active GitHub Copilot subscription (Individual, Business, or Enterprise)
* Models must be enabled in your GitHub Copilot settings
* Visit [GitHub Copilot Features](https://github.com/settings/copilot/features) to enable model access
  {% endhint %}

#### Setup Methods

**Method 1: Generate Token Using Script (Recommended)**

sfp includes a helper script to generate Copilot tokens via the GitHub device flow:

```bash
# Run the token generator script
./scripts/get-copilot-token.sh
```

The script will:

1. Request a device code from GitHub
2. Display a URL and verification code
3. Open your browser automatically (on supported systems)
4. Poll for authorization completion
5. Output the OAuth token (`ghu_` prefixed)

After the script completes, set the token:

```bash
# Set the token in your environment
export COPILOT_TOKEN="ghu_xxxxxxxxxxxx"

# Verify the configuration works
sfp ai test --provider github-copilot
```

**Method 2: Environment Variable (CI/CD)**

For CI/CD pipelines, set the `COPILOT_TOKEN` environment variable:

```bash
# Add to your shell profile or CI/CD secrets
export COPILOT_TOKEN="ghu_xxxxxxxxxxxx"
```

In GitHub Actions:

```yaml
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AI Analysis
        env:
          COPILOT_TOKEN: ${{ secrets.COPILOT_TOKEN }}
        run: |
          sfp project:analyze --provider github-copilot
```

{% hint style="warning" %}
**Important**: Use `COPILOT_TOKEN` instead of `GITHUB_TOKEN` in CI/CD environments. The `GITHUB_TOKEN` is automatically set by GitHub Actions for repository operations and may conflict with Copilot authentication.
{% endhint %}

#### How Token Exchange Works

sfp automatically handles the OAuth token exchange process:

1. **OAuth Token** (`ghu_` prefix): The token you obtain from device flow authentication
2. **API Token Exchange**: sfp automatically exchanges the OAuth token for a Copilot API token via GitHub's internal API
3. **Transparent Process**: This exchange happens automatically when you use `--provider github-copilot`

```
OAuth Token (ghu_xxx) → Exchange API → Copilot API Token → AI Model Access
```

#### Configuration File

```yaml
# In config/ai-assist.yaml
enabled: true
provider: github-copilot
# Model is optional - uses claude-sonnet-4.5 by default for GitHub Copilot
```

#### Available Models

GitHub Copilot provides access to various models. The default is `claude-sonnet-4.5`:

| Model               | Description       | Notes                |
| ------------------- | ----------------- | -------------------- |
| `claude-sonnet-4.5` | Claude Sonnet 4.5 | Default, recommended |
| `gpt-4.1`           | GPT-4.1           | Alternative option   |

{% hint style="info" %}
**Model Naming**: GitHub Copilot uses simplified model names without date suffixes (e.g., `claude-sonnet-4.5` instead of `claude-sonnet-4-20250514`).
{% endhint %}

### Claude on Google Vertex

Claude on Google Vertex serves Anthropic Claude models through your own Google Cloud project, so model traffic and billing stay inside your Google Cloud agreement. It is normally connected in the codev UI under **Settings → Integrations → AI Providers**, where the credentials are stored on the sfp server and every connected pipeline reuses them — see [AI Providers](https://docs.flxbl.io/flxbl/codev/integrations/ai-providers). The one-time Google Cloud setup (enable the Vertex AI API, enable the Claude models in Model Garden, create a service account with the **Vertex AI User** role, and confirm the project has model quota) is covered in [Claude on Vertex AI](https://docs.flxbl.io/sfp-server/configuring-ai-providers/claude-on-vertex-ai).

#### Setup

Vertex uses Google IAM auth, not an API key. To run the sfp CLI directly against Vertex, use Google Application Default Credentials:

```bash
export GOOGLE_CLOUD_PROJECT="my-project-123456"
export GOOGLE_CLOUD_LOCATION="us"          # us, eu, or global (default: global)
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"

# Verify the configuration works
sfp ai test --provider google-vertex-anthropic
```

```yaml
# In config/ai-assist.yaml
enabled: true
provider: google-vertex-anthropic
# Model is optional - uses the latest available Claude by default
```

{% hint style="info" %}
`GOOGLE_CLOUD_PROJECT` also accepts `GCP_PROJECT` or `GCLOUD_PROJECT`; `GOOGLE_CLOUD_LOCATION` also accepts `VERTEX_LOCATION`. The service-account JSON is referenced on disk via `GOOGLE_APPLICATION_CREDENTIALS`, following the standard Google Application Default Credentials pattern.
{% endhint %}

## Configuration File Reference

The AI features are configured through `config/ai-assist.yaml` in your project root:

```yaml
# Enable/disable AI features
enabled: true

# Provider Configuration
provider: anthropic  # anthropic, openai, amazon-bedrock, github-copilot, google-vertex-anthropic

# Model Configuration (Optional - uses provider defaults if not specified)
# Default models:
# - anthropic: claude-sonnet-4-5-20250929
# - openai: gpt-4o
# - github-copilot: claude-sonnet-4.5
# - amazon-bedrock: set an explicit Bedrock model id (e.g. anthropic.claude-sonnet-4-5-20250929-v1:0)
# - google-vertex-anthropic: uses the latest available Claude by default
model: claude-sonnet-4-5-20250929  # Override default model

# Architectural Patterns to Check (for PR Linter)
patterns:
  - singleton
  - factory
  - repository
  - service-layer

# Architecture Principles
principles:
  - separation-of-concerns
  - single-responsibility
  - dependency-inversion

# Focus Areas for Analysis
focusAreas:
  - security
  - performance
  - maintainability
  - testability

# Additional Context Files
contextFiles:
  - ARCHITECTURE.md
  - docs/patterns.md
  - docs/coding-standards.md
```

## Testing Provider Configuration

The test command performs a complete health check:

* **Authentication**: Verifies credentials are available
* **Connectivity**: Confirms the provider endpoint is reachable
* **Response**: Validates the model returns a valid response

### Testing Commands

`sfp ai test` requires the `--provider` flag — there is no "test all" mode. Each run tests one provider end to end.

```bash
# Test a provider with its default model
sfp ai test --provider anthropic

# Test a specific model
sfp ai test --provider openai --model gpt-4o

# Test Amazon Bedrock (default model: anthropic.claude-3-sonnet-20240229-v1:0)
sfp ai test --provider amazon-bedrock

# Test GitHub Copilot (default model: claude-sonnet-4.5)
sfp ai test --provider github-copilot

# Test Claude on Google Vertex (requires GOOGLE_CLOUD_PROJECT + GOOGLE_APPLICATION_CREDENTIALS)
sfp ai test --provider google-vertex-anthropic

# Send a custom prompt / raise the timeout / emit JSON
sfp ai test --provider anthropic --prompt "What is 2+2?" --timeout 90 --json
```

| Flag         | Alias | Default                    | Purpose                                                                                                  |
| ------------ | ----- | -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `--provider` | `-p`  | *required*                 | Provider to test (`anthropic`, `openai`, `amazon-bedrock`, `github-copilot`, `google-vertex-anthropic`). |
| `--model`    | `-m`  | provider default           | Model id to test.                                                                                        |
| `--prompt`   |       | `Respond with exactly: OK` | Prompt sent during the response check.                                                                   |
| `--timeout`  | `-t`  | `60`                       | Request timeout in seconds.                                                                              |
| `--json`     |       | `false`                    | Emit a machine-readable result instead of the formatted summary.                                         |

This command performs a simple inference test to verify:

* Authentication is configured correctly
* The provider is accessible
* Model inference is working
* Response time and performance

## Usage Priority

sfp resolves provider credentials in this order:

1. **Server-managed credentials** — when sfp is connected to an sfp server (server URL + application token present), it fetches the provider credentials from the server first. See [Server-Managed Credentials](#server-managed-credentials).
2. **Environment variables** — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AWS_BEARER_TOKEN_BEDROCK` + `AWS_REGION`, `COPILOT_TOKEN` / `GITHUB_TOKEN`, or `GOOGLE_CLOUD_PROJECT` + `GOOGLE_APPLICATION_CREDENTIALS` for Vertex. Recommended for local use and self-managed CI/CD.
3. **Configuration file** — `config/ai-assist.yaml` selects the provider and model; it does not store secrets.

## Server-Managed Credentials

When sfp runs with an sfp server connection — either via the `--sfp-server-url` and `--application-token` flags, or the `SFP_SERVER_URL` and `SFP_SERVER_TOKEN` environment variables — AI commands such as `sfp project:report` and `sfp project:analyze` fetch provider credentials from the server instead of requiring them in the pipeline environment. If the server has no credentials for the requested provider, sfp falls back to the local environment variables listed above.

This keeps API keys out of individual CI/CD pipelines: configure a provider once on the server, and every connected repository and pipeline can use it.

## Troubleshooting

### Provider Not Available

```bash

# Verify environment variables
echo $ANTHROPIC_API_KEY

# For AWS Bedrock - check both required variables
echo $AWS_BEARER_TOKEN_BEDROCK
echo $AWS_REGION

# For GitHub Copilot
echo $COPILOT_TOKEN

# Test provider connectivity
sfp ai test --provider <provider-name>
```

### AWS Bedrock Specific Issues

**Both Environment Variables Required**

```bash
# This will NOT work (missing region)
export AWS_BEARER_TOKEN_BEDROCK="token"

# This will work (both variables set)
export AWS_BEARER_TOKEN_BEDROCK="token"
export AWS_REGION="us-east-1"
```

**Authentication Failed**

* Verify both `AWS_BEARER_TOKEN_BEDROCK` and `AWS_REGION` are set
* Check that your bearer token is valid and not expired
* Ensure your AWS account has access to Claude models in Bedrock

### API Rate Limits

If you encounter rate limits:

* **Anthropic**: Check your usage at [console.anthropic.com](https://console.anthropic.com)
* **OpenAI**: Monitor at [platform.openai.com/usage](https://platform.openai.com/usage)
* **Bedrock**: Check AWS CloudWatch metrics

### Model Not Found

Ensure you're using the correct model identifier for your provider:

```yaml
# Anthropic
model: claude-sonnet-4-5-20250929

# OpenAI
model: gpt-4o

# GitHub Copilot
model: gpt-4o

# Amazon Bedrock
model: anthropic.claude-sonnet-4-5-20250929-v1:0
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp/getting-started/configuring-llm-providers.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.