LLM Connections

An LLM connection is a named provider configuration — an endpoint, an auth method, a credential, and the set of models Fabric Agents should use with it. Sessions pick which connection to run on.

Connections live inline in config.json under llmConnections:

{
  "llmConnections": [
    { "slug": "anthropic-api", "name": "Anthropic (API Key)", "providerType": "anthropic", "authType": "api_key", "defaultModel": "claude-opus-4-8", "createdAt": 1704067200000 },
    { "slug": "ollama",        "name": "Ollama (local)",       "providerType": "pi_compat", "authType": "none",     "baseUrl": "http://localhost:11434", "customEndpoint": { "api": "openai-completions" }, "models": ["llama3:70b", "mistral:7b"], "defaultModel": "llama3:70b", "createdAt": 1710000000000 }
  ],
  "defaultLlmConnection": "anthropic-api"
}

Credentials are never stored here — they live in the OS keychain (macOS / Windows) or the encrypted credential store (~/.fabric-agent/credentials/ on Linux). config.json just references connections by slug.

Provider types

Fabric Agents classifies every connection as one of four provider types:

Auth types

Full schema

interface LlmConnection {
  slug: string                 // URL-safe unique ID, e.g. "anthropic-api"
  name: string                 // Display name shown in the UI
  providerType: "anthropic" | "pi" | "pi_compat" | "azure_ai_foundry"
  authType: LlmAuthType        // see table above

  // Endpoint
  baseUrl?: string             // Custom endpoint (required for pi_compat, optional elsewhere)
  customEndpoint?: {           // pi_compat only
    api: "openai-completions" | "anthropic-messages"
    supportsImages?: boolean
  }

  // Models
  models?: (string | ModelDefinition)[]
  defaultModel?: string
  modelSelectionMode?: "automaticallySyncedFromProvider" | "userDefined3Tier"

  // Pi sub-provider selection
  piAuthProvider?: string       // e.g. "anthropic", "openai", "github-copilot", "google", "codex"

  // AWS / Bedrock (legacy; use pi with piAuthProvider: "anthropic-bedrock" instead)
  awsRegion?: string

  // GCP / Vertex (legacy)
  gcpProjectId?: string
  gcpRegion?: string

  // Azure AI Foundry
  azureResourceName?: string
  azureSubscriptionId?: string
  azureResourceGroup?: string
  azureClientId?: string

  createdAt: number
  lastUsedAt?: number
}

Models and model-selection modes

• automaticallySyncedFromProvider — Fabric Agents fetches the model list from the provider on each session. You always see the newest models without editing config.
• userDefined3Tier — You pick explicit Best / Balanced / Fast models, and they stay fixed until you change them. Useful when you want predictable routing.

For pi_compat connections (Ollama, vLLM, OpenRouter, Vercel AI Gateway, LM Studio) there's no model discovery — list the models you have available in the models array by ID.

Custom endpoints (pi_compat)

Two protocols are supported for non-Anthropic compatible servers:

Example — Ollama with image-capable model:

{
  "slug": "ollama-gemma",
  "name": "Ollama (Gemma)",
  "providerType": "pi_compat",
  "authType": "none",
  "baseUrl": "http://localhost:11434",
  "customEndpoint": {
    "api": "openai-completions",
    "supportsImages": true
  },
  "models": ["gemma-4"],
  "defaultModel": "gemma-4",
  "createdAt": 1710000000000
}

Local endpoints also need a trailing /v1 path for OpenAI-compatible servers — Ollama's default http://localhost:11434 already forwards to /v1 internally, but some servers don't.

OAuth flows

When authType: "oauth" triggers a connect action, Fabric Agents opens your browser to the provider:

Refresh happens automatically — Fabric Agents watches expiry and refreshes ~5 minutes before the access token runs out. If refresh fails (you revoked the grant on the provider's side), the connection shows Reconnect in the UI.

Resolved Anthropic identity

For Anthropic (Claude Max) OAuth grants, Fabric Agents captures the real account the grant resolves to during the token exchange and shows it under each connection in Settings → AI → Connections as email · org. This makes it obvious which Anthropic account a connection is actually using — useful when you manage several.

If two connections in the same workspace resolve to the same Anthropic account — they share quota, a mis-route that was previously invisible — an amber warning is surfaced on both so you can spot and fix the duplication.

Connection resolution

When a session opens, Fabric Agents picks a connection by walking this chain:

1. Session-locked connection — session.llmConnection. Set on the session's first message; immutable afterwards.
2. Workspace default — {workspace}/config.json → defaults.defaultLlmConnection.
3. Global default — config.json → defaultLlmConnection.
4. First available connection in llmConnections.

This is why the connection is locked after the first message of a session: switching providers mid-conversation would invalidate provider-specific session state (prompt cache, SDK session ID, context layout). The model is free to change; the connection is not.

If the session's locked connection has since been deleted, Fabric Agents surfaces a "Connection unavailable" warning and asks you to pick a replacement before the next message.

Locking model lists

For Pi and Pi-compat connections where models auto-sync, you can lock a specific subset by switching to userDefined3Tier. In Settings → AI → Connections, edit the connection and pick your three tiers. Fabric Agents stops syncing from the provider and uses the chosen models until you switch back.

Helpers

Internally these helpers decide provider-specific behaviour — useful if you're writing code against the config shape:

Related

• config.json — where the llmConnections array lives.
• Environment variables — runtime overrides for keys, endpoints, TLS.
• Conversations — where the session-locked connection behaviour lives.