Skip to Content
DocumentationAgentsE-commerce Agents

E-commerce Agents

Enthusiast agents are regular Suvereo agents. They subclass BaseToolCallingAgent from suvereo-agent-tool-calling and are registered in AVAILABLE_AGENTS, like any other agent. What makes them e-commerce agents is the builder they use, which gives their tools access to the catalog and to your e-commerce platform.

This page describes what the Enthusiast domain definition adds on top of Suvereo. For the agent contract itself (class variables, prompts, memory, tool configuration), see the Suvereo agent documentation.

The E-commerce Builder

An agent selects its builder with the BUILDER_CLASS class variable. All pre-built Enthusiast agents use EcommerceAgentBuilder from enthusiast-domain:

from enthusiast_domain.builder import EcommerceAgentBuilder from enthusiast_domain_tools import ProductExamplesTool, ProductSQLSearchTool from suvereo_agent_tool_calling import BaseToolCallingAgent from suvereo_common.config.base import LLMToolConfig from .prompt import PRODUCT_SEARCH_TOOL_CALLING_AGENT_PROMPT class ProductSearchAgent(BaseToolCallingAgent): AGENT_KEY = "enthusiast-agent-product-search" NAME = "Product Search" SYSTEM_PROMPT = PRODUCT_SEARCH_TOOL_CALLING_AGENT_PROMPT BUILDER_CLASS = EcommerceAgentBuilder TOOLS = [ LLMToolConfig(tool_class=ProductSQLSearchTool), LLMToolConfig(tool_class=ProductExamplesTool), ]

EcommerceAgentBuilder extends Suvereo’s AgentBuilder. In addition to everything the default builder provides (chat history, memory, repositories), it creates an EcommerceInjector that exposes three e-commerce dependencies to the agent’s tools.

The E-commerce Injector

Tools receive the injector when they are created and access it as self._injector. EcommerceInjector extends Suvereo’s injector with:

PropertyTypePurpose
product_retrieverProductRetrieverLooks up products in the current data set
document_retrieverDocumentRetrieverSemantic search over the documents in the current data set
ecommerce_platform_connectorECommercePlatformConnector or NonePerforms actions in the e-commerce platform configured for the data set

Product Retriever

ProductRetriever reads from the domain definition’s product table, always limited to the current data set:

  • find_products_with_sql(sql_query): runs a SELECT query written by the agent. The query is validated before it runs: it may only read the product table, and a data set condition is added automatically.
  • find_products_matching_query(user_query): asks the language model to build the query from a natural-language description.
  • get_sample_products_json(): returns a sample of products, which helps the agent understand the catalog’s structure before searching it.
  • product_details_as_json(products): serializes products for the agent.

Document Retriever

DocumentRetriever performs vector search over document chunks. find_content_matching_query(query) returns the chunks most relevant to the query, using the embedding model configured for the data set.

E-commerce Platform Connector

The connector is resolved from the data set’s E-Commerce system integration. When no such integration is configured, the property is None, and tools should tell the user to configure one:

connector = self._injector.ecommerce_platform_connector if not connector: return "The user needs to configure an ecommerce platform connector first" order_id = connector.create_order_with_items(items)

ECommercePlatformConnector (from enthusiast-domain-common) provides operations such as create_order_with_items, get_product_by_sku, create_product, update_product, update_stock and get_admin_url_for_order_id.

Shared Tools

The enthusiast-domain-tools package contains tools used by several pre-built agents, which you can also use in your own agents:

ToolPurpose
ProductExamplesToolReturns a sample of products, so the agent can learn the catalog’s structure
ProductSQLSearchToolLets the agent search the catalog with a SQL SELECT query
UpsertProductDetailsToolCreates or updates a product in the e-commerce platform

To add one to an agent, list it in TOOLS:

TOOLS = [ LLMToolConfig(tool_class=ProductExamplesTool), LLMToolConfig(tool_class=ProductSQLSearchTool), ]

Next Steps

Last updated on