{"id":30655980,"url":"https://github.com/intersystems-ib/customer-support-agent-demo","last_synced_at":"2026-04-14T15:31:12.174Z","repository":{"id":312463251,"uuid":"1045485086","full_name":"intersystems-ib/customer-support-agent-demo","owner":"intersystems-ib","description":"AI-powered customer support agent built with Python smolagents and InterSystems IRIS — SQL, RAG, and live interoperability","archived":false,"fork":false,"pushed_at":"2025-08-30T18:51:43.000Z","size":5497,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-30T20:37:04.163Z","etag":null,"topics":["ai-agent","customer-support","demo","docker","interoperability","intersystems-iris","llm","openai","python","rag","retrieval-augmented-generation","smolagents","sql","vector-search"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intersystems-ib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-27T08:45:46.000Z","updated_at":"2025-08-30T18:51:47.000Z","dependencies_parsed_at":"2025-08-30T20:47:15.271Z","dependency_job_id":null,"html_url":"https://github.com/intersystems-ib/customer-support-agent-demo","commit_stats":null,"previous_names":["intersystems-ib/customer-support-agent-demo"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/intersystems-ib/customer-support-agent-demo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersystems-ib%2Fcustomer-support-agent-demo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersystems-ib%2Fcustomer-support-agent-demo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersystems-ib%2Fcustomer-support-agent-demo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersystems-ib%2Fcustomer-support-agent-demo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intersystems-ib","download_url":"https://codeload.github.com/intersystems-ib/customer-support-agent-demo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intersystems-ib%2Fcustomer-support-agent-demo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272965497,"owners_count":25023071,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-31T02:00:09.071Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-agent","customer-support","demo","docker","interoperability","intersystems-iris","llm","openai","python","rag","retrieval-augmented-generation","smolagents","sql","vector-search"],"created_at":"2025-08-31T10:02:56.078Z","updated_at":"2026-04-14T15:31:12.168Z","avatar_url":"https://github.com/intersystems-ib.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Customer Support Agent Demo 🤖📦\n\nCustomer support agent that helps users resolve questions about orders, products, shipping, etc.\n\nIn this project you will build an **AI agent** powered by **Python [smolagents](https://huggingface.co/docs/smolagents/index)** and **InterSystems IRIS**.\n\n---\n\n## Why AI Agents? 🧠\n\nAI agents are programs that use an **LLM as their \"mind\"** and then **call external tools** (databases, APIs, knowledge bases…) to solve real-world tasks.\n\n👉 You *could* build such an agent **by hand**:\n\n* Call the LLM directly from your code.\n* Parse its responses.\n* Figure out yourself when and how to call different tools (SQL, RAG, APIs…).\n* Glue everything together.\n\nThat works… but it’s complex and fragile 😅.\n\nInstead, you can use a **framework**. In this project we use **[smolagents](https://huggingface.co/docs/smolagents/index)**, a lightweight Hugging Face library. It lets you define **tools** and data sources, while the agent handles the reasoning.\n\n* **CodeAgent** (used here) is a smolagents agent that plans by generating Python code step by step.\n* It uses the LLM to decide which tools to call and how to combine them until it has an answer.\n\nThink of it as a **tiny brain with a toolbox** 🧰.\n\n---\n\n## Project architecture 🏗️\n\nThis project relies on two key components:\n\n* **🐍 Python** → Runs the AI agent (LLM reasoning + smolagents framework).\n* **🗄️ InterSystems IRIS** → Acts as the data and integration platform:\n\n  * Stores **structured data** (customers, orders, products, shipments).\n  * Provides a **vector database** for **unstructured data** (docs, FAQs) with RAG queries.\n  * Includes **interoperability** features to simulate live shipping status calls.\n\nTogether, they showcase how IRIS enables **real enterprise AI agents** that combine reasoning, structured \u0026 unstructured data, and live integrations.\n\n---\n\n## What you will build 🚀\n\nYou will build an AI agent that:\n\n* Uses a LLM as its \"mind\" to plan and decide how to answer questions that users will ask about their orders, products, etc.\n* Uses different tools to access structured data (SQL tables), unstructured data (documents using a RAG pattern) and live external information (interoperability).\n\n---\n\n## Requirements 📋\n\nTo run this demo you’ll need:\n\n* 🐍 **[Python 3.9+](https://www.python.org/)**\n  Runs the AI agent with smolagents and connects to IRIS.\n\n* 🐳 **[Docker](https://docs.docker.com/get-docker/)**\n  Spins up an **InterSystems IRIS** container (database + vector search + interoperability).\n\n* 💻 **[VS Code](https://code.visualstudio.com/)** (recommended)\n  For editing and exploring the Python code.\n\n* 🔑 **[OpenAI API Key](https://platform.openai.com/)**\n  Used for the LLM “mind” and also to embed documents for RAG.\n\n---\n\n## Setup ⚙️\n\n### 1. Setup Python Environment\n\nCreate a virtual environment\n```bash\n# Mac/Linux\npython3 -m venv .venv\n# Windows\npython -m venv .venv\n```\n\nActivate the environment:\n```bash\n# Mac/Linux\nsource .venv/bin/activate\n\n# Windows (PowerShell)\n.venv\\Scripts\\Activate.ps1\n```\n\nThen, install dependencies:\n```bash\npip install -r requirements.txt\n```\n\nCreate a `.env` file:\n\n* Copy `.env.example` to `.env`\n* Modify it to include your OpenAI API\n\n---\n\n### 2. Setup InterSystems IRIS container\n\n```bash\ndocker compose build\ndocker compose up -d\n```\n\nYou can access IRIS [Management Portal](http://localhost:52773/csp/sys/UtilHome.csp) using:\n\n* User: `superuser`\n* Password: `SYS`\n\n---\n\n## Understanding the repo 📂\n\nHave a look at this summary of the repo contents to understand the project:\n\n```graphql\ncustomer-support-agent/\n├─ .env.example             # sample env file (copy to .env)\n│\n├─ iris/                    # InterSystems IRIS assets\n│  ├─ Dockerfile            # IRIS container build\n│  ├─ sql/                  # SQL scripts\n│  │  ├─ schema.sql         # creates tables for Customer Support use case\n│  │  ├─ load_data.sql      # loads CSVs into tables\n│  │  └─ truncate.sql      \n│  ├─ data/                 # data: customer, orders, etc.\n│  ├─ docs/                 # unstructured Knowledge Base (RAG content)\n│  └─ src/                  # IRIS classes. Simulates live shipping status interoperability \n│\n├─ agent/                   # the AI agent (Python) + tools\n│  ├─ customer_support_agent.py   # wraps smolagents CodeAgent + tools\n│  └─ tools/\n│     ├─ sql_tool.py              # SQL tools\n│     ├─ rag_tool.py              # RAG tools\n│     └─ shipping_tool.py         # calls IRIS interoperability\n│\n├─ db/                      # database adapters \u0026 helpers\n├─ cli/                     # terminal frontend\n├─ ui/                      # lightweight web UI (Gradio)\n└─ scripts/                 # utility scripts\n```\n\n---\n\n## Load SQL Data 🗄️\n\nBefore running the agent, we must create the tables and insert some data.\nThis will be the structured data that the agent will query to answer user questions.\n\nRun this SQL sentences in IRIS [SQL Explorer](http://localhost:52773/csp/sys/exp/%25CSP.UI.Portal.SQL.Home.zen?$NAMESPACE=USER) or using your favorite SQL client.\n\n```sql\nLOAD SQL FROM FILE '/app/iris/sql/schema.sql' DIALECT 'IRIS' DELIMITER ';'\n```\n\n```sql\nLOAD SQL FROM FILE '/app/iris/sql/load_data.sql' DIALECT 'IRIS' DELIMITER ';' \n```\n\nCheck the data you have just inserted and get yourself familiar with the tables.\nHere are some simple queries you can try:\n\n```sql\n-- List all customers\nSELECT * FROM Agent_Data.Customers;\n\n-- Get all orders for a given customer\nSELECT o.OrderID, o.OrderDate, o.Status, p.Name AS Product\nFROM Agent_Data.Orders o\nJOIN Agent_Data.Products p ON o.ProductID = p.ProductID\nWHERE o.CustomerID = 1;\n\n-- Check shipment info for an order\nSELECT * FROM Agent_Data.Shipments WHERE OrderID = 1001;\n\n-- See products with their warranty\nSELECT Name, WarrantyMonths FROM Agent_Data.Products;\n\n-- Find orders that are still Processing\nSELECT * FROM Agent_Data.Orders WHERE Status = 'Processing';\n```\n\n---\n\n## Load and embed non structured data 📚\n\nThe agent will be able also to query non structured data using a RAG (Retrieval Augmented Generation) pattern.\nFor that, we will be leveraging InterSystems IRIS Vector Search features.\n\nWe will embed the data using OpenAI `text-embedding-3-small` model.\nWe will leverage an InterSystems IRIS feature that allows us to setup embedding directly in the database.\n\n```sql\nINSERT INTO %Embedding.Config (Name, Configuration, EmbeddingClass, VectorLength, Description)\n  VALUES ('my-openai-config', \n          '{\"apiKey\":\"your-openai-api-key-here\", \n            \"sslConfig\": \"llm_ssl\", \n            \"modelName\": \"text-embedding-3-small\"}',\n          '%Embedding.OpenAI', \n          1536,  \n          'a small embedding model provided by OpenAI') \n```\n\nNow, run script that loops over documents and records that needs to be embedded\n\n```bash\npython scripts/embed_sql.py\n```\n\nAfter that have a look at the tables and check that embeddings are now included.\n\n```sql\n-- Products\nSELECT * FROM Agent_Data.Products;\n```\n\n```sql\n-- Chunks from documents\nSELECT * FROM Agent_Data.DocChunks;\n```\n\n---\n\n## Interoperability 🔗\n\nOne of the **most powerful features of InterSystems IRIS** is its **Interoperability framework**.\nIt allows you to seamlessly connect your solution to **other systems, APIs, and services** in a reliable, monitored, and traceable way.\n\nIn this demo, we included a **mock shipping service** that shows how an agent can call a live API to retrieve status and timeline information:\n\n```bash\ncurl --header \"Content-Type: application/json\" \\\n  --request POST \\\n  --data '{\"orderStatus\":\"Processing\",\"trackingNumber\":\"DHL7788\"}' \\\n  http://localhost:52773/api/shipping/status\n```\n\nThis information can also be consumed by the agent.\n\n✨ And since IRIS has a built-in **Visual Trace** viewer, you can actually see each message flowing through the system.\n\n\u003cimg src=\"img/message-trace.gif\" width=\"900\" /\u003e\n\n---\n\n## Understanding the agent 🤖\n\nThe agent is a smolagents **CodeAgent**:\n\n* It will use an mini OpenAI LLM model as a mind to plan and decide which tools use.\n* It will run several steps and use different tools to try to resolve a user question.\n\n➡️ Want to see how it works under the hood? Check out these key files:\n\n* [agent/customer\\_support\\_agent.py](agent/customer_support_agent.py) → main agent setup\n* [agent/tools/sql\\_tool.py](agent/tools/sql_tool.py) → SQL queries (orders, products, ranges)\n* [agent/tools/rag\\_tool.py](agent/tools/rag_tool.py) → RAG queries with IRIS Vector Search\n* [agent/tools/shipping\\_tool.py](agent/tools/shipping_tool.py) → calls the IRIS interoperability API\n\nFeel free to open them and explore the code — they’re short, simple, and quite fun to read 👀.\n\n---\n\n## Running the agent ▶️\n\nYou can run the agent in three different ways:\n\n### 🔹 One-shot mode\n\nRun a single question + get a single answer. Perfect for quick tests.\n\n```bash\npython -m cli.run --email alice@example.com --message \"Where is my order #1001?\"\n\npython -m cli.run --email alice@example.com --message \"Show electronics that are good for travel\"\n\npython -m cli.run --email alice@example.com --message \"Was my headphones order delivered, and what’s the return window?\"\n\npython -m cli.run --email alice@example.com --message \"Find headphones under $120 with ANC\"\n\npython -m cli.run --email alice@example.com --message \"If my order is out of warranty, what options do i have?\"\n\n```\n\n\u003cimg src=\"img/run-agent-one-shot.gif\" width=\"900\" /\u003e\n\n---\n\n### 🔹 Interactive CLI\n\nStart a small session where you can type multiple questions in a row.\n\n```bash\npython -m cli.run --email alice@example.com\n```\n\n---\n\n### 🔹 Web UI (Gradio)\n\nA lightweight chat UI with Gradio, so you can talk to the agent in your browser.\n\n```bash\npython -m ui.gradio\n```\n\nThen open the UI in http://localhost:7860\n\n\u003cimg src=\"img/run-agent-ui-2.gif\" width=\"900\" /\u003e\n\n---\n\n## 🎁 Bonus: Running Locally with Ollama\n\nYou don’t need OpenAI—run both **LLM** and **embeddings** entirely on your laptop using [Ollama](https://ollama.ai).\n\n### 1. Install Ollama\n\nFollow instructions at [ollama.ai/download](https://ollama.ai/download).\n\n### 2. Download models\n\n```bash\n# download an embedding model\nollama pull nomic-embed-text:latest\n\n# download a coding/LLM model\nollama pull devstral:24b-small-2505-q4_K_M\n\n# list installed models\nollama list\n```\n\n### 3. Test local models in Ollama\n\nTest [nomic-embed-text](https://ollama.com/library/nomic-embed-text) embedding model using: \n```bash\ncurl http://localhost:11434/api/embeddings -d '{\n  \"model\": \"nomic-embed-text:latest\",\n  \"prompt\": \"Ollama makes running local LLMs easy\"\n}'\n```\n\nTest [devstral](https://ollama.com/library/devstral) interactively:\n```bash\nollama run devstral:24b-small-2505-q4_K_M\n```\n\nOr using a REST interface:\n```bash\ncurl http://localhost:11434/api/generate -d '{\n  \"model\": \"devstral:24b-small-2505-q4_K_M\",\n  \"prompt\": \"Tell me a joke\",\n  \"stream\": false\n}'\n```\n\n### 4. Configure IRIS to use Ollama embeddings\n\nAs IRIS runs in Docker, access Ollama server in your localhost via `host.docker.internal`:\n\n```sql\nINSERT INTO %Embedding.Config (Name, Configuration, EmbeddingClass, VectorLength, Description)\n  VALUES ('ollama-nomic-config', \n          '{\"apiBase\":\"http://host.docker.internal:11434/api/embeddings\", \n            \"modelName\": \"nomic-embed-text:latest\"}',\n          'Embedding.Ollama', \n          768,  \n          'embedding model in Ollama');\n```\n\n### 5. Adjust embedding vector size\n\nAdjust vector columns in the schema to the size of embeddings returned by [nomic-embed-text](https://ollama.com/library/nomic-embed-text) model:\n\n```sql\nALTER TABLE Agent_Data.Products DROP COLUMN Embedding;\nALTER TABLE Agent_Data.Products ADD COLUMN Embedding VECTOR(FLOAT, 768);\n\nALTER TABLE Agent_Data.DocChunks DROP COLUMN Embedding;\nALTER TABLE Agent_Data.DocChunks ADD COLUMN Embedding VECTOR(FLOAT, 768);\n```\n\n### 6. Update `.env`\n\nUpdate the `.env` file to use local Ollama models:\n\n```bash\nOPENAI_MODEL=devstral:24b-small-2505-q4_K_M\nOPENAI_API_BASE=http://localhost:11434/v1\nEMBEDDING_CONFIG_NAME=ollama-nomic-config\n```\n\n### 7. Update embeddings \n\nRun script that loops over documents and records that needs to be embedded to update the embeddings using the local model:\n\n```bash\npython scripts/embed_sql.py\n```\n\nNow, the agent will run **fully local**: IRIS + Ollama 🚀\n\n```bash\npython -m cli.run --email alice@example.com --message \"If my order is out of warranty, what options do i have?\"\n```\n\n---\n\n## 🎉 Wrap up\n\n* You’ve just set up an **AI-powered customer support agent** that combines **LLM reasoning**, **structured SQL data**, **unstructured docs with RAG**, and **live interoperability APIs**.\n* This is a **technical repo**, but hey, customer support is never boring when you have an AI sidekick 🤖.\n* Next steps? Extend the schema, add more tools, or plug it into your own data sources!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersystems-ib%2Fcustomer-support-agent-demo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintersystems-ib%2Fcustomer-support-agent-demo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintersystems-ib%2Fcustomer-support-agent-demo/lists"}