open-commerce-agent

Provider-agnostic reference commerce agent. A fork of anthropics/commerce-agents designed for OpenAI Chat Completions–compatible endpoints — OpenRouter, Chutes, LiteLLM, vLLM, Ollama, LM Studio, self-hosted. (Only OpenRouter has been validated end-to-end so far — see the capability matrix.)

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. Live on PyPI as open-commerce-agent. Runtime shim, request + response translation, both shopping + merchant orchestrators bundled, and end-to-end wiring against Claude (via OpenRouter) and OSS models (via OpenRouter) are proven working. First real user validation and capability-matrix rows for non-OpenRouter providers still to come.

Why

The upstream reference provides Messages API, Claude Agent SDK, and Managed Agents runtimes for Claude. This independent fork vendors the shopping and merchant Messages API subset and adds a client shim for OpenAI Chat Completions–compatible endpoints — so the same tools, prompts, gates, and orchestrators can run against models reached through OpenRouter, Chutes, LiteLLM, vLLM, or a self-hosted server.

This fork retains a pinned, attributed subset of upstream's shopping and merchant tools, prompts, gates, memory, and Messages API orchestrators, and translates model-client calls. It does not include the upstream Agent SDK, Managed Agents, examples, or other omitted components.

Install

pip install --pre open-commerce-agent

(--pre needed while the current version is an alpha — 0.1.0a1. Drop the flag once v0.1.0 final lands.)

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 SKILL.md files under vendored/upstream/shopping-agent/skills/ and vendored/upstream/merchant-agent/skills/ are what make the agents feel domain-competent. Publish fork-specific skill additions here and track upstream changes in UPSTREAM.md.
• 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 Agent SDK or Managed Agents runtimes.

The shopping and merchant core, skills, and Messages API runtimes are vendored; Agent SDK and Managed Agents runtimes are not.

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/agents.md — shopping vs merchant agent families, backend contracts, wiring shape.
• 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/versioning.md — SemVer policy, vendored SHA sync cadence, release checklist.
• docs/testing.md — test tier map for contributors.
• docs/adr/ — architecture decision records.

Related

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