feat: add LiteLLM as an OpenAI-compatible model provider

[prodmanpd]

Summary

• Adds LiteLLM as a first-class model provider, alongside the existing openrouter, nim, and custom OpenAI-compatible providers.
• Use the litellm/ prefix (e.g. litellm/anthropic/claude-sonnet-4-5, litellm/gpt-4o, or any alias configured on your proxy) to route through a LiteLLM proxy, which fronts 100+ providers (OpenAI, Anthropic, Bedrock, Vertex, Azure, Gemini, Groq, and more) behind one OpenAI-compatible endpoint.
• Implemented by mirroring the existing nim provider pattern exactly (a named createOpenAICompatible default instance + a configurable case), so it is additive and low-risk.

Motivation

Teams that already run a LiteLLM proxy for centralized key management, spend tracking, routing, and rate limiting currently have to use the generic custom/ provider and hand-set providerOptions.baseURL on every model. That works, but it is undiscoverable and easy to get wrong. This mirrors why the repo already ships named nim and openrouter conveniences on top of the generic custom path: a first-class litellm/ provider gives a documented default base URL (http://localhost:4000/v1, LiteLLM's standard proxy port), env-based configuration, and UI discoverability.

Changes

• packages/agents-core/src/utils/model-factory.ts — new litellmDefault provider instance; litellm case in createProvider (custom-config path) and in the default-instance switch; litellm added to BUILT_IN_PROVIDERS; provider-enumeration error messages updated.
• packages/agents-core/src/__tests__/utils/model-factory.test.ts — parseModelString coverage for litellm/.
• agents-api/src/__tests__/run/agents/ModelFactory.test.ts — parse + create coverage (default and custom-base-URL).
• agents-manage-ui/src/components/agent/sidepane/nodes/model-selector.tsx — LiteLLM entry in the model picker (prefix display, selector item, labels/placeholder, prefix handling).
• agents-manage-ui/src/features/agent/state/use-agent-store.ts — doc comment update.
• agents-docs/content/typescript-sdk/models.mdx — provider table row + configuration section.
• .changeset/add-litellm-provider.md — patch changeset for @inkeep/agents-core and @inkeep/agents-manage-ui.

Configuration

The base URL resolves from providerOptions.baseURL, then LITELLM_API_BASE, then http://localhost:4000/v1. Set LITELLM_API_KEY to your proxy's virtual/master key; it is sent as a bearer token only when present (so keyless local proxies work too).

models: {
  base: {
    model: "litellm/anthropic/claude-sonnet-4-5",
    providerOptions: {
      baseURL: "https://my-litellm-proxy.example.com/v1", // optional; overrides LITELLM_API_BASE
    },
  },
}

Tests

1. Unit tests

agents-core (packages/agents-core):

$ pnpm exec vitest run src/__tests__/utils/model-factory.test.ts
 ✓ src/__tests__/utils/model-factory.test.ts (49 tests) 2433ms
 Test Files  1 passed (1)
      Tests  49 passed (49)

agents-api:

$ pnpm exec vitest run src/__tests__/run/agents/ModelFactory.test.ts
 ✓ |@inkeep/agents-api| src/__tests__/run/agents/ModelFactory.test.ts (70 tests) 239ms
 Test Files  1 passed (1)
      Tests  70 passed (70)

2. Format + lint (Biome) — clean on all changed files:

$ pnpm exec biome check <changed files>
Checked 5 files in 17ms. No fixes applied.

3. Typecheck — @inkeep/agents-core and @inkeep/agents-manage-ui both pass tsc --noEmit.

4. Live end-to-end through a real LiteLLM proxy

A LiteLLM proxy was started with an alias e2e-gpt routed to a live Azure AI Foundry deployment, then driven through ModelFactory.createModel('litellm/e2e-gpt') using the AI SDK's generateText and streamText:

provider: litellm.chat | modelId: e2e-gpt
LITELLM_API_BASE: http://localhost:4141/v1

[generateText]
  text: "4"
  finishReason: stop
  usage: {"inputTokens":19,"outputTokens":5,"totalTokens":24, ...}

[streamText]
streaming ok
  streamed: "streaming ok"
  finishReason: stop

This exercises the full chain: ModelFactory → createOpenAICompatible (the new litellm provider) → LiteLLM proxy → upstream provider → response parsed back through the AI SDK, for both non-streaming and streaming.

Risk / compatibility

• Additive only. No existing provider behavior changes.
• Same shape as the existing nim named OpenAI-compatible provider.
• No new dependencies (@ai-sdk/openai-compatible is already used by nim/custom).

Example usage

import { ModelFactory } from '@inkeep/agents-core';

// LITELLM_API_BASE=https://my-litellm-proxy/v1  LITELLM_API_KEY=sk-...
const model = ModelFactory.createModel({ model: 'litellm/anthropic/claude-sonnet-4-5' });

[changeset-bot]

🦋 Changeset detected

Latest commit: 62759e2

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@inkeep/agents-core	Patch
@inkeep/agents-manage-ui	Patch
@inkeep/agents-work-apps	Patch
@inkeep/ai-sdk-provider	Patch
@inkeep/create-agents	Patch
@inkeep/agents-api	Patch
@inkeep/agents-cli	Patch
@inkeep/agents-email	Patch
@inkeep/agents-mcp	Patch
@inkeep/agents-sdk	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Thanks for the contribution!

What happens next:

• A maintainer will review your PR.
• If you don't hear back within a few business days, please comment here to nudge our team.
• This repository is maintained through an internal mirror. When your change is accepted, this PR will close automatically. Don't be alarmed when it closes — that's how it merges, and your authorship is preserved.

[liuzhao1225]

I'm concerned about the supply-chain boundary of this LiteLLM integration. The upstream incident report confirms compromised PyPI releases 1.82.7/1.82.8 in March 2026; those releases were removed.

This reviewed change uses a proxy-compatible integration; it does not itself add a Python LiteLLM package installation. The deployment questions are who operates the proxy, which verified server version runs there, and whether credentials remain isolated from other providers. Please document those trust boundaries for users.

This is one of 49 observed LiteLLM integration PRs from the same account, whose author acknowledged the cross-project effort. The pattern prompted this review; it does not establish malicious intent or connect the author to the incident. The consolidated questions and corrections are in YouDub #130; this PR's review snapshot preserves the revision and scope.