A CrewAI crew for e-commerce product description writing

A reliable crewai product description writing example needs more than a single prompt—it needs role separation, a validation gate, and a fallback path for model outages. This guide walks through building a CrewAI crew that ingests raw product specs and outputs channel-ready e-commerce copy. You will end up with a runnable pipeline that separates research, drafting, and editing into distinct agents.

Step 1: Scaffold the project

Create a clean workspace and install the core dependencies. CrewAI relies on LangChain primitives for model access, so we pull langchain-openai as the LLM adapter.

mkdir product_crew && cd product_crew
python -m venv .venv && source .venv/bin/activate
pip install crewai langchain-openai pydantic

Keep the entrypoint in main.py. The crew will read a JSON file with product specs, so create specs.json with a representative SKU:

{
  "sku": "TS-RED-001",
  "title": "Heavyweight Cotton T-Shirt",
  "attributes": {
    "material": "100% combed cotton",
    "weight": "220gsm",
    "fit": "Relaxed",
    "sizes": ["S", "M", "L", "XL"],
    "colors": ["Red", "Black", "Sand"]
  },
  "bullets": [
    "Pre-shrunk fabric",
    "Reinforced collar",
    "Screen-print friendly"
  ]
}

A real catalog will have thousands of these files. The schema stays fixed; only the values change.

Step 2: Define the spec model

Use Pydantic to validate input before the crew spends a single token. This catches malformed attributes early and gives you a typed object to interpolate into task descriptions.

from pydantic import BaseModel

class ProductSpec(BaseModel):
    sku: str
    title: str
    attributes: dict
    bullets: list[str]

Load it in main.py:

import json
from pathlib import Path

spec = ProductSpec(**json.loads(Path("specs.json").read_text()))

If the JSON misses sku or bullets, Pydantic raises immediately. That is the behavior you want in a batch job.

Step 3: Configure the LLM with fallback

CrewAI accepts any LangChain chat model. For production, you want automatic fallback when a provider is rate-limited or degraded. Point CrewAI at n4n.ai’s single OpenAI-compatible endpoint to get 240+ models and built-in degradation handling without rewriting agent code.

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="openai/gpt-4o-mini",
    temperature=0.3,
    base_url="https://api.n4n.ai/v1",
    api_key="YOUR_N4N_KEY",  # or set OPENAI_API_KEY env
)

If you run without the gateway, drop base_url and use the official OpenAI key. The rest of the crew is identical. Set temperature low for the researcher and editor, higher for the copywriter if you want variant flavor.

Step 4: Define the agents

Role separation is the whole point of a crewai product description writing example. We use three agents: a researcher who converts specs to benefits, a copywriter who drafts, and an editor who enforces brand constraints.

from crewai import Agent

researcher = Agent(
    role="E-commerce Research Analyst",
    goal="Extract the top 5 selling points from the product spec",
    backstory="You specialize in translating technical attributes into customer benefits.",
    llm=llm,
    verbose=True,
)

copywriter = Agent(
    role="Conversion Copywriter",
    goal="Write a 150-200 word product description using the researched points",
    backstory="You write for a DTC apparel brand with a casual, confident tone.",
    llm=llm,
    verbose=True,
)

editor = Agent(
    role="Brand Editor",
    goal="Tighten the copy, enforce tone, and output final JSON with title, body, and meta",
    backstory="You have 10 years editing for Shopify stores.",
    llm=llm,
    verbose=True,
)

The backstory is not decoration. It seeds the system prompt and noticeably changes output rigidity. A researcher with “technical attributes” framing will not embellish; a copywriter with “casual, confident” framing will.

Step 5: Define tasks and wire dependencies

Each task declares an expected_output so the crew knows when it is done. Use context to chain tasks—CrewAI injects the prior task output into the next prompt.

from crewai import Task

research_task = Task(
    description=f"Analyze spec for {spec.sku} and list benefits",
    expected_output="Bullet list of 5 customer-facing benefits",
    agent=researcher,
)

write_task = Task(
    description="Draft a product description from the benefits",
    expected_output="Markdown description, 150-200 words",
    agent=copywriter,
    context=[research_task],
)

edit_task = Task(
    description="Edit into final structured output",
    expected_output="JSON with keys: title, body, meta_description",
    agent=editor,
    context=[write_task],
)

Note the description strings are terse. CrewAI expands them with agent role and backstory; you do not need to repeat the agent’s job in the task.

Step 6: Assemble and run the crew

Use Process.sequential because each step depends on the previous. Kickoff returns the final task output.

from crewai import Crew, Process

crew = Crew(
    agents=[researcher, copywriter, editor],
    tasks=[research_task, write_task, edit_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff()
print(result)

Verify success

Run python main.py. You should see agent logs and a final string containing valid JSON. Assert structure in a quick test:

import json

def test_output(raw):
    data = json.loads(str(raw))
    assert "title" in data and "body" in data
    assert 100 <= len(data["body"]) <= 400
    assert "meta_description" in data

test_output(result)

If the JSON parses and passes length checks, the crew works. That is the baseline crewai product description writing example you can iterate on.

Step 7: Add a cache-control hint for repeat runs

When you re-run the same SKU during development, you do not want to burn tokens re-deriving benefits. n4n.ai forwards provider cache-control hints; you can also simply cache the research task output to disk.

# naive file cache
cache = Path(f"{spec.sku}.research.json")
if cache.exists():
    research = json.loads(cache.read_text())
else:
    research = researcher.execute_task(research_task)
    cache.write_text(json.dumps(research))

This keeps the example cheap to iterate on. In a full pipeline, push the cache to Redis with a TTL matching your catalog refresh cycle.

Step 8: Scale to a batch pipeline

For a catalog of 10k SKUs, wrap the crew in a loop with rate limiting and per-file error isolation.

from pathlib import Path
import json

for spec_file in Path("catalog").glob("*.json"):
    try:
        spec = ProductSpec(**json.loads(spec_file.read_text()))
        # re-instantiate tasks with f-string per spec (same pattern as Step 5)
        # ...
        result = crew.kickoff()
        test_output(result)
        Path(f"out/{spec.sku}.json").write_text(str(result))
    except Exception as e:
        print(f"failed {spec_file}: {e}")
        continue

Use per-token usage metering (available via the gateway) to track cost per SKU. That closes the loop on a real content pipeline.

Step 9: Common failure modes

• Hallucinated attributes: The copywriter invents a color not in spec. Mitigate by passing the raw spec as a read-only context to the editor task.
• Overlong output: Enforce word count in the editor task description and validate post-run as shown.
• Rate limits: Use the fallback gateway so a single provider outage does not stall the batch.
• Drift in tone: If the editor starts rewriting in a corporate voice, tighten the backstory and add a negative constraint: “Never use words like ‘leverage’ or ‘synergy’.”

A solid crewai product description writing example separates research from writing from editing. That separation is what makes the output predictable enough to ship to a storefront without a human in the loop for every SKU. Build the crew once, validate the JSON contract, then let it run across the catalog.