Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sellfern.com/llms.txt

Use this file to discover all available pages before exploring further.

Sellfern’s Python agent example shows how to wire Claude — via the Anthropic Python SDK — to Sellfern REST endpoints so Claude can answer natural language questions about your business. You describe what you want in plain English, and Claude decides which API calls to make, executes them against the live Sellfern API, and returns a structured answer.

​
Prerequisites

  • Python 3.11 or later
  • A Sellfern API token with at least the orders:read and analytics:read scopes
  • An Anthropic API key (available at console.anthropic.com)

​
Setup

1

Navigate to the example directory

From the root of the Sellfern project directory, change into the Python agent example:
cd examples/python-agent
2

Create and activate a virtual environment

python -m venv .venv
source .venv/bin/activate
3

Install dependencies

pip install -r requirements.txt
4

Set environment variables

export ANTHROPIC_API_KEY="sk-ant-..."
export SELLFERN_API_TOKEN="sk_live_..."
export SELLFERN_API_URL="https://api.sellfern.com"
Set SELLFERN_API_URL to http://localhost:3000 if you are running a local Sellfern instance.
5

Run the agent

Pass your question as a command-line argument:
python agent.py "List all Shipped orders from the last 30 days"

​
Example usage

python agent.py "List all Shipped orders from the last 30 days"
python agent.py "What was our gross profit margin last month?"
python agent.py "Show me the 10 most recent orders from store 3"
Claude reads your prompt, decides which tool to call (and with what parameters), calls the Sellfern API, and returns a formatted answer. Multi-step questions that require more than one API call are handled automatically by the agentic loop.

​
How it works

The agent exposes two built-in tools to Claude:
ToolSellfern endpointDescription
list_ordersGET /api/v2/ordersFilter orders by status, store ID, or search query with pagination
get_analytics_summaryGET /api/v2/analytics/summaryRevenue, order count, COGS, gross profit, and margin for a period
The agentic loop runs as follows:
  1. Your prompt is sent to Claude with both tool definitions attached.
  2. Claude returns a tool_use block specifying which tool to call and what arguments to pass.
  3. The script executes the tool — a real HTTP call to SELLFERN_API_URL using your token.
  4. The tool result is sent back to Claude as a tool_result message.
  5. Steps 2–4 repeat until Claude produces a final text response with no further tool calls.

​
Extending the agent

To expose more Sellfern endpoints as tools, follow the three-step pattern from the README:
  1. Write a Python function that calls the endpoint using _sellfern_get (for GET requests) or a _sellfern_post helper you add for mutations.
  2. Add a tool definition to the TOOLS list using the same JSON schema format as the existing tools.
  3. Add a dispatch branch in run_tool() that maps the tool name to your new function.
For example, to add order status updates: 
# 1. Define the function
def update_order_status(order_id: int, status: str, tracking_number: str | None = None):
    return _sellfern_patch(f"/orders/{order_id}/status", {
        "status": status,
        "tracking_number": tracking_number,
    })

# 2. Add to TOOLS list
{
    "name": "update_order_status",
    "description": "Update the status of a Sellfern order",
    "input_schema": {
        "type": "object",
        "properties": {
            "order_id": {"type": "integer"},
            "status": {"type": "string"},
            "tracking_number": {"type": "string"},
        },
        "required": ["order_id", "status"],
    },
}

# 3. Dispatch in run_tool()
elif tool_name == "update_order_status":
    return update_order_status(**tool_input)
Other endpoints worth adding:
  • PATCH /api/v2/orders/:id/status → update_order_status
  • POST /api/v2/orders/bulk-status → bulk_update_order_status
  • GET /api/v2/analytics/by-store → get_analytics_by_store
  • GET /api/v2/fulfillment/queue → list_fulfillment_queue
The Python agent is a thin wrapper around Sellfern’s REST API — it does not have its own data store or cache. Every tool call makes a live HTTP request to SELLFERN_API_URL, so the results are always up to date. The REST API is the source of truth.