open-commerce-agent

Provider-agnostic reference commerce agent. A fork of anthropics/commerce-agents that runs on any OpenAI Chat Completions–compatible endpoint — OpenRouter, Chutes, LiteLLM, vLLM, Ollama, LM Studio, self-hosted.

Apache-2.0. Vendored subset of Anthropic's original at a pinned commit (see UPSTREAM.md); wrapped with a streaming Anthropic Messages ⇄ OpenAI Chat Completions translator so the upstream ShoppingAgent orchestrator's tool-loop, gates, and prompt work unchanged against non-Anthropic backends.

Status: Alpha / WIP. Runtime shim, request + response translation, and end-to-end wiring against Anthropic (via OpenRouter) and OSS models (via OpenRouter) are proven working. Public-facing polish (installer, docs, PyPI package) still landing.

Why

Anthropic's reference implementation binds you to Claude via their Messages API + Claude Agent SDK. That's the right call for the primary use case, but leaves everyone running OSS models — Kimi K3, DeepSeek V3.2, Qwen 3.5, GLM 5.2, Gemma, Mistral — to either roll their own commerce agent from scratch or accept vendor lock-in.

This fork keeps everything upstream ships (tools, prompts, safety gates, presentation, memory, executor) and swaps only the model call — so you can run the exact same agent on the exact same tools against whichever model wins your capability matrix this month.

Install

Wheel install (once we're on PyPI — the workflow is scaffolded):

pip install open-commerce-agent

The wheel bundles the vendored Anthropic subset as top-level commerce_common / shopping_agent / shopping_agent_runtime / merchant_agent / merchant_agent_runtime packages, so no post-install step is required. Both the shopping and merchant orchestrators use the same OpenAIChatCompatClient — one shim covers both agent families.

Source install (contributors, or before PyPI publish):

python -m venv .venv && source .venv/bin/activate
pip install -e '.[dev]'
bash scripts/install.sh   # installs the vendored subset editable

Editable-install needs the shell script because the vendored code sits under vendored/upstream/ at development time; the script pip install -es the three sibling packages so changes there flow without a reinstall. The wheel-install path doesn't need it — hatch bundles them into the wheel.

Quickstart

Copy configs/openrouter.env.example → .env, fill in a key + model, then run the smoke against a built-in mock catalog:

source .env      # OPENAI_BASE_URL, OPENAI_API_KEY, MODEL
oca smoke        # or: python examples/smoke.py

You should see the model call search → add_to_cart and end with a one-line assistant summary. That validates your provider+model combo.

To wire your own catalog, implement the StorefrontBackend protocol against your data (examples/mock_backend.py is a minimal reference, docs/adding-a-backend.md is the full guide), then:

from open_commerce_agent import build_client_from_env
from shopping_agent.config import ShoppingAgentConfig
from shopping_agent_runtime.orchestrator import ShoppingAgent

client, model = build_client_from_env()
agent = ShoppingAgent(
    backend=YourStorefrontBackend(),
    client=client,
    config=ShoppingAgentConfig(model=model),
)
# ... call agent.stream_turn(messages, session, state) per turn

See examples/smoke.py for the full session loop.

Capability matrix

Community-maintained — file a PR against this section when you add or update a row. Pass rate is from an internal reference task set (a public benchmark harness is a follow-up).

Section stub — real matrix landed after the first CI round of live smokes; see docs/capability-matrix.md for the current view.

Provider recipes

See configs/ for ready-to-copy environment configurations for each supported provider:

• configs/openrouter.env.example — OpenRouter (Claude, Kimi, DeepSeek, Qwen, GLM, Gemma, all via one endpoint)
• configs/litellm.env.example — self-hosted LiteLLM proxy
• configs/vllm.env.example — self-hosted vLLM with a chat template
• configs/openai.env.example — hosted OpenAI (fallback)

None is a "default" — the point of this package is you pick.

What upstream did well that we kept

• StorefrontBackend — clean abstract interface with one method per domain operation. Any catalog can implement it in under a day.
• Provenance gates that block hallucinated product IDs and cart writes on unseen items. Safety-relevant, keep it.
• Skills-as-prompt-modules pattern — the five SKILL.md files under vendored/upstream/shopping-agent/skills/ are what makes the agent feel domain-competent. Keep them; contribute skill additions upstream where possible.
• The full turn loop + presentation-tool streaming + memory extraction.

What we changed (all in the wrapper layer, none in the vendored code)

• runtime_openai_shim/ — the translation shim. See CHANGES.md for details.
• No default model, no cache_control fakery, no merchant agent, no Claude Agent SDK path.

License

• vendored/upstream/* — Apache-2.0, Anthropic PBC (see the vendored LICENSE).
• src/open_commerce_agent/* — Apache-2.0, ORO AI.

Neither Anthropic nor Claude endorse or maintain this fork. This is an independent adaptation for the OpenAI-compat wire protocol.

Migrating from anthropics/commerce-agents

Already running the upstream reference and want to switch providers? The diff is roughly six lines. See docs/migrating-from-upstream.md.

Observability

OpenAIChatCompatClient(..., on_request=…, on_response=…) — plug in logging / tracing / cost accounting per model call without patching the shim. See docs/observability.md.

Reference

• docs/glossary.md — terms used across the codebase and docs (StorefrontBackend, provenance gate, orchestrator, shim, presentation vs data, session vs state, …).
• docs/architecture.md — box diagram and the shim's place in the request path.
• docs/troubleshooting.md — symptom → fix for the failure modes we've actually seen (empty responses, cart stays empty, tool-calls dropped, provider quirks).
• docs/adr/ — architecture decision records.

Related

• Upstream: https://github.com/anthropics/commerce-agents
• Upstream tracking + sync: UPSTREAM.md
• Local changes: CHANGES.md