{"id":38329817,"url":"https://github.com/kylehoehns/ecommerce-demo","last_synced_at":"2026-01-17T02:49:05.955Z","repository":{"id":310887583,"uuid":"1041553643","full_name":"kylehoehns/ecommerce-demo","owner":"kylehoehns","description":"AI-powered customer support agent demo using Rod Johnson's Embabel framework for Java Spring Boot applications","archived":false,"fork":false,"pushed_at":"2025-08-30T01:32:30.000Z","size":48,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T03:18:29.942Z","etag":null,"topics":["ai","anthropic","embabel","java","llm","mcp","openai","spring-boot"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kylehoehns.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-20T16:53:44.000Z","updated_at":"2025-08-30T01:32:29.000Z","dependencies_parsed_at":"2025-08-20T21:35:00.388Z","dependency_job_id":"04381549-b2fe-4967-8a98-403b4f31c0cc","html_url":"https://github.com/kylehoehns/ecommerce-demo","commit_stats":null,"previous_names":["kylehoehns/ecommerce-demo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kylehoehns/ecommerce-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylehoehns%2Fecommerce-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylehoehns%2Fecommerce-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylehoehns%2Fecommerce-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylehoehns%2Fecommerce-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kylehoehns","download_url":"https://codeload.github.com/kylehoehns/ecommerce-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kylehoehns%2Fecommerce-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28492590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T02:39:23.645Z","status":"ssl_error","status_checked_at":"2026-01-17T02:34:19.649Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","anthropic","embabel","java","llm","mcp","openai","spring-boot"],"created_at":"2026-01-17T02:49:05.866Z","updated_at":"2026-01-17T02:49:05.940Z","avatar_url":"https://github.com/kylehoehns.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Embabel Framework Demo - E-commerce Customer Support Agent\n\nA practical example demonstrating how to use [Rod Johnson's embabel framework](https://github.com/embabel/embabel-agent) to add AI-powered customer support agents to existing Java Spring Boot applications.\n\n## What is Embabel?\n\nEmbabel is an innovative framework that allows you to create agentic AI systems using Java annotations. Instead of writing complex orchestration code, you define agent behavior declaratively using annotations like `@Agent`, `@Action`, and `@Condition`.\n\nThis repository shows how to integrate embabel into a traditional Spring Boot e-commerce application to handle customer refunds and replacements automatically.\n\n## Prerequisites\n\n- **Java 21** or higher\n- **LLM API Key** - Either OpenAI or Anthropic API key required for LLM operations\n\n## Quick Start\n\n### 1. Set Your LLM API Key\n\nThe embabel framework requires either an OpenAI or Anthropic API key to function. Choose one:\n\n**For OpenAI:**\n```bash\nexport OPENAI_API_KEY=your-openai-api-key-here\n```\n\n**For Anthropic:**\n```bash\nexport ANTHROPIC_API_KEY=your-anthropic-api-key-here\n```\n\nOr on Windows:\n```cmd\nset OPENAI_API_KEY=your-openai-api-key-here\n# OR\nset ANTHROPIC_API_KEY=your-anthropic-api-key-here\n```\n\n### 2. Run the Application\n\n```bash\ngit clone \u003cthis-repo\u003e\ncd ecommerce-demo\n./mvnw spring-boot:run\n```\n\nThe application will start on port 8080.\n\n### 3. Test the Customer Support Agent\n\nYou can interact with the agent in two ways:\n\n**Option A: Using the Interactive Shell**\n\nTo use the shell version, you need to modify the Application.java file:\n1. Comment out `@EnableAgentMcpServer` on line 10\n2. Uncomment `@EnableAgentShell` on line 11\n\nThen run:\n```bash\n./scripts/shell.sh\n```\nThis starts an interactive shell where you can chat directly with the customer support agent. Once the shell is open, prefix your messages with `x` followed by your request:\n```\nx \"Hello! I'd like to return order ORD-123.\"\n```\n\n**Option B: MCP Server (for Claude Desktop integration)**\nThe agent is also available at `http://localhost:8080/sse` and can handle customer requests like:\n\n- \"I need a refund for order ORD-123\"\n- \"Can I get a replacement for order ORD-456?\"\n- \"I'm angry about my order ORD-789, I want my money back!\"\n\n## Key Embabel Concepts Demonstrated\n\n### Agent Declaration\n```java\n@Agent(\n    name = \"Customer Support Agent\",\n    description = \"Assists customers with refunds and replacements\"\n)\npublic class CustomerSupportAgent {\n    // Agent implementation\n}\n```\n\n### Actions and Flow Control\n```java\n@Action\nParsedRequest parseRequest(UserInput userInput, OperationContext context) {\n    // Uses LLM to extract order ID, operation type, and sentiment\n}\n\n@Action(pre = \"shouldReplace\")\nOrderAdjustmentResponse processReplacement(OrderSearchResult searchResult) {\n    // Only executes if shouldReplace condition is true\n}\n```\n\n### Conditional Logic\n```java\n@Condition(name = \"shouldReplace\")\npublic boolean shouldReplace(ParsedRequest request, OrderSearchResult result) {\n    boolean wantsReplacement = OperationType.REPLACE.equals(request.operationType());\n    boolean hasInventory = inventoryService.getQuantity(result.order().sku()) \u003e 0;\n    return hasInventory \u0026\u0026 wantsReplacement;\n}\n```\n\n### MCP Server Integration\n```java\n@AchievesGoal(\n    export = @Export(\n        name = \"refundOrReplaceOrder\",\n        remote = true,\n        startingInputTypes = {UserInput.class}\n    )\n)\n```\n\n## Testing with Claude Desktop\n\nTo interact with the agent through Claude Desktop, add this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"customer-support\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-remote\", \"http://localhost:8080/sse\"]\n    }\n  }\n}\n```\n\nThen restart Claude Desktop and you can chat with the customer support agent directly.\n\n## Project Structure\n\n```\nsrc/main/java/com/kylehoehns/ecommerce/\n├── agent/\n│   ├── CustomerSupportAgent.java   # Main embabel agent\n│   ├── OperationType.java          # REFUND/REPLACE enum\n│   └── Sentiment.java              # POSITIVE/NEUTRAL/NEGATIVE enum\n├── order/                          # Order management services\n├── inventory/                      # Inventory management\n└── Application.java                # Spring Boot app with @EnableAgentMcpServer\n```\n\n## How the Agent Works\n\n1. **Input Processing**: Customer requests are parsed using LLM to extract:\n   - Order ID\n   - Desired operation (refund/replacement)\n   - Customer sentiment\n\n2. **Business Logic**: The agent checks:\n   - If the order exists\n   - Current inventory levels\n   - Customer preferences\n\n3. **Decision-Making**: Based on conditions:\n   - Replacements are offered if inventory is available\n   - Refunds are processed if no inventory or customer prefers refund\n\n4. **Response Generation**: LLM generates personalized responses considering customer sentiment\n\n## Learning More About Embabel\n\n- **GitHub Repository**: [embabel-agent](https://github.com/embabel/embabel-agent)\n- **Rod Johnson's Blog**: [Medium @springrod](https://medium.com/@springrod) - Contains in-depth examples and tutorials\n- **Framework Documentation**: Available in the embabel-agent repository\n\n## API Examples\n\nWhile the agent handles most operations, you can also interact with the underlying services:\n\n```bash\n# Check inventory\ncurl http://localhost:8080/api/inventory\n\n# Create an order\ncurl -X POST http://localhost:8080/api/orders \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"sku\": \"shirt-m\"}'\n\n# List orders\ncurl http://localhost:8080/api/orders\n```\n\n## Dependencies\n\nThe key embabel dependency is added to `pom.xml`:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.embabel.agent\u003c/groupId\u003e\n    \u003cartifactId\u003eembabel-agent-starter\u003c/artifactId\u003e\n    \u003cversion\u003e0.1.1-SNAPSHOT\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Next Steps\n\n1. Explore the `CustomerSupportAgent.java` to understand embabel patterns\n2. Try modifying conditions to change agent behavior\n3. Add new actions for additional customer support scenarios\n4. Read Rod Johnson's blog posts for advanced embabel techniques\n5. Check out the embabel-agent repository for more examples\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylehoehns%2Fecommerce-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkylehoehns%2Fecommerce-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkylehoehns%2Fecommerce-demo/lists"}